@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/zonedWallClockOperations.d.ts

@@ -0,0 +1,132 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset, Overflow } from "../types/index.js";
+type RoundingSmallestUnit = Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+interface ZonedRoundTo {
+    smallestUnit: RoundingSmallestUnit;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+}
+/**
+ * `PlainDate#toZonedDateTime(timeZone)` (start of day) or
+ * `PlainDateTime#toZonedDateTime(timeZone, { disambiguation })`, correct at the range limits and
+ * (start of day) before 1847.
+ *
+ * @param plain the date (resolved to its start of day) or date-time to place in `timeZone`
+ * @param timeZone IANA identifier, offset time zone, or RFC 9557 string carrying one
+ * @param disambiguation Temporal disambiguation for a PlainDateTime (ignored for a PlainDate)
+ * @returns the resolved Temporal.ZonedDateTime; throws where TC39 Temporal throws
+ */
+export declare function plainToZoned(plain: Temporal.PlainDate | Temporal.PlainDateTime, timeZone: string, disambiguation?: Disambiguation): Temporal.ZonedDateTime;
+/**
+ * `ZonedDateTime#startOfDay`, correct at the range limits and before 1847.
+ *
+ * @param zoned the value whose local day to start
+ * @returns the first valid wall-clock time of that day; throws where TC39 Temporal throws
+ */
+export declare function zonedStartOfDay(zoned: Temporal.ZonedDateTime): Temporal.ZonedDateTime;
+/**
+ * `ZonedDateTime#withPlainTime`, correct at the range limits and (start of day) before 1847.
+ *
+ * @param zoned the value whose local date to keep
+ * @param time the new wall-clock time; omitted means the start of the day
+ * @returns the resolved Temporal.ZonedDateTime; throws where TC39 Temporal throws
+ */
+export declare function zonedWithPlainTime(zoned: Temporal.ZonedDateTime, time?: Temporal.PlainTime | Temporal.PlainTimeLike | string): Temporal.ZonedDateTime;
+/**
+ * `ZonedDateTime#hoursInDay`, correct at the range limits and before 1847.
+ *
+ * @param zoned the value whose local day to measure
+ * @returns hours from this day's start to the next day's start; throws where TC39 Temporal throws
+ */
+export declare function zonedHoursInDay(zoned: Temporal.ZonedDateTime): number;
+/**
+ * `ZonedDateTime#getTimeZoneTransition("next")`, correct at the range limits and before 1847.
+ *
+ * - Before 1847-01-01 the polyfill never searches (defect 3), so a named zone whose offset there
+ *   differs from its offset at 1847-01-01 has its transition found by bisection first.
+ * - The polyfill's forward scan gives up once a two-week step would pass the maximum instant, so a
+ *   `null` within its three-year horizon of the maximum is re-checked by walking back from the
+ *   maximum with `getTimeZoneTransition("previous")`, which scans correctly there.
+ *
+ * @param zoned the instant to search after (exclusive)
+ * @returns the next transition, or null when there is none before the maximum instant
+ */
+export declare function zonedNextTransition(zoned: Temporal.ZonedDateTime): Temporal.ZonedDateTime | null;
+/**
+ * `ZonedDateTime#getTimeZoneTransition("previous")`, correct before 1847.
+ *
+ * The polyfill stops looking at 1847-01-01 (defect 3), so when it finds nothing in a named zone the
+ * span from the minimum instant to the floor is checked by comparing offsets and bisecting.
+ *
+ * @param zoned the instant to search before (exclusive)
+ * @returns the previous transition, or null when there is none
+ */
+export declare function zonedPreviousTransition(zoned: Temporal.ZonedDateTime): Temporal.ZonedDateTime | null;
+/**
+ * `ZonedDateTime#add`, correct at the range limits and in calendars the polyfill gets wrong.
+ *
+ * @param zoned the starting value
+ * @param duration the duration to add
+ * @param options Temporal `overflow` for the calendar part
+ * @returns the sum; throws where TC39 Temporal throws
+ */
+export declare function addToZoned(zoned: Temporal.ZonedDateTime, duration: Temporal.Duration | Temporal.DurationLike | string, options?: {
+    overflow?: Overflow;
+}): Temporal.ZonedDateTime;
+/**
+ * `ZonedDateTime#subtract`, correct at the range limits.
+ *
+ * @param zoned the starting value
+ * @param duration the duration to subtract
+ * @param options Temporal `overflow` for the calendar part
+ * @returns the difference; throws where TC39 Temporal throws
+ */
+export declare function subtractFromZoned(zoned: Temporal.ZonedDateTime, duration: Temporal.Duration | Temporal.DurationLike | string, options?: {
+    overflow?: Overflow;
+}): Temporal.ZonedDateTime;
+/**
+ * `addToZoned` / `subtractFromZoned` with a caller-chosen `disambiguation` for the intermediate
+ * wall-clock date-time — TC39 Temporal §6.5.5 AddZonedDateTime with the "compatible" argument of
+ * its `GetEpochNanosecondsFor` step replaced by `disambiguation`.
+ *
+ * - The date portion (years, months, weeks, days) is added to the wall-clock date, keeping the
+ *   wall-clock time. That intermediate date-time is resolved with `disambiguation` whenever it is
+ *   not a single instant: in a fall-back overlap "earlier"/"compatible" take the earlier instant and
+ *   "later" the later one; in a spring-forward gap "earlier" shifts it back by the gap length and
+ *   "later"/"compatible" forward (DisambiguatePossibleEpochNanoseconds); "reject" throws for both.
+ * - The time portion is then added in exact time and is never re-resolved.
+ * - With no date portion, the whole duration is exact time and `disambiguation` never applies.
+ *
+ * @param zoned the starting value
+ * @param duration the duration to add or subtract
+ * @param sign 1 to add, -1 to subtract
+ * @param options Temporal `overflow` for the calendar part and `disambiguation`
+ * @returns the result; throws where TC39 Temporal throws, or when "reject" meets a gap or overlap
+ */
+export declare function addToZonedDisambiguated(zoned: Temporal.ZonedDateTime, duration: Temporal.Duration | Temporal.DurationLike | string, sign: 1 | -1, options: {
+    overflow?: Overflow;
+    disambiguation: Disambiguation;
+}): Temporal.ZonedDateTime;
+interface ZonedWithOptions {
+    overflow?: Overflow;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}
+/**
+ * `ZonedDateTime#with`, correct at the range limits.
+ *
+ * @param zoned the value to change
+ * @param fields the date/time (and optional offset) fields to set
+ * @param options Temporal `overflow` / `disambiguation` / `offset` (default `"prefer"`)
+ * @returns the changed value; throws where TC39 Temporal throws
+ */
+export declare function withZonedFields(zoned: Temporal.ZonedDateTime, fields: Temporal.ZonedDateTimeLike, options?: ZonedWithOptions): Temporal.ZonedDateTime;
+/**
+ * `ZonedDateTime#round`, correct at the range limits and, by day, before 1847.
+ *
+ * @param zoned the value to round
+ * @param roundTo Temporal `smallestUnit` (day or smaller) / `roundingIncrement` / `roundingMode`
+ * @returns the rounded value; throws where TC39 Temporal throws
+ */
+export declare function roundZonedDateTime(zoned: Temporal.ZonedDateTime, roundTo: ZonedRoundTo): Temporal.ZonedDateTime;
+export {};

package/dist/internal/zonedWallClockOperations.js

@@ -0,0 +1,553 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { MAX_EPOCH_NANOSECONDS } from "./epochNanoseconds.js";
+import { calendarDateAdd, isCalendarArithmeticCompatNeeded, } from "./temporalCompat/index.js";
+import { epochNanosecondsFor, interpretISODateTimeOffset, isBeforePolyfillTransitionSearch, isNamedTimeZone, isNearRangeEdge, isValidEpoch, MAX_TRANSITIONS_BEFORE_MAXIMUM, missedNextTransition, missedPreviousTransition, NEXT_TRANSITION_HORIZON_NANOSECONDS, startOfDayEpochNanoseconds, timeZoneIdOf, utcOffsetStringNanoseconds, } from "./zonedWallClock.js";
+/*
+ * Polyfill-first wrappers for the Temporal operations that resolve a wall clock or a start of day
+ * inside `@js-temporal/polyfill` 0.5.1, and so inherit its range-limit defects. See the note at the
+ * top of `./zonedWallClock.ts` (defect 1: fixed on upstream main by 05ce7a3 at the maximum and
+ * 95237e0 at the minimum, both unreleased; defect 2 is unfixed upstream): each fallback is removed
+ * once a polyfill release fixing its defect at BOTH limits is GMT's dependency floor. 05ce7a3 alone
+ * never retires the defect-1 fallbacks, because the `zoned.A` canary's `min.*` probes still fail
+ * with it.
+ *
+ * Every wrapper returns the polyfill's own result whenever it has one, and re-throws the polyfill's
+ * own error unless the zone is a named, non-UTC zone and the wall clock being resolved lies within
+ * a month of either range limit — the only inputs either defect reaches.
+ *
+ * Defect 3 (the transition search floored at 1847-01-01) returns a wrong value instead of throwing,
+ * so the transition and start-of-day wrappers check for it first, and only for a named zone and an
+ * instant or local date before that floor (`needsOwnStartOfDay`); everything later goes straight to
+ * the polyfill. Retired with the `zoned.E` canary group.
+ */
+const NANOSECONDS_PER_HOUR = 3_600_000_000_000;
+const DISAMBIGUATION_PROBE = new Temporal.PlainDateTime(2000, 1, 1);
+/** An ISO date far from the limits, used only to validate an `overflow` option. */
+const OVERFLOW_PROBE = new Temporal.PlainDate(2000, 1, 1);
+/** Re-throws `error` unless `recover` computes a TC39 result (it returns null when out of scope). */
+function recoverAtRangeEdge(error, recover) {
+    const recovered = recover();
+    if (recovered === null) {
+        throw error;
+    }
+    return recovered;
+}
+function isAtRangeEdge(timeZone, date) {
+    return isNamedTimeZone(timeZone) && isNearRangeEdge(date);
+}
+/**
+ * True when the polyfill's `GetStartOfDay` may return a valid-looking wrong value for this date (or
+ * this zoned value's date) because a transition skipping its midnight lies before the polyfill's
+ * 1847-01-01 transition search floor (defect 3).
+ */
+function needsOwnStartOfDay(timeZone, value) {
+    return isNamedTimeZone(timeZone) && isBeforePolyfillTransitionSearch(value);
+}
+function inZoneOf(epochNanoseconds, zoned) {
+    return new Temporal.ZonedDateTime(epochNanoseconds, zoned.timeZoneId, zoned.calendarId);
+}
+// ---------------------------------------------------------------------------------------------
+// PlainDate / PlainDateTime -> ZonedDateTime
+// ---------------------------------------------------------------------------------------------
+function plainToZonedAtEdge(plain, timeZoneLike, disambiguation) {
+    let timeZone;
+    try {
+        timeZone = timeZoneIdOf(timeZoneLike);
+        DISAMBIGUATION_PROBE.toZonedDateTime("UTC", { disambiguation });
+    }
+    catch {
+        return null;
+    }
+    const isDate = plain instanceof Temporal.PlainDate;
+    const date = isDate ? plain : plain.toPlainDate();
+    if (!isAtRangeEdge(timeZone, date)) {
+        return null;
+    }
+    if (isDate) {
+        return plainDateFromOwnStartOfDay(plain, timeZone);
+    }
+    return new Temporal.ZonedDateTime(epochNanosecondsFor(timeZone, plain, disambiguation ?? "compatible"), timeZone, plain.calendarId);
+}
+function plainDateFromOwnStartOfDay(date, timeZone) {
+    return new Temporal.ZonedDateTime(startOfDayEpochNanoseconds(timeZone, date), timeZone, date.calendarId);
+}
+/** A PlainDate's start of day before the polyfill's transition search floor, or null. */
+function plainDateBeforeTransitionSearch(date, timeZoneLike) {
+    if (!isBeforePolyfillTransitionSearch(date))
+        return null;
+    let timeZone;
+    try {
+        timeZone = timeZoneIdOf(timeZoneLike);
+    }
+    catch {
+        return null;
+    }
+    return isNamedTimeZone(timeZone)
+        ? plainDateFromOwnStartOfDay(date, timeZone)
+        : null;
+}
+/**
+ * `PlainDate#toZonedDateTime(timeZone)` (start of day) or
+ * `PlainDateTime#toZonedDateTime(timeZone, { disambiguation })`, correct at the range limits and
+ * (start of day) before 1847.
+ *
+ * @param plain the date (resolved to its start of day) or date-time to place in `timeZone`
+ * @param timeZone IANA identifier, offset time zone, or RFC 9557 string carrying one
+ * @param disambiguation Temporal disambiguation for a PlainDateTime (ignored for a PlainDate)
+ * @returns the resolved Temporal.ZonedDateTime; throws where TC39 Temporal throws
+ */
+export function plainToZoned(plain, timeZone, disambiguation) {
+    if (plain instanceof Temporal.PlainDate) {
+        const own = plainDateBeforeTransitionSearch(plain, timeZone);
+        if (own !== null) {
+            return own;
+        }
+    }
+    try {
+        return plain instanceof Temporal.PlainDate
+            ? plain.toZonedDateTime(timeZone)
+            : plain.toZonedDateTime(timeZone, { disambiguation });
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => plainToZonedAtEdge(plain, timeZone, disambiguation));
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Start of day, withPlainTime, hoursInDay
+// ---------------------------------------------------------------------------------------------
+function startOfDayFromOwn(zoned) {
+    return inZoneOf(startOfDayEpochNanoseconds(zoned.timeZoneId, zoned.toPlainDate()), zoned);
+}
+function startOfDayAtEdge(zoned) {
+    return isAtRangeEdge(zoned.timeZoneId, zoned.toPlainDate())
+        ? startOfDayFromOwn(zoned)
+        : null;
+}
+/**
+ * `ZonedDateTime#startOfDay`, correct at the range limits and before 1847.
+ *
+ * @param zoned the value whose local day to start
+ * @returns the first valid wall-clock time of that day; throws where TC39 Temporal throws
+ */
+export function zonedStartOfDay(zoned) {
+    if (needsOwnStartOfDay(zoned.timeZoneId, zoned)) {
+        return startOfDayFromOwn(zoned);
+    }
+    try {
+        return zoned.startOfDay();
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => startOfDayAtEdge(zoned));
+    }
+}
+function withPlainTimeAtEdge(zoned, time) {
+    if (time === undefined) {
+        return startOfDayAtEdge(zoned);
+    }
+    const date = zoned.toPlainDate();
+    let wall;
+    try {
+        wall = date.toPlainDateTime(Temporal.PlainTime.from(time));
+    }
+    catch {
+        return null;
+    }
+    if (!isAtRangeEdge(zoned.timeZoneId, date)) {
+        return null;
+    }
+    return inZoneOf(epochNanosecondsFor(zoned.timeZoneId, wall, "compatible"), zoned);
+}
+/**
+ * `ZonedDateTime#withPlainTime`, correct at the range limits and (start of day) before 1847.
+ *
+ * @param zoned the value whose local date to keep
+ * @param time the new wall-clock time; omitted means the start of the day
+ * @returns the resolved Temporal.ZonedDateTime; throws where TC39 Temporal throws
+ */
+export function zonedWithPlainTime(zoned, time) {
+    if (time === undefined && needsOwnStartOfDay(zoned.timeZoneId, zoned)) {
+        return startOfDayFromOwn(zoned);
+    }
+    try {
+        return zoned.withPlainTime(time);
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => withPlainTimeAtEdge(zoned, time));
+    }
+}
+function hoursInDayAtEdge(zoned) {
+    return isAtRangeEdge(zoned.timeZoneId, zoned.toPlainDate())
+        ? hoursInDayFromOwnStartOfDay(zoned)
+        : null;
+}
+function hoursInDayFromOwnStartOfDay(zoned) {
+    const date = zoned.toPlainDate();
+    const start = startOfDayEpochNanoseconds(zoned.timeZoneId, date);
+    // Past the last representable date `add` throws, as TC39 `GetStartOfDay` does for that day.
+    const end = startOfDayEpochNanoseconds(zoned.timeZoneId, date.add({ days: 1 }));
+    return Number(end - start) / NANOSECONDS_PER_HOUR;
+}
+/**
+ * `ZonedDateTime#hoursInDay`, correct at the range limits and before 1847.
+ *
+ * @param zoned the value whose local day to measure
+ * @returns hours from this day's start to the next day's start; throws where TC39 Temporal throws
+ */
+export function zonedHoursInDay(zoned) {
+    if (needsOwnStartOfDay(zoned.timeZoneId, zoned)) {
+        return hoursInDayFromOwnStartOfDay(zoned);
+    }
+    try {
+        return zoned.hoursInDay;
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => hoursInDayAtEdge(zoned));
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Next transition
+// ---------------------------------------------------------------------------------------------
+/** The earliest transition after `zoned`, found by walking back from the maximum instant. */
+function earliestTransitionBeforeMaximum(zoned) {
+    if (zoned.epochNanoseconds >= MAX_EPOCH_NANOSECONDS) {
+        return null;
+    }
+    const maximum = inZoneOf(MAX_EPOCH_NANOSECONDS, zoned);
+    const justBeforeMaximum = inZoneOf(MAX_EPOCH_NANOSECONDS - 1n, zoned);
+    // `previous` is strict, so a transition exactly at the maximum is checked directly.
+    let earliest = justBeforeMaximum.offsetNanoseconds === maximum.offsetNanoseconds
+        ? null
+        : maximum;
+    let cursor = maximum.getTimeZoneTransition("previous");
+    for (let step = 0; cursor !== null && cursor.epochNanoseconds > zoned.epochNanoseconds; step++) {
+        if (step >= MAX_TRANSITIONS_BEFORE_MAXIMUM) {
+            throw new RangeError(`Too many transitions in ${zoned.timeZoneId} before the maximum instant`);
+        }
+        earliest = cursor;
+        cursor = cursor.getTimeZoneTransition("previous");
+    }
+    return earliest;
+}
+/**
+ * `ZonedDateTime#getTimeZoneTransition("next")`, correct at the range limits and before 1847.
+ *
+ * - Before 1847-01-01 the polyfill never searches (defect 3), so a named zone whose offset there
+ *   differs from its offset at 1847-01-01 has its transition found by bisection first.
+ * - The polyfill's forward scan gives up once a two-week step would pass the maximum instant, so a
+ *   `null` within its three-year horizon of the maximum is re-checked by walking back from the
+ *   maximum with `getTimeZoneTransition("previous")`, which scans correctly there.
+ *
+ * @param zoned the instant to search after (exclusive)
+ * @returns the next transition, or null when there is none before the maximum instant
+ */
+export function zonedNextTransition(zoned) {
+    if (isNamedTimeZone(zoned.timeZoneId)) {
+        const missed = missedNextTransition(zoned.timeZoneId, zoned.epochNanoseconds);
+        if (missed !== null) {
+            return inZoneOf(missed, zoned);
+        }
+    }
+    const next = zoned.getTimeZoneTransition("next");
+    if (next !== null ||
+        !isNamedTimeZone(zoned.timeZoneId) ||
+        MAX_EPOCH_NANOSECONDS - zoned.epochNanoseconds >
+            NEXT_TRANSITION_HORIZON_NANOSECONDS) {
+        return next;
+    }
+    return earliestTransitionBeforeMaximum(zoned);
+}
+/**
+ * `ZonedDateTime#getTimeZoneTransition("previous")`, correct before 1847.
+ *
+ * The polyfill stops looking at 1847-01-01 (defect 3), so when it finds nothing in a named zone the
+ * span from the minimum instant to the floor is checked by comparing offsets and bisecting.
+ *
+ * @param zoned the instant to search before (exclusive)
+ * @returns the previous transition, or null when there is none
+ */
+export function zonedPreviousTransition(zoned) {
+    const previous = zoned.getTimeZoneTransition("previous");
+    if (previous !== null || !isNamedTimeZone(zoned.timeZoneId)) {
+        return previous;
+    }
+    const missed = missedPreviousTransition(zoned.timeZoneId, zoned.epochNanoseconds);
+    return missed === null ? null : inZoneOf(missed, zoned);
+}
+// ---------------------------------------------------------------------------------------------
+// add / subtract
+// ---------------------------------------------------------------------------------------------
+function hasDateUnits(duration) {
+    return (duration.years !== 0 ||
+        duration.months !== 0 ||
+        duration.weeks !== 0 ||
+        duration.days !== 0);
+}
+function timeUnitsNanoseconds(duration) {
+    return (BigInt(duration.hours) * 3600000000000n +
+        BigInt(duration.minutes) * 60000000000n +
+        BigInt(duration.seconds) * 1000000000n +
+        BigInt(duration.milliseconds) * 1000000n +
+        BigInt(duration.microseconds) * 1000n +
+        BigInt(duration.nanoseconds));
+}
+/** TC39 `AddZonedDateTime` for a duration with calendar units, at the range limits. */
+function addAtEdge(zoned, durationLike, overflow, sign) {
+    let duration;
+    let wall;
+    try {
+        const parsed = Temporal.Duration.from(durationLike);
+        duration = sign === 1 ? parsed : parsed.negated();
+        const start = zoned.toPlainDateTime();
+        const { years, months, weeks, days } = duration;
+        wall = calendarDateAdd(start.toPlainDate(), { years, months, weeks, days }, overflow === undefined ? "constrain" : overflow).toPlainDateTime(start.toPlainTime());
+    }
+    catch {
+        return null;
+    }
+    // Without calendar units the sum is exact-time arithmetic, which the polyfill gets right.
+    if (!hasDateUnits(duration) ||
+        !isAtRangeEdge(zoned.timeZoneId, wall.toPlainDate())) {
+        return null;
+    }
+    const result = epochNanosecondsFor(zoned.timeZoneId, wall, "compatible") +
+        timeUnitsNanoseconds(duration);
+    if (!isValidEpoch(result)) {
+        throw new RangeError(`${zoned.toString()} + ${duration.toString()} is outside the supported range`);
+    }
+    return inZoneOf(result, zoned);
+}
+/**
+ * TC39 §6.5.5 `AddZonedDateTime` for a signed duration with calendar units: `CalendarDateAdd` runs
+ * in `calendarDateAdd` (the Temporal compat layer, CORE-6 S5); the intermediate wall clock (added
+ * date, original time) resolves with `GetEpochNanosecondsFor(timeZone, dateTime, disambiguation)`
+ * through GMT's own `plainToZoned`, so a gap or an overlap landing honours `disambiguation`; the
+ * time units are then added in exact time and never re-resolved.
+ */
+function addDateThenTime(zoned, duration, overflow, disambiguation) {
+    // Validates `overflow` exactly as ZonedDateTime#add does.
+    OVERFLOW_PROBE.add({ days: 0 }, { overflow });
+    const wall = zoned.toPlainDateTime();
+    const { years, months, weeks, days } = duration;
+    const date = calendarDateAdd(wall.toPlainDate(), { years, months, weeks, days }, overflow === undefined ? "constrain" : overflow);
+    const intermediate = plainToZoned(date.toPlainDateTime(wall.toPlainTime()), zoned.timeZoneId, disambiguation);
+    const result = intermediate.epochNanoseconds + timeUnitsNanoseconds(duration);
+    if (!isValidEpoch(result)) {
+        throw new RangeError(`${zoned.toString()} + ${duration.toString()} is outside the supported range`);
+    }
+    return inZoneOf(result, zoned);
+}
+/**
+ * `AddZonedDateTime` through the Temporal compat layer, or null when `zoned`'s calendar needs no
+ * compat or the duration has no calendar units.
+ */
+function addWithCalendarCompat(zoned, durationLike, overflow, sign) {
+    if (!isCalendarArithmeticCompatNeeded(zoned.calendarId)) {
+        return null;
+    }
+    const parsed = Temporal.Duration.from(durationLike);
+    const duration = sign === 1 ? parsed : parsed.negated();
+    if (!hasDateUnits(duration)) {
+        return null;
+    }
+    return addDateThenTime(zoned, duration, overflow, "compatible");
+}
+/**
+ * `ZonedDateTime#add`, correct at the range limits and in calendars the polyfill gets wrong.
+ *
+ * @param zoned the starting value
+ * @param duration the duration to add
+ * @param options Temporal `overflow` for the calendar part
+ * @returns the sum; throws where TC39 Temporal throws
+ */
+export function addToZoned(zoned, duration, options) {
+    const viaCompat = addWithCalendarCompat(zoned, duration, options?.overflow, 1);
+    if (viaCompat !== null) {
+        return viaCompat;
+    }
+    try {
+        return zoned.add(duration, options);
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => addAtEdge(zoned, duration, options?.overflow, 1));
+    }
+}
+/**
+ * `ZonedDateTime#subtract`, correct at the range limits.
+ *
+ * @param zoned the starting value
+ * @param duration the duration to subtract
+ * @param options Temporal `overflow` for the calendar part
+ * @returns the difference; throws where TC39 Temporal throws
+ */
+export function subtractFromZoned(zoned, duration, options) {
+    const viaCompat = addWithCalendarCompat(zoned, duration, options?.overflow, -1);
+    if (viaCompat !== null) {
+        return viaCompat;
+    }
+    try {
+        return zoned.subtract(duration, options);
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => addAtEdge(zoned, duration, options?.overflow, -1));
+    }
+}
+/**
+ * `addToZoned` / `subtractFromZoned` with a caller-chosen `disambiguation` for the intermediate
+ * wall-clock date-time — TC39 Temporal §6.5.5 AddZonedDateTime with the "compatible" argument of
+ * its `GetEpochNanosecondsFor` step replaced by `disambiguation`.
+ *
+ * - The date portion (years, months, weeks, days) is added to the wall-clock date, keeping the
+ *   wall-clock time. That intermediate date-time is resolved with `disambiguation` whenever it is
+ *   not a single instant: in a fall-back overlap "earlier"/"compatible" take the earlier instant and
+ *   "later" the later one; in a spring-forward gap "earlier" shifts it back by the gap length and
+ *   "later"/"compatible" forward (DisambiguatePossibleEpochNanoseconds); "reject" throws for both.
+ * - The time portion is then added in exact time and is never re-resolved.
+ * - With no date portion, the whole duration is exact time and `disambiguation` never applies.
+ *
+ * @param zoned the starting value
+ * @param duration the duration to add or subtract
+ * @param sign 1 to add, -1 to subtract
+ * @param options Temporal `overflow` for the calendar part and `disambiguation`
+ * @returns the result; throws where TC39 Temporal throws, or when "reject" meets a gap or overlap
+ */
+export function addToZonedDisambiguated(zoned, duration, sign, options) {
+    const { overflow, disambiguation } = options;
+    // Validates `disambiguation` even when no wall clock is resolved below.
+    DISAMBIGUATION_PROBE.toZonedDateTime("UTC", { disambiguation });
+    const parsed = Temporal.Duration.from(duration);
+    if (disambiguation === "compatible" || !hasDateUnits(parsed)) {
+        const step = sign === 1 ? addToZoned : subtractFromZoned;
+        return step(zoned, parsed, { overflow });
+    }
+    return addDateThenTime(zoned, sign === 1 ? parsed : parsed.negated(), overflow, disambiguation);
+}
+/** TC39 `ZonedDateTime#with` at the range limits. */
+function withAtEdge(zoned, fields, options) {
+    let wall;
+    let offset;
+    try {
+        Temporal.ZonedDateTime.from(zoned, options);
+        const { offset: offsetString, ...dateTimeFields } = fields;
+        wall = zoned
+            .toPlainDateTime()
+            .with(dateTimeFields, { overflow: options?.overflow });
+        offset = {
+            nanoseconds: offsetString === undefined
+                ? BigInt(zoned.offsetNanoseconds)
+                : utcOffsetStringNanoseconds(offsetString),
+        };
+    }
+    catch {
+        return null;
+    }
+    if (!isAtRangeEdge(zoned.timeZoneId, wall.toPlainDate())) {
+        return null;
+    }
+    const epoch = interpretISODateTimeOffset(zoned.timeZoneId, wall, offset, options?.disambiguation === undefined
+        ? "compatible"
+        : options.disambiguation, options?.offset === undefined ? "prefer" : options.offset, false);
+    return inZoneOf(epoch, zoned);
+}
+/**
+ * `ZonedDateTime#with`, correct at the range limits.
+ *
+ * @param zoned the value to change
+ * @param fields the date/time (and optional offset) fields to set
+ * @param options Temporal `overflow` / `disambiguation` / `offset` (default `"prefer"`)
+ * @returns the changed value; throws where TC39 Temporal throws
+ */
+export function withZonedFields(zoned, fields, options) {
+    try {
+        return zoned.with(fields, options);
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => withAtEdge(zoned, fields, options));
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// round
+// ---------------------------------------------------------------------------------------------
+/** Rounding modes that never move a non-negative progress past the start of the day. */
+const ROUNDS_TOWARD_START = new Set([
+    "floor",
+    "trunc",
+]);
+/** Rounding modes that move any positive progress to the start of the next day. */
+const ROUNDS_TOWARD_END = new Set([
+    "ceil",
+    "expand",
+]);
+/**
+ * Half modes that resolve an exact half upward. Half-floor, half-trunc and half-even (0 is the
+ * even quotient) resolve it to the start.
+ */
+const HALF_ROUNDS_TOWARD_END = new Set([
+    "halfCeil",
+    "halfExpand",
+]);
+/** TC39 `RoundTimeDurationToIncrement` for `0 <= progress < length`: either 0 or `length`. */
+function roundDayProgress(progress, length, roundingMode) {
+    if (progress === 0n || ROUNDS_TOWARD_START.has(roundingMode))
+        return 0n;
+    if (ROUNDS_TOWARD_END.has(roundingMode))
+        return length;
+    const twice = progress * 2n;
+    if (twice === length) {
+        return HALF_ROUNDS_TOWARD_END.has(roundingMode) ? length : 0n;
+    }
+    return twice < length ? 0n : length;
+}
+/**
+ * TC39 `ZonedDateTime#round` with `smallestUnit: "day"`, from GMT's own `GetStartOfDay`: to the
+ * start of this day or the next.
+ */
+function roundToDayFromOwnStartOfDay(zoned, date, roundingMode) {
+    const start = startOfDayEpochNanoseconds(zoned.timeZoneId, date);
+    // Past the last representable date `add` throws, as TC39 `GetStartOfDay` does for that day.
+    const end = startOfDayEpochNanoseconds(zoned.timeZoneId, date.add({ days: 1 }));
+    const progress = zoned.epochNanoseconds - start;
+    return inZoneOf(start + roundDayProgress(progress, end - start, roundingMode), zoned);
+}
+function isDayUnit(unit) {
+    return unit === "day" || unit === "days";
+}
+function roundAtEdge(zoned, roundTo) {
+    const date = zoned.toPlainDate();
+    let roundedWall;
+    try {
+        // Validates the options exactly as ZonedDateTime#round does, and rounds the wall clock.
+        roundedWall = zoned.toPlainDateTime().round(roundTo);
+    }
+    catch {
+        return null;
+    }
+    if (!isAtRangeEdge(zoned.timeZoneId, date)) {
+        return null;
+    }
+    if (isDayUnit(roundTo.smallestUnit)) {
+        return roundToDayFromOwnStartOfDay(zoned, date, roundTo.roundingMode ?? "halfExpand");
+    }
+    const epoch = interpretISODateTimeOffset(zoned.timeZoneId, roundedWall, { nanoseconds: BigInt(zoned.offsetNanoseconds) }, "compatible", "prefer", false);
+    return inZoneOf(epoch, zoned);
+}
+/**
+ * `ZonedDateTime#round`, correct at the range limits and, by day, before 1847.
+ *
+ * @param zoned the value to round
+ * @param roundTo Temporal `smallestUnit` (day or smaller) / `roundingIncrement` / `roundingMode`
+ * @returns the rounded value; throws where TC39 Temporal throws
+ */
+export function roundZonedDateTime(zoned, roundTo) {
+    if (isDayUnit(roundTo.smallestUnit) &&
+        needsOwnStartOfDay(zoned.timeZoneId, zoned)) {
+        // Validates the options exactly as ZonedDateTime#round does, throwing where it throws.
+        zoned.toPlainDateTime().round(roundTo);
+        return roundToDayFromOwnStartOfDay(zoned, zoned.toPlainDate(), roundTo.roundingMode ?? "halfExpand");
+    }
+    try {
+        return zoned.round(roundTo);
+    }
+    catch (error) {
+        return recoverAtRangeEdge(error, () => roundAtEdge(zoned, roundTo));
+    }
+}