@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Time.d.ts

@@ -1,205 +1,760 @@
-declare namespace _exports {
-    export { TimeModule };
-}
-declare namespace _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).
-     */
-    function setLocale(locale: string): TimeModule;
-    /**
-     * 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).
-     */
-    function setTimezone(timeZone: string | undefined): TimeModule;
-    /**
-     * Returns the current global `{ locale, timeZone }` defaults.
-     *
-     * @returns {{ locale: string, timeZone: string|undefined }} A copy of the config.
-     */
-    function getConfig(): {
-        locale: string;
-        timeZone: string | undefined;
-    };
-    /**
-     * 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.
-     */
-    function parseDuration(input: string | number): number | 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.
-     */
-    function formatDuration(ms: number, options?: {
-        long?: boolean;
-        units?: number;
-        locale?: string;
-    }): string;
-    /**
-     * 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.
-     */
-    function relative(date: Date | number | string, from?: Date | number | string, options?: {
-        locale?: string;
-        numeric?: "always" | "auto";
-    }): string;
-    /**
-     * 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.
-     */
-    function format(date: Date | number | string, pattern?: string, options?: {
-        locale?: string;
-        timeZone?: string;
-    }): string;
-    /**
-     * 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.
-     */
-    function add(date: Date | number | string, amount: number | string, unit?: "ms" | "s" | "m" | "h" | "d" | "w"): Date;
-    /**
-     * 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.
-     */
-    function subtract(date: Date | number | string, amount: number | string, unit?: "ms" | "s" | "m" | "h" | "d" | "w"): Date;
-    /**
-     * 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.
-     */
-    function diff(a: Date | number | string, b: Date | number | string, unit?: "ms" | "s" | "m" | "h" | "d" | "w"): number;
-    /**
-     * 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.
-     */
-    function isSameDay(a: Date | number | string, b: Date | number | string, options?: {
-        timeZone?: string;
-    }): boolean;
-    /**
-     * 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.
-     */
-    function startOf(date: Date | number | string, unit: "year" | "month" | "day" | "hour" | "minute" | "second"): Date;
-    /**
-     * Returns the current Unix timestamp in seconds.
-     *
-     * @returns {number} Seconds since the Unix epoch.
-     */
-    function unix(): number;
-    /**
-     * 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.
-     */
-    function stopwatch(): {
-        elapsed: () => number;
-        stop: (format?: boolean) => number | string;
-    };
-}
-export = _exports;
-/**
- * The time module itself • used as the return type of the chainable setters so
- * `setLocale().setTimezone()...` stays fully typed without inlining the type.
- */
-type TimeModule = typeof import("./Time");
+/**
+ * A date: a `Date`, a timestamp in ms, or a string `new Date()` understands
+ * (ISO 8601 is safest).
+ */
+export type DateInput = Date | number | string;
+/**
+ * A unit with a fixed length.
+ */
+export type DurationUnit = "ms" | "millisecond" | "milliseconds" | "s" | "sec" | "second" | "seconds" | "m" | "min" | "minute" | "minutes" | "h" | "hour" | "hours" | "d" | "day" | "days" | "w" | "week" | "weeks";
+/**
+ * A fixed unit, or months and years, whose length varies.
+ */
+export type CalendarUnit = DurationUnit | "M" | "month" | "months" | "y" | "year" | "years";
+/**
+ * A unit for `startOf()` and `endOf()`.
+ */
+export type StartOfUnit = "year" | "quarter" | "month" | "week" | "isoWeek" | "day" | "hour" | "minute" | "second";
+/**
+ * Options for `formatDuration()`.
+ */
+export type FormatDurationOptions = {
+    /**
+     * Full, translated words: `"1 hour 30 minutes"` instead of `"1h 30m"`.
+     */
+    long?: boolean | undefined;
+    /**
+     * Show at most this many units, largest first: `units: 2` turns `"1d 3h 5m"` into `"1d 3h"`.
+     */
+    units?: number | undefined;
+    /**
+     * Clock style, like `"01:30:05"`.
+     */
+    clock?: boolean | undefined;
+    /**
+     * Show milliseconds. Defaults to `true`.
+     */
+    milliseconds?: boolean | undefined;
+    /**
+     * Language for `long`. Defaults to the global locale.
+     */
+    locale?: string | undefined;
+};
+/**
+ * Options for `relative()`.
+ */
+export type RelativeOptions = {
+    /**
+     * Defaults to the global locale.
+     */
+    locale?: string | undefined;
+    /**
+     * `"auto"` says `"yesterday"` instead of `"1 day ago"`. Defaults to `"always"`.
+     */
+    numeric?: "auto" | "always" | undefined;
+    /**
+     * `"short"` gives `"in 3 mo."`. Defaults to `"long"`.
+     */
+    style?: "long" | "short" | "narrow" | undefined;
+};
+/**
+ * Options for `format()`.
+ */
+export type FormatDateOptions = {
+    /**
+     * Language of month and day names. Defaults to the global locale.
+     */
+    locale?: string | undefined;
+    /**
+     * Show the date in this zone, like `"Asia/Tokyo"`. Defaults to the global zone, then the system's.
+     */
+    timeZone?: string | undefined;
+};
+/**
+ * Options for `calendar()`.
+ */
+export type CalendarOptions = {
+    /**
+     * Defaults to the global locale.
+     */
+    locale?: string | undefined;
+    /**
+     * Defaults to the global zone, then the system's.
+     */
+    timeZone?: string | undefined;
+    /**
+     * What "now" is. Defaults to the current time.
+     */
+    now?: DateInput | undefined;
+};
+/**
+ * Week settings.
+ */
+export type WeekOptions = {
+    /**
+     * First day of the week: `0` for Sunday, `1` for Monday. Defaults to `1`.
+     */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
+    /**
+     * Zone whose calendar is used. Defaults to the global zone, then the system's.
+     */
+    timeZone?: string | undefined;
+};
+/**
+ * Options for `parse()`.
+ */
+export type ParseDateOptions = {
+    /**
+     * Language of month names in the text. Defaults to the global locale.
+     */
+    locale?: string | undefined;
+    /**
+     * Zone the text is written in, unless it carries its own offset. Defaults to the global zone, then the system's.
+     */
+    timeZone?: string | undefined;
+};
+/**
+ * Options for `range()`.
+ */
+export type DateRangeOptions = {
+    /**
+     * How many units between two dates. Defaults to `1`.
+     */
+    step?: number | undefined;
+    /**
+     * Zone whose calendar is used for days, weeks, months and years.
+     */
+    timeZone?: string | undefined;
+};
+/**
+ * Time zone setting.
+ */
+export type TimeZoneOptions = {
+    /**
+     * Zone used to decide which day it is. Defaults to the global zone, then the system's.
+     */
+    timeZone?: string | undefined;
+};
+/**
+ * Options for `every()`.
+ */
+export type EveryOptions = {
+    /**
+     * Also run once right away.
+     */
+    immediate?: boolean | undefined;
+    /**
+     * Let the process exit even if the schedule is active.
+     */
+    unref?: boolean | undefined;
+    /**
+     * Called when the task fails. Without it, errors surface as unhandled errors.
+     */
+    onError?: ((error: unknown) => void) | undefined;
+};
+/**
+ * Options for `cron()` and `nextRun()`.
+ */
+export type CronOptions = {
+    /**
+     * Zone in which the expression is read, like `"Europe/Paris"`. Defaults to the global zone, then the system's.
+     */
+    timeZone?: string | undefined;
+    /**
+     * `nextRun()` only: search after this date. Defaults to now.
+     */
+    from?: DateInput | undefined;
+    /**
+     * Let the process exit even if the schedule is active.
+     */
+    unref?: boolean | undefined;
+    /**
+     * Start a run even if the previous one hasn't finished. By default it's skipped.
+     */
+    overlap?: boolean | undefined;
+    /**
+     * `cron()` only: also run once right away.
+     */
+    immediate?: boolean | undefined;
+    /**
+     * Called when the task fails.
+     */
+    onError?: ((error: unknown) => void) | undefined;
+};
+/**
+ * A schedule returned by `every()` and `cron()`.
+ */
+export type ScheduledTask = {
+    /**
+     * Stops the schedule. A run in progress finishes.
+     */
+    stop: () => void;
+    /**
+     * When the next run is planned.
+     */
+    next: () => Date | undefined;
+    /**
+     * Whether a run is in progress.
+     */
+    isRunning: () => boolean;
+    /**
+     * How many runs have started.
+     */
+    runs: () => number;
+};
+/**
+ * Returned by `stopwatch()`.
+ */
+export type Stopwatch = {
+    /**
+     * Milliseconds since the start.
+     */
+    elapsed: () => number;
+    /**
+     * The elapsed time; `stop(true)` formats it, like `"1.5s"`.
+     */
+    stop: (format?: boolean) => number | string;
+    /**
+     * Records a lap and returns the ms since the previous one.
+     */
+    lap: (label?: string) => number;
+    /**
+     * Every lap so far.
+     */
+    laps: () => Array<{
+        label: string;
+        ms: number;
+        total: number;
+    }>;
+    /**
+     * Starts over.
+     */
+    reset: () => void;
+};
+/**
+ * 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.
+ */
+export function setLocale(locale: string): typeof import("./Time");
+/**
+ * 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.
+ */
+export function setTimezone(timeZone: string | undefined): typeof import("./Time");
+/**
+ * The current defaults.
+ *
+ * @example
+ * time.getConfig(); // { locale: "en", timeZone: undefined }
+ *
+ * @returns {{ locale: string, timeZone: string | undefined }}
+ */
+export function getConfig(): {
+    locale: string;
+    timeZone: string | undefined;
+};
+/**
+ * Every time zone Node knows, sorted.
+ *
+ * @example
+ * time.timezones().includes("Europe/Paris"); // true
+ *
+ * @returns {string[]}
+ */
+export function timezones(): string[];
+/**
+ * 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}
+ */
+export function offset(timeZone?: string, date?: DateInput): number;
+/**
+ * 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.
+ */
+export function parseDuration(input: string | number): number | null;
+/**
+ * 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"
+ * time.formatDuration("90m");                                   // "1h 30m"
+ *
+ * @param {number | string} duration Milliseconds, or text like `"90m"`.
+ * @param {FormatDurationOptions} [options]
+ * @returns {string}
+ */
+export function formatDuration(duration: number | string, options?: FormatDurationOptions): string;
+/**
+ * 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}
+ */
+export function relative(date: DateInput, from?: DateInput, options?: RelativeOptions): string;
+/**
+ * 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}
+ */
+export function calendar(date: DateInput, options?: CalendarOptions): string;
+/**
+ * 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 |
+ * | `Do` | 5th | | `z` | zone name, like EST or GMT+1 |
+ *
+ * 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"`.
+ */
+export function format(date: DateInput, pattern?: string, options?: FormatDateOptions): string;
+/**
+ * Reads a date written in a known format: the opposite of `format()`, with
+ * the same tokens. Parts the pattern doesn't have default to today's date
+ * and to midnight.
+ *
+ * @example
+ * time.parse("15/01/2024 14:30", "DD/MM/YYYY HH:mm");
+ * time.parse("15 janvier 2024", "D MMMM YYYY", { locale: "fr" });
+ * time.parse("2024-01-15 09:00", "YYYY-MM-DD HH:mm", { timeZone: "Asia/Tokyo" });
+ * time.parse("31/02/2024", "DD/MM/YYYY"); // undefined, no such day
+ *
+ * @param {string} text
+ * @param {string} pattern Tokens like `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, `A`, `Z`. Text in brackets must match as is.
+ * @param {ParseDateOptions} [options]
+ * @returns {Date | undefined} `undefined` when the text doesn't match or isn't a real date.
+ */
+export function parse(text: string, pattern: string, options?: ParseDateOptions): Date | undefined;
+/**
+ * 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}
+ */
+export function toISODate(date?: DateInput, options?: TimeZoneOptions): string;
+/**
+ * Adds time to a date and returns a new `Date`. Whole days, weeks, months
+ * and years follow the calendar: one day later is the same time tomorrow,
+ * even when the clocks change in between, and January 31 plus one month is
+ * the end of February. Hours and smaller units are exact.
+ *
+ * @example
+ * time.add(new Date(), "2h30m");
+ * time.add(new Date(), 3, "days");
+ * time.add(new Date(), "1 month");
+ * time.add(new Date(2024, 0, 31), 1, "month"); // 2024-02-29
+ * time.add(date, "1 day", { timeZone: "Europe/Paris" });
+ *
+ * @param {DateInput} date
+ * @param {number | string} amount A number with `unit`, or a duration like `"1h30m"` or `"1 month"`.
+ * @param {CalendarUnit | TimeZoneOptions} [unit="ms"] The unit of a number. With a text amount there is none to give: the options can come here.
+ * @param {TimeZoneOptions} [options] The zone whose calendar is followed.
+ * @returns {Date}
+ * @throws {TypeError} If a text amount isn't a duration, or the unit isn't one.
+ */
+export function add(date: DateInput, amount: number | string, unit?: CalendarUnit | TimeZoneOptions, options?: TimeZoneOptions): Date;
+/**
+ * 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 | TimeZoneOptions} [unit="ms"] The unit of a number, or the options when the amount is text.
+ * @param {TimeZoneOptions} [options]
+ * @returns {Date}
+ * @throws {TypeError} If a text amount isn't a duration, or the unit isn't one.
+ */
+export function subtract(date: DateInput, amount: number | string, unit?: CalendarUnit | TimeZoneOptions, options?: TimeZoneOptions): Date;
+/**
+ * `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"]
+ * @param {TimeZoneOptions} [options] The zone whose calendar months and years follow.
+ * @returns {number}
+ * @throws {TypeError} If the unit isn't one.
+ */
+export function diff(a: DateInput, b: DateInput, unit?: CalendarUnit, options?: TimeZoneOptions): number;
+/**
+ * A new `Date` at the start of the day, week, month... in the global time
+ * zone, or the one you name.
+ *
+ * @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
+ * time.startOf(new Date(), "day", { timeZone: "Asia/Tokyo" });  // midnight in Tokyo
+ *
+ * @param {DateInput} date
+ * @param {StartOfUnit} unit
+ * @param {WeekOptions} [options]
+ * @returns {Date}
+ */
+export function startOf(date: DateInput, unit: StartOfUnit, options?: WeekOptions): Date;
+/**
+ * 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}
+ */
+export function endOf(date: DateInput, unit: StartOfUnit, options?: WeekOptions): Date;
+/**
+ * Is `a` before `b`?
+ *
+ * @param {DateInput} a
+ * @param {DateInput} b
+ * @returns {boolean}
+ */
+export function isBefore(a: DateInput, b: DateInput): boolean;
+/**
+ * Is `a` after `b`?
+ *
+ * @example
+ * if (time.isAfter(expiresAt, Date.now())) grantAccess();
+ *
+ * @param {DateInput} a
+ * @param {DateInput} b
+ * @returns {boolean}
+ */
+export function isAfter(a: DateInput, b: DateInput): boolean;
+/**
+ * Is the date between `start` and `end`, both included?
+ *
+ * @param {DateInput} date
+ * @param {DateInput} start
+ * @param {DateInput} end
+ * @returns {boolean}
+ */
+export function isBetween(date: DateInput, start: DateInput, end: DateInput): boolean;
+/**
+ * Are both dates in the same year, month, week, day, hour...?
+ *
+ * @example
+ * time.isSame(a, b, "month");
+ * time.isSame(a, b, "day", { timeZone: "America/New_York" });
+ *
+ * @param {DateInput} a
+ * @param {DateInput} b
+ * @param {StartOfUnit} unit
+ * @param {WeekOptions} [options]
+ * @returns {boolean}
+ */
+export function isSame(a: DateInput, b: DateInput, unit: StartOfUnit, options?: WeekOptions): boolean;
+/**
+ * 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}
+ */
+export function isSameDay(a: DateInput, b: DateInput, options?: TimeZoneOptions): boolean;
+/**
+ * Is the date today?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+export function isToday(date: DateInput, options?: TimeZoneOptions): boolean;
+/**
+ * Was the date yesterday?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+export function isYesterday(date: DateInput, options?: TimeZoneOptions): boolean;
+/**
+ * Is the date tomorrow?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+export function isTomorrow(date: DateInput, options?: TimeZoneOptions): boolean;
+/**
+ * Is it a Saturday or a Sunday?
+ *
+ * @param {DateInput} date
+ * @param {TimeZoneOptions} [options]
+ * @returns {boolean}
+ */
+export function isWeekend(date: DateInput, options?: TimeZoneOptions): boolean;
+/**
+ * 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}
+ */
+export function isLeapYear(yearOrDate: number | DateInput): boolean;
+/**
+ * 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}
+ */
+export function isValid(value: unknown): boolean;
+/**
+ * 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}
+ */
+export function daysInMonth(dateOrYear: DateInput | number, month?: number): number;
+/**
+ * Day of the year, from 1 to 366.
+ *
+ * @param {DateInput} [date] Defaults to now.
+ * @param {TimeZoneOptions} [options]
+ * @returns {number}
+ */
+export function dayOfYear(date?: DateInput, options?: TimeZoneOptions): number;
+/**
+ * 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, timeZone?: string }} [options] `utc` reads the date in UTC, `timeZone` in another zone.
+ * @returns {number}
+ */
+export function weekOfYear(date?: DateInput, options?: {
+    utc?: boolean;
+    timeZone?: string;
+}): number;
+/**
+ * The earliest date.
+ *
+ * @param {Iterable<DateInput>} dates
+ * @returns {Date | undefined}
+ */
+export function min(dates: Iterable<DateInput>): Date | undefined;
+/**
+ * The latest date.
+ *
+ * @param {Iterable<DateInput>} dates
+ * @returns {Date | undefined}
+ */
+export function max(dates: Iterable<DateInput>): Date | undefined;
+/**
+ * The current Unix timestamp, in seconds.
+ *
+ * @returns {number}
+ */
+export function unix(): number;
+/**
+ * A `Date` from a Unix timestamp in seconds, as found in JWTs and many APIs.
+ *
+ * @example
+ * time.fromUnix(1705329000); // 2024-01-15T14:30:00.000Z
+ *
+ * @param {number} seconds
+ * @returns {Date}
+ */
+export function fromUnix(seconds: number): Date;
+/**
+ * Every date from `start` to `end`, both included, one unit apart. Handy
+ * for charts, calendars and reports.
+ *
+ * @example
+ * time.range("2024-01-01", "2024-01-07", "day");           // 7 dates
+ * time.range(start, end, "month");                          // the same day each month
+ * time.range(start, end, "minute", { step: 15 });           // every quarter of an hour
+ *
+ * @param {DateInput} start
+ * @param {DateInput} end
+ * @param {CalendarUnit} [unit="day"]
+ * @param {DateRangeOptions} [options]
+ * @returns {Date[]}
+ * @throws {RangeError} If the step isn't positive, or the range would hold more than a million dates.
+ */
+export function range(start: DateInput, end: DateInput, unit?: CalendarUnit, options?: DateRangeOptions): Date[];
+/**
+ * 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}
+ */
+export function stopwatch(): Stopwatch;
+/**
+ * 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.
+ */
+export function measure<T>(fn: () => T): Promise<{
+    result: Awaited<T>;
+    duration: number;
+}>;
+/**
+ * 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.
+ */
+export function every(interval: number | string, task: () => unknown, options?: EveryOptions): ScheduledTask;
+/**
+ * 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`), `L` for the last day of the month,
+ * 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.
+ */
+export function nextRun(expression: string, options?: CronOptions): Date | undefined;
+/**
+ * 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.
+ */
+export function cron(expression: string, task: () => unknown, options?: CronOptions): ScheduledTask;
 //# sourceMappingURL=Time.d.ts.map