@northguild/gmt 1.19.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/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,4 +1,4 @@
-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.

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

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

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

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

package/dist/internal/utcWallClock.js

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

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.js

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

package/dist/internal/zoneBucketCap.d.ts

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

package/dist/internal/zoneBucketCap.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+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
@@ -48,7 +48,7 @@ export function certainlyTouchesMoreBuckets(startZoned, endZoned, unit, max) {
     let backwardNs = 0n;
     let transitions = 0;
     try {
-        for (let current = startZoned, next = zonedNextTransition(current); next !== null && next.epochNanoseconds < prefixEndNs; current = next, next = zonedNextTransition(current)) {
+        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;
             }

package/dist/internal/zoneFrame.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+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.
@@ -47,7 +47,7 @@ export type ZoneFrame = {
  * @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("America/New_York") // { timeZone: "America/New_York", shiftNanoseconds: 0n }
+ * @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
@@ -68,9 +68,9 @@ export declare function zoneFrame(zone: unknown): ZoneFrame | null;
  * @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: "America/New_York", 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("America/New_Yrok") // null
+ * @example normalizeZoneFrame("Asia/Tokio") // null
  */
 export declare function normalizeZoneFrame(option?: unknown): ZoneFrame | null;
 /**

package/dist/internal/zoneFrame.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
 import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
 import { instantFrom } from "./instantNanoseconds.js";
@@ -28,7 +28,7 @@ const NANOSECONDS_PER_MINUTE = 60000000000n;
  * @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("America/New_York") // { timeZone: "America/New_York", shiftNanoseconds: 0n }
+ * @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
@@ -74,9 +74,9 @@ function frameOffsetNanoseconds(frame) {
  * @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: "America/New_York", 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("America/New_Yrok") // null
+ * @example normalizeZoneFrame("Asia/Tokio") // null
  */
 export function normalizeZoneFrame(option) {
     if (option === undefined) {

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`.