@northguild/gmt 1.15.0 → 1.17.0

package/dist/zoned/format/formatCalendarZoned.js

@@ -1,65 +1,63 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { formatCalendarDays } from "../../internal/formatCalendarDays.js";
 import { isValidUtc } from "../../utc/validate/index.js";
+import { isValidZonedFormatReference } from "../../internal/zonedFormatReference.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.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ZonedDateTime 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: { 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("2026-03-16T14:30:00+01:00[Europe/Berlin]", "de-DE", { reference: "2026-03-15T09:00:00+01:00[Europe/Berlin]" }) // "morgen um 14:30"
  * @example formatCalendarZoned("not-a-date") // ""
+ * @example formatCalendarZoned("2024-03-16T14:30:00-04:00[America/New_York]", ["fr-FR", "en-US"], { reference: "2024-03-15T09:00:00-04:00[America/New_York]" }) // "demain à 14:30"
+ * @example formatCalendarZoned("2024-03-12T10:00:00-04:00[America/New_York]", "en-US", null as never) // "" (null options)
  */
 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);
+        // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
+        // invalid input.
+        if (options === null || typeof options !== "object")
+            return "";
+        if (!isValidZonedDateTime(value))
+            return "";
+        if (!isValidZonedFormatReference(options.reference))
+            return "";
+        try {
+            const target = zonedDateTimeFrom(value);
+            const timeZone = target.timeZoneId;
+            let reference;
+            if (options.reference === undefined) {
+                reference = Temporal.Now.zonedDateTimeISO(timeZone);
+            }
+            else if (typeof options.reference === "string") {
+                reference = isValidUtc(options.reference)
+                    ? Temporal.Instant.from(options.reference).toZonedDateTimeISO(timeZone)
+                    : zonedDateTimeFrom(options.reference).withTimeZone(timeZone);
+            }
+            else {
+                reference = Temporal.Instant.fromEpochMilliseconds(options.reference).toZonedDateTimeISO(timeZone);
+            }
+            return formatCalendarDays(target.toPlainDate().since(reference.toPlainDate()).days, target.epochMilliseconds, timeZone, locale, options.timeStyle === undefined ? "short" : options.timeStyle);
         }
-        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));
+        catch {
+            return "";
         }
-        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/zoned/format/formatRelativeZoned.d.ts

@@ -21,17 +21,26 @@ export interface FormatRelativeZonedOptions {
 /**
  * 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.
+ * - 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.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ZonedDateTime 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 }
  * @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("2023-12-29T00:00:00+00:00[UTC]", "en-US", { reference: "2024-02-29T00:00:00+00:00[UTC]" }) // "2 months ago"
+ * @example formatRelativeZoned("2026-03-08T01:00:00-05:00[America/New_York]", "en-US", { reference: "2026-03-07T01:00:00-05:00[America/New_York]" }) // "tomorrow"
+ * @example formatRelativeZoned("2026-01-15T00:00:00+00:00[UTC]", "en-US", { reference: "2026-01-15T10:30:00+00:00[UTC]", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
  * @example formatRelativeZoned("not-a-date") // ""
+ * @example formatRelativeZoned("2024-02-28T23:30:00+00:00[UTC]", ["fr-FR", "en-US"], { reference: "2024-02-29T00:00:00+00:00[UTC]" }) // "il y a 30 minutes"
+ * @example formatRelativeZoned("2024-03-12T10:00:00-04:00[America/New_York]", "en-US", null as never) // "" (null options)
  */
-export declare function formatRelativeZoned(value: string, locale?: string, options?: FormatRelativeZonedOptions): string;
+export declare function formatRelativeZoned(value: string, locale?: string | string[], options?: FormatRelativeZonedOptions): string;

package/dist/zoned/format/formatRelativeZoned.js

@@ -1,79 +1,79 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { durationTotal, zonedDateTimeFrom } from "../../internal/index.js";
+import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { isValidUtc } from "../../utc/validate/index.js";
+import { isValidZonedFormatReference } from "../../internal/zonedFormatReference.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.
+ * - 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.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ZonedDateTime 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 }
  * @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("2023-12-29T00:00:00+00:00[UTC]", "en-US", { reference: "2024-02-29T00:00:00+00:00[UTC]" }) // "2 months ago"
+ * @example formatRelativeZoned("2026-03-08T01:00:00-05:00[America/New_York]", "en-US", { reference: "2026-03-07T01:00:00-05:00[America/New_York]" }) // "tomorrow"
+ * @example formatRelativeZoned("2026-01-15T00:00:00+00:00[UTC]", "en-US", { reference: "2026-01-15T10:30:00+00:00[UTC]", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
  * @example formatRelativeZoned("not-a-date") // ""
+ * @example formatRelativeZoned("2024-02-28T23:30:00+00:00[UTC]", ["fr-FR", "en-US"], { reference: "2024-02-29T00:00:00+00:00[UTC]" }) // "il y a 30 minutes"
+ * @example formatRelativeZoned("2024-03-12T10:00:00-04:00[America/New_York]", "en-US", null as never) // "" (null options)
  */
 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;
+        // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
+        // invalid input.
+        if (options === null || typeof options !== "object")
+            return "";
+        if (!isValidZonedDateTime(value))
+            return "";
+        if (!isValidZonedFormatReference(options.reference))
+            return "";
         try {
-            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            const valueZDT = zonedDateTimeFrom(value);
+            const valueInstant = valueZDT.toInstant();
+            const refZDT = resolveZonedReference(options.reference, valueZDT.timeZoneId);
+            const diff = valueInstant.since(refZDT.toInstant());
+            // month/year are calendrical and need a relativeTo anchor
+            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, refZDT));
         }
         catch {
-            // month/year are calendrical and need a relativeTo anchor
-            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: refZDT }), 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 "";
     }
 }
+/**
+ * The reference as a zoned date-time: now or a UTC string or epoch placed into `timeZoneId`, or a
+ * zoned string kept in its own zone. Throws where Temporal throws.
+ */
+function resolveZonedReference(reference, timeZoneId) {
+    if (reference === undefined) {
+        // "now" in value's own zone — keeps the calendar context consistent.
+        return Temporal.Now.zonedDateTimeISO(timeZoneId);
+    }
+    if (typeof 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]).
+        return isValidUtc(reference)
+            ? Temporal.Instant.from(reference).toZonedDateTimeISO(timeZoneId)
+            : zonedDateTimeFrom(reference);
+    }
+    // Numeric epoch (ms) → place into value's zone.
+    return Temporal.Instant.fromEpochMilliseconds(reference).toZonedDateTimeISO(timeZoneId);
+}

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

@@ -11,12 +11,25 @@
  *   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.
+ * - Fractional seconds are truncated: `second = 2DIGIT` has no fraction.
+ * - Returns `""` when the offset is not a whole number of minutes (local mean
+ *   time, e.g. Africa/Monrovia −00:44:30 before 1972): `zone` is
+ *   `("+" / "-") 4DIGIT`, meaning ±(hh·60 + mm) minutes.
+ * - Returns `""` for a negative year: `year = 4*DIGIT` has no sign. Years of
+ *   five or more digits are written in full.
+ * - **Compatibility:** before 1.16.0 these inputs gave strings outside the
+ *   grammar (`"-0044.5"`, `"00-1"`). For the value itself use
+ *   `Temporal.ZonedDateTime#toString()`.
  *
  * @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
+ * @returns RFC 5322 date-time string, or "" on invalid input, a sub-minute offset or a negative year
  *
  * @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("2024-03-15T14:30:00.999-04:00[America/New_York]") // "Fri, 15 Mar 2024 14:30:00 -0400"
+ * @example formatRfc2822("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // "" (offset −00:44:30)
+ * @example formatRfc2822("-000001-06-15T12:00:00+00:00[UTC]") // ""
+ * @example Temporal.ZonedDateTime.from("-000001-06-15T12:00:00+00:00[UTC]").toString() // "-000001-06-15T12:00:00+00:00[UTC]"
  * @example formatRfc2822("invalid") // ""
  */
 export declare function formatRfc2822(value: string): string;

package/dist/zoned/format/formatRfc2822.js

@@ -1,6 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES } from "../../internal/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { englishDateTimeStem } from "../../internal/englishCalendarNames.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+const NANOSECONDS_PER_MINUTE = 60_000_000_000;
 /**
  * Format a zoned ISO 8601 datetime string as an RFC 5322 (RFC 2822) date-time
  * — the fixed grammar email `Date:` headers require.
@@ -14,32 +15,45 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *   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.
+ * - Fractional seconds are truncated: `second = 2DIGIT` has no fraction.
+ * - Returns `""` when the offset is not a whole number of minutes (local mean
+ *   time, e.g. Africa/Monrovia −00:44:30 before 1972): `zone` is
+ *   `("+" / "-") 4DIGIT`, meaning ±(hh·60 + mm) minutes.
+ * - Returns `""` for a negative year: `year = 4*DIGIT` has no sign. Years of
+ *   five or more digits are written in full.
+ * - **Compatibility:** before 1.16.0 these inputs gave strings outside the
+ *   grammar (`"-0044.5"`, `"00-1"`). For the value itself use
+ *   `Temporal.ZonedDateTime#toString()`.
  *
  * @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
+ * @returns RFC 5322 date-time string, or "" on invalid input, a sub-minute offset or a negative year
  *
  * @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("2024-03-15T14:30:00.999-04:00[America/New_York]") // "Fri, 15 Mar 2024 14:30:00 -0400"
+ * @example formatRfc2822("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // "" (offset −00:44:30)
+ * @example formatRfc2822("-000001-06-15T12:00:00+00:00[UTC]") // ""
+ * @example Temporal.ZonedDateTime.from("-000001-06-15T12:00:00+00:00[UTC]").toString() // "-000001-06-15T12:00:00+00:00[UTC]"
  * @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 zdt = zonedDateTimeFrom(value);
+        // zone = ("+" / "-") 4DIGIT counts whole minutes (RFC 5322 §3.3); a
+        // local mean time offset such as -00:44:30 has no such form.
+        if (zdt.offsetNanoseconds % NANOSECONDS_PER_MINUTE !== 0)
+            return "";
+        // year = 4*DIGIT: unsigned, so no negative (BCE) year.
+        if (zdt.year < 0)
+            return "";
+        const totalOffsetMinutes = zdt.offsetNanoseconds / NANOSECONDS_PER_MINUTE;
         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}`;
+        return `${englishDateTimeStem(zdt)} ${sign}${offsetHH}${offsetMM}`;
     }
     catch {
         return "";

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

@@ -13,12 +13,25 @@
  *   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.)
+ * - **Sub-minute offsets are written in UTC.** `time-numoffset` holds whole minutes, and RFC 3339
+ *   §4.2 says historical offsets that are not ("applications must convert them to a representable
+ *   time zone"). A local mean time such as Africa/Monrovia's −00:44:30 is therefore written as the
+ *   same instant at `+00:00`. `Z` is not used: RFC 9557 §2.2 gives it the meaning "the offset to
+ *   local time is unknown", and here the offset is known, only not representable.
+ * - Returns `""` for a year outside `date-fullyear = 4DIGIT` (0000–9999).
+ * - Fractional seconds are kept, with trailing zeros dropped.
+ * - **Compatibility:** before 1.16.0 a sub-minute offset was rounded to the minute, naming a
+ *   different instant, and years outside 0000–9999 were written in expanded form. For either
+ *   string use `Temporal.ZonedDateTime#toString({ timeZoneName: "never" })`.
  *
  * @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
+ * @returns RFC 3339 datetime string, or "" on invalid input or a year outside 0000–9999
  *
  * @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("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // "1970-01-01T00:00:00+00:00" (offset −00:44:30)
+ * @example formatRfc3339("+010000-01-01T00:00:00+00:00[UTC]") // ""
+ * @example Temporal.ZonedDateTime.from("1969-12-31T23:15:30-00:45[Africa/Monrovia]").toString({ timeZoneName: "never" }) // "1969-12-31T23:15:30-00:45" — the pre-1.16.0 output
  * @example formatRfc3339("invalid") // ""
  */
 export declare function formatRfc3339(value: string): string;

package/dist/zoned/format/formatRfc3339.js

@@ -1,5 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+const NANOSECONDS_PER_MINUTE = 60_000_000_000;
 /**
  * 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
@@ -15,19 +16,44 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *   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.)
+ * - **Sub-minute offsets are written in UTC.** `time-numoffset` holds whole minutes, and RFC 3339
+ *   §4.2 says historical offsets that are not ("applications must convert them to a representable
+ *   time zone"). A local mean time such as Africa/Monrovia's −00:44:30 is therefore written as the
+ *   same instant at `+00:00`. `Z` is not used: RFC 9557 §2.2 gives it the meaning "the offset to
+ *   local time is unknown", and here the offset is known, only not representable.
+ * - Returns `""` for a year outside `date-fullyear = 4DIGIT` (0000–9999).
+ * - Fractional seconds are kept, with trailing zeros dropped.
+ * - **Compatibility:** before 1.16.0 a sub-minute offset was rounded to the minute, naming a
+ *   different instant, and years outside 0000–9999 were written in expanded form. For either
+ *   string use `Temporal.ZonedDateTime#toString({ timeZoneName: "never" })`.
  *
  * @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
+ * @returns RFC 3339 datetime string, or "" on invalid input or a year outside 0000–9999
  *
  * @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("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // "1970-01-01T00:00:00+00:00" (offset −00:44:30)
+ * @example formatRfc3339("+010000-01-01T00:00:00+00:00[UTC]") // ""
+ * @example Temporal.ZonedDateTime.from("1969-12-31T23:15:30-00:45[Africa/Monrovia]").toString({ timeZoneName: "never" }) // "1969-12-31T23:15:30-00:45" — the pre-1.16.0 output
  * @example formatRfc3339("invalid") // ""
  */
 export function formatRfc3339(value) {
     if (!isValidZonedDateTime(value))
         return "";
     try {
-        return Temporal.ZonedDateTime.from(value).toString({
+        const zdt = zonedDateTimeFrom(value);
+        // time-numoffset holds whole minutes. A local mean time offset (e.g.
+        // Africa/Monrovia -00:44:30) would be rounded by toString into a string
+        // naming a different instant; RFC 3339 §4.2 NOTE: "applications must
+        // convert them to a representable time zone" — UTC.
+        const target = zdt.offsetNanoseconds % NANOSECONDS_PER_MINUTE === 0
+            ? zdt
+            : zdt.withTimeZone("UTC");
+        // date-fullyear = 4DIGIT (RFC 3339 §5.6).
+        const { year } = target.toPlainDate().withCalendar("iso8601");
+        if (year < 0 || year > 9999)
+            return "";
+        return target.toString({
             timeZoneName: "never",
         });
     }

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

@@ -40,7 +40,7 @@ export interface FormatTimeZoneNameOptions {
  * - Returns "" for an invalid timeZone or locale.
  *
  * @param timeZone IANA timeZone identifier
- * @param locale BCP 47 locale tag (e.g. "en-US")
+ * @param locale BCP 47 locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
  * @param options optional: { style } name style, default "long"
  * @returns localized zone name, or "" on invalid input
  *
@@ -50,5 +50,6 @@ export interface FormatTimeZoneNameOptions {
  * @example formatTimeZoneName("Asia/Tokyo", "ja-JP", { style: "longGeneric" }) // "日本標準時"
  * @example formatTimeZoneName("Invalid/Zone", "en-US") // ""
  * @example formatTimeZoneName("America/New_York", "!!!") // ""
+ * @example formatTimeZoneName("Europe/Berlin", ["fr-FR", "en-US"], { style: "longGeneric" }) // "heure d’Europe centrale"
  */
-export declare function formatTimeZoneName(timeZone: string, locale: string, options?: FormatTimeZoneNameOptions): string;
+export declare function formatTimeZoneName(timeZone: string, locale: string | string[], options?: FormatTimeZoneNameOptions): string;

package/dist/zoned/format/formatTimeZoneName.js

@@ -1,5 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveRequiredLocale } from "../../internal/resolveLocale.js";
 import { isValidTimeZone } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the localized display name for an IANA timeZone.
  *
@@ -19,7 +21,7 @@ import { isValidTimeZone } from "../validate/index.js";
  * - Returns "" for an invalid timeZone or locale.
  *
  * @param timeZone IANA timeZone identifier
- * @param locale BCP 47 locale tag (e.g. "en-US")
+ * @param locale BCP 47 locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
  * @param options optional: { style } name style, default "long"
  * @returns localized zone name, or "" on invalid input
  *
@@ -29,28 +31,36 @@ import { isValidTimeZone } from "../validate/index.js";
  * @example formatTimeZoneName("Asia/Tokyo", "ja-JP", { style: "longGeneric" }) // "日本標準時"
  * @example formatTimeZoneName("Invalid/Zone", "en-US") // ""
  * @example formatTimeZoneName("America/New_York", "!!!") // ""
+ * @example formatTimeZoneName("Europe/Berlin", ["fr-FR", "en-US"], { style: "longGeneric" }) // "heure d’Europe centrale"
  */
 export function formatTimeZoneName(timeZone, locale, options) {
-    if (!isValidTimeZone(timeZone)) {
-        return "";
-    }
-    try {
-        new Intl.Locale(locale);
-    }
-    catch {
-        return "";
-    }
     try {
-        const style = options?.style ?? "long";
-        const formatter = new Intl.DateTimeFormat(locale, {
-            timeZone,
-            timeZoneName: style,
-            hour: "numeric",
-        });
-        const parts = formatter.formatToParts(Temporal.Now.instant().epochMilliseconds);
-        return parts.find((part) => part.type === "timeZoneName")?.value ?? "";
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        if (!isValidTimeZone(timeZone)) {
+            return "";
+        }
+        const resolvedLocale = resolveRequiredLocale(locale);
+        if (resolvedLocale === null)
+            return "";
+        try {
+            const style = options?.style === undefined ? "long" : options.style;
+            const formatter = new Intl.DateTimeFormat(resolvedLocale, {
+                timeZone,
+                timeZoneName: style,
+                hour: "numeric",
+            });
+            const parts = formatter.formatToParts(Temporal.Now.instant().epochMilliseconds);
+            return parts.find((part) => part.type === "timeZoneName")?.value ?? "";
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -2,17 +2,37 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Format a zoned ISO 8601 datetime string using the Intl.DateTimeFormat implementation.
  *
- * - Uses Temporal.ZonedDateTime.toLocaleString for formatting.
+ * - Formats as Temporal's ECMA-402 ZonedDateTime format (`ZonedDateTime#toLocaleString`) does,
+ *   through the runtime's `Intl.DateTimeFormat` in the value's own zone: the requested fields and
+ *   widths are kept, and with no date or time field (`era` alone included) the date, time and a
+ *   short zone name are the defaults.
  * - Accepts optional locale and Intl.DateTimeFormatOptions.
- * - Returns "" for invalid input.
+ * - Returns "" for invalid input, and for a `timeZone` option, where
+ *   `ZonedDateTime#toLocaleString` throws a TypeError.
+ * - Output is normalized: dash separators become ASCII "-" (unspaced between digits, spaced
+ *   otherwise), and no-break, narrow and thin spaces become U+0020.
+ * - **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"`) and `era` alone dropped the time and
+ *   zone name. Pass the fields the old text showed to keep it. To render in another zone, use
+ *   `formatUtc` with its `timeZone` option.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it (a string or number
+ *   options value formats with the defaults, as `Intl.DateTimeFormat` does).
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale optional locale tag (e.g. "en-US")
+ * @param locale optional locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized string or "" when invalid
  *
- * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "long" }) // "February 29, 2024 at 12:34:56 PM Coordinated Universal Time"
+ * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "long" }) // "February 29, 2024 at 12:34:56 PM UTC"
  * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:34"
+ * @example formatZonedDateTime("2024-02-03T14:30:45-05:00[America/New_York]", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatZonedDateTime("2024-02-03T14:30:45-05:00[America/New_York]", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatZonedDateTime("2024-02-03T14:30:45-05:00[America/New_York]", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM EST"
+ * @example formatZonedDateTime("2024-02-03T14:30:45-05:00[America/New_York]", "en-US", { era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatZonedDateTime("2024-02-03T14:30:45-05:00[America/New_York]", "en-US", { timeZone: "Asia/Tokyo" }) // "" — a ZonedDateTime keeps its own zone
+ * @example formatUtc("2024-02-03T19:30:45Z", "en-US", { timeZone: "Asia/Tokyo", includeTimeZoneName: true }) // "2/4/2024, 4:30:45 AM GMT+9" — the same instant in another zone
  * @example formatZonedDateTime("invalid", "en-US") // "" (invalid input)
+ * @example formatZonedDateTime("2024-02-03T14:30:45+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "short", timeStyle: "short" }) // "03/02/2024 14:30"
+ * @example formatZonedDateTime("2024-02-03T14:30:00-05:00[America/New_York]", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
  */
-export declare function formatZonedDateTime(value: string, locale?: string, options?: DateTimeFormatOptions): string;
+export declare function formatZonedDateTime(value: string, locale?: string | string[], options?: DateTimeFormatOptions): string;