@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/utcZonedDateTime.js

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../utc/validate/isValidUtc.js";
+import { resolveReadingTimeZone } from "./resolveReadingTimeZone.js";
+/**
+ * Read a UTC ISO string as a zoned date-time for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone` (UTC when omitted). The utc twin of
+ * `unixZonedDateTime`.
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the zoned date-time, or null when the value or the zone is invalid
+ * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00+09:00[Asia/Tokyo]"
+ * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcZonedDateTime("2024-03-15T14:30:00") // null (no Z)
+ */
+export function utcZonedDateTime(value, options) {
+    if (!isValidUtc(value))
+        return null;
+    const timeZone = resolveReadingTimeZone(options?.timeZone);
+    if (timeZone === null)
+        return null;
+    try {
+        return Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/wallClockAtOffset.d.ts

@@ -0,0 +1,22 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * The wall clock an instant reads at a fixed UTC offset, including a sub-minute or fractional
+ * one. Callers write the offset text themselves.
+ *
+ * The shift happens on the wall clock, never on the instant: a `PlainDateTime` reaches a day
+ * further either side than an `Instant` does (TC39 `ISODateTimeWithinLimits` against
+ * `IsValidEpochNanoseconds`), so shifting the instant first would reject the last 14 hours of
+ * the representable range, where `+275760-09-13T00:00:00Z` at `+14:00` names a local time that
+ * exists. No offset time zone is built either: Temporal's offset time-zone identifiers are
+ * minute precision, and an offset such as `-00:44:30` or `+05:30:15.25` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param offsetNanoseconds UTC offset in nanoseconds, east positive
+ * @returns the local wall clock at that offset
+ *
+ * @example wallClockAtOffset(Temporal.Instant.from("1970-01-01T00:00:00Z"), -2_670_000_000_000n).toString() // "1969-12-31T23:15:30"
+ * @example wallClockAtOffset(Temporal.Instant.from("+275760-09-13T00:00:00Z"), 50_400_000_000_000n).toString() // "+275760-09-13T14:00:00"
+ */
+export declare function wallClockAtOffset(instant: Temporal.Instant, offsetNanoseconds: bigint): Temporal.PlainDateTime;

package/dist/internal/wallClockAtOffset.js

@@ -0,0 +1,26 @@
+/**
+ * The wall clock an instant reads at a fixed UTC offset, including a sub-minute or fractional
+ * one. Callers write the offset text themselves.
+ *
+ * The shift happens on the wall clock, never on the instant: a `PlainDateTime` reaches a day
+ * further either side than an `Instant` does (TC39 `ISODateTimeWithinLimits` against
+ * `IsValidEpochNanoseconds`), so shifting the instant first would reject the last 14 hours of
+ * the representable range, where `+275760-09-13T00:00:00Z` at `+14:00` names a local time that
+ * exists. No offset time zone is built either: Temporal's offset time-zone identifiers are
+ * minute precision, and an offset such as `-00:44:30` or `+05:30:15.25` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param offsetNanoseconds UTC offset in nanoseconds, east positive
+ * @returns the local wall clock at that offset
+ *
+ * @example wallClockAtOffset(Temporal.Instant.from("1970-01-01T00:00:00Z"), -2_670_000_000_000n).toString() // "1969-12-31T23:15:30"
+ * @example wallClockAtOffset(Temporal.Instant.from("+275760-09-13T00:00:00Z"), 50_400_000_000_000n).toString() // "+275760-09-13T14:00:00"
+ */
+export function wallClockAtOffset(instant, offsetNanoseconds) {
+    return instant
+        .toZonedDateTimeISO("UTC")
+        .toPlainDateTime()
+        .add({ nanoseconds: Number(offsetNanoseconds) });
+}

package/dist/internal/zonedBucket.d.ts

@@ -0,0 +1,91 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeUnit } from "../types/index.js";
+/**
+ * ISO day-of-week a week starts on: 1 = Monday .. 7 = Sunday, as `Temporal`'s `dayOfWeek` reads.
+ */
+export type WeekStartDay = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/**
+ * Units the walker floors to: every `DateTimeUnit`, plus the calendar `quarter` (three local
+ * months starting January, April, July or October). Internal only — the public unit types stay
+ * unchanged.
+ */
+export type WalkerUnit = DateTimeUnit | "quarter";
+/**
+ * Return the instant the local `unit` containing `zoned` began — the bucket `zoned` falls in.
+ *
+ * A bucket is the run of instants sharing `zoned`'s local label *without interruption*, so
+ * this walks back from `zoned` to where that run started. Re-resolving a truncated wall clock
+ * cannot do the job, because truncation can land on a local time the zone never had and
+ * Temporal's "compatible" disambiguation then relocates it:
+ *
+ * - **A gap pushes the boundary past the instant being floored.** `Pacific/Chatham` springs
+ *   forward 02:45 → 03:45, so local 03:00 never happens; truncating 03:45 to the hour and
+ *   resolving it lands fifteen minutes *after* the instant it was asked to floor.
+ *   `Antarctica/Casey`'s three-hour 2020 jump lands three hours after.
+ * - **A sub-hour fall-back answers with the wrong pass.** Chatham falls back 03:45 → 02:45,
+ *   so local 02:00 and local 03:00 each name two instants an hour and three quarters apart,
+ *   and "compatible" always picks the earlier — silently skipping a boundary.
+ *
+ * So the boundary is taken in `zoned`'s own offset, then extended back through any transition
+ * the bucket runs straight through. See `startsNewBucketAt` for which those are.
+ *
+ * - Handles every `DateTimeUnit` plus `quarter`. Sub-hour units need the same own-offset treatment, because
+ *   historic offsets carry seconds (`Africa/Monrovia` ran at −00:44:30 until 1972).
+ * - Weeks start on `weekStartsOn` (ISO day number, Monday by default).
+ * - Keeps `zoned`'s calendar, so a non-ISO month or year floors in that calendar.
+ * - Returns null if the walk-back is still inside transitions after `MAX_TRANSITION_WALKBACK`
+ *   of them, which no IANA zone comes close to. The last `start` reached at that point is
+ *   only a partial answer, and a bounded walk that runs out answers with the sentinel.
+ */
+export declare function zonedUnitStart(zoned: Temporal.ZonedDateTime, unit: WalkerUnit, weekStartsOn?: WeekStartDay): Temporal.ZonedDateTime | null;
+/**
+ * Return the start of the bucket following the one containing `current` (which need not be that
+ * bucket's start).
+ *
+ * Stepping a whole unit and re-flooring is wrong, because a bucket can be shorter than its
+ * unit and would be stepped straight over: `Pacific/Chatham`'s 02:45 → 03:45 spring-forward
+ * leaves a local 03:00 hour only fifteen minutes long. So this takes whichever comes first —
+ * the next boundary in the current offset, or a transition that opens a bucket of its own —
+ * and runs through any transition that does not.
+ *
+ * - Handles every `DateTimeUnit` plus `quarter`, weeks starting on `weekStartsOn` (Monday by default).
+ * - Returns null if neither is reachable within `MAX_TRANSITION_WALKBACK` transitions, which
+ *   no IANA zone comes close to.
+ * - Throws a RangeError when the next bucket starts after the last representable instant.
+ */
+export declare function nextZonedBucketStart(current: Temporal.ZonedDateTime, unit: WalkerUnit, weekStartsOn?: WeekStartDay): Temporal.ZonedDateTime | null;
+/**
+ * Return the last instant of the local `unit` containing `zoned`: one nanosecond before the
+ * 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
+ *   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
+ *   lie before the first representable instant (the month holding `-271821-04-20T00:00:00Z` began
+ *   on 1 April), while the end does not.
+ * - Returns null if the next bucket start cannot be found.
+ */
+export declare function zonedUnitEnd(zoned: Temporal.ZonedDateTime, unit: WalkerUnit, weekStartsOn?: WeekStartDay): Temporal.ZonedDateTime | null;
+/**
+ * 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.
+ *
+ * The count is the bucket `start` is in, plus every bucket that starts after it and at or
+ * before `end` — less one when `end` sits exactly on a bucket start, since the interval does
+ * not reach into that bucket. A calendar-unit difference between truncated endpoints gets
+ * transitions wrong both ways: Chatham's 15-minute 03:00 hour is a bucket the difference
+ * never sees, and Samoa's deleted 2011-12-30 is a day the difference counts anyway.
+ *
+ * - Between transitions the wall clock runs continuously, so buckets there are counted by the
+ *   whole-unit difference of their local labels.
+ * - A transition that does not open a bucket (see `startsNewBucketAt`) leaves the label
+ *   running on, so it changes nothing and is stepped over.
+ * - A transition that does open one closes the run before it and counts the new bucket.
+ * - A `start` whose bucket began before the first representable instant still counts that
+ *   bucket once.
+ * - Returns null if either endpoint's bucket cannot be found, or the span crosses more than
+ *   `MAX_COUNTED_TRANSITIONS` transitions.
+ */
+export declare function countZonedBuckets(start: Temporal.ZonedDateTime, end: Temporal.ZonedDateTime, unit: DateTimeUnit, weekStartsOn?: WeekStartDay): number | null;

package/dist/internal/zonedBucket.js

@@ -0,0 +1,441 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { DURATION_FIELD_BY_UNIT, getUnitSpan } from "./intervalCountHelpers.js";
+import { calendarDateAdd, calendarDateFromFields, calendarDateUntil, calendarFieldsOf, isCalendarArithmeticCompatNeeded, } from "./temporalCompat/index.js";
+import { zonedNextTransition, zonedPreviousTransition, } from "./zonedWallClockOperations.js";
+/** The `Temporal.Duration` that advances a wall clock by one `unit`. */
+function oneUnit(unit) {
+    return unit === "quarter"
+        ? { months: 3 }
+        : { [DURATION_FIELD_BY_UNIT[unit]]: 1 };
+}
+/** Wall-clock fields that a local day, week, month or year boundary resets. */
+const MIDNIGHT = {
+    hour: 0,
+    minute: 0,
+    second: 0,
+    millisecond: 0,
+    microsecond: 0,
+    nanosecond: 0,
+};
+/**
+ * Wall-clock fields each unit's boundary resets. `week` is computed from the week start, and
+ * `nanosecond` resets nothing, so neither is listed.
+ */
+const FIELDS_RESET_BY_UNIT = {
+    year: { month: 1, day: 1, ...MIDNIGHT },
+    month: { day: 1, ...MIDNIGHT },
+    day: MIDNIGHT,
+    hour: { minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 },
+    minute: { second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 },
+    second: { millisecond: 0, microsecond: 0, nanosecond: 0 },
+    millisecond: { microsecond: 0, nanosecond: 0 },
+    microsecond: { nanosecond: 0 },
+};
+/**
+ * Transitions walked over while sizing one bucket.
+ *
+ * Only transitions inside the bucket matter. No IANA zone has had more than two inside one
+ * local month, but `Africa/Cairo` had four inside local 2010 (DST, suspended for Ramadan, then
+ * resumed and ended), and the walk needs one step past the last of them to see it has left
+ * the bucket — so the bound sits comfortably above five.
+ */
+const MAX_TRANSITION_WALKBACK = 8;
+/**
+ * Truncate a wall clock to the start of its `unit`. Pure wall-clock arithmetic.
+ *
+ * Calendar-aware: `local` keeps its calendar, so a Hebrew month or year truncates to the
+ * Hebrew one.
+ */
+function truncateLocal(local, unit, weekStartsOn) {
+    if (unit === "nanosecond")
+        return local;
+    if (needsCalendarCompat(local)) {
+        return truncateLocalWithCompat(local, unit, weekStartsOn);
+    }
+    return truncateLocalInOwnCalendar(local, unit, weekStartsOn);
+}
+/**
+ * CORE-6: true when `local`'s calendar arithmetic needs the Temporal compat layer in this runtime.
+ * The polyfill's `with`, `add` and `until` are then wrong or throw on its wall clocks (D1–D7), so
+ * the walker builds calendar periods from corrected reads and does everything else in ISO.
+ */
+function needsCalendarCompat(local) {
+    return (local.calendarId !== "iso8601" &&
+        isCalendarArithmeticCompatNeeded(local.calendarId));
+}
+function isCalendarPeriod(unit) {
+    return unit === "year" || unit === "quarter" || unit === "month";
+}
+/** `truncateLocal` for a calendar that needs the compat layer. */
+function truncateLocalWithCompat(local, unit, weekStartsOn) {
+    if (isCalendarPeriod(unit)) {
+        const { year, month } = calendarFieldsOf(local.toPlainDate(), local.calendarId);
+        const startMonth = unit === "year"
+            ? 1
+            : unit === "quarter"
+                ? quarterStartMonth(month)
+                : month;
+        return calendarDateFromFields(local.calendarId, { year, month: startMonth, day: 1 }, "reject").toPlainDateTime();
+    }
+    // Weeks, days and time units do not depend on the calendar.
+    return truncateLocalInOwnCalendar(local.withCalendar("iso8601"), unit, weekStartsOn).withCalendar(local.calendarId);
+}
+/** The first month of the quarter holding ordinal `month` (1, 4, 7 or 10). */
+function quarterStartMonth(month) {
+    return Math.floor((month - 1) / 3) * 3 + 1;
+}
+/** `truncateLocal` through `local`'s own calendar operations. */
+function truncateLocalInOwnCalendar(local, unit, weekStartsOn) {
+    if (unit === "nanosecond")
+        return local;
+    if (unit === "quarter") {
+        return local.with({
+            month: Math.floor((local.month - 1) / 3) * 3 + 1,
+            day: 1,
+            ...MIDNIGHT,
+        });
+    }
+    if (unit === "week") {
+        return local
+            .subtract({ days: (local.dayOfWeek - weekStartsOn + 7) % 7 })
+            .with(MIDNIGHT);
+    }
+    return local.with(FIELDS_RESET_BY_UNIT[unit]);
+}
+/** The local `unit` label `zoned` carries — what the wall clock read, with no zone opinion. */
+function localUnitLabel(zoned, unit, weekStartsOn) {
+    return truncateLocal(zoned.toPlainDateTime(), unit, weekStartsOn).toString();
+}
+/** `instant` in `like`'s zone and calendar. `toZonedDateTimeISO` alone would drop the calendar. */
+function inZoneOf(instant, like) {
+    return instant
+        .toZonedDateTimeISO(like.timeZoneId)
+        .withCalendar(like.calendarId);
+}
+/**
+ * The `unit` boundary reached from `zoned` without leaving its own offset stretch.
+ *
+ * The wall clock says how far into the unit `zoned` sits; that distance is then subtracted as
+ * exact time, so the result keeps `zoned`'s offset instead of being re-resolved — which is
+ * what stops a repeated wall time from being answered with the wrong pass of it.
+ */
+function boundaryInOwnOffset(zoned, unit, weekStartsOn) {
+    const local = zoned.toPlainDateTime();
+    const elapsed = wallClockUntil(truncateLocal(local, unit, weekStartsOn), local, "hour");
+    return inZoneOf(zoned.toInstant().subtract(elapsed), zoned);
+}
+/**
+ * `from.until(to, { largestUnit })` between two wall clocks in one calendar. Hours and smaller
+ * never depend on the calendar, so a calendar that needs the compat layer measures them in ISO.
+ */
+function wallClockUntil(from, to, largestUnit) {
+    return needsCalendarCompat(from)
+        ? from
+            .withCalendar("iso8601")
+            .until(to.withCalendar("iso8601"), { largestUnit })
+        : from.until(to, { largestUnit });
+}
+/**
+ * `from.until(to, { largestUnit: unit })` between two wall clocks already truncated to `unit`. A
+ * calendar that needs the compat layer counts years and months with `calendarDateUntil` between
+ * the dates (both clocks sit at midnight on a period start) and every other unit in ISO.
+ */
+function truncatedWallClockUntil(from, to, unit) {
+    if (!needsCalendarCompat(from)) {
+        return from.until(to, { largestUnit: unit });
+    }
+    if (unit === "year" || unit === "month") {
+        return Temporal.Duration.from(calendarDateUntil(from.toPlainDate(), to.toPlainDate(), unit));
+    }
+    return from
+        .withCalendar("iso8601")
+        .until(to.withCalendar("iso8601"), { largestUnit: unit });
+}
+/**
+ * The most recent zone transition at or before `zoned`, or null if there is none.
+ *
+ * `getTimeZoneTransition("previous")` is strict, so a transition sitting exactly on `zoned` is
+ * missed by asking from `zoned` itself. Asking from a nanosecond later would find it, but throws at
+ * the last representable instant, so this never steps past `zoned`: the first transition after
+ * `zoned - 1 ns` is `zoned` itself exactly when a transition sits on it. At the first
+ * representable instant there is no `zoned - 1 ns`, and nothing earlier, so that check is skipped.
+ */
+function transitionAtOrBefore(zoned) {
+    try {
+        if (transitionSitsOn(zoned)) {
+            return zoned;
+        }
+        return zonedPreviousTransition(zoned);
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a zone transition happens exactly at `zoned`'s instant. */
+function transitionSitsOn(zoned) {
+    let justBefore;
+    try {
+        justBefore = zoned.subtract({ nanoseconds: 1 });
+    }
+    catch {
+        return false;
+    }
+    const next = zonedNextTransition(justBefore);
+    return next !== null && next.toInstant().equals(zoned.toInstant());
+}
+/** Units whose buckets are labelled by a local date: a repeated wall time inside one stays one bucket. */
+const DATE_LABELLED_UNITS = new Set([
+    "year",
+    "quarter",
+    "month",
+    "week",
+    "day",
+]);
+/**
+ * True when the local `unit` bucket restarts at `transition` rather than continuing through it.
+ *
+ * - **The label changes discontinuously** — every unit. `Pacific/Chatham` jumps 02:45 → 03:45,
+ *   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
+ *   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.
+ * - **Day and larger never reopen on the same label.** `America/Havana` fell back 01:00 → 00:00
+ *   on 2024-11-03: the clock lands on midnight, but the date is still 3 November, so that is one
+ *   25-hour day starting at the first 00:00 — matching Temporal's `startOfDay()` and `hoursInDay`.
+ */
+function startsNewBucketAt(transition, unit, weekStartsOn) {
+    const local = transition.toPlainDateTime();
+    if (!DATE_LABELLED_UNITS.has(unit) &&
+        truncateLocal(local, unit, weekStartsOn).equals(local)) {
+        return true;
+    }
+    try {
+        return (localUnitLabel(transition.subtract({ nanoseconds: 1 }), unit, weekStartsOn) !== localUnitLabel(transition, unit, weekStartsOn));
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Return the instant the local `unit` containing `zoned` began — the bucket `zoned` falls in.
+ *
+ * A bucket is the run of instants sharing `zoned`'s local label *without interruption*, so
+ * this walks back from `zoned` to where that run started. Re-resolving a truncated wall clock
+ * cannot do the job, because truncation can land on a local time the zone never had and
+ * Temporal's "compatible" disambiguation then relocates it:
+ *
+ * - **A gap pushes the boundary past the instant being floored.** `Pacific/Chatham` springs
+ *   forward 02:45 → 03:45, so local 03:00 never happens; truncating 03:45 to the hour and
+ *   resolving it lands fifteen minutes *after* the instant it was asked to floor.
+ *   `Antarctica/Casey`'s three-hour 2020 jump lands three hours after.
+ * - **A sub-hour fall-back answers with the wrong pass.** Chatham falls back 03:45 → 02:45,
+ *   so local 02:00 and local 03:00 each name two instants an hour and three quarters apart,
+ *   and "compatible" always picks the earlier — silently skipping a boundary.
+ *
+ * So the boundary is taken in `zoned`'s own offset, then extended back through any transition
+ * the bucket runs straight through. See `startsNewBucketAt` for which those are.
+ *
+ * - Handles every `DateTimeUnit` plus `quarter`. Sub-hour units need the same own-offset treatment, because
+ *   historic offsets carry seconds (`Africa/Monrovia` ran at −00:44:30 until 1972).
+ * - Weeks start on `weekStartsOn` (ISO day number, Monday by default).
+ * - Keeps `zoned`'s calendar, so a non-ISO month or year floors in that calendar.
+ * - Returns null if the walk-back is still inside transitions after `MAX_TRANSITION_WALKBACK`
+ *   of them, which no IANA zone comes close to. The last `start` reached at that point is
+ *   only a partial answer, and a bounded walk that runs out answers with the sentinel.
+ */
+export function zonedUnitStart(zoned, unit, weekStartsOn = 1) {
+    let start = boundaryInOwnOffset(zoned, unit, weekStartsOn);
+    let cursor = zoned;
+    for (let i = 0; i < MAX_TRANSITION_WALKBACK; i++) {
+        const transition = transitionAtOrBefore(cursor);
+        // A transition exactly on `start` is still checked: Havana's second 00:00 is a unit-aligned
+        // own-offset start that the day runs straight through.
+        if (!transition || Temporal.ZonedDateTime.compare(transition, start) < 0) {
+            return start;
+        }
+        if (startsNewBucketAt(transition, unit, weekStartsOn))
+            return transition;
+        // The bucket runs through this transition, so it reaches into the older offset.
+        const justBefore = transition.subtract({ nanoseconds: 1 });
+        start = boundaryInOwnOffset(justBefore, unit, weekStartsOn);
+        cursor = justBefore;
+    }
+    return null;
+}
+/**
+ * The next `unit` boundary after `zoned`, reached without leaving its own offset stretch.
+ */
+function nextBoundaryInOwnOffset(zoned, unit, weekStartsOn) {
+    const local = zoned.toPlainDateTime();
+    // Step first, then truncate: the current unit's start may lie before the representable range,
+    // while the next unit's start does not. Both orders give the same boundary, because a one-unit
+    // step clamps within the next unit (Jan 31 + 1 month = Feb 29, whose month starts on Feb 1).
+    const remaining = wallClockUntil(local, truncateLocal(addOneUnit(local, unit), unit, weekStartsOn), "hour");
+    return inZoneOf(zoned.toInstant().add(remaining), zoned);
+}
+/**
+ * `nextBoundaryInOwnOffset`, or null when that boundary lies past Temporal's last representable
+ * instant — a transition before it may still open a representable bucket.
+ */
+function nextBoundaryWithinRange(zoned, unit, weekStartsOn) {
+    try {
+        return nextBoundaryInOwnOffset(zoned, unit, weekStartsOn);
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            return null;
+        throw error;
+    }
+}
+/**
+ * `local.add(oneUnit(unit))`. For a calendar that needs the compat layer, a calendar period steps
+ * through `calendarDateAdd` (constrained, keeping the time of day) and every other unit in ISO.
+ */
+function addOneUnit(local, unit) {
+    if (!needsCalendarCompat(local)) {
+        return local.add(oneUnit(unit));
+    }
+    if (isCalendarPeriod(unit)) {
+        return calendarDateAdd(local.toPlainDate(), unit === "year" ? { years: 1 } : { months: unit === "quarter" ? 3 : 1 }, "constrain").toPlainDateTime(local.toPlainTime());
+    }
+    return local
+        .withCalendar("iso8601")
+        .add(oneUnit(unit))
+        .withCalendar(local.calendarId);
+}
+/**
+ * Return the start of the bucket following the one containing `current` (which need not be that
+ * bucket's start).
+ *
+ * Stepping a whole unit and re-flooring is wrong, because a bucket can be shorter than its
+ * unit and would be stepped straight over: `Pacific/Chatham`'s 02:45 → 03:45 spring-forward
+ * leaves a local 03:00 hour only fifteen minutes long. So this takes whichever comes first —
+ * the next boundary in the current offset, or a transition that opens a bucket of its own —
+ * and runs through any transition that does not.
+ *
+ * - Handles every `DateTimeUnit` plus `quarter`, weeks starting on `weekStartsOn` (Monday by default).
+ * - Returns null if neither is reachable within `MAX_TRANSITION_WALKBACK` transitions, which
+ *   no IANA zone comes close to.
+ * - Throws a RangeError when the next bucket starts after the last representable instant.
+ */
+export function nextZonedBucketStart(current, unit, weekStartsOn = 1) {
+    let cursor = current;
+    for (let i = 0; i < MAX_TRANSITION_WALKBACK; i++) {
+        const boundary = nextBoundaryWithinRange(cursor, unit, weekStartsOn);
+        const transition = zonedNextTransition(cursor);
+        if (!transition ||
+            (boundary !== null &&
+                Temporal.ZonedDateTime.compare(transition, boundary) > 0)) {
+            if (boundary === null) {
+                throw new RangeError("the next bucket starts after the last representable instant");
+            }
+            return boundary;
+        }
+        if (startsNewBucketAt(transition, unit, weekStartsOn)) {
+            return transition.withCalendar(current.calendarId);
+        }
+        // The bucket runs through this transition; measure the rest of it in the new offset.
+        cursor = transition.withCalendar(current.calendarId);
+    }
+    return null;
+}
+/**
+ * Return the last instant of the local `unit` containing `zoned`: one nanosecond before the
+ * 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
+ *   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
+ *   lie before the first representable instant (the month holding `-271821-04-20T00:00:00Z` began
+ *   on 1 April), while the end does not.
+ * - Returns null if the next bucket start cannot be found.
+ */
+export function zonedUnitEnd(zoned, unit, weekStartsOn = 1) {
+    const next = nextZonedBucketStart(zoned, unit, weekStartsOn);
+    return next ? next.subtract({ nanoseconds: 1 }) : null;
+}
+/**
+ * Transitions walked while counting buckets across a span.
+ *
+ * Counting visits every zone transition inside the span, never every bucket, so an hour count
+ * across centuries stays cheap. 10,000 transitions is roughly 5,000 years of twice-yearly
+ * daylight saving — past anything counted in one call — and keeps the worst case near a
+ * second; a longer walk answers with the sentinel rather than running unbounded.
+ */
+const MAX_COUNTED_TRANSITIONS = 10_000;
+/**
+ * `countZonedBuckets` when `start`'s bucket began before the first representable instant (the
+ * week, month or year holding `-271821-04-20T00:00:00Z`). `start` is then inside that bucket, not
+ * on its start, so the span touches it once, plus every bucket from the next start on.
+ */
+function countFromBucketBeforeRange(start, end, unit, weekStartsOn) {
+    const next = nextZonedBucketStart(start, unit, weekStartsOn);
+    if (!next)
+        return null;
+    if (Temporal.ZonedDateTime.compare(next, end) >= 0)
+        return 1;
+    const rest = countZonedBuckets(next, end, unit, weekStartsOn);
+    return rest === null ? null : rest + 1;
+}
+/**
+ * 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.
+ *
+ * The count is the bucket `start` is in, plus every bucket that starts after it and at or
+ * before `end` — less one when `end` sits exactly on a bucket start, since the interval does
+ * not reach into that bucket. A calendar-unit difference between truncated endpoints gets
+ * transitions wrong both ways: Chatham's 15-minute 03:00 hour is a bucket the difference
+ * never sees, and Samoa's deleted 2011-12-30 is a day the difference counts anyway.
+ *
+ * - Between transitions the wall clock runs continuously, so buckets there are counted by the
+ *   whole-unit difference of their local labels.
+ * - A transition that does not open a bucket (see `startsNewBucketAt`) leaves the label
+ *   running on, so it changes nothing and is stepped over.
+ * - A transition that does open one closes the run before it and counts the new bucket.
+ * - A `start` whose bucket began before the first representable instant still counts that
+ *   bucket once.
+ * - Returns null if either endpoint's bucket cannot be found, or the span crosses more than
+ *   `MAX_COUNTED_TRANSITIONS` transitions.
+ */
+export function countZonedBuckets(start, end, unit, weekStartsOn = 1) {
+    let startOfStart;
+    try {
+        startOfStart = zonedUnitStart(start, unit, weekStartsOn);
+    }
+    catch (error) {
+        if (!(error instanceof RangeError))
+            throw error;
+        return countFromBucketBeforeRange(start, end, unit, weekStartsOn);
+    }
+    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;
+    let spanned = 0;
+    let runStart = startOfStart;
+    let cursor = startOfStart;
+    for (let i = 0; i < MAX_COUNTED_TRANSITIONS; i++) {
+        const transition = zonedNextTransition(cursor)?.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)) {
+            spanned +=
+                unitsBetween(label(runStart), label(transition.subtract({ nanoseconds: 1 }))) + 1;
+            runStart = transition;
+        }
+        cursor = transition;
+    }
+    return null;
+}

package/dist/internal/zonedFormatReference.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether the `reference` option of the zoned formatters can be read: omitted (`undefined`), a
+ * zoned or UTC ISO string, or a finite epoch in milliseconds. Any other type — a boolean (which
+ * ToNumber would read as epoch 1 or 0), `null`, an object or a bigint — is invalid input.
+ *
+ * @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-15T13:00:00Z") // true
+ * @example isValidZonedFormatReference(undefined) // true
+ * @example isValidZonedFormatReference(Number.NaN) // false
+ * @example isValidZonedFormatReference("2024-03-15") // false
+ * @example isValidZonedFormatReference(true) // false
+ */
+export declare function isValidZonedFormatReference(reference: unknown): boolean;

package/dist/internal/zonedFormatReference.js

@@ -0,0 +1,24 @@
+import { isValidUtc } from "../utc/validate/isValidUtc.js";
+import { isValidZonedDateTime } from "../zoned/validate/isValidZonedDateTime.js";
+/**
+ * Whether the `reference` option of the zoned formatters can be read: omitted (`undefined`), a
+ * zoned or UTC ISO string, or a finite epoch in milliseconds. Any other type — a boolean (which
+ * ToNumber would read as epoch 1 or 0), `null`, an object or a bigint — is invalid input.
+ *
+ * @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-15T13:00:00Z") // true
+ * @example isValidZonedFormatReference(undefined) // true
+ * @example isValidZonedFormatReference(Number.NaN) // false
+ * @example isValidZonedFormatReference("2024-03-15") // false
+ * @example isValidZonedFormatReference(true) // false
+ */
+export function isValidZonedFormatReference(reference) {
+    if (reference === undefined)
+        return true;
+    if (typeof reference === "string") {
+        return isValidZonedDateTime(reference) || isValidUtc(reference);
+    }
+    return typeof reference === "number" && Number.isFinite(reference);
+}

package/dist/internal/zonedLocalDates.d.ts

@@ -0,0 +1,15 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * 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`.
+ *
+ * Between two zone transitions the wall clock runs continuously, so every date from a run's
+ * first to its last instant is touched. A transition can jump the clock past a whole date
+ * (`Pacific/Apia` deleted 2011-12-30), which no instant then has, or back into the previous
+ * date (`America/Goose_Bay` at 00:01 on 2010-11-07), which is touched again but counted once.
+ *
+ * @param start the span start
+ * @param end the span end, in `start`'s zone
+ * @returns the number of distinct local dates, or null past `MAX_WALKED_TRANSITIONS` transitions
+ */
+export declare function countZonedLocalDates(start: Temporal.ZonedDateTime, end: Temporal.ZonedDateTime): number | null;