@northguild/gmt 1.15.0 → 1.17.0

package/dist/utc/compare/areUtcEqualBy.js

@@ -1,7 +1,10 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTimeUnit } from "../../plain/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { startOfUtc } from "../calculate/startOfUtc.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Compare two UTC ISO datetime strings for equality at a given unit.
  *
@@ -9,7 +12,12 @@ import { isValidUtc } from "../validate/index.js";
  *   so `"day"` always means the UTC calendar day (UTC has no DST, so this is
  *   unambiguous).
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
+ * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
+ * - Takes no `fractionalSecondDigits`: equality compares full-precision `unit` boundaries, and output
+ *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
+ *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
  * - `isSameDay(a, b)` → `areUtcEqualBy(a, b, "day")`
@@ -18,28 +26,43 @@ import { isValidUtc } from "../validate/index.js";
  *
  * @param value1 first UTC ISO datetime string
  * @param value2 second UTC ISO datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param unit date or time unit, singular or plural, to compare by
+ * @param options optional: weekStartsOn ("monday" | "sunday")
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUtcEqualBy("2024-03-15T02:00:00Z", "2024-03-15T22:00:00Z", "day") // true
  * @example areUtcEqualBy("2024-03-15T23:30:00Z", "2024-03-16T00:30:00Z", "day") // false
+ * @example areUtcEqualBy("2024-05-15T10:20:30.123Z", "2024-05-15T10:20:30.999Z", "milliseconds") // false (different milliseconds)
+ * @example areUtcEqualBy("2024-05-15T10:20:30.123Z", "2024-05-15T10:20:30.999Z", "second") // true
  * @example areUtcEqualBy("invalid", "2024-03-15T02:00:00Z", "day") // false
  */
 export function areUtcEqualBy(value1, value2, unit, options) {
-    if (!isValidUtc(value1) ||
-        !isValidUtc(value2) ||
-        !isValidDateTimeUnit(unit)) {
-        return false;
-    }
     try {
-        const start1 = startOfUtc(value1, unit, options);
-        const start2 = startOfUtc(value2, unit, options);
-        if (start1 === "" || start2 === "")
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
+        if (!isValidUtc(value1) ||
+            !isValidUtc(value2) ||
+            !isValidDateTimeUnit(resolvedUnit) ||
+            weekStartsOn === null) {
+            return false;
+        }
+        try {
+            const start1 = startOfUtc(value1, resolvedUnit, { weekStartsOn });
+            const start2 = startOfUtc(value2, resolvedUnit, { weekStartsOn });
+            if (start1 === "" || start2 === "")
+                return false;
+            return (Temporal.Instant.compare(Temporal.Instant.from(start1), Temporal.Instant.from(start2)) === 0);
+        }
+        catch {
             return false;
-        return (Temporal.Instant.compare(Temporal.Instant.from(start1), Temporal.Instant.from(start2)) === 0);
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/utc/convert/convertUtcToPlainDate.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../../zoned/index.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain date string in the format "YYYY-MM-DD".
  *
@@ -17,19 +19,29 @@ import { isValidUtc } from "../validate/index.js";
  * @example convertUtcToPlainDate("invalid") // ""
  */
 export function convertUtcToPlainDate(value, options) {
-    const { timeZone = "UTC" } = options ?? {};
-    if (!isValidTimeZone(timeZone))
-        return "";
-    if (!isValidUtc(value))
-        return "";
     try {
-        const instant = Temporal.Instant.from(value);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-            .toString()
-            .padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`;
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const { timeZone = "UTC" } = options ?? {};
+        if (!isValidTimeZone(timeZone))
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
+                .toString()
+                .padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`;
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/convert/convertUtcToPlainDateTime.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../../zoned/index.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
@@ -17,25 +19,35 @@ import { isValidUtc } from "../validate/index.js";
  * @example convertUtcToPlainDateTime("invalid") // ""
  */
 export function convertUtcToPlainDateTime(value, options) {
-    const { timeZone = "UTC" } = options ?? {};
-    if (!isValidTimeZone(timeZone))
-        return "";
-    if (!isValidUtc(value))
-        return "";
     try {
-        const instant = Temporal.Instant.from(value);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-            .toString()
-            .padStart(2, "0")}-${zonedDateTime.day
-            .toString()
-            .padStart(2, "0")}T${zonedDateTime.hour
-            .toString()
-            .padStart(2, "0")}:${zonedDateTime.minute
-            .toString()
-            .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const { timeZone = "UTC" } = options ?? {};
+        if (!isValidTimeZone(timeZone))
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
+                .toString()
+                .padStart(2, "0")}-${zonedDateTime.day
+                .toString()
+                .padStart(2, "0")}T${zonedDateTime.hour
+                .toString()
+                .padStart(2, "0")}:${zonedDateTime.minute
+                .toString()
+                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/convert/convertUtcToPlainTime.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../../zoned/index.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain time string in the format "HH:mm:ss".
  *
@@ -17,19 +19,29 @@ import { isValidUtc } from "../validate/index.js";
  * @example convertUtcToPlainTime("invalid") // ""
  */
 export function convertUtcToPlainTime(value, options) {
-    const { timeZone = "UTC" } = options ?? {};
-    if (!isValidTimeZone(timeZone))
-        return "";
-    if (!isValidUtc(value))
-        return "";
     try {
-        const instant = Temporal.Instant.from(value);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return `${zonedDateTime.hour.toString().padStart(2, "0")}:${zonedDateTime.minute
-            .toString()
-            .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const { timeZone = "UTC" } = options ?? {};
+        if (!isValidTimeZone(timeZone))
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+            return `${zonedDateTime.hour.toString().padStart(2, "0")}:${zonedDateTime.minute
+                .toString()
+                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -2,8 +2,8 @@ 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 extends CalendarOptions {
  * 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

@@ -7,17 +7,29 @@ export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
 /**
  * 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 declare function formatRelativeUtc(value: string, locale?: string | string[], options?: FormatRelativeUtcOptions): string;