@northguild/gmt 1.15.0 → 1.17.0

package/dist/unix/convert/convertUnixToUtc.d.ts

@@ -1,17 +1,25 @@
-import { type UnixUnit } from "../validate/isValidUnixUnit.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a unix epoch value to a UTC Instant ISO string.
  *
  * - Converts to UTC Instant using Temporal.Instant.
- * - Validates value and epoch unit ("seconds" | "milliseconds").
- * - Returns "" for invalid input.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param value epoch value: a safe integer or a digit string
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns UTC Instant string or "" on invalid
  *
  * @example convertUnixToUtc(1709164800000) // "2024-02-29T00:00:00Z"
- * @example convertUnixToUtc(1709164800, "seconds") // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc(1709164800, { epochUnit: "seconds" }) // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc("1709164800", { epochUnit: "second" }) // "2024-02-29T00:00:00Z"
  * @example convertUnixToUtc(-1) // "1969-12-31T23:59:59.999Z"
+ * @example convertUnixToUtc(1709164800, "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToUtc(NaN) // ""
  */
-export declare function convertUnixToUtc(value: number, ...unitInput: [unit?: UnixUnit]): string;
+export declare function convertUnixToUtc(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+}): string;

package/dist/unix/convert/convertUnixToUtc.js

@@ -1,31 +1,36 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
-import { isValidUnixUnit } from "../validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 /**
  * Convert a unix epoch value to a UTC Instant ISO string.
  *
  * - Converts to UTC Instant using Temporal.Instant.
- * - Validates value and epoch unit ("seconds" | "milliseconds").
- * - Returns "" for invalid input.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param value epoch value: a safe integer or a digit string
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns UTC Instant string or "" on invalid
  *
  * @example convertUnixToUtc(1709164800000) // "2024-02-29T00:00:00Z"
- * @example convertUnixToUtc(1709164800, "seconds") // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc(1709164800, { epochUnit: "seconds" }) // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc("1709164800", { epochUnit: "second" }) // "2024-02-29T00:00:00Z"
  * @example convertUnixToUtc(-1) // "1969-12-31T23:59:59.999Z"
+ * @example convertUnixToUtc(1709164800, "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToUtc(NaN) // ""
  */
-export function convertUnixToUtc(value, ...unitInput) {
-    const resolvedUnit = unitInput.length === 0 ? "milliseconds" : unitInput[0];
-    if (!isValidAmount(value) || !isValidUnixUnit(resolvedUnit ?? "")) {
-        return "";
-    }
+export function convertUnixToUtc(value, options) {
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(resolvedUnit === "seconds" ? value * 1000 : value);
-        return instant.toString();
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (epochUnit === null) {
+            return "";
+        }
+        return unixEpochToInstant(value, epochUnit)?.toString() ?? "";
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/unix/convert/convertUnixToZoned.d.ts

@@ -1,18 +1,25 @@
-import { type UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a unix epoch value to a zoned ISO 8601 datetime string.
  *
- * - Converts to ZonedDateTime using the specified timezone.
- * - Validates value, timezone, and epoch unit.
- * - Returns "" for invalid input.
+ * - Converts to ZonedDateTime using the specified timezone (required; an unknown zone returns "").
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
+ * @param value epoch value: a safe integer or a digit string
  * @param timeZone IANA timeZone identifier
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-29T00:00:00-05:00[America/New_York]"
- * @example convertUnixToZoned(1709164800, "UTC", "seconds") // "2024-02-29T00:00:00+00:00[UTC]"
- * @example convertUnixToZoned(-1, "UTC") // "1969-12-31T23:59:59.999Z[UTC]"
+ * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUnixToZoned(1709164800, "UTC", { epochUnit: "seconds" }) // "2024-02-29T00:00:00+00:00[UTC]"
+ * @example convertUnixToZoned("-1", "UTC") // "1969-12-31T23:59:59.999+00:00[UTC]"
+ * @example convertUnixToZoned(1709164800, "UTC", "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToZoned(NaN, "UTC") // ""
  */
-export declare function convertUnixToZoned(value: number, timeZone: string, ...unitInput: [unit?: UnixUnit]): string;
+export declare function convertUnixToZoned(value: number | string, timeZone: string, options?: {
+    epochUnit?: UnixUnit;
+}): string;

package/dist/unix/convert/convertUnixToZoned.js

@@ -1,35 +1,46 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
-import { isValidUnixUnit, } from "../../unix/validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
 /**
  * Convert a unix epoch value to a zoned ISO 8601 datetime string.
  *
- * - Converts to ZonedDateTime using the specified timezone.
- * - Validates value, timezone, and epoch unit.
- * - Returns "" for invalid input.
+ * - Converts to ZonedDateTime using the specified timezone (required; an unknown zone returns "").
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
+ * @param value epoch value: a safe integer or a digit string
  * @param timeZone IANA timeZone identifier
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-29T00:00:00-05:00[America/New_York]"
- * @example convertUnixToZoned(1709164800, "UTC", "seconds") // "2024-02-29T00:00:00+00:00[UTC]"
- * @example convertUnixToZoned(-1, "UTC") // "1969-12-31T23:59:59.999Z[UTC]"
+ * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUnixToZoned(1709164800, "UTC", { epochUnit: "seconds" }) // "2024-02-29T00:00:00+00:00[UTC]"
+ * @example convertUnixToZoned("-1", "UTC") // "1969-12-31T23:59:59.999+00:00[UTC]"
+ * @example convertUnixToZoned(1709164800, "UTC", "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToZoned(NaN, "UTC") // ""
  */
-export function convertUnixToZoned(value, timeZone, ...unitInput) {
-    const resolvedUnit = unitInput.length === 0 ? "milliseconds" : unitInput[0];
-    if (!isValidAmount(value) ||
-        !isValidTimeZone(timeZone) ||
-        !isValidUnixUnit(resolvedUnit ?? "")) {
-        return "";
-    }
+export function convertUnixToZoned(value, timeZone, options) {
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(resolvedUnit === "seconds" ? value * 1000 : value);
-        return instant.toZonedDateTimeISO(timeZone).toString();
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (epochUnit === null || !isValidTimeZone(timeZone)) {
+            return "";
+        }
+        const instant = unixEpochToInstant(value, epochUnit);
+        if (instant === null) {
+            return "";
+        }
+        try {
+            return instant.toZonedDateTimeISO(timeZone).toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,18 +1,15 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
- * Options for `formatCalendarUnix`. Mirrors the option shape of
- * `formatCalendar` but targets the unix domain, adding `epochUnit`.
+ * Options for `formatCalendarUnix`. Like `formatCalendar`, it takes a `reference` and a `timeStyle`
+ * (here also `"full"`); it adds `epochUnit` and `timeZone` for the unix domain.
  *
  * @remarks Members:
  *
  * | Member | Type | Default | Description |
  * | --- | --- | --- | --- |
- * | `style` | `"long"\|"short"\|"narrow"` | `"long"` | `RelativeTimeFormat` style for the day label. |
- * | `numeric` | `"always"\|"auto"` | `"auto"` | Numeric formatting of the relative day label. |
- * | `largestUnit` | `"year"\|"month"\|"week"\|"day"` | auto | Largest unit for the relative diff. |
- * | `roundingMethod` | `"expand"\|"trunc"\|"floor"\|"ceil"` | — | Rounding for the computed distance. |
  * | `reference` | `string\|number` | now (UTC) | Anchor epoch/ISO for the "today/tomorrow" comparison. |
- * | `epochUnit` | `"milliseconds"\|"seconds"` | `"milliseconds"` | Interpretation of numeric `value`/`reference`. |
- * | `timeZone` | `string` | `"UTC"` | IANA zone for both day-comparison and clock-time rendering. |
+ * | `epochUnit` | `"milliseconds"\|"seconds"` | `"milliseconds"` | Interpretation of epoch `value`/`reference`; singular names are accepted. |
+ * | `timeZone` | `string` | `"UTC"` | IANA zone for both day-comparison and clock-time rendering; `"local"` is the system zone; an unknown zone returns `""`. |
  * | `timeStyle` | `"short"\|"medium"\|"full"` | `"short"` | `Intl` `timeStyle` for the time-of-day portion. |
  *
  * @example
@@ -20,17 +17,13 @@
  * const opts: FormatCalendarUnixOptions = { timeZone: "America/New_York" };
  */
 export interface FormatCalendarUnixOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
-    largestUnit?: "year" | "month" | "week" | "day";
-    roundingMethod?: "expand" | "trunc" | "floor" | "ceil";
-    /** Anchor point for the relative day comparison. Accepts ISO strings or numeric epochs. */
+    /** Anchor point for the relative day comparison. Accepts UTC ISO strings or epochs (a safe integer or a digit string). */
     reference?: string | number;
-    epochUnit?: "milliseconds" | "seconds";
+    epochUnit?: UnixUnit;
     /**
      * IANA timezone used for both the calendar-day comparison and the
-     * rendered clock time. Resolved via `normalizeTimeZone` — `"local"` for
-     * the system zone, an invalid/omitted value falls back to `"UTC"`.
+     * rendered clock time. Omitted is `"UTC"`, `"local"` is the system zone,
+     * and an unknown zone makes the result `""` (ECMA-402 throws RangeError).
      */
     timeZone?: string;
     /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
@@ -43,13 +36,23 @@ export interface FormatCalendarUnixOptions {
  * variant compares calendar days and renders the clock time in `timeZone`
  * (default `"UTC"`).
  *
+ * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
+ *   digits; anything else returns `""`.
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
+ * - An unknown `timeZone` returns `""`; `"local"` is the system zone.
+ *
  * @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: { epochUnit, reference, timeZone, timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUnix(1710685845000, "en-US", { epochUnit: "milliseconds", timeZone: "America/New_York" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold
- * @example formatCalendarUnix(value, "en-US", { reference: 1710685000000 }) // e.g. "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "UTC" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix("1710772200", "en-US", { reference: "1710685000", epochUnit: "second" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatCalendarUnix(1710772200000, "en-US", null as never) // ""
  * @example formatCalendarUnix("not-a-number") // ""
+ * @example formatCalendarUnix(1710613800000, ["fr-FR", "en-US"], { reference: 1710507600000 }) // "demain à 18:30"
  */
-export declare function formatCalendarUnix(value: string | number, locale?: string, options?: FormatCalendarUnixOptions): string;
+export declare function formatCalendarUnix(value: string | number, locale?: string | string[], options?: FormatCalendarUnixOptions): string;

package/dist/unix/format/formatCalendarUnix.js

@@ -1,34 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.js";
+import { formatCalendarInstants } from "../../internal/formatCalendarDays.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { isValidUtc } from "../../utc/validate/index.js";
-const ABS_DAY_THRESHOLD = 6;
-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";
 /**
  * Format a unix epoch value as a relative day label plus time-of-day, e.g.
  * "Tomorrow at 2:30 PM" — the unix counterpart of `formatCalendar`. See
@@ -36,72 +9,53 @@ function toInstant(raw, epochUnit) {
  * variant compares calendar days and renders the clock time in `timeZone`
  * (default `"UTC"`).
  *
+ * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
+ *   digits; anything else returns `""`.
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
+ * - An unknown `timeZone` returns `""`; `"local"` is the system zone.
+ *
  * @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: { epochUnit, reference, timeZone, timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUnix(1710685845000, "en-US", { epochUnit: "milliseconds", timeZone: "America/New_York" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold
- * @example formatCalendarUnix(value, "en-US", { reference: 1710685000000 }) // e.g. "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "UTC" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix("1710772200", "en-US", { reference: "1710685000", epochUnit: "second" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatCalendarUnix(1710772200000, "en-US", null as never) // ""
  * @example formatCalendarUnix("not-a-number") // ""
+ * @example formatCalendarUnix(1710613800000, ["fr-FR", "en-US"], { reference: 1710507600000 }) // "demain à 18:30"
  */
 export function formatCalendarUnix(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") {
-        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 "";
+        const timeZone = normalizeTimeZone(options.timeZone);
+        if (!timeZone)
+            return "";
+        const target = unixEpochToInstant(value, epochUnit);
+        if (target === null)
             return "";
+        const reference = resolveUnixFormatReference(options.reference, epochUnit);
+        if (reference === null)
+            return "";
+        try {
+            return formatCalendarInstants(target, reference, timeZone, locale, options.timeStyle === undefined ? "short" : options.timeStyle);
         }
-    }
-    else {
-        const ref = toInstant(options.reference, epochUnit);
-        if (ref === null)
+        catch {
             return "";
-        reference = ref;
-    }
-    try {
-        const timeZone = normalizeTimeZone(options.timeZone);
-        const timeStyle = options.timeStyle ?? "short";
-        const targetDate = target.toZonedDateTimeISO(timeZone).toPlainDate();
-        const referenceDate = reference.toZonedDateTimeISO(timeZone).toPlainDate();
-        const diffDays = targetDate.since(referenceDate).days;
-        const epochMilliseconds = Number(target.epochMilliseconds);
-        if (Math.abs(diffDays) > ABS_DAY_THRESHOLD) {
-            return normalizeDateTime(new Intl.DateTimeFormat(locale, {
-                dateStyle: "long",
-                timeStyle,
-                timeZone,
-            }).format(epochMilliseconds));
         }
-        const dayLabel = new Intl.RelativeTimeFormat(locale, {
-            numeric: "auto",
-        }).format(diffDays, "day");
-        return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,27 +1,44 @@
 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;
+    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 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 "";
     }
 }