@northguild/gmt 1.14.2 → 1.16.0

package/dist/utc/convert/convertUtcToUnix.d.ts

@@ -1,17 +1,24 @@
-import { type UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
+import type { UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
 /**
  * Convert a UTC Instant string to a unix epoch value in milliseconds or seconds.
  *
  * - Uses Temporal.Instant.from to parse.
- * - Validates unit ("seconds" | "milliseconds").
+ * - Seconds floor toward −∞, so `"1969-12-31T23:59:59.5Z"` is second `-1` (POSIX `time_t`).
+ * - `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 null.
  * - Returns null for invalid input.
  *
  * @param value UTC Instant string
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns epoch number or null on invalid
  *
  * @example convertUtcToUnix("2024-02-29T00:00:00Z") // 1709164800000
- * @example convertUtcToUnix("2024-02-29T00:00:00Z", "seconds") // 1709164800
+ * @example convertUtcToUnix("2024-02-29T00:00:00Z", { epochUnit: "seconds" }) // 1709164800
+ * @example convertUtcToUnix("1969-12-31T23:59:59.5Z", { epochUnit: "second" }) // -1
+ * @example convertUtcToUnix("2024-02-29T00:00:00Z", "seconds" as never) // null (options must be an object)
  * @example convertUtcToUnix("invalid") // null
  */
-export declare function convertUtcToUnix(value: string, ...unitInput: [unit?: UnixUnit]): number | null;
+export declare function convertUtcToUnix(value: string, options?: {
+    epochUnit?: UnixUnit;
+}): number | null;

package/dist/utc/convert/convertUtcToUnix.js

@@ -1,33 +1,42 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidUnixUnit, } from "../../unix/validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, toUnixEpoch, } from "../../internal/unixEpochValue.js";
 import { isValidUtc } from "../validate/index.js";
 /**
  * Convert a UTC Instant string to a unix epoch value in milliseconds or seconds.
  *
  * - Uses Temporal.Instant.from to parse.
- * - Validates unit ("seconds" | "milliseconds").
+ * - Seconds floor toward −∞, so `"1969-12-31T23:59:59.5Z"` is second `-1` (POSIX `time_t`).
+ * - `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 null.
  * - Returns null for invalid input.
  *
  * @param value UTC Instant string
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns epoch number or null on invalid
  *
  * @example convertUtcToUnix("2024-02-29T00:00:00Z") // 1709164800000
- * @example convertUtcToUnix("2024-02-29T00:00:00Z", "seconds") // 1709164800
+ * @example convertUtcToUnix("2024-02-29T00:00:00Z", { epochUnit: "seconds" }) // 1709164800
+ * @example convertUtcToUnix("1969-12-31T23:59:59.5Z", { epochUnit: "second" }) // -1
+ * @example convertUtcToUnix("2024-02-29T00:00:00Z", "seconds" as never) // null (options must be an object)
  * @example convertUtcToUnix("invalid") // null
  */
-export function convertUtcToUnix(value, ...unitInput) {
-    const resolvedUnit = unitInput.length === 0 ? "milliseconds" : unitInput[0];
-    if (!isValidUtc(value) || !isValidUnixUnit(resolvedUnit ?? "")) {
-        return null;
-    }
+export function convertUtcToUnix(value, options) {
     try {
-        const milliseconds = Number(Temporal.Instant.from(value).epochMilliseconds);
-        return resolvedUnit === "seconds"
-            ? Math.floor(milliseconds / 1000)
-            : milliseconds;
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (!isValidUtc(value) || epochUnit === null) {
+            return null;
+        }
+        try {
+            return toUnixEpoch(Temporal.Instant.from(value), epochUnit);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/utc/format/formatCalendarUtc.d.ts

@@ -1,9 +1,9 @@
-export interface FormatCalendarUtcOptions {
-    reference?: string;
+import type { CalendarOptions } from "../../types/index.js";
+export interface FormatCalendarUtcOptions extends CalendarOptions {
     /**
      * 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. */
@@ -16,13 +16,18 @@ export interface FormatCalendarUtcOptions {
  * variant compares calendar days and renders the clock time in `timeZone`
  * (default `"UTC"`).
  *
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
+ *
  * @param value UTC ISO string to format
- * @param locale optional: BCP 47 locale tag
- * @param options optional: { reference, timeZone, timeStyle }
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
+ * @param options optional: { reference, timeZone (default "UTC"; "local" is the system zone; an unknown zone returns ""), timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 2:30 PM"
- * @example formatCalendarUtc(value, "fr-FR", { timeZone: "Europe/Paris" }) // "demain à 14:30"
+ * @example formatCalendarUtc("2026-03-16T13:30:00Z", "fr-FR", { timeZone: "Europe/Paris", reference: "2026-03-15T12:00:00Z" }) // "demain à 14:30"
+ * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", null as never) // ""
  * @example formatCalendarUtc("not-a-date") // ""
+ * @example formatCalendarUtc("2024-03-16T18:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T13:00:00Z" }) // "demain à 18:30"
  */
-export declare function formatCalendarUtc(value: string, locale?: string, options?: FormatCalendarUtcOptions): string;
+export declare function formatCalendarUtc(value: string, locale?: string | string[], options?: FormatCalendarUtcOptions): string;

package/dist/utc/format/formatCalendarUtc.js

@@ -1,9 +1,8 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { formatCalendarInstants } from "../../internal/formatCalendarDays.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
+import { toInstantFromUtc, toReferenceInstantFromUtc, } from "../../internal/toInstantFromUtc.js";
 import { isValidUtc } from "../validate/index.js";
-const ABS_DAY_THRESHOLD = 6;
 /**
  * Format a UTC ISO string as a relative day label plus time-of-day, e.g.
  * "Tomorrow at 2:30 PM" — the UTC counterpart of `formatCalendar`. See that
@@ -11,58 +10,50 @@ const ABS_DAY_THRESHOLD = 6;
  * variant compares calendar days and renders the clock time in `timeZone`
  * (default `"UTC"`).
  *
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
+ *
  * @param value UTC ISO string to format
- * @param locale optional: BCP 47 locale tag
- * @param options optional: { reference, timeZone, timeStyle }
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
+ * @param options optional: { reference, timeZone (default "UTC"; "local" is the system zone; an unknown zone returns ""), timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 2:30 PM"
- * @example formatCalendarUtc(value, "fr-FR", { timeZone: "Europe/Paris" }) // "demain à 14:30"
+ * @example formatCalendarUtc("2026-03-16T13:30:00Z", "fr-FR", { timeZone: "Europe/Paris", reference: "2026-03-15T12:00:00Z" }) // "demain à 14:30"
+ * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", null as never) // ""
  * @example formatCalendarUtc("not-a-date") // ""
+ * @example formatCalendarUtc("2024-03-16T18:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T13:00:00Z" }) // "demain à 18:30"
  */
 export function formatCalendarUtc(value, locale, options = {}) {
-    if (!isValidUtc(value))
-        return "";
-    if (options.reference !== undefined && !isValidUtc(options.reference))
-        return "";
-    const target = toInstantFromUtc(value);
-    if (target === null)
-        return "";
-    let reference;
-    if (options.reference) {
-        const ref = toInstantFromUtc(options.reference);
-        if (ref === null)
+    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 "";
+        if (!isValidUtc(value))
+            return "";
+        // ECMA-402 throws RangeError for an unknown zone: the sentinel, never a silent UTC.
+        const timeZone = normalizeTimeZone(options.timeZone);
+        if (!timeZone)
+            return "";
+        if (options.reference !== undefined && !isValidUtc(options.reference))
+            return "";
+        const target = toInstantFromUtc(value);
+        if (target === null)
+            return "";
+        const reference = toReferenceInstantFromUtc(options.reference);
+        if (reference === null)
             return "";
-        reference = ref;
-    }
-    else {
         try {
-            reference = Temporal.Now.instant();
+            return formatCalendarInstants(target, reference, timeZone, locale, options.timeStyle === undefined ? "short" : options.timeStyle);
         }
         catch {
             return "";
         }
     }
-    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/utc/format/formatHttp.d.ts

@@ -1,8 +1,8 @@
 /**
- * Format a UTC ISO 8601 datetime string as an RFC 7231 IMF-fixdate — the
+ * Format a UTC ISO 8601 datetime string as an RFC 9110 IMF-fixdate — the
  * fixed grammar HTTP headers like `Last-Modified`/`Date`/`Expires` require.
  *
- * - **Fixed grammar, not a display format.** RFC 7231 mandates English
+ * - **Fixed grammar, not a display format.** RFC 9110 mandates English
  *   weekday/month abbreviations and a literal `GMT` suffix regardless of
  *   caller locale — there is no locale-appropriate alternative ordering to
  *   lose (see roadmap `issues/J.md` Decision 1 / J13).
@@ -11,12 +11,18 @@
  *   sub-second field.
  * - Day, hour, minute, and second are always zero-padded to 2 digits; year
  *   is zero-padded to 4 digits.
+ * - Returns `""` for a year outside 0000–9999: IMF-fixdate's `year = 4DIGIT`.
+ * - **Compatibility:** before 1.16.0 such years gave strings outside the
+ *   grammar (`"00-1"`, `"275760"`). For the value itself use
+ *   `Temporal.Instant#toString()`.
  *
  * @param value UTC ISO 8601 datetime string (e.g. "2024-03-15T14:30:00Z")
- * @returns RFC 7231 IMF-fixdate string, or "" on invalid input
+ * @returns RFC 9110 IMF-fixdate string, or "" on invalid input or a year outside 0000–9999
  *
  * @example formatHttp("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
  * @example formatHttp("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttp("-000001-06-15T12:00:00Z") // ""
+ * @example Temporal.Instant.from("-000001-06-15T12:00:00Z").toString() // "-000001-06-15T12:00:00Z"
  * @example formatHttp("invalid") // ""
  */
 export declare function formatHttp(value: string): string;

package/dist/utc/format/formatHttp.js

@@ -1,11 +1,11 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES } from "../../internal/index.js";
+import { englishDateTimeStem } from "../../internal/englishCalendarNames.js";
 import { isValidUtc } from "../validate/index.js";
 /**
- * Format a UTC ISO 8601 datetime string as an RFC 7231 IMF-fixdate — the
+ * Format a UTC ISO 8601 datetime string as an RFC 9110 IMF-fixdate — the
  * fixed grammar HTTP headers like `Last-Modified`/`Date`/`Expires` require.
  *
- * - **Fixed grammar, not a display format.** RFC 7231 mandates English
+ * - **Fixed grammar, not a display format.** RFC 9110 mandates English
  *   weekday/month abbreviations and a literal `GMT` suffix regardless of
  *   caller locale — there is no locale-appropriate alternative ordering to
  *   lose (see roadmap `issues/J.md` Decision 1 / J13).
@@ -14,12 +14,18 @@ import { isValidUtc } from "../validate/index.js";
  *   sub-second field.
  * - Day, hour, minute, and second are always zero-padded to 2 digits; year
  *   is zero-padded to 4 digits.
+ * - Returns `""` for a year outside 0000–9999: IMF-fixdate's `year = 4DIGIT`.
+ * - **Compatibility:** before 1.16.0 such years gave strings outside the
+ *   grammar (`"00-1"`, `"275760"`). For the value itself use
+ *   `Temporal.Instant#toString()`.
  *
  * @param value UTC ISO 8601 datetime string (e.g. "2024-03-15T14:30:00Z")
- * @returns RFC 7231 IMF-fixdate string, or "" on invalid input
+ * @returns RFC 9110 IMF-fixdate string, or "" on invalid input or a year outside 0000–9999
  *
  * @example formatHttp("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
  * @example formatHttp("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttp("-000001-06-15T12:00:00Z") // ""
+ * @example Temporal.Instant.from("-000001-06-15T12:00:00Z").toString() // "-000001-06-15T12:00:00Z"
  * @example formatHttp("invalid") // ""
  */
 export function formatHttp(value) {
@@ -27,14 +33,10 @@ export function formatHttp(value) {
         return "";
     try {
         const zdt = Temporal.Instant.from(value).toZonedDateTimeISO("UTC");
-        const weekday = ENGLISH_WEEKDAY_NAMES[zdt.dayOfWeek - 1];
-        const day = String(zdt.day).padStart(2, "0");
-        const month = ENGLISH_MONTH_NAMES[zdt.month - 1];
-        const year = String(zdt.year).padStart(4, "0");
-        const hour = String(zdt.hour).padStart(2, "0");
-        const minute = String(zdt.minute).padStart(2, "0");
-        const second = String(zdt.second).padStart(2, "0");
-        return `${weekday}, ${day} ${month} ${year} ${hour}:${minute}:${second} GMT`;
+        // IMF-fixdate year = 4DIGIT (RFC 9110 §5.6.7).
+        if (zdt.year < 0 || zdt.year > 9999)
+            return "";
+        return `${englishDateTimeStem(zdt)} GMT`;
     }
     catch {
         return "";

package/dist/utc/format/formatRelativeUtc.d.ts

@@ -1,33 +1,35 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
-export interface FormatRelativeUtcOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
+import type { RelativeTimeFormatOptions, RelativeUnit } from "../../types/index.js";
+export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
     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.
-     */
-    roundingMethod?: RelativeRoundingMethod;
     reference?: string;
     timeZone?: string;
 }
 /**
  * Format the relative time between a UTC ISO string 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"`; pass `"local"` for the system time zone. An unknown zone returns `""` whatever the unit
+ *   (ECMA-402 throws RangeError for it).
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
  *
  * @param value UTC ISO string 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, reference, timeZone }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeUtc("2024-03-17T14:30:45+00:00[UTC]", "en-US") // "2 years ago"
- * @example formatRelativeUtc(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }) // "3 months ago"
+ * @example formatRelativeUtc("2026-01-15T00:00:00Z", "en-US", { reference: "2026-01-15T10:30:00Z", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeUtc("2026-01-15T00:00:00Z", "en-US", { reference: "2026-01-15T00:30:00Z", timeZone: "Invalid/Zone" }) // ""
+ * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", null as never) // ""
  * @example formatRelativeUtc("not-a-date") // ""
+ * @example formatRelativeUtc("2024-03-15T11:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00Z" }) // "il y a 30 minutes"
  */
-export declare function formatRelativeUtc(value: string, locale?: string, options?: FormatRelativeUtcOptions): string;
-export {};
+export declare function formatRelativeUtc(value: string, locale?: string | string[], options?: FormatRelativeUtcOptions): string;

package/dist/utc/format/formatRelativeUtc.js

@@ -1,76 +1,68 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { resolveRelativeRounding } from "../../internal/resolveRelativeRounding.js";
-import { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
+import { toInstantFromUtc, toReferenceInstantFromUtc, } from "../../internal/toInstantFromUtc.js";
+import { durationTotal } from "../../internal/zonedWallClockDifference.js";
 import { isValidUtc } from "../validate/index.js";
-const AUTO_UNITS = [
-    { unit: "second", maxSeconds: 60 },
-    { unit: "minute", maxSeconds: 3_600 },
-    { unit: "hour", maxSeconds: 86_400 },
-    { unit: "day", maxSeconds: Infinity },
-];
 /**
  * Format the relative time between a UTC ISO string 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"`; pass `"local"` for the system time zone. An unknown zone returns `""` whatever the unit
+ *   (ECMA-402 throws RangeError for it).
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
  *
  * @param value UTC ISO string 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, reference, timeZone }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeUtc("2024-03-17T14:30:45+00:00[UTC]", "en-US") // "2 years ago"
- * @example formatRelativeUtc(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }) // "3 months ago"
+ * @example formatRelativeUtc("2026-01-15T00:00:00Z", "en-US", { reference: "2026-01-15T10:30:00Z", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeUtc("2026-01-15T00:00:00Z", "en-US", { reference: "2026-01-15T00:30:00Z", timeZone: "Invalid/Zone" }) // ""
+ * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", null as never) // ""
  * @example formatRelativeUtc("not-a-date") // ""
+ * @example formatRelativeUtc("2024-03-15T11:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00Z" }) // "il y a 30 minutes"
  */
 export function formatRelativeUtc(value, locale, options = {}) {
-    if (!isValidUtc(value))
-        return "";
-    if (options.reference !== undefined && !isValidUtc(options.reference))
-        return "";
-    const target = toInstantFromUtc(value);
-    if (target === null)
-        return "";
-    let reference;
-    if (options.reference) {
-        const ref = toInstantFromUtc(options.reference);
-        if (ref === null)
+    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 "";
-        reference = ref;
-    }
-    else {
-        try {
-            reference = Temporal.Now.instant();
-        }
-        catch {
+        if (!isValidUtc(value))
+            return "";
+        const tz = normalizeTimeZone(options.timeZone);
+        if (!tz)
+            return "";
+        if (options.reference !== undefined && !isValidUtc(options.reference))
+            return "";
+        const target = toInstantFromUtc(value);
+        if (target === null)
+            return "";
+        const reference = toReferenceInstantFromUtc(options.reference);
+        if (reference === null)
             return "";
-        }
-    }
-    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);
+            // Only a calendrical unit (month, year) reads the anchor, so the zone is applied lazily.
+            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/utc/format/formatUtc.d.ts

@@ -1,5 +1,55 @@
+/**
+ * Options for `formatUtc`. Extends `Intl.DateTimeFormatOptions`; only the
+ * added/overridden members are listed below. All `Intl.DateTimeFormatOptions`
+ * (`dateStyle`, `timeStyle`, etc.) apply to the time-of-day portion.
+ *
+ * @remarks Members:
+ *
+ * | Member | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `timeZone` | `string` | `"UTC"` | IANA zone for rendering; omitted is UTC, `"local"` is the system zone, and an unknown zone makes `formatUtc` return `""`. |
+ * | `includeTimeZoneName` | `boolean` | `false` | Appends the localized zone name (style via `Intl`) when true. |
+ *
+ * @example
+ * import { FormatUtcOptions } from "@northguild/gmt/utc";
+ * const opts: FormatUtcOptions = { includeTimeZoneName: true };
+ */
 export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
     timeZone?: string;
     includeTimeZoneName?: boolean;
 }
-export declare function formatUtc(value: string, locale?: string, options?: FormatUtcOptions): string;
+/**
+ * Format a UTC ISO string as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid UTC string.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `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 UTC ISO string to format
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
+ * @param options optional: { timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York" }) // "3/16/2026, 2:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", includeTimeZoneName: true }) // "3/16/2026, 2:30:00 PM EDT"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZoneName: "short" }) // "2/3/2024, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZone: "Europe/Londn" }) // "" (unknown zone)
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
+ * @example formatUtc("not-a-date") // ""
+ * @example formatUtc("2024-02-03T14:30:45Z", ["fr-FR", "en-US"], { dateStyle: "long" }) // "3 février 2024"
+ */
+export declare function formatUtc(value: string, locale?: string | string[], options?: FormatUtcOptions): string;

package/dist/utc/format/formatUtc.js

@@ -1,23 +1,69 @@
+// 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 { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
 import { isValidUtc } from "../validate/index.js";
+/**
+ * Format a UTC ISO string as a localized date/time string.
+ *
+ * - Returns `""` if the input is not a valid UTC string.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `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 UTC ISO string to format
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
+ * @param options optional: { timeZone, includeTimeZoneName }
+ * @returns the formatted date/time string, or "" on invalid input
+ *
+ * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York" }) // "3/16/2026, 2:30:00 PM"
+ * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", includeTimeZoneName: true }) // "3/16/2026, 2:30:00 PM EDT"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZoneName: "short" }) // "2/3/2024, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZone: "Europe/Londn" }) // "" (unknown zone)
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
+ * @example formatUtc("not-a-date") // ""
+ * @example formatUtc("2024-02-03T14:30:45Z", ["fr-FR", "en-US"], { dateStyle: "long" }) // "3 février 2024"
+ */
 export function formatUtc(value, locale, options) {
-    if (!isValidUtc(value))
-        return "";
-    const { timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
-    const instant = toInstantFromUtc(value);
-    if (instant === null)
-        return "";
     try {
+        // ECMA-402 CoerceOptionsToObject: undefined is defaults; null is a TypeError.
+        if (options === null)
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        const { timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        const instant = toInstantFromUtc(value);
+        if (instant === null)
+            return "";
+        // ECMA-402 throws RangeError for an unknown zone: the sentinel, never a silent UTC.
         const tz = normalizeTimeZone(timeZone);
-        const zdt = instant.toZonedDateTimeISO(tz);
-        const out = includeTimeZoneName
-            ? zdt.toLocaleString(locale, intlOptions)
-            : zdt.toPlainDateTime().toLocaleString(locale, intlOptions);
-        return normalizeDateTime(out);
+        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 "";
     }
 }