@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/zoneBucketCap.js

@@ -0,0 +1,64 @@
+import { Temporal } from "./temporal.js";
+import { zonedNextTransition } from "./zonedWallClockOperations.js";
+/**
+ * A bounded walk over a zone's local buckets (hours, days, weeks, months) can refuse a span that is
+ * certainly too long without stepping through it. `bucketRange` refuses a range past 10,000
+ * buckets this way, and the free-time walk a dwell past 10,000 local days. `false` always means
+ * "not certain": the caller walks, exactly as it would without this check, so no answer changes.
+ */
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+/**
+ * The longest wall-clock stretch of each unit. Any wall-clock interval this long holds a unit
+ * start: an hour holds an hour start, 24 hours a midnight, 7 days a Monday, 31 days a first of
+ * the month.
+ */
+const LONGEST_UNIT_NANOSECONDS = {
+    hour: NANOSECONDS_PER_HOUR,
+    day: 24n * NANOSECONDS_PER_HOUR,
+    week: 168n * NANOSECONDS_PER_HOUR,
+    month: 744n * NANOSECONDS_PER_HOUR,
+};
+/** Offset transitions read before the pre-count gives up and leaves the answer to the walk. */
+const MAX_PRECOUNT_TRANSITIONS = 4_096;
+/**
+ * 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 function certainlyTouchesMoreBuckets(startZoned, endZoned, unit, max) {
+    const unitNs = LONGEST_UNIT_NANOSECONDS[unit];
+    const startNs = startZoned.epochNanoseconds;
+    const prefixEndNs = [
+        endZoned.epochNanoseconds,
+        startNs + 2n * BigInt(max + 1) * unitNs,
+    ].reduce((a, b) => (a < b ? a : b));
+    if (prefixEndNs - startNs <= BigInt(max) * unitNs) {
+        return false;
+    }
+    let backwardNs = 0n;
+    let transitions = 0;
+    try {
+        for (let current = startZoned, next = zonedNextTransition(current, prefixEndNs - 1n); next !== null; current = next, next = zonedNextTransition(current, prefixEndNs - 1n)) {
+            if (++transitions > MAX_PRECOUNT_TRANSITIONS) {
+                return false;
+            }
+            const shift = BigInt(current.offsetNanoseconds - next.offsetNanoseconds);
+            backwardNs += shift > 0n ? shift : 0n;
+        }
+    }
+    catch {
+        return false;
+    }
+    const wallStarts = (prefixEndNs - startNs - backwardNs) / unitNs;
+    return wallStarts - 2n * BigInt(transitions + 1) > BigInt(max);
+}

package/dist/internal/zoneFrame.d.ts

@@ -0,0 +1,180 @@
+import { Temporal } from "./temporal.js";
+/**
+ * How local time is read for a time zone argument: a Temporal time zone, plus the part of a stored
+ * UTC offset no time zone identifier can carry.
+ *
+ * A time zone identifier stops at minutes (TC39 Temporal §13.31, the RFC 9557 / ISO 8601 grammar:
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`), but a zone's real
+ * offset does not: `Africa/Monrovia` stood at `-00:44:30` until 1972, and `getTimeZoneOffset`
+ * returns it. A fixed offset is still a complete rule for local time, so a function whose result
+ * names no zone reads one at any precision.
+ *
+ * The real offset is the offset of `timeZone` plus `shiftNanoseconds`. One frame serves a whole
+ * call, so every value of the call is placed in the same zone.
+ */
+export type ZoneFrame = {
+    /**
+     * A Temporal time zone identifier. For an offset with seconds it is the offset's whole minutes
+     * (`-00:44` for `-00:44:30`, `+02:10` for `+02:10:08`, `+00:00` within a minute of zero).
+     */
+    timeZone: string;
+    /**
+     * `0n`, or the seconds the real offset has beyond the offset of `timeZone`, in nanoseconds:
+     * under a minute, with the offset's own sign (east positive).
+     */
+    shiftNanoseconds: bigint;
+};
+/**
+ * Read a time zone argument that may also be a stored UTC offset.
+ *
+ * The only place that turns "time zone identifier or stored offset" into something Temporal can
+ * use. It accepts exactly what `isValidTimeZone` or `isValidUtcOffset` accepts, by five rules in
+ * order:
+ *
+ * 1. Not a string: null.
+ * 2. A time zone identifier (`isValidTimeZone`): that identifier as written, no shift. Every
+ *    argument that was valid before stored offsets were read takes this branch.
+ * 3. Not a stored offset (`±HH:MM[:SS]`): null.
+ * 4. A whole number of minutes (`+05:30:00`): the identifier it canonicalises to (`+05:30`), no
+ *    shift.
+ * 5. Otherwise (`-00:44:30`): the offset's whole minutes as the zone (`-00:44`), shifted by its
+ *    seconds with the offset's own sign (30 seconds further west).
+ *
+ * - The returned `timeZone` is always a time zone identifier, so it is safe in a bracket or in
+ *   `Intl.DateTimeFormat`. A seconds offset never becomes one: a caller that writes the zone into
+ *   its result validates with `isValidTimeZone` instead and does not call this.
+ *
+ * @param zone the caller's time zone argument
+ * @returns the frame, or null when `zone` is neither a time zone identifier nor a stored offset
+ *
+ * @example zoneFrame("Asia/Kolkata") // { timeZone: "Asia/Kolkata", shiftNanoseconds: 0n }
+ * @example zoneFrame("+05:30:00") // { timeZone: "+05:30", shiftNanoseconds: 0n }
+ * @example zoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example zoneFrame("Z") // null
+ */
+export declare function zoneFrame(zone: unknown): ZoneFrame | null;
+/**
+ * Read the `timeZone` option of a `unix/` or `utc/` function whose result names no zone.
+ *
+ * - Omitted (`undefined`) is `"UTC"`: an epoch and a UTC string name an instant, so no host zone
+ *   is read unless asked for.
+ * - `"local"` is the system time zone, or null when the host reports none that is valid.
+ * - Anything else is read by `zoneFrame`.
+ *
+ * `normalizeTimeZone` is the twin for a function that writes the zone into its result or hands it
+ * to `Intl.DateTimeFormat`: it accepts a time zone identifier only.
+ *
+ * @param option the caller's `timeZone` option
+ * @returns the frame, or null when the option is invalid
+ *
+ * @example normalizeZoneFrame(undefined) // { timeZone: "UTC", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("local") // the system zone, e.g. { timeZone: "Asia/Tokyo", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example normalizeZoneFrame("Asia/Tokio") // null
+ */
+export declare function normalizeZoneFrame(option?: unknown): ZoneFrame | null;
+/**
+ * Read an instant on a frame's local wall clock. For a function that only reads fields.
+ *
+ * - A seconds offset is read with `wallClockAtOffset`, which is exact up to both limits of the
+ *   instant range; `frameZoned` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock
+ *
+ * @example frameWallClock(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:00:00"
+ */
+export declare function frameWallClock(instant: Temporal.Instant, frame: ZoneFrame): Temporal.PlainDateTime;
+/**
+ * Read the current instant on a frame's local wall clock.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock now
+ *
+ * @example frameNowWallClock(zoneFrame("-00:44:30")).toPlainDate().toString() // today's date at -00:44:30
+ */
+export declare function frameNowWallClock(frame: ZoneFrame): Temporal.PlainDateTime;
+/**
+ * Place an instant on a frame's local clock as a `Temporal.ZonedDateTime`, for a body that does
+ * arithmetic on one.
+ *
+ * - For a seconds offset the value sits in the frame's minute zone, at the instant plus the
+ *   shift, so its wall clock is the real local one. At a constant offset, arithmetic on the wall
+ *   clock is the same in any fixed-offset zone, and a day is always 24 hours. Its own
+ *   `epochNanoseconds`, `offset` and `timeZoneId` are not the real ones: turn a result back with
+ *   `frameInstant`, and never write it as a string.
+ * - Every value of one call is placed with the same frame, so all of them sit in one zone and
+ *   are off by the same shift. Comparing their `epochNanoseconds`, and `until` between them, give
+ *   what the real instants give.
+ * - Throws `RangeError` when the instant plus the shift is outside the instant range: within the
+ *   shift's length, under a minute, of the last instant for an offset east of UTC, and of the
+ *   first for one west. The caller returns its sentinel there, and its JSDoc says so. A function
+ *   that only reads fields uses `frameWallClock`, which has no such edge.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the zoned date-time to compute with
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).startOfDay(), zoneFrame("-00:44:30")).toString() // "1970-01-01T00:44:30Z"
+ */
+export declare function frameZoned(instant: Temporal.Instant, frame: ZoneFrame): Temporal.ZonedDateTime;
+/**
+ * The real epoch nanoseconds of a value `frameZoned` produced, or one computed from it.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns epoch nanoseconds of the instant it names
+ *
+ * @example frameEpochNanoseconds(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")) // 45870000000000n
+ */
+export declare function frameEpochNanoseconds(zoned: Temporal.ZonedDateTime, frame: ZoneFrame): bigint;
+/**
+ * The real instant of a value `frameZoned` produced, or one computed from it.
+ *
+ * Throws `RangeError` when the instant is outside Temporal's range; callers wrap it in their own
+ * try/catch.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns the instant it names
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export declare function frameInstant(zoned: Temporal.ZonedDateTime, frame: ZoneFrame): Temporal.Instant;
+/**
+ * A frame's stored offset as text: `±HH:MM:SS` for a seconds offset.
+ *
+ * Throws `RangeError` for a frame with no shift, whose offset is its zone's to give; callers wrap
+ * it in their own try/catch.
+ *
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the offset string
+ *
+ * @example frameOffset(zoneFrame("-00:44:30")) // "-00:44:30"
+ */
+export declare function frameOffset(frame: ZoneFrame): string;
+/**
+ * The instant a local wall time names at a frame's stored offset.
+ *
+ * The wall time and the offset are joined into one date-time string and read by Temporal, which
+ * reads an offset with seconds there (TC39 Temporal §13.31,
+ * `DateTimeUTCOffset[Z] ::: [+Z] UTCDesignator | UTCOffset[+SubMinutePrecision]`). A fixed offset has no
+ * transition, so the wall time is never repeated or skipped and there is nothing to disambiguate.
+ * Exact up to both limits of the instant range.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param wallClock an ISO 8601 `<date>T<time>` body with no offset and no annotation
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the instant
+ *
+ * @example instantOfWallClock("1970-01-01T12:00:00", zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export declare function instantOfWallClock(wallClock: string, frame: ZoneFrame): Temporal.Instant;

package/dist/internal/zoneFrame.js

@@ -0,0 +1,221 @@
+import { Temporal } from "./temporal.js";
+import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
+import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+import { instantFrom } from "./instantNanoseconds.js";
+import { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
+import { wallClockAtOffset } from "./wallClockAtOffset.js";
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/**
+ * Read a time zone argument that may also be a stored UTC offset.
+ *
+ * The only place that turns "time zone identifier or stored offset" into something Temporal can
+ * use. It accepts exactly what `isValidTimeZone` or `isValidUtcOffset` accepts, by five rules in
+ * order:
+ *
+ * 1. Not a string: null.
+ * 2. A time zone identifier (`isValidTimeZone`): that identifier as written, no shift. Every
+ *    argument that was valid before stored offsets were read takes this branch.
+ * 3. Not a stored offset (`±HH:MM[:SS]`): null.
+ * 4. A whole number of minutes (`+05:30:00`): the identifier it canonicalises to (`+05:30`), no
+ *    shift.
+ * 5. Otherwise (`-00:44:30`): the offset's whole minutes as the zone (`-00:44`), shifted by its
+ *    seconds with the offset's own sign (30 seconds further west).
+ *
+ * - The returned `timeZone` is always a time zone identifier, so it is safe in a bracket or in
+ *   `Intl.DateTimeFormat`. A seconds offset never becomes one: a caller that writes the zone into
+ *   its result validates with `isValidTimeZone` instead and does not call this.
+ *
+ * @param zone the caller's time zone argument
+ * @returns the frame, or null when `zone` is neither a time zone identifier nor a stored offset
+ *
+ * @example zoneFrame("Asia/Kolkata") // { timeZone: "Asia/Kolkata", shiftNanoseconds: 0n }
+ * @example zoneFrame("+05:30:00") // { timeZone: "+05:30", shiftNanoseconds: 0n }
+ * @example zoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example zoneFrame("Z") // null
+ */
+export function zoneFrame(zone) {
+    if (typeof zone !== "string") {
+        return null;
+    }
+    if (isValidTimeZone(zone)) {
+        return { timeZone: zone, shiftNanoseconds: 0n };
+    }
+    const offsetNanoseconds = parseUtcOffsetNanoseconds(zone);
+    if (offsetNanoseconds === null) {
+        return null;
+    }
+    // BigInt remainder keeps the dividend's sign, so this is the offset's seconds with its sign,
+    // and what is left is its whole minutes: the minute offset between it and zero.
+    const shiftNanoseconds = offsetNanoseconds % NANOSECONDS_PER_MINUTE;
+    const timeZone = formatUtcOffset(offsetNanoseconds - shiftNanoseconds);
+    return timeZone === null ? null : { timeZone, shiftNanoseconds };
+}
+/** The real offset of a frame with a shift: its minute zone's offset plus the shift. */
+function frameOffsetNanoseconds(frame) {
+    // The zone of a shifted frame is one `zoneFrame` wrote with `formatUtcOffset`, so it reads back.
+    const zoneOffset = parseUtcOffsetNanoseconds(frame.timeZone);
+    if (frame.shiftNanoseconds === 0n || zoneOffset === null) {
+        throw new RangeError("the frame carries no stored offset");
+    }
+    return zoneOffset + frame.shiftNanoseconds;
+}
+/**
+ * Read the `timeZone` option of a `unix/` or `utc/` function whose result names no zone.
+ *
+ * - Omitted (`undefined`) is `"UTC"`: an epoch and a UTC string name an instant, so no host zone
+ *   is read unless asked for.
+ * - `"local"` is the system time zone, or null when the host reports none that is valid.
+ * - Anything else is read by `zoneFrame`.
+ *
+ * `normalizeTimeZone` is the twin for a function that writes the zone into its result or hands it
+ * to `Intl.DateTimeFormat`: it accepts a time zone identifier only.
+ *
+ * @param option the caller's `timeZone` option
+ * @returns the frame, or null when the option is invalid
+ *
+ * @example normalizeZoneFrame(undefined) // { timeZone: "UTC", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("local") // the system zone, e.g. { timeZone: "Asia/Tokyo", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example normalizeZoneFrame("Asia/Tokio") // null
+ */
+export function normalizeZoneFrame(option) {
+    if (option === undefined) {
+        return { timeZone: "UTC", shiftNanoseconds: 0n };
+    }
+    return zoneFrame(option === "local" ? getSystemTimeZone() : option);
+}
+/**
+ * Read an instant on a frame's local wall clock. For a function that only reads fields.
+ *
+ * - A seconds offset is read with `wallClockAtOffset`, which is exact up to both limits of the
+ *   instant range; `frameZoned` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock
+ *
+ * @example frameWallClock(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:00:00"
+ */
+export function frameWallClock(instant, frame) {
+    return frame.shiftNanoseconds === 0n
+        ? instant.toZonedDateTimeISO(frame.timeZone).toPlainDateTime()
+        : wallClockAtOffset(instant, frameOffsetNanoseconds(frame));
+}
+/**
+ * Read the current instant on a frame's local wall clock.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock now
+ *
+ * @example frameNowWallClock(zoneFrame("-00:44:30")).toPlainDate().toString() // today's date at -00:44:30
+ */
+export function frameNowWallClock(frame) {
+    return frame.shiftNanoseconds === 0n
+        ? Temporal.Now.zonedDateTimeISO(frame.timeZone).toPlainDateTime()
+        : wallClockAtOffset(Temporal.Now.instant(), frameOffsetNanoseconds(frame));
+}
+/**
+ * Place an instant on a frame's local clock as a `Temporal.ZonedDateTime`, for a body that does
+ * arithmetic on one.
+ *
+ * - For a seconds offset the value sits in the frame's minute zone, at the instant plus the
+ *   shift, so its wall clock is the real local one. At a constant offset, arithmetic on the wall
+ *   clock is the same in any fixed-offset zone, and a day is always 24 hours. Its own
+ *   `epochNanoseconds`, `offset` and `timeZoneId` are not the real ones: turn a result back with
+ *   `frameInstant`, and never write it as a string.
+ * - Every value of one call is placed with the same frame, so all of them sit in one zone and
+ *   are off by the same shift. Comparing their `epochNanoseconds`, and `until` between them, give
+ *   what the real instants give.
+ * - Throws `RangeError` when the instant plus the shift is outside the instant range: within the
+ *   shift's length, under a minute, of the last instant for an offset east of UTC, and of the
+ *   first for one west. The caller returns its sentinel there, and its JSDoc says so. A function
+ *   that only reads fields uses `frameWallClock`, which has no such edge.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the zoned date-time to compute with
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).startOfDay(), zoneFrame("-00:44:30")).toString() // "1970-01-01T00:44:30Z"
+ */
+export function frameZoned(instant, frame) {
+    return frame.shiftNanoseconds === 0n
+        ? instant.toZonedDateTimeISO(frame.timeZone)
+        : instant
+            .add({ nanoseconds: Number(frame.shiftNanoseconds) })
+            .toZonedDateTimeISO(frame.timeZone);
+}
+/**
+ * The real epoch nanoseconds of a value `frameZoned` produced, or one computed from it.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns epoch nanoseconds of the instant it names
+ *
+ * @example frameEpochNanoseconds(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")) // 45870000000000n
+ */
+export function frameEpochNanoseconds(zoned, frame) {
+    // The value was placed the shift later than its instant, so that the minute zone's wall clock
+    // is the real local one: local time = instant + offset (TC39 Temporal GetISODateTimeFor).
+    return zoned.epochNanoseconds - frame.shiftNanoseconds;
+}
+/**
+ * The real instant of a value `frameZoned` produced, or one computed from it.
+ *
+ * Throws `RangeError` when the instant is outside Temporal's range; callers wrap it in their own
+ * try/catch.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns the instant it names
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export function frameInstant(zoned, frame) {
+    return frame.shiftNanoseconds === 0n
+        ? zoned.toInstant()
+        : Temporal.Instant.fromEpochNanoseconds(frameEpochNanoseconds(zoned, frame));
+}
+/**
+ * A frame's stored offset as text: `±HH:MM:SS` for a seconds offset.
+ *
+ * Throws `RangeError` for a frame with no shift, whose offset is its zone's to give; callers wrap
+ * it in their own try/catch.
+ *
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the offset string
+ *
+ * @example frameOffset(zoneFrame("-00:44:30")) // "-00:44:30"
+ */
+export function frameOffset(frame) {
+    const offset = formatUtcOffset(frameOffsetNanoseconds(frame));
+    if (offset === null) {
+        throw new RangeError("the frame carries no stored offset");
+    }
+    return offset;
+}
+/**
+ * The instant a local wall time names at a frame's stored offset.
+ *
+ * The wall time and the offset are joined into one date-time string and read by Temporal, which
+ * reads an offset with seconds there (TC39 Temporal §13.31,
+ * `DateTimeUTCOffset[Z] ::: [+Z] UTCDesignator | UTCOffset[+SubMinutePrecision]`). A fixed offset has no
+ * transition, so the wall time is never repeated or skipped and there is nothing to disambiguate.
+ * Exact up to both limits of the instant range.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param wallClock an ISO 8601 `<date>T<time>` body with no offset and no annotation
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the instant
+ *
+ * @example instantOfWallClock("1970-01-01T12:00:00", zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export function instantOfWallClock(wallClock, frame) {
+    return instantFrom(`${wallClock}${frameOffset(frame)}`);
+}

package/dist/internal/zonedBucket.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import type { DateTimeUnit } from "../types/index.js";
 /**
  * ISO day-of-week a week starts on: 1 = Monday .. 7 = Sunday, as `Temporal`'s `dayOfWeek` reads.
@@ -59,7 +59,7 @@ export declare function nextZonedBucketStart(current: Temporal.ZonedDateTime, un
  * next bucket starts.
  *
  * - Never earlier than `zoned`, because it is measured from the real bucket `zoned` is in —
- *   New York's second 01:00 hour on a fall-back morning ends at 01:59:59.999999999 −05:00, not
+ *   London's second 01:00 hour on a fall-back morning ends at 01:59:59.999999999 +00:00, not
  *   at the first pass's.
  * - Walks forward from `zoned` itself, never from its bucket's start. No transition between that
  *   start and `zoned` opens a bucket, so both walks reach the same next start — but the start may

package/dist/internal/zonedBucket.js

@@ -1,6 +1,10 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { DURATION_FIELD_BY_UNIT, getUnitSpan } from "./intervalCountHelpers.js";
 import { calendarDateAdd, calendarDateFromFields, calendarDateUntil, calendarFieldsOf, isCalendarArithmeticCompatNeeded, } from "./temporalCompat/index.js";
+import { floorDivide } from "./floorDivide.js";
+import { NANOSECONDS_PER_DAY } from "./foreignEpochs.js";
+import { ISO_WEEKDAYS, isoFieldsOf, isoWeekdayOf } from "./epochDay.js";
+import { offsetTimeline } from "./offsetTimeline.js";
 import { zonedNextTransition, zonedPreviousTransition, } from "./zonedWallClockOperations.js";
 /** The `Temporal.Duration` that advances a wall clock by one `unit`. */
 function oneUnit(unit) {
@@ -199,7 +203,7 @@ const DATE_LABELLED_UNITS = new Set([
  *   so the 03:00 hour begins at the transition even though the clock does not read 03:00:00; a
  *   local day whose midnight is skipped begins at 01:00 the same way; and `America/Goose_Bay`'s
  *   2010-11-07 fall-back re-enters 6 November, so that 59-minute stretch is its own day.
- * - **The clock lands on a unit boundary** — hours and smaller only. New York goes back to
+ * - **The clock lands on a unit boundary** — hours and smaller only. London goes back to
  *   01:00:00 exactly, so a second, separate 01:00 hour begins there — which is why a fall-back
  *   day has 25 hour buckets. `Australia/Lord_Howe` goes back to 01:30, mid-hour, so the hour it
  *   is already in simply runs longer: 90 minutes.
@@ -349,7 +353,7 @@ export function nextZonedBucketStart(current, unit, weekStartsOn = 1) {
  * next bucket starts.
  *
  * - Never earlier than `zoned`, because it is measured from the real bucket `zoned` is in —
- *   New York's second 01:00 hour on a fall-back morning ends at 01:59:59.999999999 −05:00, not
+ *   London's second 01:00 hour on a fall-back morning ends at 01:59:59.999999999 +00:00, not
  *   at the first pass's.
  * - Walks forward from `zoned` itself, never from its bucket's start. No transition between that
  *   start and `zoned` opens a bucket, so both walks reach the same next start — but the start may
@@ -384,6 +388,70 @@ function countFromBucketBeforeRange(start, end, unit, weekStartsOn) {
     const rest = countZonedBuckets(next, end, unit, weekStartsOn);
     return rest === null ? null : rest + 1;
 }
+/** Nanoseconds in each unit below a day. */
+const SUB_DAY_NANOSECONDS = {
+    hour: 3600000000000n,
+    minute: 60000000000n,
+    second: 1000000000n,
+    millisecond: 1000000n,
+    microsecond: 1000n,
+    nanosecond: 1n,
+};
+/**
+ * Which bucket a wall clock (nanoseconds, read as UTC) falls in, as an integer that rises by one
+ * per bucket: the unit's count since the epoch, so a difference is the whole units between two
+ * labels. Months and years are ISO; a calendar period of another calendar has no integer form.
+ */
+function bucketIndexOf(unit, weekStartsOn) {
+    const fixed = SUB_DAY_NANOSECONDS[unit];
+    if (fixed !== undefined) {
+        return (wall) => floorDivide(wall, fixed);
+    }
+    if (unit === "day") {
+        return (wall) => floorDivide(wall, NANOSECONDS_PER_DAY);
+    }
+    if (unit === "week") {
+        // Every week start falls on the same weekday, so `(start - anchor) / 7` is whole.
+        const anchor = -((isoWeekdayOf(0) - weekStartsOn + ISO_WEEKDAYS) %
+            ISO_WEEKDAYS);
+        return (wall) => {
+            const day = Number(floorDivide(wall, NANOSECONDS_PER_DAY));
+            const weekStart = day -
+                ((isoWeekdayOf(day) - weekStartsOn + ISO_WEEKDAYS) % ISO_WEEKDAYS);
+            return BigInt((weekStart - anchor) / ISO_WEEKDAYS);
+        };
+    }
+    return (wall) => {
+        const [year, month] = isoFieldsOf(Number(floorDivide(wall, NANOSECONDS_PER_DAY)));
+        return BigInt(unit === "year" ? year : year * 12 + month - 1);
+    };
+}
+/**
+ * The two questions `countZonedBuckets` asks of an offset change, in integers where the unit
+ * allows: whether a change opens a bucket (`startsNewBucketAt`'s rule), and how many whole units
+ * lie between the buckets two instants fall in. A month or year of a non-ISO calendar asks
+ * Temporal, and only at a change that crosses a date.
+ */
+function bucketWalker(start, unit, weekStartsOn) {
+    const sinceMidnight = (wall) => floorDivide(wall, NANOSECONDS_PER_DAY);
+    if (start.calendarId !== "iso8601" && (unit === "month" || unit === "year")) {
+        const zonedAt = (ns) => new Temporal.ZonedDateTime(ns, start.timeZoneId, start.calendarId);
+        const label = (ns) => truncateLocal(zonedAt(ns).toPlainDateTime(), unit, weekStartsOn);
+        return {
+            opensBucket: (transition, before, after) => sinceMidnight(transition - 1n + before) !==
+                sinceMidnight(transition + after) &&
+                startsNewBucketAt(zonedAt(transition), unit, weekStartsOn),
+            unitsBetween: (fromNs, _fromOffset, toNs) => getUnitSpan(truncatedWallClockUntil(label(fromNs), label(toNs), unit), unit),
+        };
+    }
+    const index = bucketIndexOf(unit, weekStartsOn);
+    const length = SUB_DAY_NANOSECONDS[unit];
+    return {
+        opensBucket: (transition, before, after) => index(transition - 1n + before) !== index(transition + after) ||
+            (length !== undefined && (transition + after) % length === 0n),
+        unitsBetween: (fromNs, fromOffset, toNs, toOffset) => Number(index(toNs + toOffset) - index(fromNs + fromOffset)),
+    };
+}
 /**
  * Count the local `unit` buckets the half-open interval `[start, end)` touches, in `start`'s
  * zone and calendar. `end` must already be expressed in both.
@@ -417,27 +485,30 @@ export function countZonedBuckets(start, end, unit, weekStartsOn = 1) {
     const startOfEnd = zonedUnitStart(end, unit, weekStartsOn);
     if (!startOfStart || !startOfEnd)
         return null;
-    const label = (zoned) => truncateLocal(zoned.toPlainDateTime(), unit, weekStartsOn);
-    // Whole `unit`s between two wall clocks already truncated to `unit`.
-    const unitsBetween = (from, to) => getUnitSpan(truncatedWallClockUntil(from, to, unit), unit);
-    const reachesIntoEndBucket = Temporal.ZonedDateTime.compare(startOfEnd, end) === 0 ? 0 : 1;
+    const timeline = offsetTimeline({ timeZone: start.timeZoneId, shiftNanoseconds: 0n }, startOfStart.epochNanoseconds, startOfEnd.epochNanoseconds, MAX_COUNTED_TRANSITIONS - 1);
+    if (timeline === null)
+        return null;
+    const { changes, offsets } = timeline;
+    const walker = bucketWalker(start, unit, weekStartsOn);
+    const endNs = startOfEnd.epochNanoseconds;
+    const reachesIntoEndBucket = startOfEnd.epochNanoseconds === end.epochNanoseconds ? 0 : 1;
     let spanned = 0;
-    let runStart = startOfStart;
-    let cursor = startOfStart;
-    for (let i = 0; i < MAX_COUNTED_TRANSITIONS; i++) {
-        const transition = zonedNextTransition(cursor, startOfEnd.epochNanoseconds)?.withCalendar(start.calendarId) ?? null;
-        if (!transition ||
-            Temporal.ZonedDateTime.compare(transition, startOfEnd) > 0) {
-            return (spanned +
-                unitsBetween(label(runStart), label(startOfEnd)) +
-                reachesIntoEndBucket);
-        }
-        if (startsNewBucketAt(transition, unit, weekStartsOn)) {
+    let runStart = startOfStart.epochNanoseconds;
+    let runStartOffset = offsets[0];
+    let runOffset = offsets[0];
+    // One pass over the offset changes in the span, which the cap above bounds.
+    for (let index = 0; index < changes.length; index++) {
+        const transition = changes[index];
+        const after = offsets[index + 1];
+        if (walker.opensBucket(transition, runOffset, after)) {
             spanned +=
-                unitsBetween(label(runStart), label(transition.subtract({ nanoseconds: 1 }))) + 1;
+                walker.unitsBetween(runStart, runStartOffset, transition - 1n, runOffset) + 1;
             runStart = transition;
+            runStartOffset = after;
         }
-        cursor = transition;
+        runOffset = after;
     }
-    return null;
+    return (spanned +
+        walker.unitsBetween(runStart, runStartOffset, endNs, runOffset) +
+        reachesIntoEndBucket);
 }

package/dist/internal/zonedFormatReference.d.ts

@@ -5,7 +5,7 @@
  *
  * @param reference the option as given
  * @returns false for a string of neither form, a non-finite number, or a value of another type
- * @example isValidZonedFormatReference("2024-03-15T09:00:00-04:00[America/New_York]") // true
+ * @example isValidZonedFormatReference("2024-03-15T09:00:00+09:00[Asia/Tokyo]") // true
  * @example isValidZonedFormatReference("2024-03-15T13:00:00Z") // true
  * @example isValidZonedFormatReference(undefined) // true
  * @example isValidZonedFormatReference(Number.NaN) // false

package/dist/internal/zonedFormatReference.js

@@ -7,7 +7,7 @@ import { isValidZonedDateTime } from "../zoned/validate/isValidZonedDateTime.js"
  *
  * @param reference the option as given
  * @returns false for a string of neither form, a non-finite number, or a value of another type
- * @example isValidZonedFormatReference("2024-03-15T09:00:00-04:00[America/New_York]") // true
+ * @example isValidZonedFormatReference("2024-03-15T09:00:00+09:00[Asia/Tokyo]") // true
  * @example isValidZonedFormatReference("2024-03-15T13:00:00Z") // true
  * @example isValidZonedFormatReference(undefined) // true
  * @example isValidZonedFormatReference(Number.NaN) // false

package/dist/internal/zonedLocalDates.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * 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`.