@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/toInstantFromUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 // Convert a UTC ISO datetime string to a Temporal.Instant.
 // Returns null on failure (caller should have already validated with isValidUtc).
 export function toInstantFromUtc(value) {

package/dist/internal/twoDigitYear.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a two-digit year inside a caller-chosen hundred-year window: the one year in
+ * `[windowStart, windowStart + 99]` whose last two digits are `yy`.
+ *
+ * Pure arithmetic: the function holds no window of its own and reads no clock. The window comes
+ * from the caller's `TwoDigitYearOptions.yearWindow`, resolved by `readYearWindowStart`
+ * (`internal/yearWindowStart.ts`); no standard says which century a two-digit year belongs to,
+ * so the library never supplies one.
+ *
+ * @param yy the two-digit year, 0–99, as the grammar read it
+ * @param windowStart the first year of the hundred-year window
+ * @returns the four-digit year in the window ending in `yy`
+ *
+ * @example twoDigitYear(24, 2000) // 2024
+ * @example twoDigitYear(99, 1950) // 1999
+ * @example twoDigitYear(49, 1950) // 2049
+ * @example twoDigitYear(0, 1976) // 2000
+ */
+export declare function twoDigitYear(yy: number, windowStart: number): number;

package/dist/internal/twoDigitYear.js

@@ -0,0 +1,22 @@
+/**
+ * Resolve a two-digit year inside a caller-chosen hundred-year window: the one year in
+ * `[windowStart, windowStart + 99]` whose last two digits are `yy`.
+ *
+ * Pure arithmetic: the function holds no window of its own and reads no clock. The window comes
+ * from the caller's `TwoDigitYearOptions.yearWindow`, resolved by `readYearWindowStart`
+ * (`internal/yearWindowStart.ts`); no standard says which century a two-digit year belongs to,
+ * so the library never supplies one.
+ *
+ * @param yy the two-digit year, 0–99, as the grammar read it
+ * @param windowStart the first year of the hundred-year window
+ * @returns the four-digit year in the window ending in `yy`
+ *
+ * @example twoDigitYear(24, 2000) // 2024
+ * @example twoDigitYear(99, 1950) // 1999
+ * @example twoDigitYear(49, 1950) // 2049
+ * @example twoDigitYear(0, 1976) // 2000
+ */
+export function twoDigitYear(yy, windowStart) {
+    const candidate = Math.floor(windowStart / 100) * 100 + yy;
+    return candidate < windowStart ? candidate + 100 : candidate;
+}

package/dist/internal/unixEpochValue.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /** The two units a Unix epoch value is expressed in. */
 export type UnixEpochUnit = "seconds" | "milliseconds";
 /**

package/dist/internal/unixEpochValue.js

@@ -1,5 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { MAX_EPOCH_NANOSECONDS } from "./epochNanoseconds.js";
+import { isObject } from "./isObject.js";
 // TC39 Temporal IsValidEpochNanoseconds bound (nsMaxInstant = 10^8 days) in milliseconds: 8.64e15.
 const MAX_EPOCH_MILLISECONDS = Number(MAX_EPOCH_NANOSECONDS / 1000000n);
 // An optionally negative run of ASCII digits and nothing else. `\d` without the `u` flag is
@@ -91,7 +92,7 @@ export function resolveUnixEpochUnitOptions(options) {
     if (options === undefined) {
         return "milliseconds";
     }
-    if (options === null || typeof options !== "object") {
+    if (!isObject(options)) {
         return null;
     }
     return resolveUnixEpochUnit(options.epochUnit);
@@ -231,7 +232,7 @@ export function parseUnixEpochIntervalList(intervals) {
     }
     const parsed = [];
     for (const interval of intervals) {
-        if (!interval || typeof interval !== "object") {
+        if (!isObject(interval)) {
             return null;
         }
         const { start, end } = interval;

package/dist/internal/unixFormatReference.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { type UnixEpochUnit } from "./unixEpochValue.js";
 /**
  * Resolve the `reference` option of the unix formatters to an instant.

package/dist/internal/unixFormatReference.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { isValidUtc } from "../utc/validate/isValidUtc.js";
 import { unixEpochToInstant } from "./unixEpochValue.js";
 /**

package/dist/internal/unixWallClock.d.ts

@@ -0,0 +1,24 @@
+import type { Temporal } from "./temporal.js";
+/**
+ * Read a Unix epoch argument on the local wall clock of the shared `unix/` options, or null when
+ * anything is invalid. For the `parse*FromUnix` accessors, which only read fields.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the local wall clock, or null
+ *
+ * @example unixWallClock(0)?.toString() // "1970-01-01T00:00:00"
+ * @example unixWallClock("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixWallClock(45870000, { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example unixWallClock(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export declare function unixWallClock(value: unknown, options?: {
+    epochUnit?: unknown;
+    timeZone?: unknown;
+}): Temporal.PlainDateTime | null;

package/dist/internal/unixWallClock.js

@@ -0,0 +1,35 @@
+import { resolveUnixEpochUnit, unixEpochToInstant } from "./unixEpochValue.js";
+import { frameWallClock, normalizeZoneFrame } from "./zoneFrame.js";
+/**
+ * Read a Unix epoch argument on the local wall clock of the shared `unix/` options, or null when
+ * anything is invalid. For the `parse*FromUnix` accessors, which only read fields.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the local wall clock, or null
+ *
+ * @example unixWallClock(0)?.toString() // "1970-01-01T00:00:00"
+ * @example unixWallClock("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixWallClock(45870000, { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example unixWallClock(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export function unixWallClock(value, options) {
+    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+    const frame = normalizeZoneFrame(options?.timeZone);
+    if (epochUnit === null || frame === null) {
+        return null;
+    }
+    try {
+        const instant = unixEpochToInstant(value, epochUnit);
+        return instant === null ? null : frameWallClock(instant, frame);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/utcOffsetString.d.ts

@@ -1,3 +1,4 @@
+import { Temporal } from "./temporal.js";
 /**
  * Parse a `±HH:MM[:SS]` UTC offset to the nanoseconds local time runs ahead of UTC.
  *
@@ -37,3 +38,18 @@ export declare function parseUtcOffsetNanoseconds(offset: string): bigint | null
  * @example formatUtcOffset(1n) // null — finer than a second
  */
 export declare function formatUtcOffset(offsetNanoseconds: bigint): string | null;
+/**
+ * The offset an instant string's own digits were written in, recovered without slicing them.
+ *
+ * Recovers the offset written in the body from the distance between two wall clocks: the digits
+ * as written, and the same instant read in UTC. A `Z` or `z` body is written in UTC, so its offset is
+ * `+00:00`.
+ *
+ * @param instant the instant `body` names
+ * @param body the ISO 8601 string with any bracketed annotations removed (`isoStringBody`)
+ * @returns the written offset as `±HH:MM[:SS]`, or null when it is finer than a second
+ *
+ * @example writtenOffset(Temporal.Instant.from("2024-07-15T12:00:00+05:30"), "2024-07-15T12:00:00+05:30") // "+05:30"
+ * @example writtenOffset(Temporal.Instant.from("2024-07-15T12:00:00Z"), "2024-07-15T12:00:00Z") // "+00:00"
+ */
+export declare function writtenOffset(instant: Temporal.Instant, body: string): string | null;

package/dist/internal/utcOffsetString.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { utcOffset } from "../regex/utc-offset.js";
 const NANOSECONDS_PER_SECOND = 1000000000n;
 const SECONDS_PER_MINUTE = 60n;
@@ -73,3 +73,33 @@ export function formatUtcOffset(offsetNanoseconds) {
         ? `${sign}${padTwo(hours)}:${padTwo(minutes)}`
         : `${sign}${padTwo(hours)}:${padTwo(minutes)}:${padTwo(seconds)}`;
 }
+/**
+ * The offset an instant string's own digits were written in, recovered without slicing them.
+ *
+ * Recovers the offset written in the body from the distance between two wall clocks: the digits
+ * as written, and the same instant read in UTC. A `Z` or `z` body is written in UTC, so its offset is
+ * `+00:00`.
+ *
+ * @param instant the instant `body` names
+ * @param body the ISO 8601 string with any bracketed annotations removed (`isoStringBody`)
+ * @returns the written offset as `±HH:MM[:SS]`, or null when it is finer than a second
+ *
+ * @example writtenOffset(Temporal.Instant.from("2024-07-15T12:00:00+05:30"), "2024-07-15T12:00:00+05:30") // "+05:30"
+ * @example writtenOffset(Temporal.Instant.from("2024-07-15T12:00:00Z"), "2024-07-15T12:00:00Z") // "+00:00"
+ */
+export function writtenOffset(instant, body) {
+    // The written offset is the distance between two wall clocks: the digits as written, and the
+    // same instant read in UTC. That recovers it without slicing the
+    // string. The subtraction stays on `PlainDateTime` rather than going through an
+    // instant, because a wall clock reaches a day further either side than an instant does
+    // — `+275760-09-13T14:00:00+14:00` names a representable instant whose digits, read as
+    // UTC, are past the end of the range. `PlainDateTime.from` parses every shape this
+    // grammar allows but the `Z` designator, and a `Z` string's wall clock *is* the UTC
+    // one, so its offset is `+00:00` by definition.
+    const utcWallClock = instant.toZonedDateTimeISO("UTC").toPlainDateTime();
+    const writtenWallClock = body.endsWith("Z") || body.endsWith("z")
+        ? utcWallClock
+        : Temporal.PlainDateTime.from(body);
+    return formatUtcOffset(BigInt(utcWallClock.until(writtenWallClock, { largestUnit: "nanosecond" })
+        .nanoseconds));
+}

package/dist/internal/utcReading.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A UTC label that may be a leap second.
+ *
+ * Temporal cannot represent a second of 60: `Temporal.Instant.from("2016-12-31T23:59:60.5Z")`
+ * clamps it to `…:59.5Z` (proposal-temporal `ParseISODateTime`). A reading keeps the clamped
+ * instant and a flag, so the inserted second (ITU-R TF.460-6 Annex 1 §2.2) and the second
+ * before it stay two different readings.
+ */
+export interface UtcReading {
+    /** For a leap reading, the instant of `…T23:59:59.f` (Temporal's clamp of `…:60.f`). */
+    readonly epochNanoseconds: bigint;
+    /** Whether the label's second field is 60. */
+    readonly secondSixty: boolean;
+}
+/** The last year this realm writes: its strings carry four-digit years only (a GMT rule). */
+export declare const MAX_FOUR_DIGIT_YEAR = 9999;
+/**
+ * Read a UTC instant string that may carry a second of 60.
+ *
+ * Checks shape only: an ordinary instant goes through `parseInstantNanoseconds`; a second-60
+ * instant in GMT's strict extended shape is read by `Temporal.Instant.from`, which clamps the
+ * second to 59. Whether that second 60 was a real leap second is `taiOfUtc`'s decision.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns the reading, or null when `value` is not an instant string GMT reads
+ */
+export declare function parseUtcReading(value: unknown): UtcReading | null;
+/**
+ * Write a UTC reading as an ISO 8601 instant string in `Z` form.
+ *
+ * - An ordinary reading is `Temporal.Instant#toString()`.
+ * - A second-60 reading is written `…T23:59:60[.fraction]Z` (ITU-R TF.460-6 Annex 3: "30 June,
+ *   23h 59m 60.6s UTC"), the fraction in Temporal's shortest digits.
+ * - Four-digit years only, as in the realm's time-scale strings (a GMT rule): a reading past
+ *   9999-12-31 is "", never Temporal's six-digit `+010000-…` form.
+ *
+ * @param reading the UTC reading
+ * @returns the instant string, or "" past year 9999 or when Temporal throws
+ */
+export declare function formatUtcReading(reading: UtcReading): string;
+/**
+ * The wall clock of a second-60 label, `YYYY-MM-DDTHH:MM:60[.fraction]`, from the `…:59.f`
+ * instant Temporal clamps it to. Throws where Temporal throws, so callers call it inside `try`.
+ *
+ * @param nanoseconds the clamped `…:59.f` instant or label, in epoch nanoseconds
+ * @returns the wall clock with second 60 and no designator
+ */
+export declare function secondSixtyWallClock(nanoseconds: bigint): string;
+/**
+ * The fraction of the second a nanosecond count falls in, written as Temporal writes a time's
+ * fraction: `""` for none, else `.` and the shortest digits (`".5"`, `".123456789"`).
+ *
+ * The sub-second count is split into milliseconds, microseconds and nanoseconds: passed as
+ * `nanosecond` alone, Temporal's default `overflow: "constrain"` clamps it to 999.
+ *
+ * @param nanoseconds epoch or label nanoseconds
+ * @returns the fraction, with its leading `.`, or ""
+ */
+export declare function subsecondFraction(nanoseconds: bigint): string;

package/dist/internal/utcReading.js

@@ -0,0 +1,113 @@
+import { Temporal } from "./temporal.js";
+import { plainDate } from "../regex/date.js";
+import { instantLeapSecond } from "../regex/leap-second.js";
+import { NANOSECONDS_PER_SECOND } from "./foreignEpochs.js";
+import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+import { EXTENDED_UTC_OFFSET, isoStringBody } from "./isoStringBody.js";
+/** The last year this realm writes: its strings carry four-digit years only (a GMT rule). */
+export const MAX_FOUR_DIGIT_YEAR = 9999;
+/** `plainDate` without its anchors: GMT's ISO 8601 extended calendar date. */
+const DATE = plainDate.source.slice(1, -1);
+/**
+ * An instant body (before the first `[`) whose second is 60, in GMT's strict extended shape:
+ * `<date>T<hh>:<mm>:60[.fraction]`, then `Z` or `±HH:MM[:SS[.fraction]]`. The fraction is 1 to 9
+ * digits after `.` or `,` (RFC 3339 §5.6 `time-secfrac`; Temporal's nanosecond resolution).
+ * Basic format, lower-case `t`/`z` and a space separator are refused, as `instantBody` refuses
+ * them for every other second.
+ */
+const secondSixtyInstantBody = new RegExp(`^${DATE}T(?:[01]\\d|2[0-3]):[0-5]\\d:60(?:[.,]\\d{1,9})?(?:Z|${EXTENDED_UTC_OFFSET})$`);
+/**
+ * Read a UTC instant string that may carry a second of 60.
+ *
+ * Checks shape only: an ordinary instant goes through `parseInstantNanoseconds`; a second-60
+ * instant in GMT's strict extended shape is read by `Temporal.Instant.from`, which clamps the
+ * second to 59. Whether that second 60 was a real leap second is `taiOfUtc`'s decision.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns the reading, or null when `value` is not an instant string GMT reads
+ */
+export function parseUtcReading(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const epochNanoseconds = parseInstantNanoseconds(value);
+    if (epochNanoseconds !== null) {
+        return { epochNanoseconds, secondSixty: false };
+    }
+    if (!instantLeapSecond.test(value) ||
+        !secondSixtyInstantBody.test(isoStringBody(value))) {
+        return null;
+    }
+    try {
+        return {
+            epochNanoseconds: Temporal.Instant.from(value).epochNanoseconds,
+            secondSixty: true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a UTC reading as an ISO 8601 instant string in `Z` form.
+ *
+ * - An ordinary reading is `Temporal.Instant#toString()`.
+ * - A second-60 reading is written `…T23:59:60[.fraction]Z` (ITU-R TF.460-6 Annex 3: "30 June,
+ *   23h 59m 60.6s UTC"), the fraction in Temporal's shortest digits.
+ * - Four-digit years only, as in the realm's time-scale strings (a GMT rule): a reading past
+ *   9999-12-31 is "", never Temporal's six-digit `+010000-…` form.
+ *
+ * @param reading the UTC reading
+ * @returns the instant string, or "" past year 9999 or when Temporal throws
+ */
+export function formatUtcReading(reading) {
+    try {
+        const instant = Temporal.Instant.fromEpochNanoseconds(reading.epochNanoseconds);
+        if (instant.toZonedDateTimeISO("UTC").year > MAX_FOUR_DIGIT_YEAR) {
+            return "";
+        }
+        return reading.secondSixty
+            ? `${secondSixtyWallClock(reading.epochNanoseconds)}Z`
+            : instant.toString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * The wall clock of a second-60 label, `YYYY-MM-DDTHH:MM:60[.fraction]`, from the `…:59.f`
+ * instant Temporal clamps it to. Throws where Temporal throws, so callers call it inside `try`.
+ *
+ * @param nanoseconds the clamped `…:59.f` instant or label, in epoch nanoseconds
+ * @returns the wall clock with second 60 and no designator
+ */
+export function secondSixtyWallClock(nanoseconds) {
+    const wall = Temporal.Instant.fromEpochNanoseconds(nanoseconds)
+        .toZonedDateTimeISO("UTC")
+        .toPlainDateTime();
+    return `${wall.toPlainDate().toString()}T${wall
+        .toPlainTime()
+        .toString({ smallestUnit: "minute" })}:60${subsecondFraction(nanoseconds)}`;
+}
+/**
+ * The fraction of the second a nanosecond count falls in, written as Temporal writes a time's
+ * fraction: `""` for none, else `.` and the shortest digits (`".5"`, `".123456789"`).
+ *
+ * The sub-second count is split into milliseconds, microseconds and nanoseconds: passed as
+ * `nanosecond` alone, Temporal's default `overflow: "constrain"` clamps it to 999.
+ *
+ * @param nanoseconds epoch or label nanoseconds
+ * @returns the fraction, with its leading `.`, or ""
+ */
+export function subsecondFraction(nanoseconds) {
+    const subsecond = Number(((nanoseconds % NANOSECONDS_PER_SECOND) + NANOSECONDS_PER_SECOND) %
+        NANOSECONDS_PER_SECOND);
+    return Temporal.PlainTime.from({
+        hour: 0,
+        millisecond: Math.floor(subsecond / 1e6),
+        microsecond: Math.floor(subsecond / 1e3) % 1000,
+        nanosecond: subsecond % 1000,
+    }, { overflow: "reject" })
+        .toString()
+        .slice("00:00:00".length);
+}

package/dist/internal/utcWallClock.d.ts

@@ -0,0 +1,20 @@
+import { Temporal } from "./temporal.js";
+/**
+ * Read a UTC ISO string on a local wall clock for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixWallClock`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the local wall clock, or null when the value or the zone is invalid
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00"
+ * @example utcWallClock("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcWallClock("2024-03-15T14:30:00") // null (no Z)
+ */
+export declare function utcWallClock(value: string, options?: {
+    timeZone?: string;
+}): Temporal.PlainDateTime | null;

package/dist/internal/utcWallClock.js

@@ -0,0 +1,32 @@
+import { Temporal } from "./temporal.js";
+import { isValidUtc } from "../utc/validate/isValidUtc.js";
+import { frameWallClock, normalizeZoneFrame } from "./zoneFrame.js";
+/**
+ * Read a UTC ISO string on a local wall clock for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixWallClock`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the local wall clock, or null when the value or the zone is invalid
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00"
+ * @example utcWallClock("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcWallClock("2024-03-15T14:30:00") // null (no Z)
+ */
+export function utcWallClock(value, options) {
+    if (!isValidUtc(value))
+        return null;
+    const frame = normalizeZoneFrame(options?.timeZone);
+    if (frame === null)
+        return null;
+    try {
+        return frameWallClock(Temporal.Instant.from(value), frame);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/validatedZones.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether this id already passed `isValidTimeZone`.
+ *
+ * @param timeZone the identifier
+ * @returns `true` for an id remembered as valid
+ *
+ * @example isRememberedZone("Europe/London") // false until `rememberZone("Europe/London")`
+ */
+export declare function isRememberedZone(timeZone: string): boolean;
+/**
+ * Remember an id that passed. Only a pass is stored, so hostile strings cannot grow the set;
+ * past 1,024 ids the set clears.
+ *
+ * @param timeZone the identifier that passed
+ *
+ * @example rememberZone("Europe/London") // stores it
+ */
+export declare function rememberZone(timeZone: string): void;
+/** Test seam: forget every remembered id. */
+export declare function clearValidatedZones(): void;

package/dist/internal/validatedZones.js

@@ -0,0 +1,33 @@
+/** Ids that passed both `isValidTimeZone` checks. Whether an id names a zone is fixed by the host data. */
+const validatedZones = new Set();
+/** Past this many ids the set clears. */
+const MAX_VALIDATED_ZONES = 1024;
+/**
+ * Whether this id already passed `isValidTimeZone`.
+ *
+ * @param timeZone the identifier
+ * @returns `true` for an id remembered as valid
+ *
+ * @example isRememberedZone("Europe/London") // false until `rememberZone("Europe/London")`
+ */
+export function isRememberedZone(timeZone) {
+    return validatedZones.has(timeZone);
+}
+/**
+ * Remember an id that passed. Only a pass is stored, so hostile strings cannot grow the set;
+ * past 1,024 ids the set clears.
+ *
+ * @param timeZone the identifier that passed
+ *
+ * @example rememberZone("Europe/London") // stores it
+ */
+export function rememberZone(timeZone) {
+    if (validatedZones.size >= MAX_VALIDATED_ZONES) {
+        validatedZones.clear();
+    }
+    validatedZones.add(timeZone);
+}
+/** Test seam: forget every remembered id. */
+export function clearValidatedZones() {
+    validatedZones.clear();
+}

package/dist/internal/wallClockAtOffset.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * The wall clock an instant reads at a fixed UTC offset, including a sub-minute or fractional
  * one. Callers write the offset text themselves.

package/dist/internal/yearWindowStart.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve `TwoDigitYearOptions.yearWindow` to the first year of a hundred-year window, or null
+ * when the option is absent or not one of its two forms.
+ *
+ * - An integer from 0 to 9900 is a fixed window starting in that year.
+ * - `"rolling"` (exact match) is the hundred years around today: 50 years before the current UTC
+ *   calendar year to 49 after it. The year is read once, from
+ *   `Temporal.Now.instant().toZonedDateTimeISO("UTC").year`, so the window moves at the UTC new
+ *   year, not mid-year: year granularity is a **GMT rule**. RFC 9110 §5.6.7 applies the same
+ *   50-year idea to an `rfc850-date` two-digit year, at day granularity; `internal/httpDateFields.ts`
+ *   implements that rule for HTTP dates and is not affected by this one.
+ * - Anything else (a non-integer, a negative, 9901, `NaN`, `Infinity`, a numeric string, any
+ *   other string, `null`) is null. Whether a null window matters is the caller's: a value with no
+ *   two-digit year needs none.
+ *
+ * `options` is read as an Object the way Temporal's GetOptionsObject reads one (a function is an
+ * Object); a non-Object yields null here, and the public function has already returned its
+ * sentinel for one by `isOptionsArgument`.
+ *
+ * @param options the caller's options bag
+ * @returns the window's first year, or null
+ *
+ * @example readYearWindowStart({ yearWindow: 1950 }) // 1950
+ * @example readYearWindowStart({ yearWindow: "rolling" }) // 1976 (in 2026)
+ * @example readYearWindowStart({}) // null
+ * @example readYearWindowStart({ yearWindow: 9901 }) // null
+ */
+export declare function readYearWindowStart(options: unknown): number | null;

package/dist/internal/yearWindowStart.js

@@ -0,0 +1,52 @@
+import { Temporal } from "./temporal.js";
+import { isObject } from "./isObject.js";
+/** `TwoDigitYearOptions.yearWindow` as a number: the first year of the window, 0–9900. */
+const MIN_YEAR_WINDOW_START = 0;
+/** The highest start whose every year, start + 99, is still a four-digit ISO year. */
+const MAX_YEAR_WINDOW_START = 9900;
+/** A rolling window starts this many years before the current UTC calendar year. */
+const ROLLING_YEARS_BEFORE_NOW = 50;
+/**
+ * Resolve `TwoDigitYearOptions.yearWindow` to the first year of a hundred-year window, or null
+ * when the option is absent or not one of its two forms.
+ *
+ * - An integer from 0 to 9900 is a fixed window starting in that year.
+ * - `"rolling"` (exact match) is the hundred years around today: 50 years before the current UTC
+ *   calendar year to 49 after it. The year is read once, from
+ *   `Temporal.Now.instant().toZonedDateTimeISO("UTC").year`, so the window moves at the UTC new
+ *   year, not mid-year: year granularity is a **GMT rule**. RFC 9110 §5.6.7 applies the same
+ *   50-year idea to an `rfc850-date` two-digit year, at day granularity; `internal/httpDateFields.ts`
+ *   implements that rule for HTTP dates and is not affected by this one.
+ * - Anything else (a non-integer, a negative, 9901, `NaN`, `Infinity`, a numeric string, any
+ *   other string, `null`) is null. Whether a null window matters is the caller's: a value with no
+ *   two-digit year needs none.
+ *
+ * `options` is read as an Object the way Temporal's GetOptionsObject reads one (a function is an
+ * Object); a non-Object yields null here, and the public function has already returned its
+ * sentinel for one by `isOptionsArgument`.
+ *
+ * @param options the caller's options bag
+ * @returns the window's first year, or null
+ *
+ * @example readYearWindowStart({ yearWindow: 1950 }) // 1950
+ * @example readYearWindowStart({ yearWindow: "rolling" }) // 1976 (in 2026)
+ * @example readYearWindowStart({}) // null
+ * @example readYearWindowStart({ yearWindow: 9901 }) // null
+ */
+export function readYearWindowStart(options) {
+    if (!isObject(options)) {
+        return null;
+    }
+    const { yearWindow } = options;
+    if (yearWindow === "rolling") {
+        return (Temporal.Now.instant().toZonedDateTimeISO("UTC").year -
+            ROLLING_YEARS_BEFORE_NOW);
+    }
+    if (typeof yearWindow === "number" &&
+        Number.isInteger(yearWindow) &&
+        yearWindow >= MIN_YEAR_WINDOW_START &&
+        yearWindow <= MAX_YEAR_WINDOW_START) {
+        return yearWindow;
+    }
+    return null;
+}

package/dist/internal/zoneBucketCap.d.ts

@@ -0,0 +1,18 @@
+import { Temporal } from "./temporal.js";
+import type { ZoneBucketUnit } from "../types/index.js";
+/**
+ * True when `[start, end)` certainly touches more than `max` buckets of `unit`, decided from the span
+ * instead of stepping bucket by bucket (which costs milliseconds a step in some zones).
+ *
+ * Over a prefix of the range, the local wall clock runs continuously between offset transitions.
+ * Those stretches cover at least the prefix's length less every backward offset change, in at most
+ * one stretch more than there are transitions, and each stretch of wall clock holds at least
+ * `floor(length / LONGEST_UNIT_NANOSECONDS)` distinct unit starts, each the start of its own
+ * bucket before `end`. The count subtracts two per stretch for the partial units at its ends.
+ * The bound also holds for a count of distinct local dates, which the free-time walk keeps by
+ * folding a day that re-enters an earlier date: a date can re-enter only at an offset transition,
+ * where the two units dropped per stretch already sit, and the starts counted inside one stretch
+ * fall on strictly increasing dates.
+ * `false` means "not certain": the walk decides, exactly as before.
+ */
+export declare function certainlyTouchesMoreBuckets(startZoned: Temporal.ZonedDateTime, endZoned: Temporal.ZonedDateTime, unit: ZoneBucketUnit, max: number): boolean;