@northguild/gmt 1.15.0 → 1.16.0

package/dist/internal/zonedLocalDates.js

@@ -0,0 +1,58 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { zonedNextTransition } from "./zonedWallClockOperations.js";
+const UNIX_EPOCH_DATE = new Temporal.PlainDate(1970, 1, 1);
+/**
+ * Transitions walked while collecting local dates, matching `countZonedBuckets`' cap: roughly
+ * 5,000 years of twice-yearly daylight saving; a longer walk answers with the sentinel.
+ */
+const MAX_WALKED_TRANSITIONS = 10_000;
+function epochDayOf(zoned) {
+    return UNIX_EPOCH_DATE.until(zoned.toPlainDate().withCalendar("iso8601"), {
+        largestUnit: "days",
+    }).days;
+}
+/** Size of the union of inclusive integer ranges. */
+function unionSize(ranges) {
+    const sorted = [...ranges].sort((x, y) => x[0] - y[0]);
+    let total = 0;
+    let [runStart, runEnd] = sorted[0];
+    for (const [from, to] of sorted.slice(1)) {
+        if (from > runEnd + 1) {
+            total += runEnd - runStart + 1;
+            [runStart, runEnd] = [from, to];
+        }
+        else if (to > runEnd) {
+            runEnd = to;
+        }
+    }
+    return total + runEnd - runStart + 1;
+}
+/**
+ * Count the distinct local (ISO) dates of the instants in the closed span `[start, end]`, in
+ * `start`'s time zone. `end` must already be expressed in that zone and not precede `start`.
+ *
+ * Between two zone transitions the wall clock runs continuously, so every date from a run's
+ * first to its last instant is touched. A transition can jump the clock past a whole date
+ * (`Pacific/Apia` deleted 2011-12-30), which no instant then has, or back into the previous
+ * date (`America/Goose_Bay` at 00:01 on 2010-11-07), which is touched again but counted once.
+ *
+ * @param start the span start
+ * @param end the span end, in `start`'s zone
+ * @returns the number of distinct local dates, or null past `MAX_WALKED_TRANSITIONS` transitions
+ */
+export function countZonedLocalDates(start, end) {
+    const ranges = [];
+    let runStart = start;
+    for (let i = 0; i <= MAX_WALKED_TRANSITIONS; i++) {
+        const transition = zonedNextTransition(runStart);
+        const isLastRun = transition === null ||
+            Temporal.ZonedDateTime.compare(transition, end) > 0;
+        const runEnd = isLastRun ? end : transition.subtract({ nanoseconds: 1 });
+        ranges.push([epochDayOf(runStart), epochDayOf(runEnd)]);
+        if (isLastRun) {
+            return unionSize(ranges);
+        }
+        runStart = transition;
+    }
+    return null;
+}

package/dist/internal/zonedNowUnitValue.d.ts

@@ -0,0 +1,24 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * One field of a zoned "now" as the `get*NowUnit` accessors return it: zero-padded to two digits
+ * (three for sub-second fields), the year and day of week unpadded. The week number is the
+ * caller's, since the plain and zoned accessors read it through `parseWeekFromDate` and the utc and
+ * unix ones from the ISO date.
+ *
+ * @param now the current moment on the wall clock being read
+ * @param unit a singular unit, `dayOfWeek` included (already validated by the caller)
+ * @param week the week number for `now`, as a string
+ * @returns the field, or "" for any other unit
+ * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09.012+00:00[UTC]"), "millisecond", () => "10") // "012"
+ * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09+00:00[UTC]"), "week", () => "10") // "10"
+ * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09+00:00[UTC]"), "quarter", () => "10") // ""
+ */
+export declare function zonedNowUnitValue(now: Temporal.ZonedDateTime, unit: string | null | undefined, week: (now: Temporal.ZonedDateTime) => string): string;
+/**
+ * The ISO 8601 week number of `now`'s date, the week the utc and unix `get*NowUnit` accessors read.
+ *
+ * @param now the current moment on the wall clock being read
+ * @returns the week number as a string
+ * @example isoWeekOfYear(Temporal.ZonedDateTime.from("2024-12-30T00:00:00+00:00[UTC]")) // "1"
+ */
+export declare function isoWeekOfYear(now: Temporal.ZonedDateTime): string;

package/dist/internal/zonedNowUnitValue.js

@@ -0,0 +1,58 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * One field of a zoned "now" as the `get*NowUnit` accessors return it: zero-padded to two digits
+ * (three for sub-second fields), the year and day of week unpadded. The week number is the
+ * caller's, since the plain and zoned accessors read it through `parseWeekFromDate` and the utc and
+ * unix ones from the ISO date.
+ *
+ * @param now the current moment on the wall clock being read
+ * @param unit a singular unit, `dayOfWeek` included (already validated by the caller)
+ * @param week the week number for `now`, as a string
+ * @returns the field, or "" for any other unit
+ * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09.012+00:00[UTC]"), "millisecond", () => "10") // "012"
+ * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09+00:00[UTC]"), "week", () => "10") // "10"
+ * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09+00:00[UTC]"), "quarter", () => "10") // ""
+ */
+export function zonedNowUnitValue(now, unit, week) {
+    switch (unit) {
+        case "year":
+            return now.year.toString();
+        case "month":
+            return now.month.toString().padStart(2, "0");
+        case "week":
+            return week(now);
+        case "day":
+            return now.day.toString().padStart(2, "0");
+        case "dayOfWeek":
+            return now.dayOfWeek.toString();
+        case "hour":
+            return now.hour.toString().padStart(2, "0");
+        case "minute":
+            return now.minute.toString().padStart(2, "0");
+        case "second":
+            return now.second.toString().padStart(2, "0");
+        case "millisecond":
+            return now.millisecond.toString().padStart(3, "0");
+        case "microsecond":
+            return (now.microsecond ?? 0).toString().padStart(3, "0");
+        case "nanosecond":
+            return (now.nanosecond ?? 0).toString().padStart(3, "0");
+        default:
+            return "";
+    }
+}
+/**
+ * The ISO 8601 week number of `now`'s date, the week the utc and unix `get*NowUnit` accessors read.
+ *
+ * @param now the current moment on the wall clock being read
+ * @returns the week number as a string
+ * @example isoWeekOfYear(Temporal.ZonedDateTime.from("2024-12-30T00:00:00+00:00[UTC]")) // "1"
+ */
+export function isoWeekOfYear(now) {
+    const plainDate = Temporal.PlainDate.from({
+        year: now.year,
+        month: now.month,
+        day: now.day,
+    });
+    return (plainDate.weekOfYear ?? 0).toString();
+}

package/dist/internal/zonedWallClock.d.ts

@@ -0,0 +1,84 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset, Overflow } from "../types/index.js";
+/** Options accepted by `Temporal.ZonedDateTime.from`. */
+export interface ZonedFromOptions {
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+    overflow?: Overflow;
+}
+type ResolvedDisambiguation = NonNullable<Disambiguation>;
+type ResolvedOffsetOption = NonNullable<Offset>;
+/**
+ * The offset a zoned value carries: none (resolve the wall clock), a known offset, or an offset
+ * whose own instant lies outside the representable range (so no in-range candidate can match it).
+ */
+export type CarriedOffset = "absent" | "out-of-range" | {
+    nanoseconds: bigint;
+};
+/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
+export declare const MAX_ISO_EPOCH_DAYS = 100000000;
+/**
+ * `getTimeZoneTransition("next")` looks at most three years (366-day years) past its receiver;
+ * a `null` from further than this from the maximum is the polyfill's own horizon, not defect 2.
+ */
+export declare const NEXT_TRANSITION_HORIZON_NANOSECONDS: bigint;
+/** Previous-transition steps walked back from the maximum instant; real zones need two or three. */
+export declare const MAX_TRANSITIONS_BEFORE_MAXIMUM = 64;
+/**
+ * 1847-01-01T00:00:00Z: `BEFORE_FIRST_DST` in js-temporal `lib/ecmascript.ts`. The polyfill never
+ * looks for a transition before it (defect 3).
+ */
+export declare const POLYFILL_TRANSITION_SEARCH_FLOOR = -3881520000000000000n;
+/** True for a date within `EDGE_WINDOW_DAYS` of either TC39 date limit. */
+export declare function isNearRangeEdge(date: Temporal.PlainDate): boolean;
+/** Offset time zones (`+10:00`) and `UTC` never consult tz data, so neither defect reaches them. */
+export declare function isNamedTimeZone(timeZone: string): boolean;
+/** TC39 `IsValidEpochNanoseconds`. */
+export declare function isValidEpoch(epochNanoseconds: bigint): boolean;
+/** TC39 `GetUTCEpochNanoseconds`: the wall clock read as if it were UTC (may lie outside the range). */
+export declare function utcEpochNanoseconds(wall: Temporal.PlainDateTime): bigint;
+/** TC39 `GetEpochNanosecondsFor`. */
+export declare function epochNanosecondsFor(timeZone: string, wall: Temporal.PlainDateTime, disambiguation: ResolvedDisambiguation): bigint;
+/**
+ * TC39 `GetStartOfDay`: the first valid wall-clock time on `date` in `timeZone` — midnight, or,
+ * when midnight is skipped, the transition that skips it.
+ */
+export declare function startOfDayEpochNanoseconds(timeZone: string, date: Temporal.PlainDate): bigint;
+/**
+ * True when a start of day on this local date — or, for a zoned value, on its own local date —
+ * may lie before the polyfill's transition search floor, so the polyfill's `GetStartOfDay` can
+ * miss a transition that skips it. A zoned value from 1847-01-03T00:00Z on reads no offset.
+ */
+export declare function isBeforePolyfillTransitionSearch(value: Temporal.PlainDate | Temporal.ZonedDateTime): boolean;
+/**
+ * The first transition after `epochNanoseconds` in a named zone when it lies before the polyfill's
+ * search floor, which `getTimeZoneTransition("next")` skips; null for any instant at or after the
+ * floor, or when the offset is the same at both ends (then no zone changes in between, pinned by
+ * the all-zones test in `zonedWallClock.test.ts`, and the polyfill's own answer stands).
+ */
+export declare function missedNextTransition(timeZone: string, epochNanoseconds: bigint): bigint | null;
+/**
+ * The last transition strictly before `epochNanoseconds` and before the polyfill's search floor,
+ * for a named zone where `getTimeZoneTransition("previous")` found none; null when the offset
+ * never changes between the minimum instant and there.
+ */
+export declare function missedPreviousTransition(timeZone: string, epochNanoseconds: bigint): bigint | null;
+/** TC39 `InterpretISODateTimeOffset` for a named zone and a wall clock with a time of day. */
+export declare function interpretISODateTimeOffset(timeZone: string, wall: Temporal.PlainDateTime, offset: CarriedOffset, disambiguation: ResolvedDisambiguation, offsetOption: ResolvedOffsetOption, matchMinutes: boolean): bigint;
+/** A zone id as Temporal canonicalizes it, from an identifier or any RFC 9557 string. */
+export declare function timeZoneIdOf(timeZoneLike: string): string;
+/** Offset nanoseconds of a UTC offset string (`"+10:00"`, `"-04:56:02"`), parsed by Temporal. */
+export declare function utcOffsetStringNanoseconds(offset: string): bigint;
+/**
+ * `Temporal.ZonedDateTime.from`, correct across the whole representable range.
+ *
+ * Returns the polyfill's result whenever it has one. When the polyfill throws for a named zone
+ * within a month of either range limit, the TC39 result is recomputed (see the note at the top
+ * of this file); every other failure re-throws the polyfill's own error.
+ *
+ * @param item RFC 9557 zoned string or ZonedDateTime-like property bag
+ * @param options Temporal `disambiguation` / `offset` / `overflow`
+ * @returns the resolved Temporal.ZonedDateTime; throws where TC39 Temporal throws
+ */
+export declare function zonedDateTimeFrom(item: string | Temporal.ZonedDateTimeLike, options?: ZonedFromOptions): Temporal.ZonedDateTime;
+export {};

package/dist/internal/zonedWallClock.js

@@ -0,0 +1,427 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { MAX_EPOCH_NANOSECONDS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
+const NANOSECONDS_PER_DAY = 86400000000000n;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
+export const MAX_ISO_EPOCH_DAYS = 100_000_000;
+/**
+ * Dates this many days from a range limit are the only ones either defect reaches: defect 1 needs
+ * a wall clock within a day of the limit, defect 2 a transition within the scan's two-week step.
+ */
+const EDGE_WINDOW_DAYS = 31;
+/**
+ * `getTimeZoneTransition("next")` looks at most three years (366-day years) past its receiver;
+ * a `null` from further than this from the maximum is the polyfill's own horizon, not defect 2.
+ */
+export const NEXT_TRANSITION_HORIZON_NANOSECONDS = BigInt(3 * 366 + EDGE_WINDOW_DAYS) * NANOSECONDS_PER_DAY;
+/** Previous-transition steps walked back from the maximum instant; real zones need two or three. */
+export const MAX_TRANSITIONS_BEFORE_MAXIMUM = 64;
+/**
+ * Bisection steps to pin a transition to the nanosecond: 2^75 ns covers the whole representable
+ * range (2 × 8.64e21 ns < 2^74), which `missedNextTransition` searches from the minimum instant.
+ */
+const MAX_BISECTION_STEPS = 75;
+/**
+ * 1847-01-01T00:00:00Z: `BEFORE_FIRST_DST` in js-temporal `lib/ecmascript.ts`. The polyfill never
+ * looks for a transition before it (defect 3).
+ */
+export const POLYFILL_TRANSITION_SEARCH_FLOOR = -3881520000000000000n;
+/** The last local date whose start can lie before the floor: midnight 1847-01-01 at UTC+14. */
+const LAST_DATE_BEFORE_TRANSITION_SEARCH = new Temporal.PlainDate(1847, 1, 1);
+/**
+ * Every instant from here on has a local date after 1847-01-01 in every zone (a UTC offset is
+ * always less than a day), so a zoned value can skip the date comparison and its offset read.
+ */
+const FIRST_INSTANT_AFTER_TRANSITION_SEARCH_DATE = POLYFILL_TRANSITION_SEARCH_FLOOR + 2n * NANOSECONDS_PER_DAY;
+const UNIX_EPOCH_DATE = new Temporal.PlainDate(1970, 1, 1);
+const UTC_REFERENCE = new Temporal.ZonedDateTime(0n, "UTC");
+/*
+ * Shape-only checks on an RFC 9557 string that Temporal has already parsed (the regexes never
+ * extract a value; Temporal supplies every field). Before the first `[`, a date-time string is
+ * `date [T|t|space] time [offset]`; the date and time contain no `+`/`-` after the separator, so
+ * the first sign after it opens the UTC offset.
+ */
+const TIME_SEPARATOR = /^[^[]*[Tt ]/;
+const UTC_OFFSET = /^[^[]*[Tt ][^[]*[+\-−]/;
+/** RFC 9557 offset with a seconds field — TC39 `ToTemporalZonedDateTime` then matches exactly. */
+const UTC_OFFSET_WITH_SECONDS = /^[^[]*[Tt ][^[+\-−]*[+\-−]\d{2}:?\d{2}:?\d{2}/;
+// ---------------------------------------------------------------------------------------------
+// TC39 abstract operations, rebuilt from operations the polyfill gets right at the limits
+// ---------------------------------------------------------------------------------------------
+function epochDays(date) {
+    return UNIX_EPOCH_DATE.until(date.withCalendar("iso8601"), {
+        largestUnit: "day",
+    }).days;
+}
+/** True for a date within `EDGE_WINDOW_DAYS` of either TC39 date limit. */
+export function isNearRangeEdge(date) {
+    return Math.abs(epochDays(date)) >= MAX_ISO_EPOCH_DAYS - EDGE_WINDOW_DAYS;
+}
+/** Offset time zones (`+10:00`) and `UTC` never consult tz data, so neither defect reaches them. */
+export function isNamedTimeZone(timeZone) {
+    return (timeZone !== "UTC" && !timeZone.startsWith("+") && !timeZone.startsWith("-"));
+}
+/** TC39 `IsValidEpochNanoseconds`. */
+export function isValidEpoch(epochNanoseconds) {
+    return (epochNanoseconds >= MIN_EPOCH_NANOSECONDS &&
+        epochNanoseconds <= MAX_EPOCH_NANOSECONDS);
+}
+function clampEpoch(epochNanoseconds) {
+    if (epochNanoseconds < MIN_EPOCH_NANOSECONDS)
+        return MIN_EPOCH_NANOSECONDS;
+    if (epochNanoseconds > MAX_EPOCH_NANOSECONDS)
+        return MAX_EPOCH_NANOSECONDS;
+    return epochNanoseconds;
+}
+/** UTC offset in force at an instant, reading the nearest limit for an instant outside the range. */
+function offsetAt(timeZone, epochNanoseconds) {
+    return BigInt(new Temporal.ZonedDateTime(clampEpoch(epochNanoseconds), timeZone)
+        .offsetNanoseconds);
+}
+/** TC39 `GetUTCEpochNanoseconds`: the wall clock read as if it were UTC (may lie outside the range). */
+export function utcEpochNanoseconds(wall) {
+    const days = BigInt(epochDays(wall.toPlainDate()));
+    const timeOfDay = BigInt(wall.hour) * 3600000000000n +
+        BigInt(wall.minute) * NANOSECONDS_PER_MINUTE +
+        BigInt(wall.second) * 1000000000n +
+        BigInt(wall.millisecond) * 1000000n +
+        BigInt(wall.microsecond) * 1000n +
+        BigInt(wall.nanosecond);
+    return days * NANOSECONDS_PER_DAY + timeOfDay;
+}
+/** TC39 `CheckISODaysRange`. */
+function checkISODaysRange(date) {
+    if (Math.abs(epochDays(date)) > MAX_ISO_EPOCH_DAYS) {
+        throw new RangeError(`${date.toString()} is outside the supported range`);
+    }
+}
+/**
+ * TC39 `GetPossibleEpochNanoseconds` for a named zone, with 05ce7a3's clamp: the exact times whose
+ * wall clock in `timeZone` is `wall`, ascending — none in a gap, two in an overlap.
+ *
+ * @throws RangeError when a matching exact time lies outside the representable range
+ */
+function possibleEpochNanoseconds(timeZone, wall) {
+    const isoWall = wall.withCalendar("iso8601");
+    const utc = utcEpochNanoseconds(isoWall);
+    const offsetBefore = offsetAt(timeZone, utc - NANOSECONDS_PER_DAY);
+    const offsetAfter = offsetAt(timeZone, utc + NANOSECONDS_PER_DAY);
+    const offsets = offsetBefore === offsetAfter ? [offsetBefore] : [offsetBefore, offsetAfter];
+    const candidates = [];
+    for (const offset of offsets) {
+        const candidate = utc - offset;
+        if (!isValidEpoch(candidate)) {
+            if (offsetAt(timeZone, candidate) === offset) {
+                throw new RangeError(`${isoWall.toString()} in ${timeZone} is outside the supported range`);
+            }
+            continue;
+        }
+        const resolved = new Temporal.ZonedDateTime(candidate, timeZone).toPlainDateTime();
+        if (Temporal.PlainDateTime.compare(resolved, isoWall) === 0) {
+            candidates.push(candidate);
+        }
+    }
+    return candidates;
+}
+/** TC39 `DisambiguatePossibleEpochNanoseconds`. */
+function disambiguatePossibleEpochNanoseconds(possible, timeZone, wall, disambiguation) {
+    if (possible.length === 1)
+        return possible[0];
+    if (disambiguation === "reject") {
+        throw new RangeError(`${wall.toString()} in ${timeZone} is ambiguous or does not exist`);
+    }
+    if (possible.length > 1) {
+        return disambiguation === "later"
+            ? possible[possible.length - 1]
+            : possible[0];
+    }
+    // A gap: move the wall clock by the size of the offset change, then resolve again.
+    const isoWall = wall.withCalendar("iso8601");
+    const utc = utcEpochNanoseconds(isoWall);
+    const shift = Number(offsetAt(timeZone, utc + NANOSECONDS_PER_DAY) -
+        offsetAt(timeZone, utc - NANOSECONDS_PER_DAY));
+    const shifted = disambiguation === "earlier"
+        ? possibleEpochNanoseconds(timeZone, isoWall.subtract({ nanoseconds: shift }))
+        : possibleEpochNanoseconds(timeZone, isoWall.add({ nanoseconds: shift }));
+    if (shifted.length === 0) {
+        throw new RangeError(`${wall.toString()} in ${timeZone} cannot be resolved`);
+    }
+    return disambiguation === "earlier"
+        ? shifted[0]
+        : shifted[shifted.length - 1];
+}
+/** TC39 `GetEpochNanosecondsFor`. */
+export function epochNanosecondsFor(timeZone, wall, disambiguation) {
+    return disambiguatePossibleEpochNanoseconds(possibleEpochNanoseconds(timeZone, wall), timeZone, wall, disambiguation);
+}
+/**
+ * The first instant at or after `low` whose offset is `offset`, given that `low` has a different
+ * offset and `high` has `offset`: the transition between them, to the nanosecond.
+ */
+function transitionBetween(timeZone, low, high, offset) {
+    if (offsetAt(timeZone, high) !== offset ||
+        offsetAt(timeZone, low) === offset) {
+        throw new RangeError(`No transition in ${timeZone} between the bounds`);
+    }
+    let before = low;
+    let after = high;
+    for (let step = 0; step < MAX_BISECTION_STEPS && after - before > 1n; step++) {
+        const middle = (before + after) / 2n;
+        if (offsetAt(timeZone, middle) === offset) {
+            after = middle;
+        }
+        else {
+            before = middle;
+        }
+    }
+    if (after - before > 1n) {
+        throw new RangeError(`Transition in ${timeZone} not found`);
+    }
+    return after;
+}
+/**
+ * TC39 `GetStartOfDay`: the first valid wall-clock time on `date` in `timeZone` — midnight, or,
+ * when midnight is skipped, the transition that skips it.
+ */
+export function startOfDayEpochNanoseconds(timeZone, date) {
+    const midnight = date.withCalendar("iso8601").toPlainDateTime();
+    const possible = possibleEpochNanoseconds(timeZone, midnight);
+    if (possible.length > 0)
+        return possible[0];
+    const utc = utcEpochNanoseconds(midnight);
+    const offsetBefore = offsetAt(timeZone, utc - NANOSECONDS_PER_DAY);
+    const offsetAfter = offsetAt(timeZone, utc + NANOSECONDS_PER_DAY);
+    // Midnight falls in [transition + offsetBefore, transition + offsetAfter), so the transition is
+    // after `midnight - offsetAfter` and at or before `midnight - offsetBefore`.
+    return transitionBetween(timeZone, clampEpoch(utc - offsetAfter), clampEpoch(utc - offsetBefore), offsetAfter);
+}
+// ---------------------------------------------------------------------------------------------
+// Defect 3: transitions before the polyfill's 1847-01-01 search floor
+// ---------------------------------------------------------------------------------------------
+/**
+ * True when a start of day on this local date — or, for a zoned value, on its own local date —
+ * may lie before the polyfill's transition search floor, so the polyfill's `GetStartOfDay` can
+ * miss a transition that skips it. A zoned value from 1847-01-03T00:00Z on reads no offset.
+ */
+export function isBeforePolyfillTransitionSearch(value) {
+    if (value instanceof Temporal.ZonedDateTime) {
+        return (value.epochNanoseconds < FIRST_INSTANT_AFTER_TRANSITION_SEARCH_DATE &&
+            isBeforePolyfillTransitionSearch(value.toPlainDate()));
+    }
+    return (Temporal.PlainDate.compare(value, LAST_DATE_BEFORE_TRANSITION_SEARCH) <= 0);
+}
+/**
+ * The first transition after `epochNanoseconds` in a named zone when it lies before the polyfill's
+ * search floor, which `getTimeZoneTransition("next")` skips; null for any instant at or after the
+ * floor, or when the offset is the same at both ends (then no zone changes in between, pinned by
+ * the all-zones test in `zonedWallClock.test.ts`, and the polyfill's own answer stands).
+ */
+export function missedNextTransition(timeZone, epochNanoseconds) {
+    if (epochNanoseconds >= POLYFILL_TRANSITION_SEARCH_FLOOR)
+        return null;
+    const floorOffset = offsetAt(timeZone, POLYFILL_TRANSITION_SEARCH_FLOOR);
+    if (offsetAt(timeZone, epochNanoseconds) === floorOffset)
+        return null;
+    return transitionBetween(timeZone, epochNanoseconds, POLYFILL_TRANSITION_SEARCH_FLOOR, floorOffset);
+}
+/**
+ * The last transition strictly before `epochNanoseconds` and before the polyfill's search floor,
+ * for a named zone where `getTimeZoneTransition("previous")` found none; null when the offset
+ * never changes between the minimum instant and there.
+ */
+export function missedPreviousTransition(timeZone, epochNanoseconds) {
+    const high = epochNanoseconds - 1n < POLYFILL_TRANSITION_SEARCH_FLOOR
+        ? epochNanoseconds - 1n
+        : POLYFILL_TRANSITION_SEARCH_FLOOR;
+    if (high <= MIN_EPOCH_NANOSECONDS)
+        return null;
+    const highOffset = offsetAt(timeZone, high);
+    if (offsetAt(timeZone, MIN_EPOCH_NANOSECONDS) === highOffset)
+        return null;
+    return transitionBetween(timeZone, MIN_EPOCH_NANOSECONDS, high, highOffset);
+}
+/** TC39 `RoundNumberToIncrement(value, 1 minute, "half-expand")`. */
+function roundToMinute(nanoseconds) {
+    const sign = nanoseconds < 0n ? -1n : 1n;
+    const magnitude = nanoseconds * sign;
+    const quotient = magnitude / NANOSECONDS_PER_MINUTE;
+    const remainder = magnitude % NANOSECONDS_PER_MINUTE;
+    const rounded = remainder * 2n >= NANOSECONDS_PER_MINUTE ? quotient + 1n : quotient;
+    return rounded * NANOSECONDS_PER_MINUTE * sign;
+}
+function matchingCandidate(possible, wall, offset, matchMinutes) {
+    if (typeof offset === "string")
+        return null;
+    const utc = utcEpochNanoseconds(wall);
+    for (const candidate of possible) {
+        const candidateOffset = utc - candidate;
+        if (candidateOffset === offset.nanoseconds ||
+            (matchMinutes && roundToMinute(candidateOffset) === offset.nanoseconds)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** TC39 `InterpretISODateTimeOffset` for a named zone and a wall clock with a time of day. */
+export function interpretISODateTimeOffset(timeZone, wall, offset, disambiguation, offsetOption, matchMinutes) {
+    const isoWall = wall.withCalendar("iso8601");
+    if (offset === "absent" || offsetOption === "ignore") {
+        return epochNanosecondsFor(timeZone, isoWall, disambiguation);
+    }
+    if (offsetOption === "use") {
+        const exact = offset === "out-of-range"
+            ? null
+            : utcEpochNanoseconds(isoWall) - offset.nanoseconds;
+        if (exact === null || !isValidEpoch(exact)) {
+            throw new RangeError(`${isoWall.toString()} is outside the supported range`);
+        }
+        return exact;
+    }
+    checkISODaysRange(isoWall.toPlainDate());
+    const possible = possibleEpochNanoseconds(timeZone, isoWall);
+    const matched = matchingCandidate(possible, isoWall, offset, matchMinutes);
+    if (matched !== null)
+        return matched;
+    if (offsetOption === "reject") {
+        throw new RangeError(`The offset is invalid for ${isoWall.toString()} in ${timeZone}`);
+    }
+    return disambiguatePossibleEpochNanoseconds(possible, timeZone, isoWall, disambiguation);
+}
+// ---------------------------------------------------------------------------------------------
+// Polyfill-first wrappers
+// ---------------------------------------------------------------------------------------------
+/** Validates Temporal options exactly as `ZonedDateTime.from` does, without resolving anything. */
+function validateFromOptions(options) {
+    Temporal.ZonedDateTime.from(UTC_REFERENCE, options);
+}
+/** A zone id as Temporal canonicalizes it, from an identifier or any RFC 9557 string. */
+export function timeZoneIdOf(timeZoneLike) {
+    return UTC_REFERENCE.withTimeZone(timeZoneLike).timeZoneId;
+}
+/** Offset nanoseconds of a UTC offset string (`"+10:00"`, `"-04:56:02"`), parsed by Temporal. */
+export function utcOffsetStringNanoseconds(offset) {
+    const utcMidnight = Temporal.ZonedDateTime.from({ year: 1970, month: 1, day: 1, timeZone: "UTC", offset }, { offset: "use" });
+    return -utcMidnight.epochNanoseconds;
+}
+/** The epoch nanoseconds of a zoned string near the range limits, or null when out of scope. */
+function stringEpochAtEdge(item, timeZone, wall, options) {
+    if (!TIME_SEPARATOR.test(item)) {
+        return startOfDayEpochNanoseconds(timeZone, wall.toPlainDate());
+    }
+    const disambiguation = options?.disambiguation === undefined
+        ? "compatible"
+        : options.disambiguation;
+    if (!UTC_OFFSET.test(item)) {
+        return epochNanosecondsFor(timeZone, wall, disambiguation);
+    }
+    let offset;
+    try {
+        offset = {
+            nanoseconds: utcEpochNanoseconds(wall) -
+                Temporal.Instant.from(item).epochNanoseconds,
+        };
+    }
+    catch {
+        // The grammar is already proven valid, so only the string's own instant can be out of range.
+        offset = "out-of-range";
+    }
+    return interpretISODateTimeOffset(timeZone, wall, offset, disambiguation, options?.offset === undefined ? "reject" : options.offset, !UTC_OFFSET_WITH_SECONDS.test(item));
+}
+function fromStringAtEdge(item, options) {
+    let wall;
+    let timeZone;
+    try {
+        validateFromOptions(options);
+        // A `Z` string throws here: its exact time never touches tz data, so it is never recovered.
+        wall = Temporal.PlainDateTime.from(item);
+        timeZone = timeZoneIdOf(item);
+    }
+    catch {
+        return null;
+    }
+    if (!isNamedTimeZone(timeZone) || !isNearRangeEdge(wall.toPlainDate())) {
+        return null;
+    }
+    const epoch = stringEpochAtEdge(item, timeZone, wall.withCalendar("iso8601"), options);
+    return new Temporal.ZonedDateTime(epoch, timeZone, wall.calendarId);
+}
+/** The offset a property bag carries, parsed by Temporal itself. */
+function bagOffset(offset) {
+    return offset === undefined
+        ? "absent"
+        : { nanoseconds: utcOffsetStringNanoseconds(offset) };
+}
+function fromBagAtEdge(item, options) {
+    let wall;
+    let timeZone;
+    let offset;
+    try {
+        validateFromOptions(options);
+        wall = Temporal.PlainDateTime.from(item, { overflow: options?.overflow });
+        timeZone = timeZoneIdOf(String(item.timeZone));
+        offset = bagOffset(item.offset);
+    }
+    catch {
+        return null;
+    }
+    if (!isNamedTimeZone(timeZone) || !isNearRangeEdge(wall.toPlainDate())) {
+        return null;
+    }
+    const epoch = interpretISODateTimeOffset(timeZone, wall, offset, options?.disambiguation === undefined
+        ? "compatible"
+        : options.disambiguation, options?.offset === undefined ? "reject" : options.offset, false);
+    return new Temporal.ZonedDateTime(epoch, timeZone, wall.calendarId);
+}
+/**
+ * A date-only zoned string (TC39: its start of day) whose date is on or before 1847-01-01 in a
+ * named zone, resolved with GMT's own `GetStartOfDay` (defect 3); null for anything else.
+ */
+function dateOnlyBeforeTransitionSearch(item, options) {
+    if (TIME_SEPARATOR.test(item))
+        return null;
+    let date;
+    let timeZone;
+    try {
+        validateFromOptions(options);
+        date = Temporal.PlainDate.from(item);
+        timeZone = timeZoneIdOf(item);
+    }
+    catch {
+        return null;
+    }
+    if (!isNamedTimeZone(timeZone) || !isBeforePolyfillTransitionSearch(date)) {
+        return null;
+    }
+    return new Temporal.ZonedDateTime(startOfDayEpochNanoseconds(timeZone, date), timeZone, date.calendarId);
+}
+/**
+ * `Temporal.ZonedDateTime.from`, correct across the whole representable range.
+ *
+ * Returns the polyfill's result whenever it has one. When the polyfill throws for a named zone
+ * within a month of either range limit, the TC39 result is recomputed (see the note at the top
+ * of this file); every other failure re-throws the polyfill's own error.
+ *
+ * @param item RFC 9557 zoned string or ZonedDateTime-like property bag
+ * @param options Temporal `disambiguation` / `offset` / `overflow`
+ * @returns the resolved Temporal.ZonedDateTime; throws where TC39 Temporal throws
+ */
+export function zonedDateTimeFrom(item, options) {
+    const dateOnly = typeof item === "string"
+        ? dateOnlyBeforeTransitionSearch(item, options)
+        : null;
+    if (dateOnly !== null) {
+        return dateOnly;
+    }
+    try {
+        return Temporal.ZonedDateTime.from(item, options);
+    }
+    catch (error) {
+        const recovered = typeof item === "string"
+            ? fromStringAtEdge(item, options)
+            : fromBagAtEdge(item, options);
+        if (recovered === null) {
+            throw error;
+        }
+        return recovered;
+    }
+}