@siwenwu/tiny-date-utils

Tiny, dependency-free date helpers for strict ISO date validation, readable relative time, and calendar-date operations that do not depend on the host machine's timezone. Includes the tiny-date CLI.

Install

npm install @siwenwu/tiny-date-utils

Requires Node.js 18 or newer.

Library usage

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

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

parseISODate("2024-02-29"); // Date at 2024-02-29T00:00:00.000Z

formatRelativeTime("2024-06-12T12:00:00Z", {
  baseDate: "2024-06-15T12:00:00Z"
}); // "3 days ago"

formatISODate("2024-01-01T01:00:00Z", {
  timeZone: "America/Los_Angeles"
}); // "2023-12-31"

compareDateOnly("2024-03-09", "2024-03-10"); // -1
daysBetweenDateOnly("2024-02-28", "2024-03-01"); // 2 (leap year)

Date-only strings are treated as literal calendar dates. Date objects, timestamps, and date-time strings are converted in the requested IANA timezone, which defaults to UTC.

CLI usage

tiny-date validate 2024-02-29
# valid

tiny-date relative 2024-06-12T12:00:00Z --base 2024-06-15T12:00:00Z
# 3 days ago

tiny-date format 2024-01-01T01:00:00Z --time-zone America/Los_Angeles
# 2023-12-31

tiny-date compare 2024-03-09 2024-03-10
# -1

API

• isValidISODate(value) — validates exact YYYY-MM-DD calendar dates, including leap years.
• parseISODate(value) — parses a valid date-only string as midnight UTC; throws on invalid input.
• formatISODate(value, options?) — returns YYYY-MM-DD in options.timeZone (UTC by default).
• compareDateOnly(left, right, options?) — returns -1, 0, or 1 after timezone-safe normalization.
• daysBetweenDateOnly(start, end, options?) — counts calendar-day boundaries; can be negative.
• formatRelativeTime(value, options?) — formats relative time using Intl.RelativeTimeFormat. Options include baseDate, locale, numeric, and style.

License

MIT