@northguild/gmt 1.15.0 → 1.16.0

package/dist/zoned/compare/isZonedWeekend.d.ts

@@ -8,16 +8,20 @@
  *   conversion needed, since `value` already carries its IANA timezone.
  * - Falls back to Saturday/Sunday if the runtime's `weekInfo` data doesn't
  *   resolve a weekend for the locale.
- * - Returns false if `value` or `locale` is invalid.
+ * - Returns false if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value ISO ZonedDateTime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL"), 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 false
  * @returns true if `value`'s local day is a weekend day in `locale`, false on invalid input
  *
  * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "en-US") // true (Saturday)
  * @example isZonedWeekend("2024-02-02T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
  * @example isZonedWeekend("2024-02-04T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // false (Sunday)
  * @example isZonedWeekend("invalid", "en-US") // false
- * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "not-a-locale") // false
+ * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "not-a-locale-!!") // false
+ * @example isZonedWeekend("2024-05-17T12:00:00+02:00[Europe/Berlin]", ["ar-EG", "fr-FR"]) // true
  */
-export declare function isZonedWeekend(value: string, locale: string): boolean;
+export declare function isZonedWeekend(value: string, locale: string | string[]): boolean;

package/dist/zoned/compare/isZonedWeekend.js

@@ -1,5 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { getLocaleWeekendDays } from "../../internal/index.js";
+import { getLocaleWeekendDays, zonedDateTimeFrom } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 /**
  * Return true when `value`'s local calendar day falls on a weekend for `locale`.
@@ -11,17 +10,21 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *   conversion needed, since `value` already carries its IANA timezone.
  * - Falls back to Saturday/Sunday if the runtime's `weekInfo` data doesn't
  *   resolve a weekend for the locale.
- * - Returns false if `value` or `locale` is invalid.
+ * - Returns false if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value ISO ZonedDateTime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL"), 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 false
  * @returns true if `value`'s local day is a weekend day in `locale`, false on invalid input
  *
  * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "en-US") // true (Saturday)
  * @example isZonedWeekend("2024-02-02T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
  * @example isZonedWeekend("2024-02-04T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // false (Sunday)
  * @example isZonedWeekend("invalid", "en-US") // false
- * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "not-a-locale") // false
+ * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "not-a-locale-!!") // false
+ * @example isZonedWeekend("2024-05-17T12:00:00+02:00[Europe/Berlin]", ["ar-EG", "fr-FR"]) // true
  */
 export function isZonedWeekend(value, locale) {
     if (!isValidZonedDateTime(value))
@@ -30,7 +33,7 @@ export function isZonedWeekend(value, locale) {
     if (!weekendDays)
         return false;
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return weekendDays.has(zonedDateTime.dayOfWeek);
     }
     catch {

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

@@ -1,19 +1,25 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { Disambiguation, Offset } from "../../types/index.js";
+import type { Disambiguation } from "../../types/index.js";
 /**
  * Attach the specified `timeZone` to a plain datetime string and return a zoned ISO 8601 datetime string.
  *
  * - Combines plain datetime with timezone to create ZonedDateTime.
  * - `disambiguation` controls DST gap/overlap resolution: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
- * - `offset` ("prefer" | "use" | "ignore" (default) | "reject", per Temporal's `OffsetDisambiguationOptions`) is accepted for API consistency with sibling zoned-construction functions (see `startOfZoned`, `endOfZoned`, etc.) but has **no effect here**: `value` is a plain datetime string with no UTC offset embedded, so there is never a stored offset for `offset` to prefer/use/ignore/reject against. `disambiguation` is the only option that affects this function's output.
+ * - There is no `offset` option (removed in 1.16.0): Temporal `PlainDateTime#toZonedDateTime` reads
+ *   only `disambiguation`, and a plain datetime has no UTC offset for `offset` to act on.
+ * - **Output is cut to milliseconds by default.** `smallestUnit` defaults to `"milliseconds"`
+ *   (Temporal `toString` rounding mode `"trunc"`), so microseconds and nanoseconds in `value` are
+ *   dropped. Pass `{ smallestUnit: "nanoseconds" }` to keep every digit.
  * - Returns "" for invalid input.
  *
  * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
  * @param timeZone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above)
+ * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject")
  * @returns zoned ISO 8601 datetime string or "" when invalid
  *
- * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.123-05:00[America/New_York]"
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.000-05:00[America/New_York]"
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45.123456789", "UTC") // "2024-02-29T14:30:45.123+00:00[UTC]"
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45.123456789", "UTC", { smallestUnit: "nanoseconds" }) // "2024-02-29T14:30:45.123456789+00:00[UTC]"
  * @example convertPlainDateTimeToZoned("invalid", "America/New_York") // ""
  * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T01:30:00.000-05:00[America/New_York]" (spring-forward gap)
  * @example convertPlainDateTimeToZoned("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T01:30:00.000-05:00[America/New_York]" (fall-back overlap)
@@ -22,5 +28,4 @@ import type { Disambiguation, Offset } from "../../types/index.js";
 export declare function convertPlainDateTimeToZoned(value: string, timeZone: string, optionsArg?: {
     smallestUnit?: Temporal.ZonedDateTimeToStringOptions["smallestUnit"];
     disambiguation?: Disambiguation;
-    offset?: Offset;
 }): string;

package/dist/zoned/convert/convertPlainDateTimeToZoned.js

@@ -1,42 +1,60 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTime } from "../../plain/validate/index.js";
 import { isValidTimeZone } from "../validate/index.js";
+import { isoStringBody, zonedDateTimeFrom } from "../../internal/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Attach the specified `timeZone` to a plain datetime string and return a zoned ISO 8601 datetime string.
  *
  * - Combines plain datetime with timezone to create ZonedDateTime.
  * - `disambiguation` controls DST gap/overlap resolution: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
- * - `offset` ("prefer" | "use" | "ignore" (default) | "reject", per Temporal's `OffsetDisambiguationOptions`) is accepted for API consistency with sibling zoned-construction functions (see `startOfZoned`, `endOfZoned`, etc.) but has **no effect here**: `value` is a plain datetime string with no UTC offset embedded, so there is never a stored offset for `offset` to prefer/use/ignore/reject against. `disambiguation` is the only option that affects this function's output.
+ * - There is no `offset` option (removed in 1.16.0): Temporal `PlainDateTime#toZonedDateTime` reads
+ *   only `disambiguation`, and a plain datetime has no UTC offset for `offset` to act on.
+ * - **Output is cut to milliseconds by default.** `smallestUnit` defaults to `"milliseconds"`
+ *   (Temporal `toString` rounding mode `"trunc"`), so microseconds and nanoseconds in `value` are
+ *   dropped. Pass `{ smallestUnit: "nanoseconds" }` to keep every digit.
  * - Returns "" for invalid input.
  *
  * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
  * @param timeZone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above)
+ * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject")
  * @returns zoned ISO 8601 datetime string or "" when invalid
  *
- * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.123-05:00[America/New_York]"
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.000-05:00[America/New_York]"
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45.123456789", "UTC") // "2024-02-29T14:30:45.123+00:00[UTC]"
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45.123456789", "UTC", { smallestUnit: "nanoseconds" }) // "2024-02-29T14:30:45.123456789+00:00[UTC]"
  * @example convertPlainDateTimeToZoned("invalid", "America/New_York") // ""
  * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T01:30:00.000-05:00[America/New_York]" (spring-forward gap)
  * @example convertPlainDateTimeToZoned("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T01:30:00.000-05:00[America/New_York]" (fall-back overlap)
  * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "reject" }) // ""
  */
 export function convertPlainDateTimeToZoned(value, timeZone, optionsArg) {
-    if (!isValidDateTime(value) || !isValidTimeZone(timeZone)) {
-        return "";
-    }
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
-    const options = {
-        smallestUnit: optionsArg?.smallestUnit ?? "milliseconds",
-    };
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(`${value}[${timeZone}]`, {
-            disambiguation,
-            offset,
-        });
-        return zonedDateTime.toString(options);
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        if (!isValidDateTime(value) || !isValidTimeZone(timeZone)) {
+            return "";
+        }
+        const disambiguation = optionsArg?.disambiguation === undefined
+            ? "compatible"
+            : optionsArg.disambiguation;
+        const options = {
+            smallestUnit: optionsArg?.smallestUnit === undefined
+                ? "milliseconds"
+                : optionsArg.smallestUnit,
+        };
+        try {
+            const zonedDateTime = zonedDateTimeFrom(`${isoStringBody(value)}[${timeZone}]`, { disambiguation });
+            return zonedDateTime.toString(options);
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,49 +1,37 @@
 import type { CalendarSystem } from "../../types/index.js";
 /**
- * Convert a zoned datetime to the same instant expressed in a different calendar system.
+ * Express a zoned datetime in a calendar system: the RFC 9557 string
+ * `Temporal.ZonedDateTime#toString()` writes for that instant, zone and calendar.
  *
- * - 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`.
+ * - The instant, the wall time, the UTC offset, the IANA zone and the digits are all unchanged:
+ *   the date is always written as ISO 8601. A `[u-ca=<id>]` annotation after the `[timeZone]`
+ *   annotation names the calendar (RFC 9557 §3.3, §4.1). Eras and calendar years are never part
+ *   of the string.
+ * - `"iso8601"` writes a bare ISO zoned string; every other calendar, `"gregory"` included, is
+ *   annotated.
+ * - Accepts a bare ISO zoned datetime or any calendar-annotated one GMT reads (see
+ *   `isValidCalendarZonedDateTime`), so conversions chain between calendars.
+ * - `calendar` is a canonical calendar id; like Temporal's `withCalendar`, an alias or another
+ *   letter case is canonicalized.
  * - 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.
+ * Compatibility: since 1.16.0 the string is RFC 9557. Earlier releases wrote the calendar's own
+ * year, month and day, a `;era=` suffix for `japanese` and `ethiopic`, the calendar annotation
+ * before the time zone, and the ids `gregorian`, `taiwan`, `islamic-tabular` and
+ * `ethiopic-amete-alem`; those strings are not converted.
  *
  * @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
+ * @param calendar target calendar id ("iso8601" | "gregory" | "hebrew" | "islamic-civil" |
+ *   "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" |
+ *   "indian" | "ethiopic" | "ethioaa" | "coptic")
+ * @returns RFC 9557 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("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew") // "2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]", "iso8601") // "2024-10-03T14:30:45-04:00[America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "japanese") // "2024-10-03T14:30:45-04:00[America/New_York][u-ca=japanese]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "roc") // "2024-10-03T14:30:45-04:00[America/New_York][u-ca=roc]"
+ * @example convertZonedToCalendar("+275760-09-13T00:00:00+00:00[UTC]", "hebrew") // "+275760-09-13T00:00:00+00:00[UTC][u-ca=hebrew]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[u-ca=hebrew][America/New_York]", "iso8601") // "" (calendar before zone is not RFC 9557)
  * @example convertZonedToCalendar("invalid", "hebrew") // ""
  */
 export declare function convertZonedToCalendar(value: string, calendar: CalendarSystem): string;

package/dist/zoned/convert/convertZonedToCalendar.js

@@ -1,65 +1,50 @@
-import { formatZonedInCalendar, isEthiopicFamilyCalendar, parseCalendarZonedValue, temporalCalendarIds, } from "../../internal/index.js";
+import { canonicalCalendarSystem, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Convert a zoned datetime to the same instant expressed in a different calendar system.
+ * Express a zoned datetime in a calendar system: the RFC 9557 string
+ * `Temporal.ZonedDateTime#toString()` writes for that instant, zone and calendar.
  *
- * - 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`.
+ * - The instant, the wall time, the UTC offset, the IANA zone and the digits are all unchanged:
+ *   the date is always written as ISO 8601. A `[u-ca=<id>]` annotation after the `[timeZone]`
+ *   annotation names the calendar (RFC 9557 §3.3, §4.1). Eras and calendar years are never part
+ *   of the string.
+ * - `"iso8601"` writes a bare ISO zoned string; every other calendar, `"gregory"` included, is
+ *   annotated.
+ * - Accepts a bare ISO zoned datetime or any calendar-annotated one GMT reads (see
+ *   `isValidCalendarZonedDateTime`), so conversions chain between calendars.
+ * - `calendar` is a canonical calendar id; like Temporal's `withCalendar`, an alias or another
+ *   letter case is canonicalized.
  * - 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.
+ * Compatibility: since 1.16.0 the string is RFC 9557. Earlier releases wrote the calendar's own
+ * year, month and day, a `;era=` suffix for `japanese` and `ethiopic`, the calendar annotation
+ * before the time zone, and the ids `gregorian`, `taiwan`, `islamic-tabular` and
+ * `ethiopic-amete-alem`; those strings are not converted.
  *
  * @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
+ * @param calendar target calendar id ("iso8601" | "gregory" | "hebrew" | "islamic-civil" |
+ *   "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" |
+ *   "indian" | "ethiopic" | "ethioaa" | "coptic")
+ * @returns RFC 9557 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("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew") // "2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]", "iso8601") // "2024-10-03T14:30:45-04:00[America/New_York]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "japanese") // "2024-10-03T14:30:45-04:00[America/New_York][u-ca=japanese]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "roc") // "2024-10-03T14:30:45-04:00[America/New_York][u-ca=roc]"
+ * @example convertZonedToCalendar("+275760-09-13T00:00:00+00:00[UTC]", "hebrew") // "+275760-09-13T00:00:00+00:00[UTC][u-ca=hebrew]"
+ * @example convertZonedToCalendar("2024-10-03T14:30:45-04:00[u-ca=hebrew][America/New_York]", "iso8601") // "" (calendar before zone is not RFC 9557)
  * @example convertZonedToCalendar("invalid", "hebrew") // ""
  */
 export function convertZonedToCalendar(value, calendar) {
-    if (!isValidCalendarZonedDateTime(value) ||
-        !(calendar in temporalCalendarIds)) {
+    if (!isValidCalendarZonedDateTime(value)) {
+        return "";
+    }
+    const target = canonicalCalendarSystem(calendar);
+    if (!target) {
         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);
+        return formatZonedInCalendar(parseCalendarZonedValue(value), target);
     }
     catch {
         return "";

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

@@ -3,11 +3,17 @@
  *
  * - Extracts the local date-time components without timezone info.
  * - Validation is performed on the input.
+ * - **The offset is dropped, and with it which occurrence of a repeated wall time was meant.**
+ *   In a fall-back overlap the same plain date-time names two instants; converting back with
+ *   `convertPlainDateTimeToZoned` picks the earlier one by default. Keep the zoned string, or
+ *   pass `{ disambiguation: "later" }` when converting back, to recover the second occurrence.
  *
  * @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("2024-11-03T01:30:00-05:00[America/New_York]") // "2024-11-03T01:30:00" (the second 01:30, EST)
+ * @example convertZonedToPlainDateTime("2024-11-03T01:30:00-04:00[America/New_York]") // "2024-11-03T01:30:00" (the first 01:30, EDT)
  * @example convertZonedToPlainDateTime("invalid") // ""
  */
 export declare function convertZonedToPlainDateTime(value: string): string;

package/dist/zoned/convert/convertZonedToPlainDateTime.js

@@ -1,15 +1,21 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.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.
+ * - **The offset is dropped, and with it which occurrence of a repeated wall time was meant.**
+ *   In a fall-back overlap the same plain date-time names two instants; converting back with
+ *   `convertPlainDateTimeToZoned` picks the earlier one by default. Keep the zoned string, or
+ *   pass `{ disambiguation: "later" }` when converting back, to recover the second occurrence.
  *
  * @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("2024-11-03T01:30:00-05:00[America/New_York]") // "2024-11-03T01:30:00" (the second 01:30, EST)
+ * @example convertZonedToPlainDateTime("2024-11-03T01:30:00-04:00[America/New_York]") // "2024-11-03T01:30:00" (the first 01:30, EDT)
  * @example convertZonedToPlainDateTime("invalid") // ""
  */
 export function convertZonedToPlainDateTime(value) {
@@ -17,7 +23,7 @@ export function convertZonedToPlainDateTime(value) {
         return "";
     }
     try {
-        return Temporal.ZonedDateTime.from(value).toPlainDateTime().toString();
+        return zonedDateTimeFrom(value).toPlainDateTime().toString();
     }
     catch {
         return "";

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

@@ -1,17 +1,23 @@
-import { type UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
+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").
+ * - Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
+ * - `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 zoned ISO 8601 datetime string
- * @param unit optional: "seconds" | "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "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("2024-02-29T12:34:56.789+00:00[UTC]") // 1709210096789
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]", { epochUnit: "seconds" }) // 1709210096
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]", "seconds" as never) // null (options must be an object)
  * @example convertZonedToUnix("invalid") // null
  */
-export declare function convertZonedToUnix(value: string, ...unitInput: [unit?: UnixUnit]): number | null;
+export declare function convertZonedToUnix(value: string, options?: {
+    epochUnit?: UnixUnit;
+}): number | null;

package/dist/zoned/convert/convertZonedToUnix.js

@@ -1,34 +1,41 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUnixUnit, } from "../../unix/validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, toUnixEpoch, } from "../../internal/unixEpochValue.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/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").
+ * - Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
+ * - `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 zoned ISO 8601 datetime string
- * @param unit optional: "seconds" | "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "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("2024-02-29T12:34:56.789+00:00[UTC]") // 1709210096789
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]", { epochUnit: "seconds" }) // 1709210096
+ * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]", "seconds" as never) // null (options must be an object)
  * @example convertZonedToUnix("invalid") // null
  */
-export function convertZonedToUnix(value, ...unitInput) {
-    const resolvedUnit = unitInput.length === 0 ? "milliseconds" : unitInput[0];
-    if (!isValidZonedDateTime(value) || !isValidUnixUnit(resolvedUnit ?? "")) {
-        return null;
-    }
+export function convertZonedToUnix(value, options) {
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
-        const milliseconds = Number(zonedDateTime.toInstant().epochMilliseconds);
-        return resolvedUnit === "seconds"
-            ? Math.floor(milliseconds / 1000)
-            : milliseconds;
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (!isValidZonedDateTime(value) || epochUnit === null) {
+            return null;
+        }
+        try {
+            return toUnixEpoch(zonedDateTimeFrom(value).toInstant(), epochUnit);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/zoned/convert/convertZonedToUtc.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Convert an ISO 8601 zoned datetime string to a UTC Instant string (ISO).
  *
@@ -17,7 +17,7 @@ export function convertZonedToUtc(value) {
         return "";
     }
     try {
-        return Temporal.ZonedDateTime.from(value).toInstant().toString();
+        return zonedDateTimeFrom(value).toInstant().toString();
     }
     catch {
         return "";

package/dist/zoned/convert/convertZonedToZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone, isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Convert a zoned ISO 8601 datetime string to the same instant in a different `timeZone`.
  *
@@ -18,7 +18,7 @@ export function convertZonedToZoned(value, timeZone) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.withTimeZone(timeZone).toString();
     }
     catch {

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

@@ -21,14 +21,18 @@ export interface FormatCalendarZonedOptions {
  * 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 declare function formatCalendarZoned(value: string, locale?: string, options?: FormatCalendarZonedOptions): string;
+export declare function formatCalendarZoned(value: string, locale?: string | string[], options?: FormatCalendarZonedOptions): string;