@northguild/gmt 1.19.0 → 1.20.0

package/dist/internal/instantFormatOptions.js

@@ -1,8 +1,4 @@
-// Option resolution for formatting an exact time (a ZonedDateTime, or an
-// Instant in a given zone) through the runtime's `Intl.DateTimeFormat`. The
-// rules are the Temporal proposal's ECMA-402 amendments: CreateDateTimeFormat
-// and GetDateTimeFormat with required ~any~ and inherit ~all~, so every caller
-// field, including `era` and `timeZoneName`, is passed on unchanged.
+import { cachedFormatter, checkFormatterArguments } from "./formatterCache.js";
 import { plainDateTimeFormatOptions } from "./plainFormatOptions.js";
 import { optionOrDefault } from "./optionOrDefault.js";
 // GetDateTimeFormat requiredOptions for ~any~. `era` and `timeZoneName` are
@@ -86,15 +82,15 @@ export function instantFormatOptions(options, timeZone, defaults) {
  * @returns the formatted text, not yet normalised
  */
 export function formatWallClockOrZoned(zonedDateTime, locale, options, includeTimeZoneName) {
-    new Intl.DateTimeFormat(locale, options);
+    checkFormatterArguments("DateTimeFormat", locale, options);
     if (includeTimeZoneName) {
         const resolved = instantFormatOptions(options, zonedDateTime.timeZoneId, "zoned-date-time");
         return resolved === null
             ? ""
-            : new Intl.DateTimeFormat(locale, resolved).format(zonedDateTime.epochMilliseconds);
+            : cachedFormatter("DateTimeFormat", locale, resolved).format(zonedDateTime.epochMilliseconds);
     }
     const wallClockMilliseconds = zonedDateTime
         .toPlainDateTime()
         .toZonedDateTime("UTC").epochMilliseconds;
-    return new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options)).format(wallClockMilliseconds);
+    return cachedFormatter("DateTimeFormat", locale, plainDateTimeFormatOptions(options)).format(wallClockMilliseconds);
 }

package/dist/internal/instantIntervalText.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /**
  * Re-serialise instant intervals to `Temporal.Instant.prototype.toString()` spelling.
  *

package/dist/internal/instantNanoseconds.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /**
  * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
  *
@@ -47,7 +47,7 @@ import { Temporal } from "@js-temporal/polyfill";
  *   bracket; a `Z` instant; an offset written with seconds, which TC39 matches exactly
  *   (`-00:45:00[Africa/Monrovia]` is −00:45:00); a bracket whose zone does not exist; and a
  *   bracket whose zone has no instant in range with that wall time at the written offset or at
- *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `-05:00[America/New_York]` in
+ *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `+00:00[Europe/London]` in
  *   June). Such a bracket is not validated here; a function that keeps the zone
  *   (`transitTime`, `toOffsetInstant`) rejects it instead. Calendar and elective annotations
  *   never change the reading. A string whose written reading is outside the instant range, and

package/dist/internal/instantNanoseconds.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { instantLeapSecond } from "../regex/leap-second.js";
 import { hasInstantShape, isoStringBody } from "./isoStringBody.js";
 import { parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
@@ -68,7 +68,7 @@ const minuteOffset = /[+-]\d{2}:\d{2}$/;
  *   bracket; a `Z` instant; an offset written with seconds, which TC39 matches exactly
  *   (`-00:45:00[Africa/Monrovia]` is −00:45:00); a bracket whose zone does not exist; and a
  *   bracket whose zone has no instant in range with that wall time at the written offset or at
- *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `-05:00[America/New_York]` in
+ *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `+00:00[Europe/London]` in
  *   June). Such a bracket is not validated here; a function that keeps the zone
  *   (`transitTime`, `toOffsetInstant`) rejects it instead. Calendar and elective annotations
  *   never change the reading. A string whose written reading is outside the instant range, and

package/dist/internal/intervalCountHelpers.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 import type { DateTimeUnit } from "../types/index.js";
 /**
  * Singular DateTimeUnit to its `Temporal.Duration` field name.

package/dist/internal/isoStringBody.d.ts

@@ -50,8 +50,8 @@ export declare const TIME_ZONE_ANNOTATION = "\\[!?[^\\]=]+\\]";
  * @param value candidate zoned datetime string
  * @returns whether the unannotated part has GMT's strict extended zoned shape
  *
- * @example hasZonedDateTimeShape("2024-10-03T14:30:00-04:00[America/New_York]") // true
- * @example hasZonedDateTimeShape("2024-10-03 14:30:00-04:00[America/New_York]") // false
+ * @example hasZonedDateTimeShape("2024-10-03T14:30:00+05:30[Asia/Kolkata]") // true
+ * @example hasZonedDateTimeShape("2024-10-03 14:30:00+05:30[Asia/Kolkata]") // false
  */
 export declare function hasZonedDateTimeShape(value: string): boolean;
 /**

package/dist/internal/isoStringBody.js

@@ -85,8 +85,8 @@ const instantBody = new RegExp(`^${EXTENDED_DATE_TIME}(?:Z|${EXTENDED_UTC_OFFSET
  * @param value candidate zoned datetime string
  * @returns whether the unannotated part has GMT's strict extended zoned shape
  *
- * @example hasZonedDateTimeShape("2024-10-03T14:30:00-04:00[America/New_York]") // true
- * @example hasZonedDateTimeShape("2024-10-03 14:30:00-04:00[America/New_York]") // false
+ * @example hasZonedDateTimeShape("2024-10-03T14:30:00+05:30[Asia/Kolkata]") // true
+ * @example hasZonedDateTimeShape("2024-10-03 14:30:00+05:30[Asia/Kolkata]") // false
  */
 export function hasZonedDateTimeShape(value) {
     return (typeof value === "string" && zonedDateTimeBody.test(isoStringBody(value)));

package/dist/internal/joinDateTimeConnector.js

@@ -1,3 +1,4 @@
+import { cachedFormatter } from "./formatterCache.js";
 // `Intl.DateTimeFormat`'s part types that belong to the *date* half of a
 // combined `dateStyle` + `timeStyle` format. Everything else (`hour`,
 // `minute`, `second`, `fractionalSecond`, `dayPeriod`, `timeZoneName`, and
@@ -48,7 +49,7 @@ const DATE_PART_TYPES = new Set([
  * @returns `dayLabel` joined to the localized time with the locale's own connector
  */
 export function joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle) {
-    const parts = new Intl.DateTimeFormat(locale, {
+    const parts = cachedFormatter("DateTimeFormat", locale, {
         dateStyle: "full",
         timeStyle,
         timeZone,
@@ -62,7 +63,7 @@ export function joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLa
     // dateStyle-only format would still produce with no time present — it
     // belongs to the date field, not the connector, even though the combined
     // format fuses it into the same literal token as the real connector.
-    const dateOnlyParts = new Intl.DateTimeFormat(locale, {
+    const dateOnlyParts = cachedFormatter("DateTimeFormat", locale, {
         dateStyle: "full",
         timeZone,
     }).formatToParts(epochMilliseconds);

package/dist/internal/leapSeconds.d.ts

@@ -0,0 +1,63 @@
+import type { UtcReading } from "./utcReading.js";
+/** TAI − UTC by date: `at[i]` (epoch ns, 00:00:00 UTC on a month's first day) starts `taiMinusUtc[i]`. */
+export interface LeapSecondSteps {
+    /** Epoch nanoseconds at which each row's TAI − UTC takes effect, strictly increasing. */
+    readonly at: readonly bigint[];
+    /** TAI − UTC in whole seconds from `at[i]` until `at[i + 1]`. */
+    readonly taiMinusUtc: readonly bigint[];
+}
+/**
+ * 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 declare const LEAP_SECOND_STEPS: LeapSecondSteps;
+/**
+ * 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 declare function taiOfUtc(steps: LeapSecondSteps, reading: UtcReading): bigint | null;
+/**
+ * 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 declare function utcOfTai(steps: LeapSecondSteps, tai: bigint): UtcReading | null;
+/**
+ * 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 declare function stepReading(steps: LeapSecondSteps, index: number): UtcReading;
+/**
+ * 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 declare function nextStepIndex(steps: LeapSecondSteps, reading: UtcReading): number;

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/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

@@ -17,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

@@ -19,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)];
+}