@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/leapSeconds.js

@@ -0,0 +1,162 @@
+import { NANOSECONDS_PER_SECOND } from "./foreignEpochs.js";
+// IERS Earth Orientation Center, Leap_Second.dat, "Updated through IERS Bulletin 72 issued in
+// July 2026": one row per MJD with TAI − UTC from that date. Each bigint is
+// `Temporal.Instant.from(<date>).epochNanoseconds` of the date in its comment;
+// leapSeconds.test.ts asserts each one. The first row is where whole-second TAI − UTC begins
+// (BIPM Annual Report on Time Activities vol. 15, Table 2: "1972 Jan. 1 … 10 (integral number of
+// seconds)"); the 27 after it are the 27 inserted leap seconds (ITU-R TF.460-6 Annex 1 §2.2).
+const ROWS = [
+    [63072000000000000n, 10n], // 1972-01-01T00:00:00Z
+    [78796800000000000n, 11n], // 1972-07-01T00:00:00Z
+    [94694400000000000n, 12n], // 1973-01-01T00:00:00Z
+    [126230400000000000n, 13n], // 1974-01-01T00:00:00Z
+    [157766400000000000n, 14n], // 1975-01-01T00:00:00Z
+    [189302400000000000n, 15n], // 1976-01-01T00:00:00Z
+    [220924800000000000n, 16n], // 1977-01-01T00:00:00Z
+    [252460800000000000n, 17n], // 1978-01-01T00:00:00Z
+    [283996800000000000n, 18n], // 1979-01-01T00:00:00Z
+    [315532800000000000n, 19n], // 1980-01-01T00:00:00Z
+    [362793600000000000n, 20n], // 1981-07-01T00:00:00Z
+    [394329600000000000n, 21n], // 1982-07-01T00:00:00Z
+    [425865600000000000n, 22n], // 1983-07-01T00:00:00Z
+    [489024000000000000n, 23n], // 1985-07-01T00:00:00Z
+    [567993600000000000n, 24n], // 1988-01-01T00:00:00Z
+    [631152000000000000n, 25n], // 1990-01-01T00:00:00Z
+    [662688000000000000n, 26n], // 1991-01-01T00:00:00Z
+    [709948800000000000n, 27n], // 1992-07-01T00:00:00Z
+    [741484800000000000n, 28n], // 1993-07-01T00:00:00Z
+    [773020800000000000n, 29n], // 1994-07-01T00:00:00Z
+    [820454400000000000n, 30n], // 1996-01-01T00:00:00Z
+    [867715200000000000n, 31n], // 1997-07-01T00:00:00Z
+    [915148800000000000n, 32n], // 1999-01-01T00:00:00Z
+    [1136073600000000000n, 33n], // 2006-01-01T00:00:00Z
+    [1230768000000000000n, 34n], // 2009-01-01T00:00:00Z
+    [1341100800000000000n, 35n], // 2012-07-01T00:00:00Z
+    [1435708800000000000n, 36n], // 2015-07-01T00:00:00Z
+    [1483228800000000000n, 37n], // 2017-01-01T00:00:00Z
+];
+/**
+ * IERS Earth Orientation Center, Leap_Second.dat (https://hpiers.obspm.fr/iers/bul/bulc/Leap_Second.dat),
+ * updated through IERS Bulletin C 72, 6 July 2026. Closed: CGPM 2026 Resolution 5 makes UTC
+ * continuous from 20 May 2027, and Bulletin C 72 rules out the end of December 2026. After the last
+ * row TAI − UTC stays 37 s. Checked weekly against IERS by scripts/leap-seconds.mjs.
+ */
+export const LEAP_SECOND_STEPS = Object.freeze({
+    at: Object.freeze(ROWS.map(([at]) => at)),
+    taiMinusUtc: Object.freeze(ROWS.map(([, offset]) => offset)),
+});
+/** Index of the last row that starts at or before `u`, or −1 before the first row. */
+function rowAt(steps, u) {
+    let found = -1;
+    for (let index = 0; index < steps.at.length && steps.at[index] <= u; index += 1) {
+        found = index;
+    }
+    return found;
+}
+/** TAI − UTC of row `index`, in nanoseconds. */
+function offsetOf(steps, index) {
+    return steps.taiMinusUtc[index] * NANOSECONDS_PER_SECOND;
+}
+/** The step from row `index − 1` to row `index`, in nanoseconds: `+S` inserts, `−S` deletes. */
+function stepAt(steps, index) {
+    return offsetOf(steps, index) - offsetOf(steps, index - 1);
+}
+/**
+ * TAI of a UTC reading, as label nanoseconds (the TAI wall clock read as if UTC), or `null` when
+ * the reading has no TAI instant.
+ *
+ * - `null` before the first row: TAI − UTC was not a whole number of seconds before 1972 (BIPM
+ *   Annual Report vol. 15, Table 2).
+ * - A second-60 reading is valid only in the second before a positive step, where it maps to
+ *   that inserted second: old offset + 1 s (ITU-R TF.460-6 Annex 1 §2.2).
+ * - An ordinary reading inside a deleted second (before a negative step) has no instant.
+ * - No upper bound: after the last row its offset holds.
+ *
+ * @param steps the leap-second table
+ * @param reading the UTC reading
+ * @returns TAI label nanoseconds, or null
+ */
+export function taiOfUtc(steps, reading) {
+    const u = reading.epochNanoseconds;
+    if (u < steps.at[0]) {
+        return null;
+    }
+    if (reading.secondSixty) {
+        for (let index = 1; index < steps.at.length; index += 1) {
+            if (steps.at[index] - NANOSECONDS_PER_SECOND <= u &&
+                u < steps.at[index] &&
+                stepAt(steps, index) === NANOSECONDS_PER_SECOND) {
+                return u + offsetOf(steps, index - 1) + NANOSECONDS_PER_SECOND;
+            }
+        }
+        return null;
+    }
+    const index = rowAt(steps, u);
+    const next = index + 1;
+    if (next < steps.at.length &&
+        stepAt(steps, next) === -NANOSECONDS_PER_SECOND &&
+        u >= steps.at[next] - NANOSECONDS_PER_SECOND) {
+        return null;
+    }
+    return u + offsetOf(steps, index);
+}
+/**
+ * The UTC reading of a TAI instant given as label nanoseconds, or `null` before the table's
+ * first TAI instant (1972-01-01T00:00:10 TAI).
+ *
+ * - Inside an inserted second the reading is second 60: its `epochNanoseconds` is the
+ *   `…T23:59:59.f` instant Temporal would clamp `…:60.f` to.
+ * - A negative step needs no special case: the deleted second has no TAI instant to map.
+ *
+ * @param steps the leap-second table
+ * @param tai TAI label nanoseconds
+ * @returns the UTC reading, or null
+ */
+export function utcOfTai(steps, tai) {
+    let index = -1;
+    for (let row = 0; row < steps.at.length && steps.at[row] + offsetOf(steps, row) <= tai; row += 1) {
+        index = row;
+    }
+    if (index === -1) {
+        return null;
+    }
+    const u = tai - offsetOf(steps, index);
+    if (index + 1 < steps.at.length && u >= steps.at[index + 1]) {
+        return { epochNanoseconds: u - NANOSECONDS_PER_SECOND, secondSixty: true };
+    }
+    return { epochNanoseconds: u, secondSixty: false };
+}
+/**
+ * The UTC reading of step `index`'s own second, the second before `at[index]` (ITU-R TF.460-6
+ * Annex 1 §2.2): for a positive step the inserted `…T23:59:60` (a second-60 reading); for a
+ * negative step the omitted `…T23:59:59` (an ordinary reading of its label).
+ *
+ * @param steps the leap-second table
+ * @param index a row index from 1
+ * @returns the reading of that step's second
+ */
+export function stepReading(steps, index) {
+    return {
+        epochNanoseconds: steps.at[index] - NANOSECONDS_PER_SECOND,
+        secondSixty: stepAt(steps, index) > 0n,
+    };
+}
+/**
+ * Index of the first step (row 1 on) that starts after a UTC reading, or −1 when there is none.
+ * A second-60 reading counts as the instant one second later, so its own step is behind it.
+ *
+ * @param steps the leap-second table
+ * @param reading the UTC reading
+ * @returns the row index, or −1
+ */
+export function nextStepIndex(steps, reading) {
+    const u = reading.secondSixty
+        ? reading.epochNanoseconds + NANOSECONDS_PER_SECOND
+        : reading.epochNanoseconds;
+    for (let index = 1; index < steps.at.length; index += 1) {
+        if (steps.at[index] > u) {
+            return index;
+        }
+    }
+    return -1;
+}

package/dist/internal/localeWeekInfo.d.ts

@@ -27,7 +27,7 @@ declare global {
  * - Throws `RangeError` (from `Intl.Locale`) if `locale` is not a well-formed BCP 47 tag; callers turn
  *   that into their sentinel.
  *
- * @example localeWeekInfo("en-US")?.firstDay // 7
+ * @example localeWeekInfo("pt-BR")?.firstDay // 7
  * @example localeWeekInfo("ar-SA")?.weekend // [5, 6]
  */
 export declare function localeWeekInfo(locale: LocalesArgument): Partial<LocaleWeekInfo> | undefined;

package/dist/internal/localeWeekInfo.js

@@ -12,7 +12,7 @@ import { resolveRequiredLocale } from "./resolveLocale.js";
  * - Throws `RangeError` (from `Intl.Locale`) if `locale` is not a well-formed BCP 47 tag; callers turn
  *   that into their sentinel.
  *
- * @example localeWeekInfo("en-US")?.firstDay // 7
+ * @example localeWeekInfo("pt-BR")?.firstDay // 7
  * @example localeWeekInfo("ar-SA")?.weekend // [5, 6]
  */
 export function localeWeekInfo(locale) {

package/dist/internal/maxPieces.js

@@ -1,3 +1,4 @@
+import { isObject } from "./isObject.js";
 /**
  * Default `maxPieces` for functions that return one array element per generated piece
  * (`splitIntervalByUnit*`, `intervalDivideEqually*`, `mapDatesInRange`, `mapZonedDatesInRange`).
@@ -27,7 +28,7 @@ export function resolveMaxPieces(options) {
     if (options === undefined) {
         return DEFAULT_MAX_PIECES;
     }
-    if (typeof options !== "object" || options === null) {
+    if (!isObject(options)) {
         return null;
     }
     const { maxPieces } = options;

package/dist/internal/monthGridWeekRow.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * Return the 1-based calendar-grid week row that `dayInMonth` falls on for
  * `firstOfMonth`'s month, given `firstDay` (locale first day of week,

package/dist/internal/normalizeDateTime.d.ts

@@ -6,7 +6,8 @@
  * - Normalizes various non-breaking and narrow spaces to plain space
  * - Collapses repeated whitespace to a single space and trims
  * - Normalizes common dash/minus characters to ASCII hyphen-minus
- * - Optionally lowercases the result (disabled by default)
+ * - Optionally lowercases the result (disabled by default), in
+ *   `opts.locale` (default `"en"`: a language, not one country)
  */
 export declare function normalizeDateTime(input: string, opts?: {
     lower?: boolean;

package/dist/internal/normalizeDateTime.js

@@ -6,12 +6,13 @@
  * - Normalizes various non-breaking and narrow spaces to plain space
  * - Collapses repeated whitespace to a single space and trims
  * - Normalizes common dash/minus characters to ASCII hyphen-minus
- * - Optionally lowercases the result (disabled by default)
+ * - Optionally lowercases the result (disabled by default), in
+ *   `opts.locale` (default `"en"`: a language, not one country)
  */
 export function normalizeDateTime(input, opts) {
     if (typeof input !== "string")
         return "";
-    const { lower = false, locale = "en-US" } = opts ?? {};
+    const { lower = false, locale = "en" } = opts ?? {};
     // Use NFC where available for stable composed characters
     let s = typeof input.normalize === "function" ? input.normalize("NFC") : input;
     // Remove Unicode format characters (includes bidi marks), zero-width space, BOM

package/dist/internal/normalizeTimeZone.d.ts

@@ -1,5 +1,8 @@
 /**
- * Resolve the `timeZone` option of every `unix/` and `utc/` function that takes one.
+ * Resolve the `timeZone` option of the `unix/` and `utc/` functions that hand the zone to
+ * `Intl.DateTimeFormat`, which takes a time zone identifier only. A function whose result names no
+ * zone reads its option with `normalizeZoneFrame` instead, which also accepts a stored UTC offset
+ * with seconds.
  *
  * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
  *   zone is read unless asked for.
@@ -14,7 +17,7 @@
  * @returns the zone to use, or `""` when invalid
  *
  * @example normalizeTimeZone(undefined) // "UTC"
- * @example normalizeTimeZone("local") // system zone, e.g. "America/New_York"
+ * @example normalizeTimeZone("local") // system zone, e.g. "Asia/Tokyo"
  * @example normalizeTimeZone("Europe/Helsinki") // "Europe/Helsinki"
  * @example normalizeTimeZone("America/New_Yrok") // ""
  */

package/dist/internal/normalizeTimeZone.js

@@ -1,7 +1,10 @@
 import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
 import { isValidTimeZone } from "../zoned/validate/index.js";
 /**
- * Resolve the `timeZone` option of every `unix/` and `utc/` function that takes one.
+ * Resolve the `timeZone` option of the `unix/` and `utc/` functions that hand the zone to
+ * `Intl.DateTimeFormat`, which takes a time zone identifier only. A function whose result names no
+ * zone reads its option with `normalizeZoneFrame` instead, which also accepts a stored UTC offset
+ * with seconds.
  *
  * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
  *   zone is read unless asked for.
@@ -16,7 +19,7 @@ import { isValidTimeZone } from "../zoned/validate/index.js";
  * @returns the zone to use, or `""` when invalid
  *
  * @example normalizeTimeZone(undefined) // "UTC"
- * @example normalizeTimeZone("local") // system zone, e.g. "America/New_York"
+ * @example normalizeTimeZone("local") // system zone, e.g. "Asia/Tokyo"
  * @example normalizeTimeZone("Europe/Helsinki") // "Europe/Helsinki"
  * @example normalizeTimeZone("America/New_Yrok") // ""
  */

package/dist/internal/offsetTimeline.d.ts

@@ -0,0 +1,56 @@
+import type { Disambiguation } from "../types/index.js";
+import type { ZoneFrame } from "./zoneFrame.js";
+/**
+ * A frame's offset as constant stretches over `[fromNs, toNs]`. `offsets[i]` holds from
+ * `changes[i - 1]` (or `fromNs`) up to, not including, `changes[i]`; it includes
+ * `frame.shiftNanoseconds`. Outside the range the first and last stretch are extended, so a
+ * caller reads a time past `toNs` only after `extendTimeline`.
+ */
+export type OffsetTimeline = {
+    frame: ZoneFrame;
+    /** The first instant the timeline was built from. */
+    fromNs: bigint;
+    /** The last instant whose offset is known to be complete. */
+    toNs: bigint;
+    /** Epoch nanoseconds of each offset change, ascending. */
+    changes: bigint[];
+    offsets: bigint[];
+};
+/**
+ * Build the timeline of `frame` over `[fromNs, toNs]`. A fixed-offset frame (an offset zone,
+ * `UTC`, an offset with seconds) is one stretch and runs no search, unless `maxChanges` is given.
+ *
+ * With `maxChanges`, a range holding more changes than that returns `null` as soon as the
+ * `maxChanges + 1`th is found, without searching further.
+ *
+ * Throws what Temporal throws for an instant outside its range; callers keep clear of it.
+ */
+export declare function offsetTimeline(frame: ZoneFrame, fromNs: bigint, toNs: bigint): OffsetTimeline;
+export declare function offsetTimeline(frame: ZoneFrame, fromNs: bigint, toNs: bigint, maxChanges: number): OffsetTimeline | null;
+/**
+ * Make `timeline` complete up to `ns`, reading ahead so a walk that advances a day at a time
+ * searches in chunks: it grows by at least its own length, up to three years.
+ */
+export declare function ensureTimeline(timeline: OffsetTimeline, ns: bigint): void;
+/** The offset in force at `ns`, in nanoseconds east of UTC. */
+export declare function offsetOf(timeline: OffsetTimeline, ns: bigint): bigint;
+/**
+ * TC39 `GetPossibleEpochNanoseconds`, read from the timeline: the instants whose wall clock is
+ * `wallNs` (the wall clock read as UTC), ascending. A stretch contributes `wallNs - offset` when
+ * that instant lies in the stretch; offsets differ by well under two days, so only the stretches
+ * within two days either side can.
+ */
+export declare function possibleAt(timeline: OffsetTimeline, wallNs: bigint): bigint[];
+/**
+ * TC39 `GetEpochNanosecondsFor`: the instant a wall clock names, by
+ * `DisambiguatePossibleEpochNanoseconds`. One candidate is the answer; two give the first
+ * (`"compatible"`, `"earlier"`) or last (`"later"`); none moves the wall clock by the offset
+ * change, back for `"earlier"` and forward otherwise. `undefined` where `"reject"` refuses.
+ * Throws `RangeError` where a moved wall clock names nothing, which no zone's data produces.
+ */
+export declare function resolveWallNs(timeline: OffsetTimeline, wallNs: bigint, disambiguation: Disambiguation): bigint | undefined;
+/**
+ * TC39 `GetStartOfDay`: the first instant of the local date `epochDay` days from 1970-01-01 -
+ * its first candidate for midnight, else (midnight skipped) the change that ends the gap.
+ */
+export declare function startOfDayNs(timeline: OffsetTimeline, epochDay: number): bigint;

package/dist/internal/offsetTimeline.js

@@ -0,0 +1,166 @@
+import { Temporal } from "./temporal.js";
+import { NANOSECONDS_PER_DAY } from "./foreignEpochs.js";
+import { isNamedTimeZone } from "./zonedWallClock.js";
+import { zonedNextTransition } from "./zonedWallClockOperations.js";
+/**
+ * The longest span one transition search covers: three 366-day years, the horizon the
+ * polyfill-compatible search keeps with or without a limit (TC39 `GetNamedTimeZoneNextTransition`
+ * leaves the horizon to the implementation). A search that passes `until` inside it is exact.
+ */
+const MAX_SEARCH_SPAN = 3n * 366n * NANOSECONDS_PER_DAY;
+export function offsetTimeline(frame, fromNs, toNs, maxChanges) {
+    const first = new Temporal.ZonedDateTime(fromNs, frame.timeZone);
+    const timeline = {
+        frame,
+        fromNs,
+        toNs: fromNs,
+        changes: [],
+        offsets: [BigInt(first.offsetNanoseconds) + frame.shiftNanoseconds],
+    };
+    return extendTimeline(timeline, toNs, maxChanges) ? timeline : null;
+}
+/**
+ * Grow `timeline` so that it is complete up to `toNs`, one search of at most three years at a
+ * time, or one search per change up to `toNs` under `maxChanges`. Each search passes `until`,
+ * so it never stops at a clock-based horizon short of it. Returns `false` once the timeline holds
+ * more than `maxChanges` changes.
+ */
+function extendTimeline(timeline, toNs, maxChanges = Infinity) {
+    const { frame } = timeline;
+    if (toNs <= timeline.toNs) {
+        return true;
+    }
+    if (maxChanges !== Infinity) {
+        // A capped walk asks the zone for each next change up to `toNs`, one search per change, even
+        // for a fixed offset, so the cap counts what the zone reports and the search reaches no
+        // further than the caller's range.
+        let at = new Temporal.ZonedDateTime(timeline.toNs, frame.timeZone);
+        for (;;) {
+            const next = zonedNextTransition(at, toNs);
+            if (next === null) {
+                break;
+            }
+            timeline.changes.push(next.epochNanoseconds);
+            timeline.offsets.push(BigInt(next.offsetNanoseconds) + frame.shiftNanoseconds);
+            at = next;
+            if (timeline.changes.length > maxChanges) {
+                return false;
+            }
+        }
+    }
+    else if (isNamedTimeZone(frame.timeZone)) {
+        let chunkStart = timeline.toNs;
+        while (chunkStart < toNs) {
+            const chunkEnd = toNs - chunkStart > MAX_SEARCH_SPAN
+                ? chunkStart + MAX_SEARCH_SPAN
+                : toNs;
+            let at = new Temporal.ZonedDateTime(chunkStart, frame.timeZone);
+            for (;;) {
+                const next = zonedNextTransition(at, chunkEnd);
+                if (next === null) {
+                    break;
+                }
+                timeline.changes.push(next.epochNanoseconds);
+                timeline.offsets.push(BigInt(next.offsetNanoseconds) + frame.shiftNanoseconds);
+                at = next;
+            }
+            chunkStart = chunkEnd;
+        }
+    }
+    timeline.toNs = toNs;
+    return true;
+}
+/**
+ * Make `timeline` complete up to `ns`, reading ahead so a walk that advances a day at a time
+ * searches in chunks: it grows by at least its own length, up to three years.
+ */
+export function ensureTimeline(timeline, ns) {
+    if (ns <= timeline.toNs) {
+        return;
+    }
+    const length = timeline.toNs - timeline.fromNs;
+    const step = length > MAX_SEARCH_SPAN ? MAX_SEARCH_SPAN : length;
+    extendTimeline(timeline, ns > timeline.toNs + step ? ns : timeline.toNs + step);
+}
+/** Index of the stretch holding `ns`: the number of changes at or before it. */
+function stretchAt(timeline, ns) {
+    const { changes } = timeline;
+    let low = 0;
+    let high = changes.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (changes[middle] <= ns) {
+            low = middle + 1;
+        }
+        else {
+            high = middle;
+        }
+    }
+    return low;
+}
+/** The offset in force at `ns`, in nanoseconds east of UTC. */
+export function offsetOf(timeline, ns) {
+    return timeline.offsets[stretchAt(timeline, ns)];
+}
+/**
+ * TC39 `GetPossibleEpochNanoseconds`, read from the timeline: the instants whose wall clock is
+ * `wallNs` (the wall clock read as UTC), ascending. A stretch contributes `wallNs - offset` when
+ * that instant lies in the stretch; offsets differ by well under two days, so only the stretches
+ * within two days either side can.
+ */
+export function possibleAt(timeline, wallNs) {
+    const { changes, offsets } = timeline;
+    const last = stretchAt(timeline, wallNs + 2n * NANOSECONDS_PER_DAY);
+    const possible = [];
+    for (let index = stretchAt(timeline, wallNs - 2n * NANOSECONDS_PER_DAY); index <= last; index++) {
+        const instant = wallNs - offsets[index];
+        if ((index === 0 || instant >= changes[index - 1]) &&
+            (index === changes.length || instant < changes[index])) {
+            possible.push(instant);
+        }
+    }
+    return possible;
+}
+/**
+ * TC39 `GetEpochNanosecondsFor`: the instant a wall clock names, by
+ * `DisambiguatePossibleEpochNanoseconds`. One candidate is the answer; two give the first
+ * (`"compatible"`, `"earlier"`) or last (`"later"`); none moves the wall clock by the offset
+ * change, back for `"earlier"` and forward otherwise. `undefined` where `"reject"` refuses.
+ * Throws `RangeError` where a moved wall clock names nothing, which no zone's data produces.
+ */
+export function resolveWallNs(timeline, wallNs, disambiguation) {
+    const possible = possibleAt(timeline, wallNs);
+    if (possible.length === 1) {
+        return possible[0];
+    }
+    if (disambiguation === "reject") {
+        return undefined;
+    }
+    if (possible.length > 1) {
+        return disambiguation === "later"
+            ? possible[possible.length - 1]
+            : possible[0];
+    }
+    const change = offsetOf(timeline, wallNs + NANOSECONDS_PER_DAY) -
+        offsetOf(timeline, wallNs - NANOSECONDS_PER_DAY);
+    const shifted = possibleAt(timeline, disambiguation === "earlier" ? wallNs - change : wallNs + change);
+    if (shifted.length === 0) {
+        throw new RangeError("the wall clock cannot be resolved");
+    }
+    return disambiguation === "earlier"
+        ? shifted[0]
+        : shifted[shifted.length - 1];
+}
+/**
+ * TC39 `GetStartOfDay`: the first instant of the local date `epochDay` days from 1970-01-01 -
+ * its first candidate for midnight, else (midnight skipped) the change that ends the gap.
+ */
+export function startOfDayNs(timeline, epochDay) {
+    const midnight = BigInt(epochDay) * NANOSECONDS_PER_DAY;
+    const possible = possibleAt(timeline, midnight);
+    if (possible.length > 0) {
+        return possible[0];
+    }
+    const { changes } = timeline;
+    return changes[stretchAt(timeline, midnight - NANOSECONDS_PER_DAY)];
+}

package/dist/internal/operatingSchedule.d.ts

@@ -1,34 +1,39 @@
 import type { Disambiguation } from "../types/index.js";
 import { type IntervalNanoseconds } from "./intervalNanoseconds.js";
-/** A `LocalWindow` validated once: canonical PlainTime strings, and whether it wraps midnight. */
+import { type ZoneFrame } from "./zoneFrame.js";
+/**
+ * A `LocalWindow` validated once: canonical PlainTime strings, the same times in nanoseconds
+ * since local midnight, and whether it wraps midnight.
+ */
 export type ResolvedWindow = {
     from: string;
     to: string;
+    fromNs: bigint;
+    toNs: bigint;
     wraps: boolean;
 };
 /** An `OperatingSchedule` reduced to the lookups the day walk needs. */
 export type ResolvedSchedule = {
+    /** The zone as the caller wrote it: a time zone identifier or a stored UTC offset. */
     timeZone: string;
+    /** How local time is read in that zone (`zoneFrame`). */
+    frame: ZoneFrame;
     /** Windows by ISO weekday; index 0 is unused. */
     weekly: readonly (readonly ResolvedWindow[])[];
-    holidays: ReadonlySet<string>;
-    overrides: ReadonlyMap<string, readonly ResolvedWindow[]>;
+    /** Holiday epoch days, sorted ascending; never mutated. */
+    holidays: Readonly<Int32Array>;
+    /** Override windows by epoch day (days since 1970-01-01). */
+    overrides: ReadonlyMap<number, readonly ResolvedWindow[]>;
+    /** Epoch days with a holiday or an override, sorted ascending, no repeats. */
+    specials: Readonly<Int32Array>;
 };
 /**
- * Local dates a range may span, counted from the date its start falls on: about 27 years, the
- * same bound `bucketRange` puts on a day walk. A walk that runs out answers with the sentinel,
- * never a partial list.
- */
-export declare const MAX_SCHEDULE_DAYS = 10000;
-/**
- * The search horizon of `nextOpenAt`, `nextCloseAt` and `addOperatingTime` when the caller
- * gives no `within`: one calendar year in the schedule's zone.
- */
-export declare const DEFAULT_OPERATING_HORIZON = "P1Y";
-/**
- * Parse `OperatingSchedule['weekly']`: an object whose own keys are ISO weekdays `"1"`–`"7"`,
- * each holding an array of `LocalWindow`s (or `undefined`, meaning closed). Any other key, or a
- * malformed window, returns `null`.
+ * Parse `OperatingSchedule['weekly']`: an object keyed by ISO weekday `"1"`–`"7"`, each holding an
+ * array of `LocalWindow`s (or `undefined`, meaning closed). Each weekday is read with an ordinary
+ * property get, as Temporal's `Get` reads a field list, so a non-enumerable or inherited weekday
+ * applies. Any other own enumerable key, string or symbol, or a malformed window, returns `null`;
+ * a non-enumerable one is not an entry, as `Object.assign` and spread do not copy it, so a
+ * function carrying the weekdays is read without its built-in `length` and `name`.
  */
 export declare function parseWeeklyPattern(value: unknown): ResolvedWindow[][] | null;
 /** Validate an `OperatingSchedule`, or `null` when any part of it is malformed. */
@@ -47,7 +52,7 @@ export declare function parseScheduleDisambiguation(options: unknown): Disambigu
  * that instant, since nothing after it can be answered. `null` when `within` is not a
  * non-negative ISO duration.
  */
-export declare function parseSearchHorizon(fromNs: bigint, within: unknown, timeZone: string): bigint | null;
+export declare function parseSearchHorizon(fromNs: bigint, within: unknown, frame: ZoneFrame): bigint | null;
 /**
  * What the walk tells its caller.
  *
@@ -73,23 +78,13 @@ export type ScheduleWalk = {
     unresolvedStart: bigint | undefined;
 };
 /**
- * Walk the schedule's local dates from a little before `fromNs`, handing the visitor each open
- * run as soon as no later window can extend it.
- *
- * - Dates come from the day buckets `floorToZone` and `bucketRange` use, so a deleted date
- *   (`Pacific/Apia`, 2011-12-30) is never visited, and a date the clock re-enters after a
- *   fall-back (`America/Goose_Bay`, 2010-11-06) is visited once.
- * - A window can start as early as the previous date's first instant (see `resolveDateWindows`),
- *   so the walk settles one date behind: once a date is resolved, the first instant of the date
- *   resolved before it is the `bound` no later window starts before.
- * - When the visitor stops the walk from `day`, or the last representable day is reached, the
- *   runs still pending are handed over too.
- * - Returns `null` when a day bucket could not be found, or the walk would resolve a date
- *   `MAX_SCHEDULE_DAYS + 2` after the one `fromNs` falls on. Neither use reaches that: a range
- *   is refused up front past `MAX_SCHEDULE_DAYS` dates, and a search's horizon ends with the
- *   `MAX_SCHEDULE_DAYS`th date, so its walk stops by the horizon one date later.
+ * The text of a run's edges: the range's own where the run was clipped to it, else the instant's
+ * UTC string, written here and only for the runs a caller returns.
  */
-export declare function walkSchedule(schedule: ResolvedSchedule, fromNs: bigint, disambiguation: Disambiguation, visitor: ScheduleVisitor): ScheduleWalk | null;
+export declare function runText(run: IntervalNanoseconds): {
+    start: string;
+    end: string;
+};
 /**
  * The schedule's open runs clipped to `[startNs, endNs)`, in the range's own strings where a run
  * is clipped. `null` when the walk fails (see `walkSchedule`), or when a window rejected under
@@ -127,3 +122,13 @@ export declare function instantAfterOpenTime(schedule: ResolvedSchedule, fromNs:
 export declare function parseOpenTimeAmount(value: unknown): bigint | null;
 /** Epoch nanoseconds as a UTC instant string ending in `Z`. */
 export declare function instantText(nanoseconds: bigint): string;
+/**
+ * Open time in `[range.start, range.end)`, in nanoseconds; `null` exactly when
+ * `scheduleRunsWithin` would be.
+ *
+ * Open time is additive over disjoint half-open pieces. Whole day buckets inside a stretch of
+ * constant offset are summed in closed form (whole weeks of the weekly pattern, plus a correction
+ * for each holiday and override); the pieces between them, the range's ends and the dates near an
+ * offset change, are walked.
+ */
+export declare function openTimeWithin(schedule: ResolvedSchedule, range: IntervalNanoseconds, disambiguation: Disambiguation): bigint | null;