@siwenwu/tiny-date-helpers

Tiny, dependency-free date helpers for Node.js. The package handles strict ISO date validation, relative time, and calendar-date comparison in an explicit timezone. It also includes a small tiny-date command-line tool.

Install

npm install @siwenwu/tiny-date-helpers

Node.js 18 or newer is required.

Library usage

import {
  compareDateOnly,
  formatISODate,
  formatRelativeTime,
  isSameDateOnly,
  isValidISODate,
  parseISODate
} from "@siwenwu/tiny-date-helpers";

isValidISODate("2024-02-29"); // true
isValidISODate("2023-02-29"); // false

parseISODate("2024-02-29").toISOString();
// "2024-02-29T00:00:00.000Z"

formatRelativeTime("2024-03-07T12:00:00Z", {
  baseDate: "2024-03-10T12:00:00Z"
});
// "3 days ago"

formatISODate("2024-03-01T00:30:00Z", {
  timeZone: "America/Los_Angeles"
});
// "2024-02-29"

compareDateOnly(
  "2024-03-01T00:30:00Z",
  "2024-02-29T18:00:00Z",
  { timeZone: "America/Los_Angeles" }
); // 0

isSameDateOnly(new Date(), new Date(), { timeZone: "Asia/Tokyo" }); // true

compareDateOnly returns -1, 0, or 1. A strict YYYY-MM-DD input is treated as a calendar date and is never shifted between timezones. Dates and timestamps are converted to the requested IANA timezone first. The default timezone is UTC.

formatRelativeTime uses Intl.RelativeTimeFormat and fixed boundaries of 60 seconds, 60 minutes, 24 hours, 30 days, and 365 days. Pass numeric: "auto" to get words such as now, yesterday, and tomorrow where supported by the locale.

CLI usage

npx @siwenwu/tiny-date-helpers validate 2024-02-29
npx @siwenwu/tiny-date-helpers format 2024-03-01T00:30:00Z --time-zone America/Los_Angeles
npx @siwenwu/tiny-date-helpers relative 2024-03-07T12:00:00Z --base 2024-03-10T12:00:00Z
npx @siwenwu/tiny-date-helpers compare 2024-02-29 2024-03-01

The validate command exits with status 1 when its input is invalid.

API

• isValidISODate(value)
• parseISODate(value)
• formatISODate(value, { timeZone })
• compareDateOnly(left, right, { timeZone })
• isSameDateOnly(left, right, { timeZone })
• formatRelativeTime(value, { baseDate, locale, numeric })

License

MIT