@northguild/gmt 1.16.0 → 1.18.0

package/dist/internal/splitStep.js

@@ -68,7 +68,8 @@ function closedAtRangeLimit(slices, current, end, maxSlices) {
  * - A step that goes backwards returns `null`.
  * - More than `maxSlices` slices returns `null` as soon as the next one is due, so the work stays
  *   bounded by the limit (owner decision A2, CORE-8).
- * - The last slice's end is trimmed to `end`. Callers handle `start >= end` before calling.
+ * - The last slice's end is `end` itself, whether the last step passes `end` (trimmed) or lands on
+ *   it. Callers handle `start >= end` before calling.
  * - A step that throws a RangeError (it lands past Temporal's last representable value, so after
  *   `end`) closes the split with a last slice ending at `end`.
  *
@@ -111,7 +112,9 @@ export function tileByUnit(start, end, compare, unit, amount, maxSlices, add = (
             return null;
         }
         stalled = 0;
-        slices.push([current, compare(next, end) > 0 ? end : next]);
+        // A step that lands on `end` closes with `end` itself, as a trimmed one does: the two compare
+        // equal but may be written differently (a zoned `end` in another zone than `start`).
+        slices.push([current, compare(next, end) >= 0 ? end : next]);
         current = next;
     }
     return slices;
@@ -135,6 +138,35 @@ const LONGEST_UNIT_NANOSECONDS = {
     months: 31 * NANOSECONDS_PER_DAY,
     years: 385 * NANOSECONDS_PER_DAY,
 };
+/**
+ * The step a split takes when its boundaries are then floored to whole `floorUnit`s.
+ *
+ * - An exact step shorter than one `floorUnit` moves each boundary by less than one unit, so the
+ *   floored boundaries are every whole unit from the start to the end, each one repeated once per
+ *   step that falls inside it. Stepping by one `floorUnit` gives those boundaries once each: no
+ *   empty piece, and no work spent on steps the result cannot show.
+ * - Any other step is returned unchanged: a step of one `floorUnit` or more never floors two
+ *   boundaries to the same value, a calendar step is never shorter than a second, and a
+ *   fractional `amount` is left for Temporal to reject.
+ * - The split's start must itself be a whole `floorUnit`, as a Unix epoch is.
+ *
+ * @param unit plural duration unit, as returned by `resolveDurationUnit`
+ * @param amount positive number of units per step
+ * @param floorUnit plural exact unit the boundaries are floored to
+ * @returns the `[unit, amount]` to step by
+ *
+ * @example stepNoFinerThan("milliseconds", 500, "seconds") // ["seconds", 1]
+ * @example stepNoFinerThan("milliseconds", 1500, "seconds") // ["milliseconds", 1500]
+ * @example stepNoFinerThan("days", 1, "seconds") // ["days", 1]
+ */
+export function stepNoFinerThan(unit, amount, floorUnit) {
+    const isFiner = isExactDurationUnit(unit) &&
+        isExactDurationUnit(floorUnit) &&
+        Number.isInteger(amount) &&
+        LONGEST_UNIT_NANOSECONDS[unit] * amount <
+            LONGEST_UNIT_NANOSECONDS[floorUnit];
+    return isFiner ? [floorUnit, 1] : [unit, amount];
+}
 /**
  * A zoned boundary can sit this far from its wall-clock distance: a UTC offset lies strictly
  * within ±24 hours (Temporal IsOffsetTimeZoneIdentifier / ECMA-262 time zone offset range), so

package/dist/internal/startOrEndOfZoned.js

@@ -5,6 +5,7 @@ import { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 import { resolveWeekStartsOn } from "./resolveWeekStartsOn.js";
 import { isValidDateTimeUnit } from "../plain/validate/index.js";
 import { isValidZonedDateTime } from "../zoned/validate/index.js";
+import { optionOrDefault } from "./optionOrDefault.js";
 /**
  * Internal shared implementation for `startOfZoned` / `endOfZoned`.
  *
@@ -32,9 +33,7 @@ export function startOrEndOfZoned(value, unit, options, isEnd) {
     // An end is next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
     // print an earlier instant than the end (Calendar & zone semantics §3).
     const fractionalSecondDigits = isEnd
-        ? options.fractionalSecondDigits === undefined
-            ? 9
-            : options.fractionalSecondDigits
+        ? optionOrDefault(options.fractionalSecondDigits, 9)
         : defaultFractionalDigits(resolvedUnit, options.fractionalSecondDigits);
     try {
         const source = zonedDateTimeFrom(value);

package/dist/internal/temporalCompat/capabilities.d.ts

@@ -3,6 +3,11 @@ import { type DefectId, type Repro } from "./repros.js";
 export declare function runRepro(repro: Pick<Repro, "run">): string;
 /** True when a repro's output is the spec-correct value, i.e. the installed runtime is fixed. */
 export declare function reproPasses(repro: Pick<Repro, "expected">, output: string): boolean;
+/**
+ * True when any of `candidates` for this defect and Temporal calendar id fails. Stops at the first
+ * failure, so the order of a defect's repros is the order they are tried in.
+ */
+export declare function anyReproFails(candidates: readonly Repro[], defect: DefectId, calendar: string): boolean;
 /**
  * True when any repro for this defect and Temporal calendar id fails in the installed runtime.
  * A calendar with no repro for the defect is not affected by it.
@@ -19,6 +24,27 @@ export declare function isDefectPresent(defect: DefectId, calendar: string): boo
  * take the spec path through `isCalendarArithmeticCompatNeeded`.
  */
 export declare function isNudgeWindowCompatNeeded(): boolean;
+/**
+ * True when this runtime matches a zoned string's offset by minutes even when the offset is
+ * written with seconds (defect D12).
+ *
+ * TC39 `ToTemporalZonedDateTime` matches by minutes only an offset with no seconds part; one
+ * written with seconds must equal the zone's offset exactly. A runtime that always matches by
+ * minutes accepts `-00:45:00[Africa/Monrovia]` for a zone at −00:44:30, and picks the wrong pass
+ * of a second repeated by a sub-minute transition (Pacific/Niue, 1952).
+ */
+export declare function isSecondsOffsetMatchCompatNeeded(): boolean;
+/**
+ * True when this runtime's time zone transition search cannot be trusted (defect D13).
+ *
+ * TC39 `GetNamedTimeZoneNextTransition` returns the first offset change after an instant. A runtime
+ * that samples the offset in steps longer than the gap between two changes skips a pair that
+ * returns to the same offset, and can loop for ever on three different offsets in one step. The
+ * skipped-pair repros come first and none of them can stall, so on such a runtime the probe
+ * answers before a stalling repro is reached. Every repro has to pass for the workaround to go
+ * dormant: a runtime that fixes the skipped pairs and still stalls on one zone keeps it.
+ */
+export declare function isTransitionSearchCompatNeeded(): boolean;
 /**
  * True when calendar arithmetic in `calendarId` needs the compat layer in this runtime: any of its
  * add, until or read probes fails (CORE-6 spec §3.6.2). `iso8601` never does, and costs nothing.

package/dist/internal/temporalCompat/capabilities.js

@@ -21,6 +21,15 @@ export function runRepro(repro) {
 export function reproPasses(repro, output) {
     return output === repro.expected;
 }
+/**
+ * True when any of `candidates` for this defect and Temporal calendar id fails. Stops at the first
+ * failure, so the order of a defect's repros is the order they are tried in.
+ */
+export function anyReproFails(candidates, defect, calendar) {
+    return candidates.some((repro) => repro.defect === defect &&
+        repro.calendar === calendar &&
+        !reproPasses(repro, runRepro(repro)));
+}
 const cache = new Map();
 /**
  * True when any repro for this defect and Temporal calendar id fails in the installed runtime.
@@ -32,9 +41,7 @@ export function isDefectPresent(defect, calendar) {
     if (cached !== undefined) {
         return cached;
     }
-    const present = repros.some((repro) => repro.defect === defect &&
-        repro.calendar === calendar &&
-        !reproPasses(repro, runRepro(repro)));
+    const present = anyReproFails(repros, defect, calendar);
     cache.set(key, present);
     return present;
 }
@@ -51,6 +58,31 @@ export function isDefectPresent(defect, calendar) {
 export function isNudgeWindowCompatNeeded() {
     return isDefectPresent("D11", "iso8601");
 }
+/**
+ * True when this runtime matches a zoned string's offset by minutes even when the offset is
+ * written with seconds (defect D12).
+ *
+ * TC39 `ToTemporalZonedDateTime` matches by minutes only an offset with no seconds part; one
+ * written with seconds must equal the zone's offset exactly. A runtime that always matches by
+ * minutes accepts `-00:45:00[Africa/Monrovia]` for a zone at −00:44:30, and picks the wrong pass
+ * of a second repeated by a sub-minute transition (Pacific/Niue, 1952).
+ */
+export function isSecondsOffsetMatchCompatNeeded() {
+    return isDefectPresent("D12", "iso8601");
+}
+/**
+ * True when this runtime's time zone transition search cannot be trusted (defect D13).
+ *
+ * TC39 `GetNamedTimeZoneNextTransition` returns the first offset change after an instant. A runtime
+ * that samples the offset in steps longer than the gap between two changes skips a pair that
+ * returns to the same offset, and can loop for ever on three different offsets in one step. The
+ * skipped-pair repros come first and none of them can stall, so on such a runtime the probe
+ * answers before a stalling repro is reached. Every repro has to pass for the workaround to go
+ * dormant: a runtime that fixes the skipped pairs and still stalls on one zone keeps it.
+ */
+export function isTransitionSearchCompatNeeded() {
+    return isDefectPresent("D13", "iso8601");
+}
 /** Defects that make the runtime's calendar arithmetic or reads differ from the spec. */
 const ARITHMETIC_DEFECTS = [
     "D1",

package/dist/internal/temporalCompat/fieldSearch.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { MAX_ISO_EPOCH_DAYS } from "../zonedWallClock.js";
+import { MAX_ISO_EPOCH_DAYS } from "../epochNanoseconds.js";
 import { calendarFieldsOf } from "./calendarFields.js";
 /*
  * Read-only fields → ISO search. Calendar fields increase strictly with ISO order under the key

package/dist/internal/temporalCompat/index.d.ts

@@ -1,4 +1,4 @@
 export { type CalendarDateUnit, calendarDateAdd, calendarDateUntil, } from "./calendarDateArithmetic.js";
 export { calendarDateFromFields } from "./calendarDateFromFields.js";
-export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, } from "./capabilities.js";
+export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, isSecondsOffsetMatchCompatNeeded, isTransitionSearchCompatNeeded, } from "./capabilities.js";
 export { calendarFieldsOf } from "./calendarFields.js";

package/dist/internal/temporalCompat/index.js

@@ -1,5 +1,5 @@
 // The only import surface of the Temporal compat layer. See README.md.
 export { calendarDateAdd, calendarDateUntil, } from "./calendarDateArithmetic.js";
 export { calendarDateFromFields } from "./calendarDateFromFields.js";
-export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, } from "./capabilities.js";
+export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, isSecondsOffsetMatchCompatNeeded, isTransitionSearchCompatNeeded, } from "./capabilities.js";
 export { calendarFieldsOf } from "./calendarFields.js";

package/dist/internal/temporalCompat/repros.d.ts

@@ -1,5 +1,5 @@
 /** Defect ids from the CORE-6 calendar-correctness spec §1.2. */
-export type DefectId = "D1" | "D2" | "D3" | "D4" | "D5" | "D6" | "D7" | "D8" | "D10" | "D11";
+export type DefectId = "D1" | "D2" | "D3" | "D4" | "D5" | "D6" | "D7" | "D8" | "D10" | "D11" | "D12" | "D13";
 /**
  * Zoned defects worked around in `internal/zonedWallClock*`: the range-limit defects (upstream
  * issue drafts A, B and D in the CORE-6 polyfill research) and zoned.E, the transition search

package/dist/internal/temporalCompat/repros.js

@@ -498,6 +498,161 @@ const d9Repros = [
         },
     ];
 });
+/** The epoch nanoseconds `Temporal.ZonedDateTime.from(item)` reads, or the error's name. */
+function zonedStringEpoch(item) {
+    try {
+        return String(Temporal.ZonedDateTime.from(item).epochNanoseconds);
+    }
+    catch (error) {
+        return error instanceof Error ? error.name : "Error";
+    }
+}
+/**
+ * D12 (`internal/zonedWallClock.ts` defect 4): `ToTemporalZonedDateTime` matches a string's
+ * offset against the zone by minutes even when the offset is written with seconds, where TC39
+ * requires match-exactly ("If offsetParseResult contains more than one MinuteSecond Parse Node,
+ * set matchBehaviour to match-exactly"). Expected values: test262
+ * `test/intl402/Temporal/ZonedDateTime/from/zoneddatetime-sub-minute-offset.js` ("rounded
+ * HH:MM:SS not accepted in string offset (offset=reject)", and the Pacific/Niue edge case,
+ * "-11:20:00 is accepted as -11:20:00": `reference + 20_000_000_000n`). The test writes the
+ * Monrovia time as `T12`; `T12:00` is the same wall time.
+ */
+const d12Repros = [
+    {
+        defect: "D12",
+        calendar: "iso8601",
+        name: "roundedSecondsRejected",
+        expected: "RangeError",
+        run: () => zonedStringEpoch("1970-01-01T12:00-00:45:00[Africa/Monrovia]"),
+    },
+    {
+        defect: "D12",
+        calendar: "iso8601",
+        name: "exactSecondsSecondPass",
+        expected: "-543069601000000000",
+        run: () => zonedStringEpoch("1952-10-15T23:59:59-11:20:00[Pacific/Niue]"),
+    },
+];
+/** More `Intl.DateTimeFormat#format` reads than this for one transition lookup is a stalled search. */
+const D13_INTL_READ_LIMIT = 20_000;
+/**
+ * `run()`'s output, or a note when it made more than `D13_INTL_READ_LIMIT` reads through
+ * `Intl.DateTimeFormat.prototype.format`, where the read then throws so a search that would never
+ * return stops. Polyfill 0.5.1 reads every offset through that getter.
+ */
+function withBoundedOffsetReads(run) {
+    const prototype = Intl.DateTimeFormat.prototype;
+    const original = Object.getOwnPropertyDescriptor(prototype, "format");
+    const originalGet = original?.get;
+    if (original === undefined || originalGet === undefined) {
+        return "cannot bound Intl.DateTimeFormat#format";
+    }
+    let reads = 0;
+    Object.defineProperty(prototype, "format", {
+        configurable: true,
+        get() {
+            const format = originalGet.call(this);
+            return (date) => {
+                reads++;
+                if (reads > D13_INTL_READ_LIMIT) {
+                    throw new RangeError(`more than ${D13_INTL_READ_LIMIT} offset reads`);
+                }
+                return format(date);
+            };
+        },
+    });
+    try {
+        return run();
+    }
+    finally {
+        Object.defineProperty(prototype, "format", original);
+    }
+}
+/** America/Boa_Vista's 2000-10-08T04:00:00Z advance (−04:00 → −03:00, local midnight skipped). */
+const BOA_VISTA_ADVANCE = "2000-10-08T01:00:00-03:00[America/Boa_Vista]";
+/**
+ * D13 (`internal/zonedWallClock.ts` defect 5): `GetNamedTimeZoneNextTransition` and
+ * `…PreviousTransition` sample the offset every 14 days. Two changes inside one step that return
+ * to the same offset are skipped (America/Boa_Vista 2000-10-08 and 2000-10-15, 601,200 s apart),
+ * so `GetStartOfDay` for the skipped midnight of 2000-10-08 fails too; three different offsets in
+ * one step (Europe/Riga 1944-10-02 and 1944-10-12) make `bisect` loop for ever, its assertion
+ * compiled out. Spec: TC39 Temporal `GetNamedTimeZoneNextTransition`, "the smallest integer
+ * greater than epochNanoseconds" at which the offset changes. Expected values: Node 26.10.0's
+ * native Temporal and `zdump -v` (tz 2026c). The polyfill's main branch (a79c6a1, per-zone search
+ * windows, in no release) fixes the zones it lists but leaves `bisect` unchanged, and its 17-day
+ * window for Africa/El_Aaiun holds three offsets in 1976: `stall.nextElAaiun` covers that, so the
+ * workaround stays until every repro here passes.
+ *
+ * Order matters: the capability probe stops at the first failing repro, so the `skip.*` repros,
+ * which cannot stall, come before `stall.*`, which a runtime that fails them never runs in
+ * process. The canary runs `stall.*` under `withBoundedOffsetReads`.
+ */
+const d13Repros = [
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.nextBoaVista",
+        expected: BOA_VISTA_ADVANCE,
+        run: () => String(Temporal.Instant.from("2000-10-01T12:00:00Z")
+            .toZonedDateTimeISO("America/Boa_Vista")
+            .getTimeZoneTransition("next")),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.previousBoaVista",
+        expected: "2000-10-14T23:00:00-04:00[America/Boa_Vista]",
+        run: () => String(Temporal.Instant.from("2000-10-20T12:00:00Z")
+            .toZonedDateTimeISO("America/Boa_Vista")
+            .getTimeZoneTransition("previous")),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.startOfDayBoaVista",
+        expected: BOA_VISTA_ADVANCE,
+        run: () => String(Temporal.PlainDate.from("2000-10-08").toZonedDateTime("America/Boa_Vista")),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.hoursInDayNoronha",
+        expected: "23",
+        run: () => String(Temporal.ZonedDateTime.from("2000-10-08T12:00[America/Noronha]")
+            .hoursInDay),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "stall.nextRiga",
+        expected: "1944-10-02T02:00:00+01:00[Europe/Riga]",
+        run: () => withBoundedOffsetReads(() => String(Temporal.Instant.from("1944-04-15T12:00:00Z")
+            .toZonedDateTimeISO("Europe/Riga")
+            .getTimeZoneTransition("next"))),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "stall.nextSimferopol",
+        expected: "1944-04-03T03:00:00+02:00[Europe/Simferopol]",
+        run: () => withBoundedOffsetReads(() => String(Temporal.Instant.from("1943-10-15T12:00:00Z")
+            .toZonedDateTimeISO("Europe/Simferopol")
+            .getTimeZoneTransition("next"))),
+    },
+    // js-temporal main (a79c6a1) gives Africa/El_Aaiun a 17-day search window. Its changes of
+    // 1976-04-14T01:00:00Z (−01:00 → +00:00) and 1976-05-01T00:00:00Z (+00:00 → +01:00) are 16.958
+    // days apart, so one window holds three offsets and `bisect`, unchanged there, cannot narrow.
+    // 0.5.1's 14-day step passes these two; a release with a79c6a1 alone would not.
+    ...["1976-04-14T00:30:00Z", "1976-03-28T00:30:00Z"].map((from) => ({
+        defect: "D13",
+        calendar: "iso8601",
+        name: `stall.nextElAaiun ${from}`,
+        expected: "1976-04-14T01:00:00+00:00[Africa/El_Aaiun]",
+        run: () => withBoundedOffsetReads(() => String(Temporal.Instant.from(from)
+            .toZonedDateTimeISO("Africa/El_Aaiun")
+            .getTimeZoneTransition("next"))),
+    })),
+];
 export const repros = [
     ...d9Repros,
     ...zonedARepros,
@@ -508,6 +663,8 @@ export const repros = [
     ...d1ArithmeticRepros,
     d1RelativeToRepro,
     ...d10Repros,
+    ...d12Repros,
+    ...d13Repros,
     ...d6Repros,
     d7Repro,
     d7LeapMonthEndRepro,

package/dist/internal/timestampEvents.d.ts

@@ -0,0 +1,32 @@
+import type { TimestampClass } from "../types/index.js";
+/** A validated `TimestampEvent`, with both of its moments as epoch nanoseconds. */
+export type ParsedTimestampEvent = {
+    classifier: TimestampClass;
+    /** The event's `at`, exactly as the caller wrote it. */
+    at: string;
+    atNanoseconds: bigint;
+    recordedNanoseconds: bigint;
+};
+/**
+ * Validate a list of `TimestampEvent`s and put them in recording order, or `null`.
+ *
+ * The shared reading behind `bestAvailable` and `estimateDrift`:
+ *
+ * - Every event must be an object whose `classifier` is exactly `PLN`, `EST`, `REQ` or `ACT` and
+ *   whose `at` and `recordedAt` are instants (`Z`/offset) or zoned strings, read as
+ *   `parseInstantNanoseconds` reads them: the offset fixes the instant, a minute-rounded offset
+ *   is read as its bracketed zone's real offset, and the bracket is otherwise not checked. One
+ *   invalid event makes the whole list invalid.
+ * - The result is sorted by `recordedAt`, earliest first. Events recorded at the same instant
+ *   keep their input order, so of two ties the later index is the later record.
+ * - `at` is kept exactly as written, so a caller can echo it.
+ * - An empty list is `[]`; the caller decides what that means.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param events candidate list of timestamp events
+ * @returns the events in recording order with their instants, or null on invalid input
+ *
+ * @example parseTimestampEvents([]) // []
+ * @example parseTimestampEvents([{ classifier: "ETA", at: "2024-06-15T12:00:00Z", recordedAt: "2024-06-15T10:00:00Z" }]) // null
+ */
+export declare function parseTimestampEvents(events: unknown): ParsedTimestampEvent[] | null;

package/dist/internal/timestampEvents.js

@@ -0,0 +1,76 @@
+import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+import { isObject } from "./isObject.js";
+const TIMESTAMP_CLASSES = new Set([
+    "PLN",
+    "EST",
+    "REQ",
+    "ACT",
+]);
+/** One event validated, or `null`. */
+function parseEvent(event) {
+    if (!isObject(event)) {
+        return null;
+    }
+    const { classifier, at, recordedAt } = event;
+    if (!TIMESTAMP_CLASSES.has(classifier) || typeof at !== "string") {
+        return null;
+    }
+    const atNanoseconds = parseInstantNanoseconds(at);
+    const recordedNanoseconds = parseInstantNanoseconds(recordedAt);
+    if (atNanoseconds === null || recordedNanoseconds === null) {
+        return null;
+    }
+    return {
+        classifier: classifier,
+        at,
+        atNanoseconds,
+        recordedNanoseconds,
+    };
+}
+/**
+ * Validate a list of `TimestampEvent`s and put them in recording order, or `null`.
+ *
+ * The shared reading behind `bestAvailable` and `estimateDrift`:
+ *
+ * - Every event must be an object whose `classifier` is exactly `PLN`, `EST`, `REQ` or `ACT` and
+ *   whose `at` and `recordedAt` are instants (`Z`/offset) or zoned strings, read as
+ *   `parseInstantNanoseconds` reads them: the offset fixes the instant, a minute-rounded offset
+ *   is read as its bracketed zone's real offset, and the bracket is otherwise not checked. One
+ *   invalid event makes the whole list invalid.
+ * - The result is sorted by `recordedAt`, earliest first. Events recorded at the same instant
+ *   keep their input order, so of two ties the later index is the later record.
+ * - `at` is kept exactly as written, so a caller can echo it.
+ * - An empty list is `[]`; the caller decides what that means.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param events candidate list of timestamp events
+ * @returns the events in recording order with their instants, or null on invalid input
+ *
+ * @example parseTimestampEvents([]) // []
+ * @example parseTimestampEvents([{ classifier: "ETA", at: "2024-06-15T12:00:00Z", recordedAt: "2024-06-15T10:00:00Z" }]) // null
+ */
+export function parseTimestampEvents(events) {
+    try {
+        if (!Array.isArray(events)) {
+            return null;
+        }
+        const parsed = [];
+        for (const event of events) {
+            const one = parseEvent(event);
+            if (one === null) {
+                return null;
+            }
+            parsed.push(one);
+        }
+        // Array.prototype.sort is stable, so ties keep their input order.
+        return parsed.sort((a, b) => a.recordedNanoseconds < b.recordedNanoseconds
+            ? -1
+            : a.recordedNanoseconds > b.recordedNanoseconds
+                ? 1
+                : 0);
+    }
+    catch {
+        // A hostile value (a throwing getter, a revoked Proxy) is invalid input.
+        return null;
+    }
+}

package/dist/internal/utcZonedDateTime.d.ts

@@ -1,13 +1,16 @@
 import { Temporal } from "@js-temporal/polyfill";
 /**
  * Read a UTC ISO string as a zoned date-time for the `parse*FromUtc` accessors: the instant it
- * names, on the wall clock of `options.timeZone` (UTC when omitted). The utc twin of
- * `unixZonedDateTime`.
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixZonedDateTime`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
+ *   (see `normalizeTimeZone`).
  *
  * @param value UTC ISO 8601 datetime string
  * @param options optional `{ timeZone }`
  * @returns the zoned date-time, or null when the value or the zone is invalid
  * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00+09:00[Asia/Tokyo]"
+ * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "local" })?.timeZoneId // the system zone, e.g. "America/New_York"
  * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
  * @example utcZonedDateTime("2024-03-15T14:30:00") // null (no Z)
  */

package/dist/internal/utcZonedDateTime.js

@@ -1,23 +1,26 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidUtc } from "../utc/validate/isValidUtc.js";
-import { resolveReadingTimeZone } from "./resolveReadingTimeZone.js";
+import { normalizeTimeZone } from "./normalizeTimeZone.js";
 /**
  * Read a UTC ISO string as a zoned date-time for the `parse*FromUtc` accessors: the instant it
- * names, on the wall clock of `options.timeZone` (UTC when omitted). The utc twin of
- * `unixZonedDateTime`.
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixZonedDateTime`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
+ *   (see `normalizeTimeZone`).
  *
  * @param value UTC ISO 8601 datetime string
  * @param options optional `{ timeZone }`
  * @returns the zoned date-time, or null when the value or the zone is invalid
  * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00+09:00[Asia/Tokyo]"
+ * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "local" })?.timeZoneId // the system zone, e.g. "America/New_York"
  * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
  * @example utcZonedDateTime("2024-03-15T14:30:00") // null (no Z)
  */
 export function utcZonedDateTime(value, options) {
     if (!isValidUtc(value))
         return null;
-    const timeZone = resolveReadingTimeZone(options?.timeZone);
-    if (timeZone === null)
+    const timeZone = normalizeTimeZone(options?.timeZone);
+    if (timeZone === "")
         return null;
     try {
         return Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);

package/dist/internal/wallClockAtOffset.d.ts

@@ -0,0 +1,22 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * The wall clock an instant reads at a fixed UTC offset, including a sub-minute or fractional
+ * one. Callers write the offset text themselves.
+ *
+ * The shift happens on the wall clock, never on the instant: a `PlainDateTime` reaches a day
+ * further either side than an `Instant` does (TC39 `ISODateTimeWithinLimits` against
+ * `IsValidEpochNanoseconds`), so shifting the instant first would reject the last 14 hours of
+ * the representable range, where `+275760-09-13T00:00:00Z` at `+14:00` names a local time that
+ * exists. No offset time zone is built either: Temporal's offset time-zone identifiers are
+ * minute precision, and an offset such as `-00:44:30` or `+05:30:15.25` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param offsetNanoseconds UTC offset in nanoseconds, east positive
+ * @returns the local wall clock at that offset
+ *
+ * @example wallClockAtOffset(Temporal.Instant.from("1970-01-01T00:00:00Z"), -2_670_000_000_000n).toString() // "1969-12-31T23:15:30"
+ * @example wallClockAtOffset(Temporal.Instant.from("+275760-09-13T00:00:00Z"), 50_400_000_000_000n).toString() // "+275760-09-13T14:00:00"
+ */
+export declare function wallClockAtOffset(instant: Temporal.Instant, offsetNanoseconds: bigint): Temporal.PlainDateTime;

package/dist/internal/wallClockAtOffset.js

@@ -0,0 +1,26 @@
+/**
+ * The wall clock an instant reads at a fixed UTC offset, including a sub-minute or fractional
+ * one. Callers write the offset text themselves.
+ *
+ * The shift happens on the wall clock, never on the instant: a `PlainDateTime` reaches a day
+ * further either side than an `Instant` does (TC39 `ISODateTimeWithinLimits` against
+ * `IsValidEpochNanoseconds`), so shifting the instant first would reject the last 14 hours of
+ * the representable range, where `+275760-09-13T00:00:00Z` at `+14:00` names a local time that
+ * exists. No offset time zone is built either: Temporal's offset time-zone identifiers are
+ * minute precision, and an offset such as `-00:44:30` or `+05:30:15.25` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param offsetNanoseconds UTC offset in nanoseconds, east positive
+ * @returns the local wall clock at that offset
+ *
+ * @example wallClockAtOffset(Temporal.Instant.from("1970-01-01T00:00:00Z"), -2_670_000_000_000n).toString() // "1969-12-31T23:15:30"
+ * @example wallClockAtOffset(Temporal.Instant.from("+275760-09-13T00:00:00Z"), 50_400_000_000_000n).toString() // "+275760-09-13T14:00:00"
+ */
+export function wallClockAtOffset(instant, offsetNanoseconds) {
+    return instant
+        .toZonedDateTimeISO("UTC")
+        .toPlainDateTime()
+        .add({ nanoseconds: Number(offsetNanoseconds) });
+}

package/dist/internal/zonedBucket.js

@@ -160,12 +160,13 @@ function truncatedWallClockUntil(from, to, unit) {
  * `zoned - 1 ns` is `zoned` itself exactly when a transition sits on it. At the first
  * representable instant there is no `zoned - 1 ns`, and nothing earlier, so that check is skipped.
  */
-function transitionAtOrBefore(zoned) {
+function transitionAtOrBefore(zoned, notBefore) {
     try {
         if (transitionSitsOn(zoned)) {
             return zoned;
         }
-        return zonedPreviousTransition(zoned);
+        // The caller ignores a transition before `notBefore`, so the search stops there.
+        return zonedPreviousTransition(zoned, notBefore.epochNanoseconds - 1n);
     }
     catch {
         return null;
@@ -180,7 +181,7 @@ function transitionSitsOn(zoned) {
     catch {
         return false;
     }
-    const next = zonedNextTransition(justBefore);
+    const next = zonedNextTransition(justBefore, zoned.epochNanoseconds);
     return next !== null && next.toInstant().equals(zoned.toInstant());
 }
 /** Units whose buckets are labelled by a local date: a repeated wall time inside one stays one bucket. */
@@ -250,7 +251,7 @@ export function zonedUnitStart(zoned, unit, weekStartsOn = 1) {
     let start = boundaryInOwnOffset(zoned, unit, weekStartsOn);
     let cursor = zoned;
     for (let i = 0; i < MAX_TRANSITION_WALKBACK; i++) {
-        const transition = transitionAtOrBefore(cursor);
+        const transition = transitionAtOrBefore(cursor, start);
         // A transition exactly on `start` is still checked: Havana's second 00:00 is a unit-aligned
         // own-offset start that the day runs straight through.
         if (!transition || Temporal.ZonedDateTime.compare(transition, start) < 0) {
@@ -325,7 +326,8 @@ export function nextZonedBucketStart(current, unit, weekStartsOn = 1) {
     let cursor = current;
     for (let i = 0; i < MAX_TRANSITION_WALKBACK; i++) {
         const boundary = nextBoundaryWithinRange(cursor, unit, weekStartsOn);
-        const transition = zonedNextTransition(cursor);
+        // A transition after the boundary changes nothing, so the search stops there.
+        const transition = zonedNextTransition(cursor, boundary?.epochNanoseconds);
         if (!transition ||
             (boundary !== null &&
                 Temporal.ZonedDateTime.compare(transition, boundary) > 0)) {
@@ -423,7 +425,7 @@ export function countZonedBuckets(start, end, unit, weekStartsOn = 1) {
     let runStart = startOfStart;
     let cursor = startOfStart;
     for (let i = 0; i < MAX_COUNTED_TRANSITIONS; i++) {
-        const transition = zonedNextTransition(cursor)?.withCalendar(start.calendarId) ?? null;
+        const transition = zonedNextTransition(cursor, startOfEnd.epochNanoseconds)?.withCalendar(start.calendarId) ?? null;
         if (!transition ||
             Temporal.ZonedDateTime.compare(transition, startOfEnd) > 0) {
             return (spanned +

package/dist/internal/zonedLocalDates.js

@@ -44,7 +44,7 @@ export function countZonedLocalDates(start, end) {
     const ranges = [];
     let runStart = start;
     for (let i = 0; i <= MAX_WALKED_TRANSITIONS; i++) {
-        const transition = zonedNextTransition(runStart);
+        const transition = zonedNextTransition(runStart, end.epochNanoseconds);
         const isLastRun = transition === null ||
             Temporal.ZonedDateTime.compare(transition, end) > 0;
         const runEnd = isLastRun ? end : transition.subtract({ nanoseconds: 1 });