@northguild/gmt 1.15.0 → 1.17.0

package/dist/zoned/format/formatZonedDateTime.js

@@ -1,30 +1,61 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime } from "../../internal/index.js";
+import { normalizeDateTime, zonedDateTimeFrom } from "../../internal/index.js";
+import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 import { isValidZonedDateTime } from "../validate/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 function formatZonedDateTime(value, locale, options) {
+    // ECMA-402 CoerceOptionsToObject: null options throw TypeError, so they are invalid input.
+    if (options === null) {
+        return "";
+    }
     if (!isValidZonedDateTime(value)) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
-        const out = zonedDateTime.toLocaleString(locale, options);
-        return normalizeDateTime(out);
+        // The runtime's Intl.DateTimeFormat formats the instant in the value's own
+        // zone with the options ZonedDateTime#toLocaleString resolves to
+        // (GetDateTimeFormat ~any~, ~zoned-date-time~, ~all~), so the requested
+        // fields and widths are kept.
+        const zonedDateTime = zonedDateTimeFrom(value);
+        const resolved = instantFormatOptions(options ?? {}, zonedDateTime.timeZoneId, "zoned-date-time");
+        if (resolved === null) {
+            return "";
+        }
+        return normalizeDateTime(new Intl.DateTimeFormat(locale, resolved).format(zonedDateTime.epochMilliseconds));
     }
     catch {
         return "";

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

@@ -3,17 +3,35 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * Format a zoned datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
  * - Both datetimes must have the same timezone.
- * - Uses Temporal.ZonedDateTime.toInstant for formatting.
- * - Returns "" for invalid input or mismatched timezones.
+ * - Formats both instants as Temporal's ECMA-402 Instant format does, through the runtime's
+ *   `Intl.DateTimeFormat#formatRange` in the endpoints' zone: the requested fields and widths are
+ *   kept, and with no date or time field (`era` alone included) the date and time are the
+ *   defaults.
+ * - Returns "" for invalid input, mismatched timezones, or a `timeZone` option (a ZonedDateTime
+ *   keeps its own zone).
+ * - **Compatibility:** before 1.16.0 some locales lost a requested width (zh-CN with
+ *   `{ year: "numeric", month: "long" }` gave `"2024/2"`), `era` alone dropped the time, and a
+ *   `timeZone` option was silently overridden by the endpoints' zone. Pass the fields the old text
+ *   showed to keep it, and drop the `timeZone` option to keep the endpoints' zone.
+ * - Output is normalized: dash separators become ASCII "-" (unspaced between digits, spaced
+ *   otherwise), and no-break, narrow and thin spaces become U+0020.
+ * - `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 from zoned ISO 8601 datetime string (range start)
  * @param to zoned ISO 8601 datetime string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag, or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *
- * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 29, 2024 at 12:00 PM – 2:00 PM Coordinated Universal Time"
- * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00 – 14:00"
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 29, 2024, 12:00 - 2:00 PM"
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00-14:00"
+ * @example formatZonedRange("2024-02-03T14:30:45-05:00[America/New_York]", "2024-02-03T15:30:45-05:00[America/New_York]", "zh-CN", { year: "numeric", month: "long" }) // "2024年2月"
+ * @example formatZonedRange("2024-02-03T14:30:45-05:00[America/New_York]", "2024-02-03T15:30:45-05:00[America/New_York]", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM - 3:30:45 PM"
+ * @example formatZonedRange("2024-02-29T10:00:00-05:00[America/New_York]", "2024-02-29T12:00:00-05:00[America/New_York]", "en-US", { hour: "numeric", timeZone: "UTC" }) // "" — a ZonedDateTime keeps its own zone
+ * @example formatZonedRange("2024-02-29T10:00:00-05:00[America/New_York]", "2024-02-29T12:00:00-05:00[America/New_York]", "en-US", { hour: "numeric", minute: "numeric", timeZoneName: "short" }) // "10:00 AM - 12:00 PM EST" — the pre-1.16.0 text
  * @example formatZonedRange("invalid", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US") // "" (invalid input)
+ * @example formatZonedRange("2024-02-03T14:30:45+01:00[Europe/Paris]", "2024-02-03T16:46:15+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "short", timeStyle: "short" }) // "03/02/2024, 14:30 - 16:46"
+ * @example formatZonedRange("2024-02-03T14:30:00-05:00[America/New_York]", "2024-02-05T17:00:00-05:00[America/New_York]", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
  */
-export declare function formatZonedRange(from: string, to: string, locale?: string, options?: DateTimeFormatOptions): string;
+export declare function formatZonedRange(from: string, to: string, locale?: string | string[], options?: DateTimeFormatOptions): string;

package/dist/zoned/format/formatZonedRange.js

@@ -1,48 +1,81 @@
-import { Temporal, Intl as TemporalIntl } from "@js-temporal/polyfill";
-import { normalizeDateTime } from "../../internal/index.js";
+import { normalizeDateTime, zonedDateTimeFrom } from "../../internal/index.js";
+import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 /**
  * Format a zoned datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
  * - Both datetimes must have the same timezone.
- * - Uses Temporal.ZonedDateTime.toInstant for formatting.
- * - Returns "" for invalid input or mismatched timezones.
+ * - Formats both instants as Temporal's ECMA-402 Instant format does, through the runtime's
+ *   `Intl.DateTimeFormat#formatRange` in the endpoints' zone: the requested fields and widths are
+ *   kept, and with no date or time field (`era` alone included) the date and time are the
+ *   defaults.
+ * - Returns "" for invalid input, mismatched timezones, or a `timeZone` option (a ZonedDateTime
+ *   keeps its own zone).
+ * - **Compatibility:** before 1.16.0 some locales lost a requested width (zh-CN with
+ *   `{ year: "numeric", month: "long" }` gave `"2024/2"`), `era` alone dropped the time, and a
+ *   `timeZone` option was silently overridden by the endpoints' zone. Pass the fields the old text
+ *   showed to keep it, and drop the `timeZone` option to keep the endpoints' zone.
+ * - Output is normalized: dash separators become ASCII "-" (unspaced between digits, spaced
+ *   otherwise), and no-break, narrow and thin spaces become U+0020.
+ * - `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 from zoned ISO 8601 datetime string (range start)
  * @param to zoned ISO 8601 datetime string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag, or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *
- * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 29, 2024 at 12:00 PM – 2:00 PM Coordinated Universal Time"
- * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00 – 14:00"
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 29, 2024, 12:00 - 2:00 PM"
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00-14:00"
+ * @example formatZonedRange("2024-02-03T14:30:45-05:00[America/New_York]", "2024-02-03T15:30:45-05:00[America/New_York]", "zh-CN", { year: "numeric", month: "long" }) // "2024年2月"
+ * @example formatZonedRange("2024-02-03T14:30:45-05:00[America/New_York]", "2024-02-03T15:30:45-05:00[America/New_York]", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM - 3:30:45 PM"
+ * @example formatZonedRange("2024-02-29T10:00:00-05:00[America/New_York]", "2024-02-29T12:00:00-05:00[America/New_York]", "en-US", { hour: "numeric", timeZone: "UTC" }) // "" — a ZonedDateTime keeps its own zone
+ * @example formatZonedRange("2024-02-29T10:00:00-05:00[America/New_York]", "2024-02-29T12:00:00-05:00[America/New_York]", "en-US", { hour: "numeric", minute: "numeric", timeZoneName: "short" }) // "10:00 AM - 12:00 PM EST" — the pre-1.16.0 text
  * @example formatZonedRange("invalid", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US") // "" (invalid input)
+ * @example formatZonedRange("2024-02-03T14:30:45+01:00[Europe/Paris]", "2024-02-03T16:46:15+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "short", timeStyle: "short" }) // "03/02/2024, 14:30 - 16:46"
+ * @example formatZonedRange("2024-02-03T14:30:00-05:00[America/New_York]", "2024-02-05T17:00:00-05:00[America/New_York]", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
  */
 export function formatZonedRange(from, to, locale, options) {
-    if (!isValidZonedDateTime(from) || !isValidZonedDateTime(to)) {
-        return "";
-    }
-    let zdt1;
-    let zdt2;
-    try {
-        zdt1 = Temporal.ZonedDateTime.from(from);
-        zdt2 = Temporal.ZonedDateTime.from(to);
-    }
-    catch {
-        return "";
-    }
-    if (zdt1.timeZoneId !== zdt2.timeZoneId) {
-        return "";
-    }
-    const formatOptions = {
-        ...options,
-        timeZone: zdt1.timeZoneId,
-    };
     try {
-        const out = new TemporalIntl.DateTimeFormat(locale, formatOptions).formatRange(zdt1.toInstant(), zdt2.toInstant());
-        return normalizeDateTime(out);
+        // ECMA-402 CoerceOptionsToObject: null options throw TypeError, so they are invalid input.
+        if (options === null) {
+            return "";
+        }
+        if (!isValidZonedDateTime(from) || !isValidZonedDateTime(to)) {
+            return "";
+        }
+        let zdt1;
+        let zdt2;
+        try {
+            zdt1 = zonedDateTimeFrom(from);
+            zdt2 = zonedDateTimeFrom(to);
+        }
+        catch {
+            return "";
+        }
+        if (zdt1.timeZoneId !== zdt2.timeZoneId) {
+            return "";
+        }
+        // Both instants are formatted in the endpoints' own zone with the options
+        // an Instant format resolves to (GetDateTimeFormat ~any~, ~all~, ~all~), so
+        // the requested fields and widths are kept. A `timeZone` option is rejected
+        // rather than silently overridden.
+        const formatOptions = instantFormatOptions(options ?? {}, zdt1.timeZoneId, "all");
+        if (formatOptions === null) {
+            return "";
+        }
+        try {
+            const out = new Intl.DateTimeFormat(locale, formatOptions).formatRange(zdt1.epochMilliseconds, zdt2.epochMilliseconds);
+            return normalizeDateTime(out);
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -8,23 +8,46 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   while the *locale* keeps control of order. See Decision 1 in
  *   `context/roadmap/issues/J.md`.
  * - Each part is `{ type, value }` where `type` can be:
- *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"hour"`,
- *   `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
+ *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
+ *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
  *   `"timeZoneName"`, `"literal"`.
+ * - A lunisolar calendar adds two more: `zh-u-ca-chinese` and `ko-u-ca-dangi` emit
+ *   `"relatedYear"` (the Gregorian year the cycle falls in) and `"yearName"` (the sexagenary
+ *   cycle name) in place of, or beside, `"year"`. Code that looks up a `"year"` part must handle
+ *   their absence.
  * - The caller should iterate the array as returned; reassembling in a fixed
  *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - With no date/time field and no `dateStyle`/`timeStyle`, year, month, day,
+ *   hour, minute and second default to `"numeric"` and `timeZoneName` to
+ *   `"short"` unless given (ECMA-402 as amended by Temporal). The parts, joined,
+ *   are the text `formatZonedDateTime` returns for the same arguments before its
+ *   whitespace normalisation.
+ * - A ZonedDateTime is formatted in its own zone: a `timeZone` option returns
+ *   `[]`, as `ZonedDateTime#toLocaleString` throws a TypeError for one.
+ * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
+ *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
  * - Returns `[]` for invalid input.
+ * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts, with
+ *   no time zone name. Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
+ *   Before 1.16.0 a `timeZone` option re-rendered the instant in that zone; `formatUtc` with its
+ *   `timeZone` option gives that text.
+ * - `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 array of `{ type, value }` parts, or `[]` on invalid input
  *
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: " " }, { type: "dayPeriod", value: "PM" }]
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // includes { type: "timeZoneName", value: "GMT-4" }
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "EDT" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT-04:00" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZone: "Asia/Tokyo" }) // [] — a ZonedDateTime keeps its own zone
  * @example formatZonedToParts("invalid", "en-US") // []
+ * @example formatZonedToParts("2024-02-03T14:30:45+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "medium", timeStyle: "short" }) // parts of "3 févr. 2024, 14:30"
+ * @example formatZonedToParts("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 formatZonedToParts(value: string, locale?: string, options?: DateTimeFormatOptions): Array<{
+export declare function formatZonedToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
     type: string;
     value: string;
 }>;

package/dist/zoned/format/formatZonedToParts.js

@@ -1,5 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 /**
  * Return the locale-formatted parts of a ZonedDateTime.
  *
@@ -9,36 +10,64 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *   while the *locale* keeps control of order. See Decision 1 in
  *   `context/roadmap/issues/J.md`.
  * - Each part is `{ type, value }` where `type` can be:
- *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"hour"`,
- *   `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
+ *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
+ *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
  *   `"timeZoneName"`, `"literal"`.
+ * - A lunisolar calendar adds two more: `zh-u-ca-chinese` and `ko-u-ca-dangi` emit
+ *   `"relatedYear"` (the Gregorian year the cycle falls in) and `"yearName"` (the sexagenary
+ *   cycle name) in place of, or beside, `"year"`. Code that looks up a `"year"` part must handle
+ *   their absence.
  * - The caller should iterate the array as returned; reassembling in a fixed
  *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - With no date/time field and no `dateStyle`/`timeStyle`, year, month, day,
+ *   hour, minute and second default to `"numeric"` and `timeZoneName` to
+ *   `"short"` unless given (ECMA-402 as amended by Temporal). The parts, joined,
+ *   are the text `formatZonedDateTime` returns for the same arguments before its
+ *   whitespace normalisation.
+ * - A ZonedDateTime is formatted in its own zone: a `timeZone` option returns
+ *   `[]`, as `ZonedDateTime#toLocaleString` throws a TypeError for one.
+ * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
+ *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
  * - Returns `[]` for invalid input.
+ * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts, with
+ *   no time zone name. Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
+ *   Before 1.16.0 a `timeZone` option re-rendered the instant in that zone; `formatUtc` with its
+ *   `timeZone` option gives that text.
+ * - `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 array of `{ type, value }` parts, or `[]` on invalid input
  *
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: " " }, { type: "dayPeriod", value: "PM" }]
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // includes { type: "timeZoneName", value: "GMT-4" }
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "EDT" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT-04:00" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZone: "Asia/Tokyo" }) // [] — a ZonedDateTime keeps its own zone
  * @example formatZonedToParts("invalid", "en-US") // []
+ * @example formatZonedToParts("2024-02-03T14:30:45+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "medium", timeStyle: "short" }) // parts of "3 févr. 2024, 14:30"
+ * @example formatZonedToParts("2024-02-03T14:30:00-05:00[America/New_York]", "en-US", null as never) // [] (null options, as ECMA-402 rejects them)
  */
 export function formatZonedToParts(value, locale, options) {
+    // ECMA-402 CoerceOptionsToObject: null options throw TypeError, so they are invalid input.
+    if (options === null) {
+        return [];
+    }
     if (!isValidZonedDateTime(value)) {
         return [];
     }
     try {
         // Intl.DateTimeFormat cannot format a Temporal.ZonedDateTime directly —
         // pass its instant (epochMilliseconds) and its own IANA zone as the
-        // formatter's timeZone, mirroring formatTimeZoneName's approach.
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
-        const formatter = new Intl.DateTimeFormat(locale, {
-            timeZone: zonedDateTime.timeZoneId,
-            ...options,
-        });
-        return formatter
+        // formatter's timeZone, with the options ZonedDateTime#toLocaleString
+        // resolves to (GetDateTimeFormat ~any~, ~zoned-date-time~, ~all~).
+        const zonedDateTime = zonedDateTimeFrom(value);
+        const resolved = instantFormatOptions(options ?? {}, zonedDateTime.timeZoneId, "zoned-date-time");
+        if (resolved === null) {
+            return [];
+        }
+        return new Intl.DateTimeFormat(locale, resolved)
             .formatToParts(zonedDateTime.epochMilliseconds)
             .map((p) => ({ type: p.type, value: p.value }));
     }

package/dist/zoned/get/getDstTransitions.d.ts

@@ -34,8 +34,11 @@ export interface DstTransition {
  *   constructing a single instant that lands in a gap/overlap).
  * - Most zones have 0 or 2 transitions per year; some (e.g. `Africa/Casablanca`,
  *   which pauses DST for Ramadan) can have more.
+ * - A transition landing exactly on local January 1 00:00 belongs to that year
+ *   (e.g. `Asia/Singapore` moving to +08:00 at the start of 1982).
  * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
- *   with zero transitions in that year (not an error case).
+ *   with zero transitions in that year (not an error case), and when the scan
+ *   exhausts its internal bound — never a partial list.
  *
  * @param timeZone IANA timeZone identifier
  * @param year calendar year to scan (must be an integer)
@@ -46,6 +49,8 @@ export interface DstTransition {
  * //   { instant: "2024-03-10T07:00:00Z", offsetBefore: "-05:00", offsetAfter: "-04:00" },
  * //   { instant: "2024-11-03T06:00:00Z", offsetBefore: "-04:00", offsetAfter: "-05:00" },
  * // ]
+ * @example getDstTransitions("Asia/Singapore", 1982)
+ * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]
  * @example getDstTransitions("Asia/Tokyo", 2024) // []
  * @example getDstTransitions("Invalid/Zone", 2024) // []
  */

package/dist/zoned/get/getDstTransitions.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../validate/index.js";
+import { zonedDateTimeFrom, zonedNextTransition, zonedStartOfDay, } from "../../internal/index.js";
 const MAX_TRANSITIONS_PER_YEAR = 20;
 /**
  * List every DST transition instant for an IANA timezone within a given year.
@@ -12,8 +12,11 @@ const MAX_TRANSITIONS_PER_YEAR = 20;
  *   constructing a single instant that lands in a gap/overlap).
  * - Most zones have 0 or 2 transitions per year; some (e.g. `Africa/Casablanca`,
  *   which pauses DST for Ramadan) can have more.
+ * - A transition landing exactly on local January 1 00:00 belongs to that year
+ *   (e.g. `Asia/Singapore` moving to +08:00 at the start of 1982).
  * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
- *   with zero transitions in that year (not an error case).
+ *   with zero transitions in that year (not an error case), and when the scan
+ *   exhausts its internal bound — never a partial list.
  *
  * @param timeZone IANA timeZone identifier
  * @param year calendar year to scan (must be an integer)
@@ -24,6 +27,8 @@ const MAX_TRANSITIONS_PER_YEAR = 20;
  * //   { instant: "2024-03-10T07:00:00Z", offsetBefore: "-05:00", offsetAfter: "-04:00" },
  * //   { instant: "2024-11-03T06:00:00Z", offsetBefore: "-04:00", offsetAfter: "-05:00" },
  * // ]
+ * @example getDstTransitions("Asia/Singapore", 1982)
+ * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]
  * @example getDstTransitions("Asia/Tokyo", 2024) // []
  * @example getDstTransitions("Invalid/Zone", 2024) // []
  */
@@ -32,20 +37,16 @@ export function getDstTransitions(timeZone, year) {
         return [];
     }
     try {
-        let cur = Temporal.ZonedDateTime.from({
-            year,
-            month: 1,
-            day: 1,
-            hour: 0,
-            minute: 0,
-            second: 0,
-            timeZone,
-        });
+        // getTimeZoneTransition("next") is strictly after its receiver, so start 1ns before the
+        // year opens to catch a transition landing exactly on local January 1 00:00.
+        let cur = zonedStartOfDay(zonedDateTimeFrom({ year, month: 1, day: 1, timeZone })).subtract({ nanoseconds: 1 });
         const transitions = [];
-        for (let i = 0; i < MAX_TRANSITIONS_PER_YEAR; i++) {
-            const next = cur.getTimeZoneTransition("next");
+        // `<=`: up to MAX in-year transitions are pushed, plus one more lookup to observe the scan
+        // leaving the year.
+        for (let i = 0; i <= MAX_TRANSITIONS_PER_YEAR; i++) {
+            const next = zonedNextTransition(cur);
             if (!next || next.year > year) {
-                break;
+                return transitions;
             }
             transitions.push({
                 instant: next.toInstant().toString(),
@@ -54,7 +55,8 @@ export function getDstTransitions(timeZone, year) {
             });
             cur = next;
         }
-        return transitions;
+        // The bound ran out before the scan left the year: a partial list would be wrong.
+        return [];
     }
     catch {
         return [];

package/dist/zoned/get/getTimeZoneOffset.d.ts

@@ -6,7 +6,14 @@
  *   why (like `getDstTransitions`) it lives in `get/` despite taking two
  *   arguments: neither is a date *value* being described, both are
  *   coordinates for a zone-level lookup.
- * - Returns "" for an invalid timeZone or instant.
+ * - Returns "" for an invalid timeZone or instant, including a leap second in any spelling
+ *   (`23:59:60`, `t`/space separator, basic `235960`), which Temporal would read as `:59`.
+ *   Compatibility: to look up the offset at the clamped `:59` instant as earlier releases did,
+ *   pass that instant (`"2016-12-31T23:59:59Z"`), or call
+ *   `Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone).offset` directly.
+ * - The instant is ISO 8601 extended format before any annotation (`<date>T<time>`, then `Z` or
+ *   `±HH:MM[:SS[.fraction]]`): basic format, a `t` or space separator, a lower-case `z` and an
+ *   hour-only offset return "".
  *
  * @param timeZone IANA timeZone identifier
  * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
@@ -17,5 +24,8 @@
  * @example getTimeZoneOffset("Asia/Kathmandu", "2024-01-15T12:00:00Z") // "+05:45"
  * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
  * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
+ * @example getTimeZoneOffset("America/New_York", "2024-07-15T16:00:00z") // "" (lower-case z)
+ * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z") // "" (leap second)
+ * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z".replace(":60", ":59")) // "+00:00" (the clamped instant)
  */
 export declare function getTimeZoneOffset(timeZone: string, instant: string): string;

package/dist/zoned/get/getTimeZoneOffset.js

@@ -1,4 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { hasInstantShape } from "../../internal/isoStringBody.js";
+import { instantLeapSecond } from "../../regex/index.js";
 import { isValidTimeZone } from "../validate/index.js";
 /**
  * Return an IANA timeZone's UTC offset at a given instant.
@@ -8,7 +10,14 @@ import { isValidTimeZone } from "../validate/index.js";
  *   why (like `getDstTransitions`) it lives in `get/` despite taking two
  *   arguments: neither is a date *value* being described, both are
  *   coordinates for a zone-level lookup.
- * - Returns "" for an invalid timeZone or instant.
+ * - Returns "" for an invalid timeZone or instant, including a leap second in any spelling
+ *   (`23:59:60`, `t`/space separator, basic `235960`), which Temporal would read as `:59`.
+ *   Compatibility: to look up the offset at the clamped `:59` instant as earlier releases did,
+ *   pass that instant (`"2016-12-31T23:59:59Z"`), or call
+ *   `Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone).offset` directly.
+ * - The instant is ISO 8601 extended format before any annotation (`<date>T<time>`, then `Z` or
+ *   `±HH:MM[:SS[.fraction]]`): basic format, a `t` or space separator, a lower-case `z` and an
+ *   hour-only offset return "".
  *
  * @param timeZone IANA timeZone identifier
  * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
@@ -19,9 +28,17 @@ import { isValidTimeZone } from "../validate/index.js";
  * @example getTimeZoneOffset("Asia/Kathmandu", "2024-01-15T12:00:00Z") // "+05:45"
  * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
  * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
+ * @example getTimeZoneOffset("America/New_York", "2024-07-15T16:00:00z") // "" (lower-case z)
+ * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z") // "" (leap second)
+ * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z".replace(":60", ":59")) // "+00:00" (the clamped instant)
  */
 export function getTimeZoneOffset(timeZone, instant) {
-    if (!isValidTimeZone(timeZone)) {
+    if (typeof instant !== "string") {
+        return "";
+    }
+    if (!isValidTimeZone(timeZone) ||
+        instantLeapSecond.test(instant) ||
+        !hasInstantShape(instant)) {
         return "";
     }
     try {

package/dist/zoned/get/getZonedNow.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the current zoned datetime for the specified IANA timeZone.
  *
@@ -14,18 +15,28 @@ import { isValidTimeZone } from "../validate/index.js";
  * @example getZonedNow("Invalid/Zone") // ""
  */
 export function getZonedNow(ianaTimezone, optionsArg) {
-    const options = {
-        smallestUnit: "millisecond",
-        ...optionsArg,
-    };
-    if (!isValidTimeZone(ianaTimezone)) {
-        return "";
-    }
     try {
-        const now = Temporal.Now.zonedDateTimeISO(ianaTimezone);
-        return now.toString(options);
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const options = {
+            smallestUnit: "millisecond",
+            ...optionsArg,
+        };
+        if (!isValidTimeZone(ianaTimezone)) {
+            return "";
+        }
+        try {
+            const now = Temporal.Now.zonedDateTimeISO(ianaTimezone);
+            return now.toString(options);
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/zoned/get/getZonedNowUnit.d.ts

@@ -1,3 +1,4 @@
+import { Temporal } from "@js-temporal/polyfill";
 /**
  * Units extractable from the current time in a specific IANA timeZone, as
  * consumed by `getZonedNowUnit`.
@@ -15,26 +16,29 @@
  * | `minute` | 0–59, zero-padded. |
  * | `second` | 0–59, zero-padded. |
  * | `millisecond` | 0–999, zero-padded to 3. |
- * | `microsecond` | Sub-millisecond microseconds (0–999999). |
- * | `nanosecond` | Sub-millisecond nanoseconds (0–999999999). |
+ * | `microsecond` | Microseconds within the millisecond, 0–999, zero-padded to 3. |
+ * | `nanosecond` | Nanoseconds within the microsecond, 0–999, zero-padded to 3. |
  *
  * @example
  * import { ZonedNowUnit } from "@northguild/gmt/zoned";
  * const u: ZonedNowUnit = "hour";
  */
-export type ZonedNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";
+export type ZonedNowUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"> | "dayOfWeek";
 /**
  * Return the requested current unit value for the specified IANA timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
- * - Uses weekOfYear helper for week calculations.
+ * - `week` is the ISO 8601 week number, from `parseWeekFromDate`.
  * - Validation is performed on timezone and unit.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
  *
  * @param ianaTimezone IANA timeZone identifier
  * @param unit unit to extract from current zoned time
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example getZonedNowUnit("America/New_York", "hour") // "07"
+ * @example getZonedNowUnit("UTC", "hours") // "14", if the UTC time is 14:xx (plural unit name)
  * @example getZonedNowUnit("invalid", "hour") // ""
  */
 export declare function getZonedNowUnit(ianaTimezone: string, unit: ZonedNowUnit): string;