@northguild/gmt 1.14.2 → 1.16.0

package/dist/unix/format/formatRelativeUnix.d.ts

@@ -1,34 +1,44 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
+import type { RelativeRoundingMethod, RelativeUnit } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 export interface FormatRelativeUnixOptions {
     style?: "long" | "short" | "narrow";
     numeric?: "always" | "auto";
-    largestUnit?: RelativeUnit;
-    /**
-     * How the computed distance rounds to the display unit: "floor" rounds toward the
-     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
-     * matches current behavior when omitted.
-     */
+    largestUnit?: RelativeUnit | `${RelativeUnit}s`;
     roundingMethod?: RelativeRoundingMethod;
-    epochUnit?: "milliseconds" | "seconds";
+    epochUnit?: UnixUnit;
     reference?: string | number;
     timeZone?: string;
 }
 /**
  * Format the relative time between a unix epoch value and a reference instant.
  *
- * - Auto-picks the display unit (second through year) based on the distance, unless
- *   `largestUnit` forces one.
+ * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
+ *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
+ *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
+ *   "3 years ago".
+ * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
+ *   Pass `largestUnit: "day"` to keep a day count.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `timeZone` anchors a calendar unit (week, month or year, auto-picked or forced). Omitted, it is
+ *   `"UTC"`, as in every `unix/` function; `"local"` is the system zone; an unknown zone returns
+ *   `""` whatever the unit (ECMA-402 throws RangeError for it).
+ * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
+ *   digits; `largestUnit` and `epochUnit` accept singular or plural names.
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
  *
  * @param value unix epoch (string or number, per `epochUnit`) to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { style, numeric, largestUnit, roundingMethod, epochUnit, reference, timeZone }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3 years ago"
- * @example formatRelativeUnix(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000 }) // "3 years ago"
+ * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000, largestUnit: "day" }) // "1,096 days ago"
+ * @example formatRelativeUnix(0, "en-US", { reference: 37800000, roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeUnix("0", "en-US", { reference: "1800", epochUnit: "second", largestUnit: "minutes" }) // "30 minutes ago"
+ * @example formatRelativeUnix(0, "en-US", { reference: 1800000, timeZone: "Invalid/Zone" }) // ""
+ * @example formatRelativeUnix(0, "en-US", null as never) // ""
  * @example formatRelativeUnix("not-a-number") // ""
+ * @example formatRelativeUnix(1709163000000, ["fr-FR", "en-US"], { reference: 1709164800000 }) // "il y a 30 minutes"
  */
-export declare function formatRelativeUnix(value: string | number, locale?: string, options?: FormatRelativeUnixOptions): string;
-export {};
+export declare function formatRelativeUnix(value: string | number, locale?: string | string[], options?: FormatRelativeUnixOptions): string;

package/dist/unix/format/formatRelativeUnix.js

@@ -1,118 +1,71 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
+import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { resolveRelativeRounding } from "../../internal/resolveRelativeRounding.js";
-import { isValidUtc } from "../../utc/validate/index.js";
-const AUTO_UNITS = [
-    { unit: "second", maxSeconds: 60 },
-    { unit: "minute", maxSeconds: 3_600 },
-    { unit: "hour", maxSeconds: 86_400 },
-    { unit: "day", maxSeconds: Infinity },
-];
-function toInstant(raw, epochUnit) {
-    let n;
-    if (typeof raw === "number") {
-        n = raw;
-    }
-    else if (typeof raw === "string") {
-        const trimmed = raw.trim();
-        // Mirror formatUnix.parseEpochMs: only accept integer-looking strings,
-        // so "" / "not-a-date" / "12.5" don't silently coerce to 0/12.
-        if (!/^-?\d+$/.test(trimmed))
-            return null;
-        n = Number(trimmed);
-    }
-    else {
-        return null;
-    }
-    if (!Number.isFinite(n))
-        return null;
-    try {
-        const ms = epochUnit === "seconds" ? n * 1000 : n;
-        return Temporal.Instant.fromEpochMilliseconds(ms);
-    }
-    catch {
-        return null;
-    }
-}
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { resolveUnixFormatReference } from "../../internal/unixFormatReference.js";
+import { durationTotal } from "../../internal/zonedWallClockDifference.js";
 /**
  * Format the relative time between a unix epoch value and a reference instant.
  *
- * - Auto-picks the display unit (second through year) based on the distance, unless
- *   `largestUnit` forces one.
+ * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
+ *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
+ *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
+ *   "3 years ago".
+ * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
+ *   Pass `largestUnit: "day"` to keep a day count.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `timeZone` anchors a calendar unit (week, month or year, auto-picked or forced). Omitted, it is
+ *   `"UTC"`, as in every `unix/` function; `"local"` is the system zone; an unknown zone returns
+ *   `""` whatever the unit (ECMA-402 throws RangeError for it).
+ * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
+ *   digits; `largestUnit` and `epochUnit` accept singular or plural names.
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
  *
  * @param value unix epoch (string or number, per `epochUnit`) to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { style, numeric, largestUnit, roundingMethod, epochUnit, reference, timeZone }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3 years ago"
- * @example formatRelativeUnix(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000 }) // "3 years ago"
+ * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000, largestUnit: "day" }) // "1,096 days ago"
+ * @example formatRelativeUnix(0, "en-US", { reference: 37800000, roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeUnix("0", "en-US", { reference: "1800", epochUnit: "second", largestUnit: "minutes" }) // "30 minutes ago"
+ * @example formatRelativeUnix(0, "en-US", { reference: 1800000, timeZone: "Invalid/Zone" }) // ""
+ * @example formatRelativeUnix(0, "en-US", null as never) // ""
  * @example formatRelativeUnix("not-a-number") // ""
+ * @example formatRelativeUnix(1709163000000, ["fr-FR", "en-US"], { reference: 1709164800000 }) // "il y a 30 minutes"
  */
 export function formatRelativeUnix(value, locale, options = {}) {
-    const epochUnit = options.epochUnit ?? "milliseconds";
-    const target = toInstant(value, epochUnit);
-    if (target === null)
-        return "";
-    let reference;
-    if (options.reference === undefined) {
-        try {
-            reference = Temporal.Now.instant();
-        }
-        catch {
+    try {
+        // Temporal GetOptionsObject: undefined is defaults (the parameter default); anything else that is
+        // not an object, including null, is a TypeError.
+        if (options === null || typeof options !== "object")
             return "";
-        }
-    }
-    else if (typeof options.reference === "string") {
-        // String references can be a numeric unix epoch ("1709164800000") OR a
-        // UTC ISO string ("2024-02-29T00:00:00Z"). Try the numeric path first to
-        // match formatUnix's symmetry, then fall back to UTC.
-        const numericRef = toInstant(options.reference, epochUnit);
-        if (numericRef !== null) {
-            reference = numericRef;
-        }
-        else if (isValidUtc(options.reference)) {
-            try {
-                reference = Temporal.Instant.from(options.reference);
-            }
-            catch {
-                return "";
-            }
-        }
-        else {
+        const epochUnit = resolveUnixEpochUnit(options.epochUnit);
+        if (epochUnit === null)
             return "";
-        }
-    }
-    else {
-        const ref = toInstant(options.reference, epochUnit);
-        if (ref === null)
+        const tz = normalizeTimeZone(options.timeZone);
+        if (!tz)
+            return "";
+        const target = unixEpochToInstant(value, epochUnit);
+        if (target === null)
+            return "";
+        const reference = resolveUnixFormatReference(options.reference, epochUnit);
+        if (reference === null)
             return "";
-        reference = ref;
-    }
-    try {
-        const diff = target.since(reference);
-        const absSeconds = Math.abs(diff.total("second"));
-        const unit = options.largestUnit ??
-            AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ??
-            "day";
-        let amount;
         try {
-            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            const diff = target.since(reference);
+            // month/year are calendrical and need a relativeTo anchor.
+            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, reference.toZonedDateTimeISO(tz)));
         }
         catch {
-            // month/year are calendrical and need a relativeTo anchor.
-            // Defer timezone normalization until we know we need it.
-            const tz = normalizeTimeZone(options.timeZone);
-            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: reference.toZonedDateTimeISO(tz) }), options.roundingMethod);
+            return "";
         }
-        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-            numeric: options.numeric ?? "auto",
-            style: options.style ?? "long",
-        }).format(amount, unit));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/unix/format/formatUnix.d.ts

@@ -1,6 +1,47 @@
+import type { UnixUnit } from "../validate/index.js";
 export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
-    epochUnit?: "milliseconds" | "seconds";
+    epochUnit?: UnixUnit;
     timeZone?: string;
     includeTimeZoneName?: boolean;
 }
-export declare function formatUnix(value: string | number, locale?: string, options?: FormatUnixOptions): string;
+/**
+ * Format a unix epoch value (string or number) as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
+ * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits (no whitespace, `+`,
+ *   decimal point or exponent); `epochUnit` also accepts `"second"` / `"millisecond"`.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`, `"local"` is the
+ *   system zone, and an unknown zone returns `""` (ECMA-402 throws RangeError for it).
+ * - `includeTimeZoneName` appends the localized timezone name when true.
+ * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
+ *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
+ *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
+ *   and `era` alone still gets the date and time defaults.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
+ *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
+ *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
+ *
+ * @param value unix epoch value to format (string or number, per `epochUnit`)
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
+ * @param options optional: { epochUnit, timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUnix(0, "en-US", { timeZoneName: "short" }) // "1/1/1970, 12:00:00 AM"
+ * @example formatUnix(1710685845000, "en-US", { timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatUnix("1710685845000.0") // "" (not a digit string)
+ * @example formatUnix(0, "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
+ * @example formatUnix("not-a-number") // ""
+ * @example formatUnix(1710685845000, ["fr-FR", "en-US"], { dateStyle: "long" }) // "17 mars 2024"
+ */
+export declare function formatUnix(value: string | number, locale?: string | string[], options?: FormatUnixOptions): string;

package/dist/unix/format/formatUnix.js

@@ -1,41 +1,74 @@
-import { Temporal } from "@js-temporal/polyfill";
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
+import { formatWallClockOrZoned } from "../../internal/instantFormatOptions.js";
 import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { isValidUnixUnit } from "../validate/index.js";
-function parseEpochMs(value, epochUnit) {
-    let n;
-    if (typeof value === "number") {
-        n = value;
-    }
-    else if (typeof value === "string") {
-        const trimmed = value.trim();
-        if (!/^-?\d+$/.test(trimmed))
-            return null;
-        n = Number(trimmed);
-    }
-    else {
-        return null;
-    }
-    if (!Number.isFinite(n))
-        return null;
-    return epochUnit === "seconds" ? n * 1000 : n;
-}
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+/**
+ * Format a unix epoch value (string or number) as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
+ * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits (no whitespace, `+`,
+ *   decimal point or exponent); `epochUnit` also accepts `"second"` / `"millisecond"`.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`, `"local"` is the
+ *   system zone, and an unknown zone returns `""` (ECMA-402 throws RangeError for it).
+ * - `includeTimeZoneName` appends the localized timezone name when true.
+ * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
+ *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
+ *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
+ *   and `era` alone still gets the date and time defaults.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
+ *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
+ *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
+ *
+ * @param value unix epoch value to format (string or number, per `epochUnit`)
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
+ * @param options optional: { epochUnit, timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
+ * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUnix(0, "en-US", { timeZoneName: "short" }) // "1/1/1970, 12:00:00 AM"
+ * @example formatUnix(1710685845000, "en-US", { timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatUnix("1710685845000.0") // "" (not a digit string)
+ * @example formatUnix(0, "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
+ * @example formatUnix("not-a-number") // ""
+ * @example formatUnix(1710685845000, ["fr-FR", "en-US"], { dateStyle: "long" }) // "17 mars 2024"
+ */
 export function formatUnix(value, locale, options) {
-    const { epochUnit = "milliseconds", timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
-    if (!isValidUnixUnit(epochUnit))
-        return "";
-    const ms = parseEpochMs(value, epochUnit);
-    if (ms === null)
-        return "";
-    const tz = normalizeTimeZone(timeZone);
     try {
-        const zdt = Temporal.Instant.fromEpochMilliseconds(ms).toZonedDateTimeISO(tz);
-        const out = includeTimeZoneName
-            ? zdt.toLocaleString(locale, intlOptions)
-            : zdt.toPlainDateTime().toLocaleString(locale, intlOptions);
-        return normalizeDateTime(out);
+        // ECMA-402 CoerceOptionsToObject: undefined is defaults; null is a TypeError.
+        if (options === null)
+            return "";
+        const { epochUnit, timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        const resolvedUnit = resolveUnixEpochUnit(epochUnit);
+        if (resolvedUnit === null)
+            return "";
+        const instant = unixEpochToInstant(value, resolvedUnit);
+        if (instant === null)
+            return "";
+        const tz = normalizeTimeZone(timeZone);
+        if (!tz)
+            return "";
+        try {
+            const zdt = instant.toZonedDateTimeISO(tz);
+            return normalizeDateTime(formatWallClockOrZoned(zdt, locale, intlOptions, includeTimeZoneName));
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/unix/get/getUnixNow.d.ts

@@ -1,15 +1,21 @@
-import { type UnixUnit } from "../validate/isValidUnixUnit.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return the current Unix timestamp in either seconds or milliseconds.
  *
  * - Uses Temporal.Now.instant() to get current time.
- * - Defaults to "milliseconds" if no unit specified.
- * - Returns 0 on failure.
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
+ * - An explicit `undefined` is the same as omitted. An unknown `epochUnit`, or a non-object
+ *   `options` (such as a bare `"seconds"` string), returns null.
  *
- * @param unit optional unit specifier: "seconds" | "milliseconds"
- * @returns number (unix timestamp)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @returns the current unix timestamp, or null on invalid options
  *
  * @example getUnixNow() // 1700000000000
- * @example getUnixNow("seconds") // 1700000000
+ * @example getUnixNow({ epochUnit: "seconds" }) // 1700000000
+ * @example getUnixNow({ epochUnit: "minutes" as never }) // null
+ * @example getUnixNow("seconds" as never) // null (options must be an object)
  */
-export declare function getUnixNow(...unitInput: [unit?: UnixUnit]): number;
+export declare function getUnixNow(options?: {
+    epochUnit?: UnixUnit;
+}): number | null;

package/dist/unix/get/getUnixNow.js

@@ -1,28 +1,38 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidUnixUnit } from "../validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, toUnixEpoch, } from "../../internal/unixEpochValue.js";
 /**
  * Return the current Unix timestamp in either seconds or milliseconds.
  *
  * - Uses Temporal.Now.instant() to get current time.
- * - Defaults to "milliseconds" if no unit specified.
- * - Returns 0 on failure.
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
+ * - An explicit `undefined` is the same as omitted. An unknown `epochUnit`, or a non-object
+ *   `options` (such as a bare `"seconds"` string), returns null.
  *
- * @param unit optional unit specifier: "seconds" | "milliseconds"
- * @returns number (unix timestamp)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @returns the current unix timestamp, or null on invalid options
  *
  * @example getUnixNow() // 1700000000000
- * @example getUnixNow("seconds") // 1700000000
+ * @example getUnixNow({ epochUnit: "seconds" }) // 1700000000
+ * @example getUnixNow({ epochUnit: "minutes" as never }) // null
+ * @example getUnixNow("seconds" as never) // null (options must be an object)
  */
-export function getUnixNow(...unitInput) {
-    const rawUnit = unitInput.length === 0 ? undefined : unitInput[0];
-    const resolvedUnit = unitInput.length === 0
-        ? "milliseconds"
-        : isValidUnixUnit(String(rawUnit ?? ""))
-            ? rawUnit
-            : "milliseconds";
-    const instant = Temporal.Now.instant();
-    if (resolvedUnit === "seconds") {
-        return Math.floor(instant.epochMilliseconds / 1000);
+export function getUnixNow(options) {
+    try {
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (epochUnit === null) {
+            return null;
+        }
+        try {
+            return toUnixEpoch(Temporal.Now.instant(), epochUnit);
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
     }
-    return instant.epochMilliseconds;
 }

package/dist/unix/get/getUnixNowUnit.d.ts

@@ -1,9 +1,11 @@
-import type { DateTimeUnit } from "../../types/index.js";
-type UnixNowUnit = DateTimeUnit | "dayOfWeek";
+import { Temporal } from "@js-temporal/polyfill";
+import type { UnixNowUnit } from "../../types/index.js";
+export type { UnixNowUnit };
 /**
  * Return the requested unit value from the current Unix timestamp in UTC.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
+ * - `microsecond` and `nanosecond` are Temporal's 0–999 fields, zero-padded to 3 digits.
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns "" on invalid unit or failure.
  *
@@ -12,7 +14,7 @@ type UnixNowUnit = DateTimeUnit | "dayOfWeek";
  *
  * @example getUnixNowUnit("year") // "2024"
  * @example getUnixNowUnit("month") // "02"
+ * @example getUnixNowUnit("months") // "02" (plural unit)
  * @example getUnixNowUnit("invalid") // ""
  */
-export declare function getUnixNowUnit(unit: UnixNowUnit): string;
-export {};
+export declare function getUnixNowUnit(unit: UnixNowUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>): string;

package/dist/unix/get/getUnixNowUnit.js

@@ -1,12 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoWeekOfYear, zonedNowUnitValue, } from "../../internal/zonedNowUnitValue.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
 function isValidUnixNowUnit(unit) {
-    return isValidDateTimeUnit(unit) || ["dayOfWeek"].includes(unit);
+    return isValidDateTimeUnit(unit) || unit === "dayOfWeek";
 }
 /**
  * Return the requested unit value from the current Unix timestamp in UTC.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
+ * - `microsecond` and `nanosecond` are Temporal's 0–999 fields, zero-padded to 3 digits.
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns "" on invalid unit or failure.
  *
@@ -15,45 +18,16 @@ function isValidUnixNowUnit(unit) {
  *
  * @example getUnixNowUnit("year") // "2024"
  * @example getUnixNowUnit("month") // "02"
+ * @example getUnixNowUnit("months") // "02" (plural unit)
  * @example getUnixNowUnit("invalid") // ""
  */
 export function getUnixNowUnit(unit) {
-    if (!isValidUnixNowUnit(String(unit ?? "")))
+    const resolved = typeof unit === "string" ? resolveDateTimeUnit(unit) : "";
+    if (!isValidUnixNowUnit(resolved))
         return "";
     try {
         const now = Temporal.Now.instant().toZonedDateTimeISO("UTC");
-        const plainDateTime = now.toPlainDateTime();
-        const plainDate = Temporal.PlainDate.from({
-            year: plainDateTime.year,
-            month: plainDateTime.month,
-            day: plainDateTime.day,
-        });
-        switch (unit) {
-            case "year":
-                return plainDateTime.year.toString();
-            case "month":
-                return plainDateTime.month.toString().padStart(2, "0");
-            case "week":
-                return (plainDate.weekOfYear ?? 0).toString();
-            case "day":
-                return plainDateTime.day.toString().padStart(2, "0");
-            case "dayOfWeek":
-                return now.dayOfWeek.toString();
-            case "hour":
-                return plainDateTime.hour.toString().padStart(2, "0");
-            case "minute":
-                return plainDateTime.minute.toString().padStart(2, "0");
-            case "second":
-                return plainDateTime.second.toString().padStart(2, "0");
-            case "millisecond":
-                return plainDateTime.millisecond.toString().padStart(3, "0");
-            case "microsecond":
-                return (plainDateTime.microsecond ?? 0).toString().padStart(3, "0");
-            case "nanosecond":
-                return (plainDateTime.nanosecond ?? 0).toString().padStart(3, "0");
-            default:
-                return "";
-        }
+        return zonedNowUnitValue(now, resolved, isoWeekOfYear);
     }
     catch {
         return "";

package/dist/unix/index.d.ts

@@ -1,3 +1,4 @@
+export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./convert/index.js";

package/dist/unix/index.js

@@ -1,3 +1,5 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./convert/index.js";

package/dist/unix/interval/intervalAbutsUnix.d.ts

@@ -1,22 +1,27 @@
 /**
- * Return true when two Unix intervals are exactly adjacent — one's end equals the other's
- * start minus 1 (no gap, no overlap).
+ * Return true when two half-open Unix intervals `[start, end)` are exactly adjacent — one ends
+ * where the other starts, so they share no value and leave no gap (Allen's "meets", either order).
  *
  * - Compares numeric Unix epoch values directly.
- * - Returns `true` when `aEnd + 1 === bStart` or `bEnd + 1 === aStart`.
- * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
- * - Returns `false` on invalid input (non-numeric types, non-finite values).
+ * - Returns `true` when `aEnd === bStart` or `bEnd === aStart` and neither interval is empty. No
+ *   value is stepped by an epoch unit.
+ * - Returns `false` when intervals overlap, are disjoint with a gap (even one epoch unit), or when
+ *   either is empty (`start === end`): an empty interval abuts nothing.
+ * - Returns `false` on invalid input: non-numeric types, empty strings, and values that are not
+ *   safe integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // true
- * @example intervalAbutsUnix(1500000001, 1700000000, 0, 1500000000) // true
- * @example intervalAbutsUnix(0, 1500000000, 1500000002, 1700000000) // false (gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1700000000) // true
+ * @example intervalAbutsUnix(1500000000, 1700000000, 0, 1500000000) // true
+ * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // false (one-unit gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1500000000) // false (an empty interval abuts nothing)
  * @example intervalAbutsUnix(0, 1500000001, 1500000000, 1700000000) // false (overlap)
  * @example intervalAbutsUnix(NaN, 1500000000, 1500000001, 1700000000) // false
+ * @example intervalAbutsUnix(0, 1.5, 1.5, 3) // false (fractional epochs)
  */
 export declare function intervalAbutsUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): boolean;