@northguild/gmt 1.14.2

package/dist/zoned/convert/convertZonedToCalendar.d.ts

@@ -0,0 +1,49 @@
+import type { CalendarSystem } from "../../types/index.js";
+/**
+ * Convert a zoned datetime to the same instant expressed in a different calendar system.
+ *
+ * - Accepts a bare ISO zoned datetime ("2024-10-03T14:30:45-04:00[America/New_York]") or a
+ *   calendar-annotated zoned datetime previously produced by this function
+ *   ("5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]"), so conversions can chain
+ *   between calendar systems.
+ * - The instant, the wall time, the UTC offset and the IANA zone are all unchanged — only the
+ *   calendar the date fields resolve through changes.
+ * - The output for "gregorian" is always a bare, unannotated ISO zoned string, matching every
+ *   other GMT zoned string. Any other calendar returns its own native year/month/day tagged with
+ *   `[u-ca=<identifier>]`, placed BEFORE the `[timeZone]` segment.
+ * - **The segment ordering `[u-ca=...][timeZone]` is the reverse of RFC 9557 and is deliberate.**
+ *   GMT's digits are calendar-native, so the string is never valid RFC 9557 anyway; ordering the
+ *   annotation first makes Temporal reject the whole shape instead of silently misreading a
+ *   Hebrew year 5784 as ISO year 5784. See `regex/calendar-zoned-date-time.ts`.
+ * - Uses Temporal's built-in calendar support for every calendar except the Ethiopic family
+ *   ("ethiopic" / "ethiopic-amete-alem" / "coptic"), which is computed with GMT-owned arithmetic
+ *   through the ICU-independent "ethioaa" carrier — see `internal/ethiopicFamilyCalendar.ts`.
+ * - Returns "" on invalid input or an unsupported `calendar`.
+ *
+ * "japanese" and "ethiopic" are the two calendars tagged with an era instead of a plain native
+ * year — see the README's calendar-systems section for why.
+ *
+ * @param value ISO zoned datetime string, optionally calendar-annotated
+ * @param calendar target calendar system ("gregorian" | "hebrew" | "islamic-civil" |
+ *   "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" |
+ *   "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic")
+ * @returns calendar-native zoned datetime string, or "" on invalid input
+ *
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew") // "5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]"
+ * @example convertZonedToCalendar("5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]", "gregorian") // "2024-10-03T14:30:45-04:00[America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "gregorian") // "2024-10-03T14:30:45-04:00[America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "islamic-civil") // "1446-03-29T14:30:45-04:00[u-ca=islamic-civil][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "islamic-tabular") // "1446-03-30T14:30:45-04:00[u-ca=islamic-tabular][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "islamic-umalqura") // "1446-03-30T14:30:45-04:00[u-ca=islamic-umalqura][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "japanese") // "0006-10-03T14:30:45-04:00[u-ca=japanese;era=reiwa][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "buddhist") // "2567-10-03T14:30:45-04:00[u-ca=buddhist][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "taiwan") // "0113-10-03T14:30:45-04:00[u-ca=taiwan][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "persian") // "1403-07-12T14:30:45-04:00[u-ca=persian][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "indian") // "1946-07-11T14:30:45-04:00[u-ca=indian][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "ethiopic") // "2017-01-23T14:30:45-04:00[u-ca=ethiopic;era=ethiopic][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "ethiopic-amete-alem") // "7517-01-23T14:30:45-04:00[u-ca=ethiopic-amete-alem][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "coptic") // "1741-01-23T14:30:45-04:00[u-ca=coptic][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]", "gregorian") // "" (Temporal's segment ordering is not GMT's grammar)
+ * @example convertZonedToCalendar("invalid", "hebrew") // ""
+ */
+export declare function convertZonedToCalendar(value: string, calendar: CalendarSystem): string;

package/dist/zoned/convert/convertZonedToCalendar.js

@@ -0,0 +1,67 @@
+import { formatZonedInCalendar, isEthiopicFamilyCalendar, parseCalendarZonedValue, temporalCalendarIds, } from "../../internal/index.js";
+import { isValidCalendarZonedDateTime } from "../validate/index.js";
+/**
+ * Convert a zoned datetime to the same instant expressed in a different calendar system.
+ *
+ * - Accepts a bare ISO zoned datetime ("2024-10-03T14:30:45-04:00[America/New_York]") or a
+ *   calendar-annotated zoned datetime previously produced by this function
+ *   ("5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]"), so conversions can chain
+ *   between calendar systems.
+ * - The instant, the wall time, the UTC offset and the IANA zone are all unchanged — only the
+ *   calendar the date fields resolve through changes.
+ * - The output for "gregorian" is always a bare, unannotated ISO zoned string, matching every
+ *   other GMT zoned string. Any other calendar returns its own native year/month/day tagged with
+ *   `[u-ca=<identifier>]`, placed BEFORE the `[timeZone]` segment.
+ * - **The segment ordering `[u-ca=...][timeZone]` is the reverse of RFC 9557 and is deliberate.**
+ *   GMT's digits are calendar-native, so the string is never valid RFC 9557 anyway; ordering the
+ *   annotation first makes Temporal reject the whole shape instead of silently misreading a
+ *   Hebrew year 5784 as ISO year 5784. See `regex/calendar-zoned-date-time.ts`.
+ * - Uses Temporal's built-in calendar support for every calendar except the Ethiopic family
+ *   ("ethiopic" / "ethiopic-amete-alem" / "coptic"), which is computed with GMT-owned arithmetic
+ *   through the ICU-independent "ethioaa" carrier — see `internal/ethiopicFamilyCalendar.ts`.
+ * - Returns "" on invalid input or an unsupported `calendar`.
+ *
+ * "japanese" and "ethiopic" are the two calendars tagged with an era instead of a plain native
+ * year — see the README's calendar-systems section for why.
+ *
+ * @param value ISO zoned datetime string, optionally calendar-annotated
+ * @param calendar target calendar system ("gregorian" | "hebrew" | "islamic-civil" |
+ *   "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" |
+ *   "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic")
+ * @returns calendar-native zoned datetime string, or "" on invalid input
+ *
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew") // "5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]"
+ * @example convertZonedToCalendar("5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]", "gregorian") // "2024-10-03T14:30:45-04:00[America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "gregorian") // "2024-10-03T14:30:45-04:00[America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "islamic-civil") // "1446-03-29T14:30:45-04:00[u-ca=islamic-civil][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "islamic-tabular") // "1446-03-30T14:30:45-04:00[u-ca=islamic-tabular][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "islamic-umalqura") // "1446-03-30T14:30:45-04:00[u-ca=islamic-umalqura][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "japanese") // "0006-10-03T14:30:45-04:00[u-ca=japanese;era=reiwa][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "buddhist") // "2567-10-03T14:30:45-04:00[u-ca=buddhist][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "taiwan") // "0113-10-03T14:30:45-04:00[u-ca=taiwan][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "persian") // "1403-07-12T14:30:45-04:00[u-ca=persian][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "indian") // "1946-07-11T14:30:45-04:00[u-ca=indian][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "ethiopic") // "2017-01-23T14:30:45-04:00[u-ca=ethiopic;era=ethiopic][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "ethiopic-amete-alem") // "7517-01-23T14:30:45-04:00[u-ca=ethiopic-amete-alem][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "coptic") // "1741-01-23T14:30:45-04:00[u-ca=coptic][America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]", "gregorian") // "" (Temporal's segment ordering is not GMT's grammar)
+ * @example convertZonedToCalendar("invalid", "hebrew") // ""
+ */
+export function convertZonedToCalendar(value, calendar) {
+    if (!isValidCalendarZonedDateTime(value) ||
+        !(calendar in temporalCalendarIds)) {
+        return "";
+    }
+    try {
+        const zoned = parseCalendarZonedValue(value);
+        // The whole Ethiopic family computes through "ethioaa" rather than Temporal's own
+        // "ethiopic"/"coptic" ids, which throw under ICU >= 78 — see internal/ethiopicFamilyCalendar.ts.
+        const temporalCalendarId = isEthiopicFamilyCalendar(calendar)
+            ? "ethioaa"
+            : temporalCalendarIds[calendar];
+        return formatZonedInCalendar(zoned.withCalendar(temporalCalendarId), calendar);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/convert/convertZonedToPlainDateTime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Convert a zoned ISO 8601 datetime string to a plain datetime string.
+ *
+ * - Extracts the local date-time components without timezone info.
+ * - Validation is performed on the input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns plain datetime string or "" on invalid input
+ *
+ * @example convertZonedToPlainDateTime("2024-02-29T14:30:45.123-05:00[America/New_York]") // "2024-02-29T14:30:45.123"
+ * @example convertZonedToPlainDateTime("invalid") // ""
+ */
+export declare function convertZonedToPlainDateTime(value: string): string;

package/dist/zoned/convert/convertZonedToPlainDateTime.js

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+/**
+ * Convert a zoned ISO 8601 datetime string to a plain datetime string.
+ *
+ * - Extracts the local date-time components without timezone info.
+ * - Validation is performed on the input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns plain datetime string or "" on invalid input
+ *
+ * @example convertZonedToPlainDateTime("2024-02-29T14:30:45.123-05:00[America/New_York]") // "2024-02-29T14:30:45.123"
+ * @example convertZonedToPlainDateTime("invalid") // ""
+ */
+export function convertZonedToPlainDateTime(value) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        return Temporal.ZonedDateTime.from(value).toPlainDateTime().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/convert/convertZonedToUnix.d.ts

@@ -0,0 +1,17 @@
+import { type UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
+/**
+ * Convert an ISO 8601 zoned datetime string to a unix epoch value in milliseconds (default) or seconds.
+ *
+ * - Uses Temporal.ZonedDateTime.toInstant to convert.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns null for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit optional: "seconds" | "milliseconds"
+ * @returns epoch number or null on invalid
+ *
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]") // 1709200496789
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]", "seconds") // 1709200496
+ * @example convertZonedToUnix("invalid") // null
+ */
+export declare function convertZonedToUnix(value: string, ...unitInput: [unit?: UnixUnit]): number | null;

package/dist/zoned/convert/convertZonedToUnix.js

@@ -0,0 +1,34 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUnixUnit, } from "../../unix/validate/isValidUnixUnit.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Convert an ISO 8601 zoned datetime string to a unix epoch value in milliseconds (default) or seconds.
+ *
+ * - Uses Temporal.ZonedDateTime.toInstant to convert.
+ * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Returns null for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit optional: "seconds" | "milliseconds"
+ * @returns epoch number or null on invalid
+ *
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]") // 1709200496789
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]", "seconds") // 1709200496
+ * @example convertZonedToUnix("invalid") // null
+ */
+export function convertZonedToUnix(value, ...unitInput) {
+    const resolvedUnit = unitInput.length === 0 ? "milliseconds" : unitInput[0];
+    if (!isValidZonedDateTime(value) || !isValidUnixUnit(resolvedUnit ?? "")) {
+        return null;
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const milliseconds = Number(zonedDateTime.toInstant().epochMilliseconds);
+        return resolvedUnit === "seconds"
+            ? Math.floor(milliseconds / 1000)
+            : milliseconds;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/zoned/convert/convertZonedToUtc.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Convert an ISO 8601 zoned datetime string to a UTC Instant string (ISO).
+ *
+ * - Uses Temporal.ZonedDateTime.toInstant to convert.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns UTC Instant ISO string or "" when invalid
+ *
+ * @example convertZonedToUtc("2024-02-29T12:34:56.789+00:00[UTC]") // "2024-02-29T12:34:56.789Z"
+ * @example convertZonedToUtc("invalid") // ""
+ */
+export declare function convertZonedToUtc(value: string): string;

package/dist/zoned/convert/convertZonedToUtc.js

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Convert an ISO 8601 zoned datetime string to a UTC Instant string (ISO).
+ *
+ * - Uses Temporal.ZonedDateTime.toInstant to convert.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns UTC Instant ISO string or "" when invalid
+ *
+ * @example convertZonedToUtc("2024-02-29T12:34:56.789+00:00[UTC]") // "2024-02-29T12:34:56.789Z"
+ * @example convertZonedToUtc("invalid") // ""
+ */
+export function convertZonedToUtc(value) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        return Temporal.ZonedDateTime.from(value).toInstant().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/convert/convertZonedToZoned.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert a zoned ISO 8601 datetime string to the same instant in a different `timeZone`.
+ *
+ * - Uses Temporal.ZonedDateTime.withTimeZone to convert.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param timeZone target IANA timeZone identifier
+ * @returns zoned ISO 8601 string in target timeZone or "" when invalid
+ *
+ * @example convertZonedToZoned("2024-02-29T12:34:56.789+00:00[UTC]", "America/New_York") // "2024-02-29T07:34:56.789-05:00[America/New_York]"
+ * @example convertZonedToZoned("invalid", "America/New_York") // ""
+ */
+export declare function convertZonedToZoned(value: string, timeZone: string): string;

package/dist/zoned/convert/convertZonedToZoned.js

@@ -0,0 +1,27 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone, isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Convert a zoned ISO 8601 datetime string to the same instant in a different `timeZone`.
+ *
+ * - Uses Temporal.ZonedDateTime.withTimeZone to convert.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param timeZone target IANA timeZone identifier
+ * @returns zoned ISO 8601 string in target timeZone or "" when invalid
+ *
+ * @example convertZonedToZoned("2024-02-29T12:34:56.789+00:00[UTC]", "America/New_York") // "2024-02-29T07:34:56.789-05:00[America/New_York]"
+ * @example convertZonedToZoned("invalid", "America/New_York") // ""
+ */
+export function convertZonedToZoned(value, timeZone) {
+    if (!isValidZonedDateTime(value) || !isValidTimeZone(timeZone)) {
+        return "";
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        return zonedDateTime.withTimeZone(timeZone).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/convert/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./convertPlainDateTimeToZoned.js";
+export * from "./convertZonedToCalendar.js";
+export * from "./convertZonedToPlainDateTime.js";
+export * from "./convertZonedToUnix.js";
+export * from "./convertZonedToUtc.js";
+export * from "./convertZonedToZoned.js";

package/dist/zoned/convert/index.js

@@ -0,0 +1,6 @@
+export * from "./convertPlainDateTimeToZoned.js";
+export * from "./convertZonedToCalendar.js";
+export * from "./convertZonedToPlainDateTime.js";
+export * from "./convertZonedToUnix.js";
+export * from "./convertZonedToUtc.js";
+export * from "./convertZonedToZoned.js";

package/dist/zoned/format/formatCalendarZoned.d.ts

@@ -0,0 +1,34 @@
+export interface FormatCalendarZonedOptions {
+    /**
+     * Anchor point for the relative diff.
+     *
+     * - ZonedDateTime ISO string: converted into `value`'s own zone before
+     *   comparing calendar days. Unlike `formatRelativeZoned`'s `reference`
+     *   (which keeps a ZonedDateTime reference in its own zone for
+     *   elapsed-time diffing), a calendar *label* is meaningless without
+     *   picking one zone's wall clock — `value`'s zone is the natural choice,
+     *   since that is whose "today" is being described.
+     * - UTC ISO string or numeric epoch (ms): placed into `value`'s timezone.
+     * - Omitted: "now" in `value`'s own timezone.
+     */
+    reference?: string | number;
+    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
+    timeStyle?: "short" | "medium" | "full";
+}
+/**
+ * Format a zoned date-time as a relative day label plus time-of-day, e.g.
+ * "Tomorrow at 2:30 PM" — the zoned counterpart of `formatCalendar`. See
+ * that function's JSDoc for the day-label/threshold/connector design; this
+ * variant differs only in reading `value`'s IANA timezone for both the
+ * calendar-day comparison and the rendered clock time.
+ *
+ * @param value ZonedDateTime ISO string to format
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { reference, timeStyle }
+ * @returns the formatted calendar string, or "" on invalid input
+ *
+ * @example formatCalendarZoned("2026-03-16T14:30:00-04:00[America/New_York]", "en-US", { reference: "2026-03-15T09:00:00-04:00[America/New_York]" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarZoned(value, "de-DE") // "morgen um 14:30"
+ * @example formatCalendarZoned("not-a-date") // ""
+ */
+export declare function formatCalendarZoned(value: string, locale?: string, options?: FormatCalendarZonedOptions): string;

package/dist/zoned/format/formatCalendarZoned.js

@@ -0,0 +1,65 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.js";
+import { isValidUtc } from "../../utc/validate/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+const ABS_DAY_THRESHOLD = 6;
+/**
+ * Format a zoned date-time as a relative day label plus time-of-day, e.g.
+ * "Tomorrow at 2:30 PM" — the zoned counterpart of `formatCalendar`. See
+ * that function's JSDoc for the day-label/threshold/connector design; this
+ * variant differs only in reading `value`'s IANA timezone for both the
+ * calendar-day comparison and the rendered clock time.
+ *
+ * @param value ZonedDateTime ISO string to format
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { reference, timeStyle }
+ * @returns the formatted calendar string, or "" on invalid input
+ *
+ * @example formatCalendarZoned("2026-03-16T14:30:00-04:00[America/New_York]", "en-US", { reference: "2026-03-15T09:00:00-04:00[America/New_York]" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarZoned(value, "de-DE") // "morgen um 14:30"
+ * @example formatCalendarZoned("not-a-date") // ""
+ */
+export function formatCalendarZoned(value, locale, options = {}) {
+    if (!isValidZonedDateTime(value))
+        return "";
+    if (typeof options.reference === "string" &&
+        !isValidZonedDateTime(options.reference) &&
+        !isValidUtc(options.reference))
+        return "";
+    if (typeof options.reference === "number" &&
+        !Number.isFinite(options.reference))
+        return "";
+    try {
+        const target = Temporal.ZonedDateTime.from(value);
+        const timeZone = target.timeZoneId;
+        let reference;
+        if (options.reference == null) {
+            reference = Temporal.Now.zonedDateTimeISO(timeZone);
+        }
+        else if (typeof options.reference === "string") {
+            reference = isValidUtc(options.reference)
+                ? Temporal.Instant.from(options.reference).toZonedDateTimeISO(timeZone)
+                : Temporal.ZonedDateTime.from(options.reference).withTimeZone(timeZone);
+        }
+        else {
+            reference = Temporal.Instant.fromEpochMilliseconds(options.reference).toZonedDateTimeISO(timeZone);
+        }
+        const diffDays = target.toPlainDate().since(reference.toPlainDate()).days;
+        const timeStyle = options.timeStyle ?? "short";
+        const epochMilliseconds = 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 {
+        return "";
+    }
+}

package/dist/zoned/format/formatRelativeZoned.d.ts

@@ -0,0 +1,44 @@
+import type { RelativeRoundingMethod } from "../../types/index.js";
+type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
+export interface FormatRelativeZonedOptions {
+    style?: "long" | "short" | "narrow";
+    numeric?: "always" | "auto";
+    largestUnit?: RelativeUnit;
+    /**
+     * How the computed distance rounds to the display unit: "floor" rounds toward the
+     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
+     * matches current behavior when omitted.
+     */
+    roundingMethod?: RelativeRoundingMethod;
+    /**
+     * Anchor point for the relative diff.
+     *
+     * - ZonedDateTime ISO string: kept in its own zone; Temporal handles
+     *   cross-zone diffs correctly. The label is therefore zone-aware — a value
+     *   and reference in different zones can produce a non-zero diff even when
+     *   they describe the same absolute instant.
+     * - UTC ISO string: placed into `value`'s timezone before diffing so the
+     *   calendar anchor matches the value's wall clock.
+     * - Numeric epoch (ms): same — placed into `value`'s timezone.
+     * - Omitted: "now" in `value`'s own timezone.
+     */
+    reference?: string | number;
+}
+/**
+ * Format the relative time between a zoned date-time and a reference instant.
+ *
+ * - Auto-picks the display unit (second through year) based on the distance, unless
+ *   `largestUnit` forces one.
+ * - `roundingMethod` controls how the distance rounds to the display unit.
+ *
+ * @param value ZonedDateTime ISO string to format
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @returns the formatted relative-time string, or "" on invalid input
+ *
+ * @example formatRelativeZoned("2026-03-08T01:00:00-05:00[America/New_York]", "en-US") // "tomorrow"
+ * @example formatRelativeZoned(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeZoned("not-a-date") // ""
+ */
+export declare function formatRelativeZoned(value: string, locale?: string, options?: FormatRelativeZonedOptions): string;
+export {};

package/dist/zoned/format/formatRelativeZoned.js

@@ -0,0 +1,79 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { isValidUtc } from "../../utc/validate/index.js";
+import { isValidZonedDateTime } 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 zoned date-time and a reference instant.
+ *
+ * - Auto-picks the display unit (second through year) based on the distance, unless
+ *   `largestUnit` forces one.
+ * - `roundingMethod` controls how the distance rounds to the display unit.
+ *
+ * @param value ZonedDateTime ISO string to format
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @returns the formatted relative-time string, or "" on invalid input
+ *
+ * @example formatRelativeZoned("2026-03-08T01:00:00-05:00[America/New_York]", "en-US") // "tomorrow"
+ * @example formatRelativeZoned(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeZoned("not-a-date") // ""
+ */
+export function formatRelativeZoned(value, locale, options = {}) {
+    if (!isValidZonedDateTime(value))
+        return "";
+    // String reference must be a valid ZonedDateTime or UTC ISO string.
+    if (typeof options.reference === "string" &&
+        !isValidZonedDateTime(options.reference) &&
+        !isValidUtc(options.reference))
+        return "";
+    if (typeof options.reference === "number" &&
+        !Number.isFinite(options.reference))
+        return "";
+    try {
+        const valueZDT = Temporal.ZonedDateTime.from(value);
+        const valueInstant = valueZDT.toInstant();
+        let refZDT;
+        if (options.reference == null) {
+            // "now" in value's own zone — keeps the calendar context consistent.
+            refZDT = Temporal.Now.zonedDateTimeISO(valueZDT.timeZoneId);
+        }
+        else if (typeof options.reference === "string") {
+            // UTC string → place into value's zone for a consistent calendar anchor.
+            // ZonedDateTime string → keep its own zone; Temporal handles cross-zone diffs.
+            // isValidUtc covers both `Z` and `z` suffixes (the regex accepts [Zz]).
+            refZDT = isValidUtc(options.reference)
+                ? Temporal.Instant.from(options.reference).toZonedDateTimeISO(valueZDT.timeZoneId)
+                : Temporal.ZonedDateTime.from(options.reference);
+        }
+        else {
+            // Numeric epoch (ms) → place into value's zone.
+            refZDT = Temporal.Instant.fromEpochMilliseconds(options.reference).toZonedDateTimeISO(valueZDT.timeZoneId);
+        }
+        const diff = valueInstant.since(refZDT.toInstant());
+        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);
+        }
+        catch {
+            // month/year are calendrical and need a relativeTo anchor
+            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: refZDT }), options.roundingMethod);
+        }
+        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
+            numeric: options.numeric ?? "auto",
+            style: options.style ?? "long",
+        }).format(amount, unit));
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/format/formatRfc2822.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Format a zoned ISO 8601 datetime string as an RFC 5322 (RFC 2822) date-time
+ * — the fixed grammar email `Date:` headers require.
+ *
+ * - **Fixed grammar, not a display format.** RFC 5322 mandates English
+ *   weekday/month abbreviations and a numeric `+HHMM`/`-HHMM` offset
+ *   regardless of caller locale — there is no locale-appropriate alternative
+ *   ordering to lose, so this does not conflict with Decision 1's exclusion
+ *   of a general token formatter (see roadmap `issues/J.md`, J13).
+ * - Uses the input's own UTC offset at that instant (DST-aware); never emits
+ *   an obsolete named zone like "GMT" or "EST" on output, only numeric.
+ * - Day, hour, minute, and second are always zero-padded to 2 digits; year
+ *   is zero-padded to 4 digits.
+ *
+ * @param value zoned ISO 8601 datetime string (e.g. "2024-03-15T14:30:00-04:00[America/New_York]")
+ * @returns RFC 5322 date-time string, or "" on invalid input
+ *
+ * @example formatRfc2822("2024-03-15T14:30:00-04:00[America/New_York]") // "Fri, 15 Mar 2024 14:30:00 -0400"
+ * @example formatRfc2822("2024-01-05T09:00:00+00:00[UTC]") // "Fri, 05 Jan 2024 09:00:00 +0000"
+ * @example formatRfc2822("invalid") // ""
+ */
+export declare function formatRfc2822(value: string): string;

package/dist/zoned/format/formatRfc2822.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Format a zoned ISO 8601 datetime string as an RFC 5322 (RFC 2822) date-time
+ * — the fixed grammar email `Date:` headers require.
+ *
+ * - **Fixed grammar, not a display format.** RFC 5322 mandates English
+ *   weekday/month abbreviations and a numeric `+HHMM`/`-HHMM` offset
+ *   regardless of caller locale — there is no locale-appropriate alternative
+ *   ordering to lose, so this does not conflict with Decision 1's exclusion
+ *   of a general token formatter (see roadmap `issues/J.md`, J13).
+ * - Uses the input's own UTC offset at that instant (DST-aware); never emits
+ *   an obsolete named zone like "GMT" or "EST" on output, only numeric.
+ * - Day, hour, minute, and second are always zero-padded to 2 digits; year
+ *   is zero-padded to 4 digits.
+ *
+ * @param value zoned ISO 8601 datetime string (e.g. "2024-03-15T14:30:00-04:00[America/New_York]")
+ * @returns RFC 5322 date-time string, or "" on invalid input
+ *
+ * @example formatRfc2822("2024-03-15T14:30:00-04:00[America/New_York]") // "Fri, 15 Mar 2024 14:30:00 -0400"
+ * @example formatRfc2822("2024-01-05T09:00:00+00:00[UTC]") // "Fri, 05 Jan 2024 09:00:00 +0000"
+ * @example formatRfc2822("invalid") // ""
+ */
+export function formatRfc2822(value) {
+    if (!isValidZonedDateTime(value))
+        return "";
+    try {
+        const zdt = Temporal.ZonedDateTime.from(value);
+        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");
+        const totalOffsetMinutes = zdt.offsetNanoseconds / 60_000_000_000;
+        const sign = totalOffsetMinutes < 0 ? "-" : "+";
+        const absMinutes = Math.abs(totalOffsetMinutes);
+        const offsetHH = String(Math.trunc(absMinutes / 60)).padStart(2, "0");
+        const offsetMM = String(absMinutes % 60).padStart(2, "0");
+        return `${weekday}, ${day} ${month} ${year} ${hour}:${minute}:${second} ${sign}${offsetHH}${offsetMM}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/format/formatRfc3339.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Format a zoned ISO 8601 datetime string as strict RFC 3339 — the ISO 8601
+ * *profile* RFC 3339 §5.6 defines, permitting only an explicit numeric
+ * offset or `Z`, never a bracketed IANA zone name.
+ *
+ * - **Not a passthrough.** GMT's own zoned strings always carry a bracketed
+ *   IANA zone annotation (e.g. `...+00:00[UTC]`) that plain
+ *   `Temporal.ZonedDateTime.prototype.toString()` reproduces by default —
+ *   that annotation is *not* valid RFC 3339. This function's only job is to
+ *   strip it (`{ timeZoneName: "never" }`), which is exactly the detail a
+ *   caller reaching for "give me RFC 3339" would otherwise miss. (Go/no-go
+ *   recorded in roadmap `issues/J.md` J13: this narrow gap is real; a
+ *   parallel `utc`/`unix` wrapper was *not* added, because
+ *   `Temporal.Instant.prototype.toString()` is already fully RFC 3339
+ *   compliant with no bracket to strip — that would be a pure passthrough.)
+ *
+ * @param value zoned ISO 8601 datetime string (e.g. "2024-03-15T14:30:00-04:00[America/New_York]")
+ * @returns RFC 3339 datetime string, or "" on invalid input
+ *
+ * @example formatRfc3339("2024-03-15T14:30:00-04:00[America/New_York]") // "2024-03-15T14:30:00-04:00"
+ * @example formatRfc3339("2024-03-15T14:30:00Z[UTC]") // "2024-03-15T14:30:00+00:00"
+ * @example formatRfc3339("invalid") // ""
+ */
+export declare function formatRfc3339(value: string): string;