@ix-xs/node-comfort 1.2.0 → 2.0.0

package/src/Time.js

@@ -1,338 +1,581 @@
+"use strict";
+
 /**
- * Date & time utilities.
- *
- * Parsing durations, human-friendly relative time ("3 hours ago"), duration
- * formatting, add/diff arithmetic and a tiny date formatter • with no
- * dependency on heavyweight date libraries.
- *
- * ### Internationalization & time zones
- *
- * `relative`, `formatDuration` and `format` are locale-aware and use the
- * platform's built-in `Intl` (full ICU ships with Node), so **every language
- * is supported out of the box** • no locale files, no dependencies.
- *
- * The default locale is `"en"` (for deterministic output). Change it globally
- * with {@link module:Time.setLocale}, or per call via an `options.locale`. A
- * time zone can be set globally with {@link module:Time.setTimezone} or passed
- * per call via `options.timeZone` (IANA name, e.g. `"Europe/Paris"`).
+ * Dates and durations: formatting, relative time, calendar math, time zones
+ * and scheduling, in any language `Intl` knows. The default language is
+ * English so results are the same on every machine; change it with
+ * `setLocale()` or per call with `{ locale }`. Time zones work the same way
+ * with `setTimezone()` or `{ timeZone }`.
  *
  * @example
- * nodeComfort.time.setLocale("fr").setTimezone("Europe/Paris");
- * nodeComfort.time.relative(Date.now() - 3600e3);        // "il y a 1 heure"
- * nodeComfort.time.format(Date.now(), "dddd D MMMM YYYY"); // "lundi 15 janvier 2024"
+ * time.setLocale("fr").setTimezone("Europe/Paris");
+ * time.relative(Date.now() - 3600e3);        // "il y a 1 heure"
+ * time.format(new Date(), "dddd D MMMM YYYY"); // "lundi 15 janvier 2024"
+ * time.cron("0 9 * * 1-5", sendReport);        // weekdays at 9:00
+ */
+
+const { types } = require("node:util");
+
+/**
+ * A date: a `Date`, a timestamp in ms, or a string `new Date()` understands
+ * (ISO 8601 is safest).
+ * @typedef {Date | number | string} DateInput
  */
 
 /**
- * The time module itself • used as the return type of the chainable setters so
- * `setLocale().setTimezone()...` stays fully typed without inlining the type.
- * @typedef {typeof import("./Time")} TimeModule
+ * A unit with a fixed length.
+ * @typedef {"ms" | "millisecond" | "milliseconds" | "s" | "sec" | "second" | "seconds" | "m" | "min" | "minute" | "minutes" | "h" | "hour" | "hours" | "d" | "day" | "days" | "w" | "week" | "weeks"} DurationUnit
  */
 
-const MS = {
-  ms: 1,
-  s: 1000,
-  m: 60_000,
-  h: 3_600_000,
-  d: 86_400_000,
-  w: 604_800_000,
-};
+/**
+ * A fixed unit, or months and years, whose length varies.
+ * @typedef {DurationUnit | "M" | "month" | "months" | "y" | "year" | "years"} CalendarUnit
+ */
+
+/**
+ * A unit for `startOf()` and `endOf()`.
+ * @typedef {"year" | "quarter" | "month" | "week" | "isoWeek" | "day" | "hour" | "minute" | "second"} StartOfUnit
+ */
+
+/**
+ * Options for `formatDuration()`.
+ * @typedef {object} FormatDurationOptions
+ * @property {boolean} [long] Full, translated words: `"1 hour 30 minutes"` instead of `"1h 30m"`.
+ * @property {number} [units] Show at most this many units, largest first: `units: 2` turns `"1d 3h 5m"` into `"1d 3h"`.
+ * @property {boolean} [clock] Clock style, like `"01:30:05"`.
+ * @property {boolean} [milliseconds] Show milliseconds. Defaults to `true`.
+ * @property {string} [locale] Language for `long`. Defaults to the global locale.
+ */
+
+/**
+ * Options for `relative()`.
+ * @typedef {object} RelativeOptions
+ * @property {string} [locale] Defaults to the global locale.
+ * @property {"always" | "auto"} [numeric] `"auto"` says `"yesterday"` instead of `"1 day ago"`. Defaults to `"always"`.
+ * @property {"long" | "short" | "narrow"} [style] `"short"` gives `"in 3 mo."`. Defaults to `"long"`.
+ */
+
+/**
+ * Options for `format()`.
+ * @typedef {object} FormatDateOptions
+ * @property {string} [locale] Language of month and day names. Defaults to the global locale.
+ * @property {string} [timeZone] Show the date in this zone, like `"Asia/Tokyo"`. Defaults to the global zone, then the system's.
+ */
+
+/**
+ * Options for `calendar()`.
+ * @typedef {object} CalendarOptions
+ * @property {string} [locale] Defaults to the global locale.
+ * @property {string} [timeZone] Defaults to the global zone, then the system's.
+ * @property {DateInput} [now] What "now" is. Defaults to the current time.
+ */
+
+/**
+ * Week settings.
+ * @typedef {object} WeekOptions
+ * @property {0 | 1 | 2 | 3 | 4 | 5 | 6} [weekStartsOn] First day of the week: `0` for Sunday, `1` for Monday. Defaults to `1`.
+ */
+
+/**
+ * Time zone setting.
+ * @typedef {object} TimeZoneOptions
+ * @property {string} [timeZone] Zone used to decide which day it is. Defaults to the global zone, then the system's.
+ */
+
+/**
+ * Options for `every()`.
+ * @typedef {object} EveryOptions
+ * @property {boolean} [immediate] Also run once right away.
+ * @property {boolean} [unref] Let the process exit even if the schedule is active.
+ * @property {(error: unknown) => void} [onError] Called when the task fails. Without it, errors surface as unhandled errors.
+ */
+
+/**
+ * Options for `cron()` and `nextRun()`.
+ * @typedef {object} CronOptions
+ * @property {string} [timeZone] Zone in which the expression is read, like `"Europe/Paris"`. Defaults to the global zone, then the system's.
+ * @property {DateInput} [from] `nextRun()` only: search after this date. Defaults to now.
+ * @property {boolean} [unref] Let the process exit even if the schedule is active.
+ * @property {boolean} [overlap] Start a run even if the previous one hasn't finished. By default it's skipped.
+ * @property {(error: unknown) => void} [onError] Called when the task fails.
+ */
+
+/**
+ * A schedule returned by `every()` and `cron()`.
+ * @typedef {object} ScheduledTask
+ * @property {() => void} stop Stops the schedule. A run in progress finishes.
+ * @property {() => Date | undefined} next When the next run is planned.
+ * @property {() => boolean} isRunning Whether a run is in progress.
+ * @property {() => number} runs How many runs have started.
+ */
+
+/**
+ * Returned by `stopwatch()`.
+ * @typedef {object} Stopwatch
+ * @property {() => number} elapsed Milliseconds since the start.
+ * @property {(format?: boolean) => number | string} stop The elapsed time; `stop(true)` formats it, like `"1.5s"`.
+ * @property {(label?: string) => number} lap Records a lap and returns the ms since the previous one.
+ * @property {() => Array<{ label: string, ms: number, total: number }>} laps Every lap so far.
+ * @property {() => void} reset Starts over.
+ */
 
+const MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+
+/** @type {Record<string, keyof typeof MS | "M" | "y">} */
 const UNIT_ALIASES = {
-  ms: "ms", milli: "ms", millisecond: "ms", milliseconds: "ms",
+  ms: "ms", msec: "ms", milli: "ms", millis: "ms", millisecond: "ms", milliseconds: "ms",
   s: "s", sec: "s", secs: "s", second: "s", seconds: "s",
   m: "m", min: "m", mins: "m", minute: "m", minutes: "m",
   h: "h", hr: "h", hrs: "h", hour: "h", hours: "h",
   d: "d", day: "d", days: "d",
-  w: "w", week: "w", weeks: "w",
+  w: "w", wk: "w", wks: "w", week: "w", weeks: "w",
+  M: "M", mo: "M", month: "M", months: "M",
+  y: "y", yr: "y", yrs: "y", year: "y", years: "y",
 };
 
-/**
- * Global defaults for locale-aware formatting. `locale` defaults to `"en"` so
- * output is deterministic regardless of the host machine; `timeZone`
- * `undefined` means the system local zone.
- * @private
- * @type {{ locale: string, timeZone: string|undefined }}
- */
-const _config = { locale: "en", timeZone: undefined };
+/** Global defaults. English by default so output never depends on the machine. */
+const _config = { locale: "en", timeZone: /** @type {string | undefined} */ (undefined) };
 
 /**
- * Coerces a value into a Date.
- * @private
- * @param {Date|number|string} [value]
+ * @param {DateInput | undefined} value
  * @returns {Date}
  */
-const _toDate = (value) => (value instanceof Date ? new Date(value.getTime()) : value === undefined ? new Date() : new Date(value));
+const _toDate = (value) => (types.isDate(value) ? new Date(value.getTime()) : value === undefined ? new Date() : new Date(value));
 
+/**
+ * @param {number} n
+ * @param {number} [len=2]
+ */
 const _pad = (n, len = 2) => String(Math.abs(n)).padStart(len, "0");
 
 /**
- * Extracts numeric calendar parts of a date, optionally in a target time zone.
- * When no zone is given, the host's local time is used (fast path).
- * @private
- * @param {Date} d - Date to read.
- * @param {string} [timeZone] - IANA time-zone name.
- * @returns {{ year: number, month: number, day: number, hour: number, minute: number, second: number, ms: number }}
+ * @param {string} unit
+ * @returns {keyof typeof MS | "M" | "y" | undefined}
  */
-const _numericParts = (d, timeZone) => {
+const _unit = (unit) => UNIT_ALIASES[unit] ?? UNIT_ALIASES[unit.toLowerCase()];
+
+/** @type {Map<string, Intl.DateTimeFormat>} */
+const _dtfCache = new Map();
+
+/**
+ * Calendar parts of a date in a time zone.
+ * @param {Date} d
+ * @param {string} [timeZone]
+ * @returns {{ year: number, month: number, day: number, hour: number, minute: number, second: number, ms: number, weekday: number }}
+ */
+const _parts = (d, timeZone) => {
   if (!timeZone) {
     return {
-      year: d.getFullYear(),
-      month: d.getMonth() + 1,
-      day: d.getDate(),
-      hour: d.getHours(),
-      minute: d.getMinutes(),
-      second: d.getSeconds(),
-      ms: d.getMilliseconds(),
+      year: d.getFullYear(), month: d.getMonth() + 1, day: d.getDate(), hour: d.getHours(),
+      minute: d.getMinutes(), second: d.getSeconds(), ms: d.getMilliseconds(), weekday: d.getDay(),
     };
   }
-  const dtf = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-    hour: "2-digit",
-    minute: "2-digit",
-    second: "2-digit",
-    hourCycle: "h23",
-  });
-  const parts = {};
-  for (const p of dtf.formatToParts(d)) parts[p.type] = p.value;
+  let dtf = _dtfCache.get(timeZone);
+  if (!dtf) {
+    dtf = new Intl.DateTimeFormat("en-US", {
+      timeZone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit",
+      minute: "2-digit", second: "2-digit", hourCycle: "h23", weekday: "short",
+    });
+    _dtfCache.set(timeZone, dtf);
+  }
+  /** @type {Record<string, string>} */
+  const p = {};
+  for (const part of dtf.formatToParts(d)) p[part.type] = part.value;
   return {
-    year: +parts.year,
-    month: +parts.month,
-    day: +parts.day,
-    hour: +parts.hour,
-    minute: +parts.minute,
-    second: +parts.second,
-    ms: d.getMilliseconds(),
+    year: Number(p.year), month: Number(p.month), day: Number(p.day), hour: Number(p.hour) % 24,
+    minute: Number(p.minute), second: Number(p.second), ms: d.getMilliseconds(),
+    weekday: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"].indexOf(p.weekday),
+  };
+};
+
+/**
+ * UTC offset of a zone at an instant, in minutes.
+ * @param {Date} d
+ * @param {string} [timeZone]
+ * @returns {number}
+ */
+const _offset = (d, timeZone) => {
+  if (!timeZone) return -d.getTimezoneOffset();
+  const p = _parts(d, timeZone);
+  const asUTC = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second, p.ms);
+  return Math.round((asUTC - d.getTime()) / 60_000);
+};
+
+/**
+ * Wall-clock time in a zone to an instant. `undefined` when that time is
+ * skipped by a daylight-saving change.
+ * @param {number} year
+ * @param {number} month 1-12
+ * @param {number} day
+ * @param {number} hour
+ * @param {number} minute
+ * @param {number} second
+ * @param {string} [timeZone]
+ * @returns {Date | undefined}
+ */
+const _fromWall = (year, month, day, hour, minute, second, timeZone) => {
+  const guess = Date.UTC(year, month - 1, day, hour, minute, second);
+  let instant = guess - _offset(new Date(guess), timeZone) * 60_000;
+  const second2 = guess - _offset(new Date(instant), timeZone) * 60_000;
+  if (second2 !== instant) instant = second2;
+  const p = _parts(new Date(instant), timeZone);
+  if (p.year !== year || p.month !== month || p.day !== day || p.hour !== hour || p.minute !== minute) return undefined;
+  return new Date(instant);
+};
+
+/**
+ * @param {number} year
+ * @param {number} month 1-12
+ */
+const _daysIn = (year, month) => new Date(Date.UTC(year, month, 0)).getUTCDate();
+
+/**
+ * Adds calendar months, keeping the day in range (Jan 31 + 1 month = end of Feb).
+ * @param {Date} d
+ * @param {number} months
+ * @returns {Date}
+ */
+const _addMonths = (d, months) => {
+  const out = new Date(d.getTime());
+  const day = out.getDate();
+  out.setDate(1);
+  out.setMonth(out.getMonth() + months);
+  out.setDate(Math.min(day, _daysIn(out.getFullYear(), out.getMonth() + 1)));
+  return out;
+};
+
+/**
+ * `setTimeout` that also works past its 24.8-day limit.
+ * @param {() => void} fn
+ * @param {number} ms
+ * @param {boolean} unref
+ * @returns {() => void}
+ */
+const _longTimeout = (fn, ms, unref) => {
+  const MAX = 2 ** 31 - 1;
+  /** @type {NodeJS.Timeout} */
+  let timer;
+  const schedule = (/** @type {number} */ remaining) => {
+    timer = setTimeout(() => (remaining > MAX ? schedule(remaining - MAX) : fn()), Math.min(remaining, MAX));
+    if (unref) timer.unref();
   };
+  schedule(Math.max(0, ms));
+  return () => clearTimeout(timer);
+};
+
+/**
+ * @param {() => unknown} task
+ * @param {((error: unknown) => void) | undefined} onError
+ * @returns {Promise<void>}
+ */
+const _run = async (task, onError) => {
+  try {
+    await task();
+  } catch (error) {
+    if (onError) onError(error);
+    else setImmediate(() => { throw error; });
+  }
 };
 
 /**
- * Formats a single localized component (month/weekday name) via `Intl`.
- * @private
- * @param {Date} d - Date to format.
- * @param {Intl.DateTimeFormatOptions} opt - Component options.
- * @param {string} locale - BCP-47 locale.
- * @param {string} [timeZone] - IANA time-zone name.
+ * Sets the default language for `relative`, `calendar`, `formatDuration`
+ * and `format`.
+ *
+ * @example
+ * time.setLocale("fr");
+ * time.relative(Date.now() - 60e3); // "il y a 1 minute"
+ *
+ * @param {string} locale Like `"fr"`, `"en-GB"`, `"pt-BR"` or `"ja"`.
+ * @returns {typeof import("./Time")} The module, so calls chain.
+ */
+function setLocale(locale) {
+  _config.locale = locale;
+  return module.exports;
+}
+
+/**
+ * Sets the default time zone for `format`, `calendar`, `isSameDay`,
+ * `cron`... Pass `undefined` to go back to the system zone.
+ *
+ * @example
+ * time.setTimezone("Europe/Paris");
+ *
+ * @param {string | undefined} timeZone Like `"America/New_York"`.
+ * @returns {typeof import("./Time")} The module, so calls chain.
+ * @throws {RangeError} If the zone doesn't exist.
+ */
+function setTimezone(timeZone) {
+  if (timeZone !== undefined) new Intl.DateTimeFormat("en-US", { timeZone });
+  _config.timeZone = timeZone;
+  return module.exports;
+}
+
+/**
+ * The current defaults.
+ *
+ * @example
+ * time.getConfig(); // { locale: "en", timeZone: undefined }
+ *
+ * @returns {{ locale: string, timeZone: string | undefined }}
+ */
+function getConfig() {
+  return { ..._config };
+}
+
+/**
+ * Every time zone Node knows, sorted.
+ *
+ * @example
+ * time.timezones().includes("Europe/Paris"); // true
+ *
+ * @returns {string[]}
+ */
+function timezones() {
+  return Intl.supportedValuesOf("timeZone");
+}
+
+/**
+ * A zone's UTC offset at a given date, in minutes. Daylight saving included.
+ *
+ * @example
+ * time.offset("Europe/Paris", "2024-07-01"); // 120
+ * time.offset("Europe/Paris", "2024-01-01"); // 60
+ *
+ * @param {string} [timeZone] Defaults to the global zone, then the system's.
+ * @param {DateInput} [date] Defaults to now.
+ * @returns {number}
+ */
+function offset(timeZone, date) {
+  return _offset(_toDate(date), timeZone ?? _config.timeZone);
+}
+
+/**
+ * Turns a duration into milliseconds. Understands `"1h30m"`, `"2 days"`,
+ * `"500ms"`, clock times like `"01:30:00"`, ISO durations like `"PT1H30M"`,
+ * and plain numbers. Months and years are refused because their length
+ * varies; use `add()` for those.
+ *
+ * @example
+ * time.parseDuration("1h30m");    // 5400000
+ * time.parseDuration("01:30:00"); // 5400000
+ * time.parseDuration("banana");   // null
+ *
+ * @param {string | number} input
+ * @returns {number | null} `null` when it isn't a duration.
+ */
+function parseDuration(input) {
+  if (typeof input === "number") return Number.isFinite(input) ? input : null;
+  if (typeof input !== "string") return null;
+  const text = input.trim();
+  if (!text) return null;
+  if (/^[-+]?\d+(?:\.\d+)?$/.test(text)) return Number(text);
+
+  const iso = /^([-+])?P(?:(\d+(?:[.,]\d+)?)W)?(?:(\d+(?:[.,]\d+)?)D)?(?:T(?:(\d+(?:[.,]\d+)?)H)?(?:(\d+(?:[.,]\d+)?)M)?(?:(\d+(?:[.,]\d+)?)S)?)?$/i.exec(text);
+  if (iso && /\d/.test(text)) {
+    const [, sign, w, d, h, m, s] = iso;
+    const n = (/** @type {string | undefined} */ v) => (v ? Number(v.replace(",", ".")) : 0);
+    const total = n(w) * MS.w + n(d) * MS.d + n(h) * MS.h + n(m) * MS.m + n(s) * MS.s;
+    return sign === "-" ? -total : total;
+  }
+
+  const clock = /^([-+])?(?:(\d+):)?(\d+):(\d{1,2})(?:\.(\d{1,3}))?$/.exec(text);
+  if (clock) {
+    const [, sign, h, m, s, ms] = clock;
+    const total = Number(h ?? 0) * MS.h + Number(m) * MS.m + Number(s) * MS.s + (ms ? Number(ms.padEnd(3, "0")) : 0);
+    return sign === "-" ? -total : total;
+  }
+
+  const regex = /(-?\d*\.?\d+)\s*([a-zA-Z]+)/g;
+  let total = 0;
+  let consumed = "";
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    const unit = _unit(match[2]);
+    if (!unit || unit === "M" || unit === "y") return null;
+    total += Number(match[1]) * MS[unit];
+    consumed += match[0];
+  }
+  if (!consumed || consumed.replace(/\s+/g, "") !== text.replace(/[\s,]+|and/g, "")) return null;
+  return total;
+}
+
+/**
+ * Writes a duration for humans.
+ *
+ * @example
+ * time.formatDuration(5_400_000);                               // "1h 30m"
+ * time.formatDuration(90_000, { long: true });                  // "1 minute 30 seconds"
+ * time.formatDuration(90_000, { long: true, locale: "fr" });    // "1 minute 30 secondes"
+ * time.formatDuration(93_784_000, { units: 2 });                // "1d 2h"
+ * time.formatDuration(5_405_000, { clock: true });              // "01:30:05"
+ *
+ * @param {number} ms
+ * @param {FormatDurationOptions} [options]
  * @returns {string}
  */
-const _named = (d, opt, locale, timeZone) =>
-  new Intl.DateTimeFormat(locale, { ...opt, timeZone }).format(d);
+function formatDuration(ms, options = {}) {
+  if (!Number.isFinite(ms)) return String(ms);
+  const sign = ms < 0 ? "-" : "";
+  let rest = Math.abs(Math.trunc(ms));
 
-module.exports = {
-  /**
-   * Sets the global default locale used by `relative`, `formatDuration` and
-   * `format` (named tokens). Chainable.
-   *
-   * @example
-   * nodeComfort.time.setLocale("fr");
-   *
-   * @param {string} locale - A BCP-47 locale tag (e.g. `"fr"`, `"en-GB"`, `"ja"`).
-   * @returns {TimeModule} The time module (for chaining).
-   */
-  setLocale(locale) {
-    _config.locale = locale;
-    return this;
-  },
-
-  /**
-   * Sets the global default time zone used by `format` and `isSameDay`.
-   * Chainable. Pass `undefined` to fall back to the system local zone.
-   *
-   * @example
-   * nodeComfort.time.setTimezone("Europe/Paris");
-   *
-   * @param {string|undefined} timeZone - An IANA time-zone name (e.g. `"America/New_York"`).
-   * @returns {TimeModule} The time module (for chaining).
-   */
-  setTimezone(timeZone) {
-    _config.timeZone = timeZone;
-    return this;
-  },
-
-  /**
-   * Returns the current global `{ locale, timeZone }` defaults.
-   *
-   * @returns {{ locale: string, timeZone: string|undefined }} A copy of the config.
-   */
-  getConfig() {
-    return { ..._config };
-  },
-
-  /**
-   * Parses a human duration string into milliseconds.
-   *
-   * Accepts things like `"1h"`, `"30m"`, `"1h30m"`, `"2 days"`, `"500ms"`.
-   * A plain number is treated as milliseconds.
-   *
-   * @example
-   * nodeComfort.time.parseDuration("1h30m"); // 5400000
-   * nodeComfort.time.parseDuration("2 days"); // 172800000
-   *
-   * @param {string|number} input - Duration string or millisecond count.
-   * @returns {number|null} Milliseconds, or null if it can't be parsed.
-   */
-  parseDuration(input) {
-    if (typeof input === "number") return input;
-    if (typeof input !== "string") return null;
-
-    const regex = /(-?\d*\.?\d+)\s*([a-z]+)/gi;
-    let total = 0;
-    let matched = false;
-    let match;
-    while ((match = regex.exec(input)) !== null) {
-      const value = parseFloat(match[1]);
-      const unit = UNIT_ALIASES[match[2].toLowerCase()];
-      if (!unit) return null;
-      total += value * MS[unit];
-      matched = true;
-    }
-    return matched ? total : null;
-  },
-
-  /**
-   * Formats a millisecond duration into a human string.
-   *
-   * The compact form (default) is language-neutral (`"1h 30m"`). The `long`
-   * form is fully localized through `Intl` • pass `options.locale` or set a
-   * global locale with {@link module:Time.setLocale}.
-   *
-   * @example
-   * nodeComfort.time.formatDuration(5400000);                       // "1h 30m"
-   * nodeComfort.time.formatDuration(90000, { long: true });         // "1 minute 30 seconds"
-   * nodeComfort.time.formatDuration(90000, { long: true, locale: "fr" }); // "1 minute 30 secondes"
-   *
-   * @param {number} ms - Duration in milliseconds.
-   * @param {{ long?: boolean, units?: number, locale?: string }} [options] - Formatting options (`units` caps how many parts show).
-   * @returns {string} The formatted duration.
-   */
-  formatDuration(ms, options = {}) {
-    const long = options.long ?? false;
-    const maxUnits = options.units ?? Infinity;
-    const locale = options.locale ?? _config.locale;
-    if (!Number.isFinite(ms)) return String(ms);
-    const sign = ms < 0 ? "-" : "";
-    ms = Math.abs(Math.trunc(ms));
-
-    const parts = [
-      { v: Math.floor(ms / MS.d), short: "d", unit: "day" },
-      { v: Math.floor((ms % MS.d) / MS.h), short: "h", unit: "hour" },
-      { v: Math.floor((ms % MS.h) / MS.m), short: "m", unit: "minute" },
-      { v: Math.floor((ms % MS.m) / MS.s), short: "s", unit: "second" },
-      { v: ms % MS.s, short: "ms", unit: "millisecond" },
-    ].filter((p) => p.v > 0);
-
-    if (!parts.length) {
-      return long
-        ? new Intl.NumberFormat(locale, { style: "unit", unit: "second", unitDisplay: "long" }).format(0)
-        : "0s";
-    }
+  if (options.clock) {
+    const d = Math.floor(rest / MS.d);
+    const h = Math.floor((rest % MS.d) / MS.h);
+    const m = Math.floor((rest % MS.h) / MS.m);
+    const s = Math.floor((rest % MS.m) / MS.s);
+    return `${sign}${d ? `${d}:${_pad(h)}` : _pad(h)}:${_pad(m)}:${_pad(s)}`;
+  }
 
-    return sign + parts
-      .slice(0, maxUnits)
-      .map((p) =>
-        long
-          ? new Intl.NumberFormat(locale, { style: "unit", unit: p.unit, unitDisplay: "long" }).format(p.v)
-          : `${p.v}${p.short}`,
-      )
-      .join(" ");
-  },
-
-  /**
-   * Returns a human-friendly, localized relative time string.
-   *
-   * Built on `Intl.RelativeTimeFormat`, so it speaks every language. Set
-   * `options.locale` (or a global locale) to translate; `options.numeric`
-   * controls wording (`"always"` → "1 day ago", `"auto"` → "yesterday").
-   *
-   * @example
-   * nodeComfort.time.relative(Date.now() - 3600e3);                 // "1 hour ago"
-   * nodeComfort.time.relative(Date.now() - 3600e3, undefined, { locale: "fr" }); // "il y a 1 heure"
-   * nodeComfort.time.relative(Date.now() - 86400e3, undefined, { numeric: "auto" }); // "yesterday"
-   *
-   * @param {Date|number|string} date - Target date.
-   * @param {Date|number|string} [from] - Reference date (defaults to now).
-   * @param {{ locale?: string, numeric?: "always"|"auto" }} [options] - Formatting options.
-   * @returns {string} The relative time string.
-   */
-  relative(date, from, options = {}) {
-    const locale = options.locale ?? _config.locale;
-    const numeric = options.numeric ?? "always";
-    const target = _toDate(date).getTime();
-    const base = _toDate(from).getTime();
-    const diff = target - base;
-    const abs = Math.abs(diff);
-
-    if (abs < MS.s) {
-      return new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(0, "second");
-    }
+  const locale = options.locale ?? _config.locale;
+  const showMs = options.milliseconds ?? true;
+  /** @type {Array<{ v: number, short: string, unit: string }>} */
+  const parts = [];
+  for (const [size, short, unit] of /** @type {Array<[number, string, string]>} */ ([[MS.d, "d", "day"], [MS.h, "h", "hour"], [MS.m, "m", "minute"], [MS.s, "s", "second"], [1, "ms", "millisecond"]])) {
+    const v = Math.floor(rest / size);
+    rest -= v * size;
+    if (v > 0 && (unit !== "millisecond" || showMs)) parts.push({ v, short, unit });
+  }
+  if (!parts.length) {
+    return options.long ? new Intl.NumberFormat(locale, { style: "unit", unit: "second", unitDisplay: "long" }).format(0) : "0s";
+  }
+  return sign + parts
+    .slice(0, options.units ?? Infinity)
+    .map((p) => (options.long ? new Intl.NumberFormat(locale, { style: "unit", unit: p.unit, unitDisplay: "long" }).format(p.v) : `${p.v}${p.short}`))
+    .join(" ");
+}
 
-    const units = [
-      { limit: MS.m, div: MS.s, name: "second" },
-      { limit: MS.h, div: MS.m, name: "minute" },
-      { limit: MS.d, div: MS.h, name: "hour" },
-      { limit: MS.w, div: MS.d, name: "day" },
-      { limit: MS.d * 30, div: MS.w, name: "week" },
-      { limit: MS.d * 365, div: MS.d * 30, name: "month" },
-      { limit: Infinity, div: MS.d * 365, name: "year" },
-    ];
-
-    const rtf = new Intl.RelativeTimeFormat(locale, { numeric });
-    for (const unit of units) {
-      if (abs < unit.limit) {
-        const value = Math.floor(abs / unit.div);
-        return rtf.format(diff < 0 ? -value : value, /** @type {Intl.RelativeTimeFormatUnit} */ (unit.name));
-      }
+/**
+ * Describes a date relative to now: `"3 hours ago"`, `"in 2 days"`, in
+ * any language.
+ *
+ * @example
+ * time.relative(Date.now() - 3_600_000);                                  // "1 hour ago"
+ * time.relative(Date.now() - 86_400_000, undefined, { numeric: "auto" }); // "yesterday"
+ * time.relative(Date.now() - 3_600_000, undefined, { locale: "fr" });     // "il y a 1 heure"
+ *
+ * @param {DateInput} date
+ * @param {DateInput} [from] Compare with this date instead of now.
+ * @param {RelativeOptions} [options]
+ * @returns {string}
+ */
+function relative(date, from, options = {}) {
+  const locale = options.locale ?? _config.locale;
+  const diffMs = _toDate(date).getTime() - _toDate(from).getTime();
+  const abs = Math.abs(diffMs);
+  if (abs < MS.s) return new Intl.RelativeTimeFormat(locale, { numeric: "auto", style: options.style ?? "long" }).format(0, "second");
+  /** @type {Array<[number, number, Intl.RelativeTimeFormatUnit]>} */
+  const scale = [
+    [MS.m, MS.s, "second"], [MS.h, MS.m, "minute"], [MS.d, MS.h, "hour"], [MS.w, MS.d, "day"],
+    [MS.d * 30, MS.w, "week"], [MS.d * 365, MS.d * 30, "month"], [Infinity, MS.d * 365, "year"],
+  ];
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: options.numeric ?? "always", style: options.style ?? "long" });
+  for (const [limit, size, unit] of scale) {
+    if (abs < limit) {
+      const value = Math.floor(abs / size);
+      return rtf.format(diffMs < 0 ? -value : value, unit);
     }
-    return rtf.format(0, "second");
-  },
-
-  /**
-   * Formats a date using a small token syntax, with optional locale & time zone.
-   *
-   * **Numeric tokens:** `YYYY` `YY` `MM` `M` `DD` `D` `HH` `H` (24h) `hh` `h`
-   * (12h) `mm` `m` `ss` `s` `SSS`.
-   * **Localized tokens:** `MMMM` (month name) `MMM` (short month) `dddd` (weekday)
-   * `ddd` (short weekday) `A` (AM/PM) `a` (am/pm).
-   *
-   * Wrap literal text in square brackets to keep it verbatim: `"[Today is] dddd"`.
-   *
-   * @example
-   * nodeComfort.time.format(new Date(), "YYYY-MM-DD HH:mm:ss");
-   * nodeComfort.time.format(Date.now(), "dddd D MMMM YYYY", { locale: "fr" });
-   * nodeComfort.time.format(Date.now(), "HH:mm", { timeZone: "Asia/Tokyo" });
-   *
-   * @param {Date|number|string} date - Date to format.
-   * @param {string} [pattern="YYYY-MM-DD HH:mm:ss"] - Format pattern.
-   * @param {{ locale?: string, timeZone?: string }} [options] - Locale / time-zone overrides.
-   * @returns {string} The formatted date.
-   */
-  format(date, pattern = "YYYY-MM-DD HH:mm:ss", options = {}) {
-    const d = _toDate(date);
-    if (Number.isNaN(d.getTime())) return "Invalid Date";
-
-    const locale = options.locale ?? _config.locale;
-    const timeZone = options.timeZone ?? _config.timeZone;
-    const p = _numericParts(d, timeZone);
-
-    const replacer = (token, escaped) => {
+  }
+  return rtf.format(0, "second");
+}
+
+/**
+ * Describes a date like a chat app does: `"Today at 2:30 PM"`,
+ * `"Yesterday at 9:05 AM"`, a weekday for the coming days, and the full date
+ * beyond that.
+ *
+ * @example
+ * time.calendar(new Date());                     // "Today at 2:30 PM"
+ * time.calendar(yesterday, { locale: "fr" });    // "Hier à 09:05"
+ *
+ * @param {DateInput} date
+ * @param {CalendarOptions} [options]
+ * @returns {string}
+ */
+function calendar(date, options = {}) {
+  const locale = options.locale ?? _config.locale;
+  const timeZone = options.timeZone ?? _config.timeZone;
+  const d = _toDate(date);
+  const now = _toDate(options.now);
+  const p = _parts(d, timeZone);
+  const n = _parts(now, timeZone);
+  const dayIndex = (/** @type {{ year: number, month: number, day: number }} */ x) => Date.UTC(x.year, x.month - 1, x.day) / MS.d;
+  const delta = dayIndex(p) - dayIndex(n);
+  const hhmm = new Intl.DateTimeFormat(locale, { timeStyle: "short", timeZone }).format(d);
+  const at = (/** @type {string} */ label) => {
+    const joined = new Intl.DateTimeFormat(locale, { dateStyle: "full", timeStyle: "short", timeZone }).formatToParts(d);
+    const literal = joined.find((part, i) => part.type === "literal" && joined[i + 1]?.type === "hour")?.value ?? " ";
+    return `${label.charAt(0).toUpperCase()}${label.slice(1)}${literal}${hhmm}`;
+  };
+  if (Math.abs(delta) <= 1) {
+    return at(new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(delta, "day"));
+  }
+  if (delta > 1 && delta < 7) {
+    return at(new Intl.DateTimeFormat(locale, { weekday: "long", timeZone }).format(d));
+  }
+  return new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone }).format(d);
+}
+
+/**
+ * Formats a date with tokens, in any language and time zone.
+ *
+ * | Token | Output | | Token | Output |
+ * | --- | --- | --- | --- | --- |
+ * | `YYYY` / `YY` | 2024 / 24 | | `HH` / `H` | 09 / 9 (24h) |
+ * | `Q` | quarter, 1-4 | | `hh` / `h` | 09 / 9 (12h) |
+ * | `MMMM` / `MMM` | January / Jan | | `mm` / `m` | 05 / 5 |
+ * | `MM` / `M` | 01 / 1 | | `ss` / `s` | 07 / 7 |
+ * | `DD` / `D` | 05 / 5 | | `SSS` | 042 (ms) |
+ * | `dddd` / `ddd` | Monday / Mon | | `A` / `a` | PM / pm |
+ * | `d` | weekday, 0 is Sunday | | `Z` / `ZZ` | +02:00 / +0200 |
+ * | `W` / `WW` | ISO week | | `X` / `x` | Unix seconds / ms |
+ *
+ * Text in brackets stays as is: `"[Today is] dddd"`.
+ *
+ * @example
+ * time.format(new Date(), "YYYY-MM-DD HH:mm:ss");                  // "2024-01-15 14:30:05"
+ * time.format(Date.now(), "dddd D MMMM YYYY", { locale: "fr" });    // "lundi 15 janvier 2024"
+ * time.format(Date.now(), "HH:mm Z", { timeZone: "Asia/Tokyo" });   // "22:30 +09:00"
+ *
+ * @param {DateInput} date
+ * @param {string} [pattern="YYYY-MM-DD HH:mm:ss"]
+ * @param {FormatDateOptions} [options]
+ * @returns {string} Or `"Invalid Date"`.
+ */
+function format(date, pattern = "YYYY-MM-DD HH:mm:ss", options = {}) {
+  const d = _toDate(date);
+  if (Number.isNaN(d.getTime())) return "Invalid Date";
+  const locale = options.locale ?? _config.locale;
+  const timeZone = options.timeZone ?? _config.timeZone;
+  const p = _parts(d, timeZone);
+  const named = (/** @type {Intl.DateTimeFormatOptions} */ opt) => new Intl.DateTimeFormat(locale, { ...opt, timeZone }).format(d);
+  const tz = (/** @type {string} */ sep) => {
+    const off = _offset(d, timeZone);
+    return `${off < 0 ? "-" : "+"}${_pad(Math.floor(Math.abs(off) / 60))}${sep}${_pad(Math.abs(off) % 60)}`;
+  };
+  const h12 = p.hour % 12 === 0 ? 12 : p.hour % 12;
+  const isoWeek = () => weekOfYear(Date.UTC(p.year, p.month - 1, p.day), { utc: true });
+
+  return pattern.replace(
+    /\[([^\]]*)\]|YYYY|MMMM|dddd|SSS|MMM|ddd|YY|MM|DD|HH|hh|mm|ss|ZZ|WW|M|D|d|H|h|m|s|A|a|Z|Q|X|x|W/g,
+    (token, escaped) => {
       if (escaped !== undefined) return escaped;
       switch (token) {
         case "YYYY": return String(p.year);
         case "YY": return String(p.year).slice(-2);
-        case "MMMM": return _named(d, { month: "long" }, locale, timeZone);
-        case "MMM": return _named(d, { month: "short" }, locale, timeZone);
+        case "Q": return String(Math.ceil(p.month / 3));
+        case "MMMM": return named({ month: "long" });
+        case "MMM": return named({ month: "short" });
         case "MM": return _pad(p.month);
         case "M": return String(p.month);
         case "DD": return _pad(p.day);
         case "D": return String(p.day);
-        case "dddd": return _named(d, { weekday: "long" }, locale, timeZone);
-        case "ddd": return _named(d, { weekday: "short" }, locale, timeZone);
+        case "dddd": return named({ weekday: "long" });
+        case "ddd": return named({ weekday: "short" });
+        case "d": return String(p.weekday);
         case "HH": return _pad(p.hour);
         case "H": return String(p.hour);
-        case "hh": return _pad(p.hour % 12 === 0 ? 12 : p.hour % 12);
-        case "h": return String(p.hour % 12 === 0 ? 12 : p.hour % 12);
+        case "hh": return _pad(h12);
+        case "h": return String(h12);
         case "mm": return _pad(p.minute);
         case "m": return String(p.minute);
         case "ss": return _pad(p.second);
@@ -340,146 +583,741 @@ module.exports = {
         case "SSS": return _pad(p.ms, 3);
         case "A": return p.hour < 12 ? "AM" : "PM";
         case "a": return p.hour < 12 ? "am" : "pm";
+        case "Z": return tz(":");
+        case "ZZ": return tz("");
+        case "X": return String(Math.floor(d.getTime() / 1000));
+        case "x": return String(d.getTime());
+        case "W": return String(isoWeek());
+        case "WW": return _pad(isoWeek());
         default: return token;
       }
-    };
+    },
+  );
+}
+
+/**
+ * The date as `YYYY-MM-DD`, the format `<input type="date">` and most APIs
+ * expect.
+ *
+ * @example
+ * time.toISODate(new Date(2024, 0, 5)); // "2024-01-05"
+ *
+ * @param {DateInput} [date] Defaults to now.
+ * @param {TimeZoneOptions} [options]
+ * @returns {string}
+ */
+function toISODate(date, options = {}) {
+  return format(date ?? new Date(), "YYYY-MM-DD", { timeZone: options.timeZone ?? _config.timeZone });
+}
+
+/**
+ * Adds time to a date and returns a new `Date`. Months and years follow the
+ * calendar: January 31 plus one month is the end of February.
+ *
+ * @example
+ * time.add(new Date(), "2h30m");
+ * time.add(new Date(), 3, "days");
+ * time.add(new Date(2024, 0, 31), 1, "month"); // 2024-02-29
+ *
+ * @param {DateInput} date
+ * @param {number | string} amount A number with `unit`, or a duration like `"1h30m"`.
+ * @param {CalendarUnit} [unit="ms"]
+ * @returns {Date}
+ */
+function add(date, amount, unit = "ms") {
+  const d = _toDate(date);
+  if (typeof amount === "string") return new Date(d.getTime() + (parseDuration(amount) ?? 0));
+  const u = _unit(unit) ?? "ms";
+  if (u === "M") return _addMonths(d, amount);
+  if (u === "y") return _addMonths(d, amount * 12);
+  return new Date(d.getTime() + amount * MS[u]);
+}
+
+/**
+ * Subtracts time from a date and returns a new `Date`.
+ *
+ * @example
+ * time.subtract(new Date(), 7, "days");
+ * time.subtract(new Date(), "90m");
+ *
+ * @param {DateInput} date
+ * @param {number | string} amount
+ * @param {CalendarUnit} [unit="ms"]
+ * @returns {Date}
+ */
+function subtract(date, amount, unit = "ms") {
+  if (typeof amount === "string") return add(date, -(parseDuration(amount) ?? 0));
+  return add(date, -amount, unit);
+}
+
+/**
+ * `a - b` in a unit. Fixed units can give fractions; months and years are
+ * whole calendar months and years.
+ *
+ * @example
+ * time.diff("2024-01-03", "2024-01-01", "days");   // 2
+ * time.diff("2024-03-15", "2024-01-20", "months"); // 1
+ *
+ * @param {DateInput} a
+ * @param {DateInput} b
+ * @param {CalendarUnit} [unit="ms"]
+ * @returns {number}
+ */
+function diff(a, b, unit = "ms") {
+  const da = _toDate(a);
+  const db = _toDate(b);
+  const u = _unit(unit) ?? "ms";
+  if (u === "M" || u === "y") {
+    const sign = da >= db ? 1 : -1;
+    const [late, early] = sign > 0 ? [da, db] : [db, da];
+    let months = (late.getFullYear() - early.getFullYear()) * 12 + late.getMonth() - early.getMonth();
+    if (_addMonths(early, months) > late) months--;
+    return sign * (u === "y" ? Math.trunc(months / 12) : months) || 0;
+  }
+  return (da.getTime() - db.getTime()) / MS[u];
+}
+
+/**
+ * A new `Date` at the start of the day, week, month... in local time.
+ *
+ * @example
+ * time.startOf(new Date(), "day");                         // today at 00:00
+ * time.startOf(new Date(), "week");                        // Monday at 00:00
+ * time.startOf(new Date(), "week", { weekStartsOn: 0 });   // Sunday at 00:00
+ *
+ * @param {DateInput} date
+ * @param {StartOfUnit} unit
+ * @param {WeekOptions} [options]
+ * @returns {Date}
+ */
+function startOf(date, unit, options = {}) {
+  const d = _toDate(date);
+  switch (unit) {
+    case "year":
+      d.setMonth(0, 1);
+      d.setHours(0, 0, 0, 0);
+      break;
+    case "quarter":
+      d.setMonth(Math.floor(d.getMonth() / 3) * 3, 1);
+      d.setHours(0, 0, 0, 0);
+      break;
+    case "month":
+      d.setDate(1);
+      d.setHours(0, 0, 0, 0);
+      break;
+    case "week":
+    case "isoWeek": {
+      const start = unit === "isoWeek" ? 1 : options.weekStartsOn ?? 1;
+      d.setDate(d.getDate() - ((d.getDay() - start + 7) % 7));
+      d.setHours(0, 0, 0, 0);
+      break;
+    }
+    case "day":
+      d.setHours(0, 0, 0, 0);
+      break;
+    case "hour":
+      d.setMinutes(0, 0, 0);
+      break;
+    case "minute":
+      d.setSeconds(0, 0);
+      break;
+    case "second":
+      d.setMilliseconds(0);
+      break;
+  }
+  return d;
+}
+
+/**
+ * A new `Date` at the last millisecond of the day, week, month...
+ *
+ * @example
+ * time.endOf(new Date(), "month"); // last day of the month, 23:59:59.999
+ *
+ * @param {DateInput} date
+ * @param {StartOfUnit} unit
+ * @param {WeekOptions} [options]
+ * @returns {Date}
+ */
+function endOf(date, unit, options = {}) {
+  const start = startOf(date, unit, options);
+  /** @type {Date} */
+  let next;
+  switch (unit) {
+    case "year": next = _addMonths(start, 12); break;
+    case "quarter": next = _addMonths(start, 3); break;
+    case "month": next = _addMonths(start, 1); break;
+    case "week":
+    case "isoWeek": next = new Date(start); next.setDate(next.getDate() + 7); break;
+    case "day": next = new Date(start); next.setDate(next.getDate() + 1); break;
+    case "hour": next = new Date(start.getTime() + MS.h); break;
+    case "minute": next = new Date(start.getTime() + MS.m); break;
+    default: next = new Date(start.getTime() + MS.s); break;
+  }
+  return new Date(next.getTime() - 1);
+}
+
+/**
+ * Is `a` before `b`?
+ *
+ * @param {DateInput} a
+ * @param {DateInput} b
+ * @returns {boolean}
+ */
+function isBefore(a, b) {
+  return _toDate(a).getTime() < _toDate(b).getTime();
+}
+
+/**
+ * Is `a` after `b`?
+ *
+ * @example
+ * if (time.isAfter(expiresAt, Date.now())) grantAccess();
+ *
+ * @param {DateInput} a
+ * @param {DateInput} b
+ * @returns {boolean}
+ */
+function isAfter(a, b) {
+  return _toDate(a).getTime() > _toDate(b).getTime();
+}
+
+/**
+ * Is the date between `start` and `end`, both included?
+ *
+ * @param {DateInput} date
+ * @param {DateInput} start
+ * @param {DateInput} end
+ * @returns {boolean}
+ */
+function isBetween(date, start, end) {
+  const t = _toDate(date).getTime();
+  return t >= _toDate(start).getTime() && t <= _toDate(end).getTime();
+}
+
+/**
+ * Are both dates on the same calendar day?
+ *
+ * @example
+ * time.isSameDay(a, b);                            // local time
+ * time.isSameDay(a, b, { timeZone: "Asia/Tokyo" }); // as seen in Tokyo
+ *
+ * @param {DateInput} a
+ * @param {DateInput} b
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+function isSameDay(a, b, options = {}) {
+  const timeZone = options.timeZone ?? _config.timeZone;
+  const pa = _parts(_toDate(a), timeZone);
+  const pb = _parts(_toDate(b), timeZone);
+  return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
+}
+
+/**
+ * Is the date today?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+function isToday(date, options = {}) {
+  return isSameDay(date, new Date(), options);
+}
+
+/**
+ * Was the date yesterday?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+function isYesterday(date, options = {}) {
+  return isSameDay(date, add(new Date(), -1, "d"), options);
+}
+
+/**
+ * Is the date tomorrow?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+function isTomorrow(date, options = {}) {
+  return isSameDay(date, add(new Date(), 1, "d"), options);
+}
+
+/**
+ * Is it a Saturday or a Sunday?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+function isWeekend(date, options = {}) {
+  const day = _parts(_toDate(date), options.timeZone ?? _config.timeZone).weekday;
+  return day === 0 || day === 6;
+}
+
+/**
+ * Is it a leap year?
+ *
+ * @example
+ * time.isLeapYear(2024); // true
+ * time.isLeapYear(1900); // false
+ *
+ * @param {number | DateInput} yearOrDate A year (1000 to 9999) or a date.
+ * @returns {boolean}
+ */
+function isLeapYear(yearOrDate) {
+  const year = typeof yearOrDate === "number" && yearOrDate >= 1000 && yearOrDate <= 9999 ? yearOrDate : _toDate(yearOrDate).getFullYear();
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+/**
+ * Is it a real date, or something that parses to one?
+ *
+ * @example
+ * time.isValid("2024-02-29"); // true
+ * time.isValid("2024-02-30"); // false
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isValid(value) {
+  if (types.isDate(value)) return !Number.isNaN(value.getTime());
+  if (typeof value === "string") {
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+    if (m && Number(m[3]) > _daysIn(Number(m[1]), Number(m[2]))) return false;
+  }
+  if (typeof value !== "string" && typeof value !== "number") return false;
+  return !Number.isNaN(new Date(value).getTime());
+}
+
+/**
+ * Number of days in a month.
+ *
+ * @example
+ * time.daysInMonth(new Date(2024, 1)); // 29
+ * time.daysInMonth(2023, 2);           // 28
+ *
+ * @param {DateInput | number} dateOrYear A date, or a year when you pass `month`.
+ * @param {number} [month] 1 to 12.
+ * @returns {number}
+ */
+function daysInMonth(dateOrYear, month) {
+  if (typeof dateOrYear === "number" && month !== undefined) return _daysIn(dateOrYear, month);
+  const d = _toDate(dateOrYear);
+  return _daysIn(d.getFullYear(), d.getMonth() + 1);
+}
+
+/**
+ * Day of the year, from 1 to 366.
+ *
+ * @param {DateInput} [date] Defaults to now.
+ * @returns {number}
+ */
+function dayOfYear(date) {
+  const d = _toDate(date);
+  return Math.round((Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) - Date.UTC(d.getFullYear(), 0, 1)) / MS.d) + 1;
+}
+
+/**
+ * ISO week number, from 1 to 53. Weeks start on Monday, and week 1 holds
+ * the year's first Thursday.
+ *
+ * @example
+ * time.weekOfYear(new Date(2021, 0, 3)); // 53, the last week of 2020
+ *
+ * @param {DateInput} [date] Defaults to now.
+ * @param {{ utc?: boolean }} [options] Read the date in UTC.
+ * @returns {number}
+ */
+function weekOfYear(date, options = {}) {
+  const d = _toDate(date);
+  const utc = options.utc
+    ? new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))
+    : new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+  const day = utc.getUTCDay() || 7;
+  utc.setUTCDate(utc.getUTCDate() + 4 - day);
+  const yearStart = Date.UTC(utc.getUTCFullYear(), 0, 1);
+  return Math.ceil(((utc.getTime() - yearStart) / MS.d + 1) / 7);
+}
+
+/**
+ * The earliest date.
+ *
+ * @param {Iterable<DateInput>} dates
+ * @returns {Date | undefined}
+ */
+function min(dates) {
+  /** @type {Date | undefined} */
+  let best;
+  for (const value of dates) {
+    const d = _toDate(value);
+    if (!best || d < best) best = d;
+  }
+  return best;
+}
 
-    return pattern.replace(
-      /\[([^\]]*)\]|YYYY|MMMM|dddd|SSS|MMM|ddd|YY|MM|DD|HH|hh|mm|ss|M|D|H|h|m|s|A|a/g,
-      replacer,
-    );
-  },
-
-  /**
-   * Adds a duration to a date and returns a new Date.
-   *
-   * The duration may be a millisecond number or a string like `"1h30m"`.
-   *
-   * @example
-   * nodeComfort.time.add(new Date(), "2h");
-   * nodeComfort.time.add(new Date(), -1, "days");
-   *
-   * @param {Date|number|string} date - Base date.
-   * @param {number|string} amount - Amount (ms/string) or a number paired with `unit`.
-   * @param {"ms"|"s"|"m"|"h"|"d"|"w"} [unit] - Unit when `amount` is a plain number.
-   * @returns {Date} The resulting date.
-   */
-  add(date, amount, unit) {
-    const d = _toDate(date);
-    let ms;
-    if (typeof amount === "number") {
-      ms = unit ? amount * (MS[UNIT_ALIASES[unit] ?? unit] ?? 1) : amount;
-    } else {
-      ms = this.parseDuration(amount) ?? 0;
+/**
+ * The latest date.
+ *
+ * @param {Iterable<DateInput>} dates
+ * @returns {Date | undefined}
+ */
+function max(dates) {
+  /** @type {Date | undefined} */
+  let best;
+  for (const value of dates) {
+    const d = _toDate(value);
+    if (!best || d > best) best = d;
+  }
+  return best;
+}
+
+/**
+ * The current Unix timestamp, in seconds.
+ *
+ * @returns {number}
+ */
+function unix() {
+  return Math.floor(Date.now() / 1000);
+}
+
+/**
+ * Starts a precise stopwatch.
+ *
+ * @example
+ * const sw = time.stopwatch();
+ * await loadConfig(); sw.lap("config");
+ * await connectDb();  sw.lap("db");
+ * console.log(sw.stop(true)); // "182.4ms"
+ *
+ * @returns {Stopwatch}
+ */
+function stopwatch() {
+  let start = process.hrtime.bigint();
+  let lastLap = start;
+  /** @type {Array<{ label: string, ms: number, total: number }>} */
+  let laps = [];
+  const since = (/** @type {bigint} */ t) => Number(process.hrtime.bigint() - t) / 1e6;
+  const pretty = (/** @type {number} */ ms) =>
+    ms < 1000 ? `${Math.round(ms * 100) / 100}ms` : ms < MS.m ? `${Math.round(ms / 10) / 100}s` : formatDuration(ms, { units: 2, milliseconds: false });
+  return {
+    elapsed: () => since(start),
+    stop: (fmt = false) => (fmt ? pretty(since(start)) : since(start)),
+    lap: (label) => {
+      const now = process.hrtime.bigint();
+      const ms = Number(now - lastLap) / 1e6;
+      lastLap = now;
+      laps.push({ label: label ?? `lap ${laps.length + 1}`, ms, total: Number(now - start) / 1e6 });
+      return ms;
+    },
+    laps: () => laps.map((l) => ({ ...l })),
+    reset: () => {
+      start = process.hrtime.bigint();
+      lastLap = start;
+      laps = [];
+    },
+  };
+}
+
+/**
+ * Runs a function, sync or async, and tells you how long it took.
+ *
+ * @example
+ * const { result, duration } = await time.measure(() => db.query(sql));
+ * nc.info(`Query took ${duration.toFixed(1)}ms`);
+ *
+ * @template T
+ * @param {() => T} fn
+ * @returns {Promise<{ result: Awaited<T>, duration: number }>} `duration` is in milliseconds.
+ */
+async function measure(fn) {
+  const start = process.hrtime.bigint();
+  const result = await fn();
+  return { result, duration: Number(process.hrtime.bigint() - start) / 1e6 };
+}
+
+/**
+ * Runs a task at a regular interval. Unlike `setInterval`, a slow run
+ * delays the next one instead of piling up, timing doesn't drift, and
+ * errors are caught.
+ *
+ * @example
+ * const job = time.every("5m", syncInventory, { immediate: true, onError: nc.error });
+ * job.next(); // when it runs next
+ * job.stop();
+ *
+ * @param {number | string} interval In ms, or a duration like `"30s"`.
+ * @param {() => unknown} task Can be async.
+ * @param {EveryOptions} [options]
+ * @returns {ScheduledTask}
+ * @throws {RangeError} If the interval isn't a positive duration.
+ */
+function every(interval, task, options = {}) {
+  const ms = parseDuration(interval);
+  if (ms === null || ms <= 0) throw new RangeError(`Invalid interval: ${String(interval)}`);
+  let stopped = false;
+  let running = false;
+  let runs = 0;
+  /** @type {() => void} */
+  let cancel = () => {};
+  let nextAt = Date.now() + (options.immediate ? 0 : ms);
+
+  const tick = async () => {
+    if (stopped) return;
+    running = true;
+    runs++;
+    await _run(task, options.onError);
+    running = false;
+    if (stopped) return;
+    const now = Date.now();
+    nextAt += ms;
+    if (nextAt <= now) nextAt = now + ms - ((now - nextAt) % ms);
+    cancel = _longTimeout(tick, nextAt - Date.now(), options.unref ?? false);
+  };
+  cancel = _longTimeout(tick, nextAt - Date.now(), options.unref ?? false);
+
+  return {
+    stop: () => {
+      stopped = true;
+      cancel();
+    },
+    next: () => (stopped ? undefined : new Date(nextAt)),
+    isRunning: () => running,
+    runs: () => runs,
+  };
+}
+
+/**
+ * Parsed cron fields.
+ * @typedef {{ seconds: Set<number>, minutes: Set<number>, hours: Set<number>, days: Set<number>, months: Set<number>, weekdays: Set<number>, anyDay: boolean, anyWeekday: boolean }} CronSpec
+ */
+
+/** @type {Record<string, string>} */
+const _CRON_MACROS = {
+  "@yearly": "0 0 1 1 *", "@annually": "0 0 1 1 *", "@monthly": "0 0 1 * *", "@weekly": "0 0 * * 0",
+  "@daily": "0 0 * * *", "@midnight": "0 0 * * *", "@hourly": "0 * * * *",
+};
+const _MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const _DAY_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+
+/**
+ * @param {string} expression
+ * @returns {CronSpec}
+ */
+const _parseCron = (expression) => {
+  const text = _CRON_MACROS[expression.trim().toLowerCase()] ?? expression.trim();
+  const fields = text.split(/\s+/);
+  if (fields.length !== 5 && fields.length !== 6) throw new SyntaxError(`Invalid cron expression "${expression}": expected 5 or 6 fields`);
+  if (fields.length === 5) fields.unshift("0");
+  /** @type {(field: string, min: number, max: number, names?: string[]) => Set<number>} */
+  const parse = (field, min, max, names) => {
+    const values = new Set();
+    for (const part of field.split(",")) {
+      const [rangePart, stepPart] = part.split("/");
+      const step = stepPart === undefined ? 1 : Number(stepPart);
+      if (!Number.isInteger(step) || step < 1) throw new SyntaxError(`Invalid step "${part}" in cron expression "${expression}"`);
+      const toNumber = (/** @type {string} */ token) => {
+        const index = names ? names.indexOf(token.toLowerCase()) : -1;
+        const n = index >= 0 ? index + (min === 1 ? 1 : 0) : Number(token);
+        if (!Number.isInteger(n)) throw new SyntaxError(`Invalid value "${token}" in cron expression "${expression}"`);
+        return n;
+      };
+      let from = min;
+      let to = max;
+      if (rangePart !== "*" && rangePart !== "?") {
+        const [a, b] = rangePart.split("-");
+        from = toNumber(a);
+        to = b === undefined ? (stepPart === undefined ? from : max) : toNumber(b);
+      }
+      if (from < min || to > max || from > to) throw new SyntaxError(`Value out of range in "${part}" (allowed ${min}-${max}) in cron expression "${expression}"`);
+      for (let v = from; v <= to; v += step) values.add(v);
+    }
+    return values;
+  };
+  const weekdays = parse(fields[5], 0, 7, _DAY_NAMES);
+  if (weekdays.has(7)) {
+    weekdays.delete(7);
+    weekdays.add(0);
+  }
+  return {
+    seconds: parse(fields[0], 0, 59),
+    minutes: parse(fields[1], 0, 59),
+    hours: parse(fields[2], 0, 23),
+    days: parse(fields[3], 1, 31),
+    months: parse(fields[4], 1, 12, _MONTH_NAMES),
+    weekdays,
+    anyDay: fields[3] === "*" || fields[3] === "?",
+    anyWeekday: fields[5] === "*" || fields[5] === "?",
+  };
+};
+
+/**
+ * @param {CronSpec} spec
+ * @param {Date} from
+ * @param {string | undefined} timeZone
+ * @returns {Date | undefined}
+ */
+const _nextCron = (spec, from, timeZone) => {
+  const start = _parts(new Date(from.getTime() + 1000), timeZone);
+  // Walk wall-clock time (stored in a UTC Date) and convert matches to instants.
+  const wall = new Date(Date.UTC(start.year, start.month - 1, start.day, start.hour, start.minute, start.second));
+  const limit = wall.getTime() + 8 * 366 * MS.d;
+  const dayMatches = () => {
+    const dom = spec.days.has(wall.getUTCDate());
+    const dow = spec.weekdays.has(wall.getUTCDay());
+    if (spec.anyDay && spec.anyWeekday) return true;
+    if (spec.anyDay) return dow;
+    if (spec.anyWeekday) return dom;
+    return dom || dow;
+  };
+  while (wall.getTime() <= limit) {
+    if (!spec.months.has(wall.getUTCMonth() + 1)) {
+      wall.setUTCMonth(wall.getUTCMonth() + 1, 1);
+      wall.setUTCHours(0, 0, 0, 0);
+      continue;
     }
-    return new Date(d.getTime() + ms);
-  },
-
-  /**
-   * Subtracts a duration from a date and returns a new Date.
-   *
-   * @param {Date|number|string} date - Base date.
-   * @param {number|string} amount - Amount (ms/string) or a number paired with `unit`.
-   * @param {"ms"|"s"|"m"|"h"|"d"|"w"} [unit] - Unit when `amount` is a plain number.
-   * @returns {Date} The resulting date.
-   */
-  subtract(date, amount, unit) {
-    if (typeof amount === "number") return this.add(date, -amount, unit);
-    const ms = this.parseDuration(amount) ?? 0;
-    return this.add(date, -ms);
-  },
-
-  /**
-   * Returns the difference between two dates in the requested unit.
-   *
-   * @example
-   * nodeComfort.time.diff("2024-01-02", "2024-01-01", "d"); // 1
-   *
-   * @param {Date|number|string} a - First date.
-   * @param {Date|number|string} b - Second date.
-   * @param {"ms"|"s"|"m"|"h"|"d"|"w"} [unit="ms"] - Result unit.
-   * @returns {number} The signed difference (`a - b`) in the given unit.
-   */
-  diff(a, b, unit = "ms") {
-    const ms = _toDate(a).getTime() - _toDate(b).getTime();
-    return ms / (MS[UNIT_ALIASES[unit] ?? unit] ?? 1);
-  },
-
-  /**
-   * Checks whether two dates fall on the same calendar day.
-   *
-   * Uses local time by default; pass `options.timeZone` (or set a global zone)
-   * to compare calendar days in a specific zone.
-   *
-   * @param {Date|number|string} a - First date.
-   * @param {Date|number|string} b - Second date.
-   * @param {{ timeZone?: string }} [options] - Time-zone override.
-   * @returns {boolean} True if both are the same day.
-   */
-  isSameDay(a, b, options = {}) {
-    const timeZone = options.timeZone ?? _config.timeZone;
-    const pa = _numericParts(_toDate(a), timeZone);
-    const pb = _numericParts(_toDate(b), timeZone);
-    return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
-  },
-
-  /**
-   * Returns a new Date at the start of the given unit (day/hour/etc).
-   *
-   * @example
-   * nodeComfort.time.startOf(new Date(), "day"); // midnight today
-   *
-   * @param {Date|number|string} date - Base date.
-   * @param {"year"|"month"|"day"|"hour"|"minute"|"second"} unit - Unit to reset to.
-   * @returns {Date} The start-of-unit date.
-   */
-  startOf(date, unit) {
-    const d = _toDate(date);
-    switch (unit) {
-      case "year": d.setMonth(0);
-      // falls through
-      case "month": d.setDate(1);
-      // falls through
-      case "day": d.setHours(0);
-      // falls through
-      case "hour": d.setMinutes(0);
-      // falls through
-      case "minute": d.setSeconds(0);
-      // falls through
-      case "second": d.setMilliseconds(0);
+    if (!dayMatches()) {
+      wall.setUTCDate(wall.getUTCDate() + 1);
+      wall.setUTCHours(0, 0, 0, 0);
+      continue;
     }
-    return d;
-  },
-
-  /**
-   * Returns the current Unix timestamp in seconds.
-   *
-   * @returns {number} Seconds since the Unix epoch.
-   */
-  unix() {
-    return Math.floor(Date.now() / 1000);
-  },
-
-  /**
-   * Returns a high-resolution stopwatch you can `.stop()` to get elapsed ms.
-   *
-   * @example
-   * const timer = nodeComfort.time.stopwatch();
-   * doWork();
-   * console.log(timer.stop());          // e.g. 12.34 (ms, sub-ms precise)
-   * console.log(timer.stop(true));      // "12.34ms"
-   *
-   * @returns {{ elapsed: () => number, stop: (format?: boolean) => number|string }} A stopwatch handle.
-   */
-  stopwatch() {
-    const start = process.hrtime.bigint();
-    const elapsed = () => Number(process.hrtime.bigint() - start) / 1e6;
-    return {
-      elapsed,
-      stop: (format = false) => {
-        const ms = elapsed();
-        return format ? `${Math.round(ms * 100) / 100}ms` : ms;
-      },
-    };
-  },
+    if (!spec.hours.has(wall.getUTCHours())) {
+      wall.setUTCHours(wall.getUTCHours() + 1, 0, 0, 0);
+      continue;
+    }
+    if (!spec.minutes.has(wall.getUTCMinutes())) {
+      wall.setUTCMinutes(wall.getUTCMinutes() + 1, 0, 0);
+      continue;
+    }
+    if (!spec.seconds.has(wall.getUTCSeconds())) {
+      wall.setUTCSeconds(wall.getUTCSeconds() + 1, 0);
+      continue;
+    }
+    const instant = _fromWall(wall.getUTCFullYear(), wall.getUTCMonth() + 1, wall.getUTCDate(), wall.getUTCHours(), wall.getUTCMinutes(), wall.getUTCSeconds(), timeZone);
+    if (instant && instant.getTime() > from.getTime()) return instant;
+    wall.setUTCSeconds(wall.getUTCSeconds() + 1, 0);
+  }
+  return undefined;
+};
+
+/**
+ * The next date matching a cron expression, without scheduling anything.
+ *
+ * Expressions have 5 fields (`minute hour day month weekday`), or 6 with
+ * seconds first. You can use `*`, lists (`1,15`), ranges (`1-5`), steps
+ * (`*\/15`), names (`jan`, `mon-fri`) and `@daily`, `@hourly`, `@weekly`,
+ * `@monthly`, `@yearly`. As in classic cron, when both the day and the
+ * weekday are set, either one matching is enough.
+ *
+ * @example
+ * time.nextRun("0 9 * * mon-fri");                              // next weekday at 09:00
+ * time.nextRun("0 0 1 * *", { timeZone: "America/New_York" });  // next 1st of the month
+ *
+ * @param {string} expression
+ * @param {CronOptions} [options]
+ * @returns {Date | undefined} `undefined` if nothing matches within 8 years.
+ * @throws {SyntaxError} If the expression is invalid.
+ */
+function nextRun(expression, options = {}) {
+  return _nextCron(_parseCron(expression), _toDate(options.from), options.timeZone ?? _config.timeZone);
+}
+
+/**
+ * Runs a task on a cron schedule, in any time zone. Daylight-saving changes
+ * are handled: a skipped time is skipped, a repeated one runs once. See
+ * `nextRun()` for the syntax.
+ *
+ * @example
+ * const job = time.cron("0 9 * * 1-5", sendDailyReport, { timeZone: "Europe/Paris" });
+ * time.cron("*\/15 * * * *", refreshCache, { onError: nc.error });
+ * job.stop();
+ *
+ * @param {string} expression
+ * @param {() => unknown} task Can be async.
+ * @param {CronOptions} [options]
+ * @returns {ScheduledTask}
+ * @throws {SyntaxError} If the expression is invalid.
+ */
+function cron(expression, task, options = {}) {
+  const spec = _parseCron(expression);
+  const timeZone = options.timeZone ?? _config.timeZone;
+  let stopped = false;
+  let running = false;
+  let runs = 0;
+  /** @type {Date | undefined} */
+  let nextDate;
+  /** @type {() => void} */
+  let cancel = () => {};
+
+  const plan = (/** @type {Date} */ after) => {
+    nextDate = _nextCron(spec, after, timeZone);
+    if (!nextDate || stopped) return;
+    const target = nextDate;
+    cancel = _longTimeout(() => {
+      if (stopped) return;
+      plan(target);
+      if (running && !options.overlap) return;
+      running = true;
+      runs++;
+      _run(task, options.onError).finally(() => {
+        running = false;
+      });
+    }, target.getTime() - Date.now(), options.unref ?? false);
+  };
+  plan(new Date());
+
+  return {
+    stop: () => {
+      stopped = true;
+      nextDate = undefined;
+      cancel();
+    },
+    next: () => (stopped ? undefined : nextDate),
+    isRunning: () => running,
+    runs: () => runs,
+  };
+}
+
+module.exports = {
+  setLocale,
+  setTimezone,
+  getConfig,
+  timezones,
+  offset,
+  parseDuration,
+  formatDuration,
+  relative,
+  calendar,
+  format,
+  toISODate,
+  add,
+  subtract,
+  diff,
+  startOf,
+  endOf,
+  isBefore,
+  isAfter,
+  isBetween,
+  isSameDay,
+  isToday,
+  isYesterday,
+  isTomorrow,
+  isWeekend,
+  isLeapYear,
+  isValid,
+  daysInMonth,
+  dayOfYear,
+  weekOfYear,
+  min,
+  max,
+  unix,
+  stopwatch,
+  measure,
+  every,
+  nextRun,
+  cron,
 };