@northguild/gmt 1.17.0 → 1.19.0

package/dist/internal/zonedWallClockOperations.d.ts

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import type { Disambiguation, Offset, Overflow } from "../types/index.js";
+import type { DATE_TIME_FIELDS, SetFields } from "./readSetFields.js";
 type RoundingSmallestUnit = Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
 interface ZonedRoundTo {
     smallestUnit: RoundingSmallestUnit;
@@ -40,28 +41,40 @@ export declare function zonedWithPlainTime(zoned: Temporal.ZonedDateTime, time?:
  */
 export declare function zonedHoursInDay(zoned: Temporal.ZonedDateTime): number;
 /**
- * `ZonedDateTime#getTimeZoneTransition("next")`, correct at the range limits and before 1847.
+ * `ZonedDateTime#getTimeZoneTransition("next")`: TC39 `GetNamedTimeZoneNextTransition`, the first
+ * offset change strictly after `zoned`.
  *
- * - 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.
+ * - While the D13 probe fails (two changes inside one of the polyfill's 14-day search steps are
+ *   skipped, or stall it for ever), a named zone is searched by GMT's own bounded search
+ *   (`zonedTransitionSearch.ts`) and the polyfill's search is never called.
+ * - Otherwise the polyfill answers, corrected before 1847 (defect 3: it never searches there, so
+ *   the change is found by bisection first) and within its three-year horizon of the maximum
+ *   instant (defect 2: its forward scan gives up once a step would pass the maximum, so a `null`
+ *   is re-checked by walking back from the maximum).
  *
  * @param zoned the instant to search after (exclusive)
- * @returns the next transition, or null when there is none before the maximum instant
+ * @param until optional: the last instant to search, in epoch nanoseconds (inclusive). A caller
+ *   that needs only changes up to there passes it so the search reads no further
+ * @returns the next transition, or null when there is none up to `until` or, without it, none
+ *   that Temporal reports
  */
-export declare function zonedNextTransition(zoned: Temporal.ZonedDateTime): Temporal.ZonedDateTime | null;
+export declare function zonedNextTransition(zoned: Temporal.ZonedDateTime, until?: bigint): Temporal.ZonedDateTime | null;
 /**
- * `ZonedDateTime#getTimeZoneTransition("previous")`, correct before 1847.
+ * `ZonedDateTime#getTimeZoneTransition("previous")`: TC39 `GetNamedTimeZonePreviousTransition`,
+ * the last offset change strictly before `zoned`.
  *
- * 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.
+ * - While the D13 probe fails, a named zone is searched by GMT's own bounded search and the
+ *   polyfill's search is never called (see `zonedNextTransition`).
+ * - Otherwise the polyfill answers, corrected before 1847 (defect 3): when it finds nothing in a
+ *   named zone, the span from the minimum instant to its 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
+ * @param since optional: where the search stops, in epoch nanoseconds (exclusive). A caller that
+ *   needs only changes after there passes it so the search reads no further back
+ * @returns the previous transition, or null when there is none after `since` or, without it, none
  */
-export declare function zonedPreviousTransition(zoned: Temporal.ZonedDateTime): Temporal.ZonedDateTime | null;
+export declare function zonedPreviousTransition(zoned: Temporal.ZonedDateTime, since?: bigint): Temporal.ZonedDateTime | null;
 /**
  * `ZonedDateTime#add`, correct at the range limits and in calendars the polyfill gets wrong.
  *
@@ -96,6 +109,7 @@ export declare function subtractFromZoned(zoned: Temporal.ZonedDateTime, duratio
  *   "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.
+ * - Each option is converted to a string once, as Temporal GetOption converts it.
  *
  * @param zoned the starting value
  * @param duration the duration to add or subtract
@@ -112,15 +126,17 @@ interface ZonedWithOptions {
     disambiguation?: Disambiguation;
     offset?: Offset;
 }
+/** The date and time fields a `set*` function passes, as `readSetFields` checked them. */
+type ZonedWithFields = SetFields<(typeof DATE_TIME_FIELDS)[number]>;
 /**
  * `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 fields the date and time 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;
+export declare function withZonedFields(zoned: Temporal.ZonedDateTime, fields: ZonedWithFields, options?: ZonedWithOptions): Temporal.ZonedDateTime;
 /**
  * `ZonedDateTime#round`, correct at the range limits and, by day, before 1847.
  *

package/dist/internal/zonedWallClockOperations.js

@@ -1,7 +1,9 @@
 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";
+import { calendarDateAdd, isCalendarArithmeticCompatNeeded, isTransitionSearchCompatNeeded, } from "./temporalCompat/index.js";
+import { nextTransitionAfter, previousTransitionBefore, } from "./zonedTransitionSearch.js";
+import { epochNanosecondsFor, interpretISODateTimeOffset, isNamedTimeZone, isNearRangeEdge, isValidEpoch, MAX_TRANSITIONS_BEFORE_MAXIMUM, missedNextTransition, missedPreviousTransition, needsOwnDayBoundsSearch, needsOwnStartOfDaySearch, NEXT_TRANSITION_HORIZON_NANOSECONDS, startOfDayEpochNanoseconds, timeZoneIdOf, } from "./zonedWallClock.js";
+import { optionOrDefault } from "./optionOrDefault.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
@@ -19,6 +21,11 @@ import { epochNanosecondsFor, interpretISODateTimeOffset, isBeforePolyfillTransi
  * 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.
+ *
+ * Defect 5 (two changes inside one 14-day search step are skipped, or stall the search for ever;
+ * temporalCompat D13) cannot be tried and recovered either. While its probe fails, the transition
+ * wrappers run GMT's own search (`zonedTransitionSearch.ts`) and the start-of-day wrappers GMT's
+ * own `GetStartOfDay`, for every named zone.
  */
 const NANOSECONDS_PER_HOUR = 3_600_000_000_000;
 const DISAMBIGUATION_PROBE = new Temporal.PlainDateTime(2000, 1, 1);
@@ -37,11 +44,17 @@ function isAtRangeEdge(timeZone, 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).
+ * this zoned value's date): a transition skipping its midnight lies before the polyfill's
+ * 1847-01-01 transition search floor (defect 3), or the polyfill's search can skip or stall on two
+ * changes in one step (defect 5, while the D13 probe fails).
  */
 function needsOwnStartOfDay(timeZone, value) {
-    return isNamedTimeZone(timeZone) && isBeforePolyfillTransitionSearch(value);
+    return isNamedTimeZone(timeZone) && needsOwnStartOfDaySearch(timeZone, value);
+}
+/** `needsOwnStartOfDay` for a measure that also reads the next day's start. */
+function needsOwnDayBounds(zoned) {
+    return (isNamedTimeZone(zoned.timeZoneId) &&
+        needsOwnDayBoundsSearch(zoned.timeZoneId, zoned));
 }
 function inZoneOf(epochNanoseconds, zoned) {
     return new Temporal.ZonedDateTime(epochNanoseconds, zoned.timeZoneId, zoned.calendarId);
@@ -73,8 +86,6 @@ function plainDateFromOwnStartOfDay(date, timeZone) {
 }
 /** 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);
@@ -82,7 +93,7 @@ function plainDateBeforeTransitionSearch(date, timeZoneLike) {
     catch {
         return null;
     }
-    return isNamedTimeZone(timeZone)
+    return needsOwnStartOfDay(timeZone, date)
         ? plainDateFromOwnStartOfDay(date, timeZone)
         : null;
 }
@@ -194,7 +205,7 @@ function hoursInDayFromOwnStartOfDay(zoned) {
  * @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)) {
+    if (needsOwnDayBounds(zoned)) {
         return hoursInDayFromOwnStartOfDay(zoned);
     }
     try {
@@ -228,19 +239,13 @@ function earliestTransitionBeforeMaximum(zoned) {
     }
     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) {
+/** `transition` unless it is null or lies outside the caller's limit. */
+function withinLimit(transition, isInside) {
+    return transition !== null && isInside(transition.epochNanoseconds)
+        ? transition
+        : null;
+}
+function polyfillNextTransition(zoned) {
     if (isNamedTimeZone(zoned.timeZoneId)) {
         const missed = missedNextTransition(zoned.timeZoneId, zoned.epochNanoseconds);
         if (missed !== null) {
@@ -257,15 +262,34 @@ export function zonedNextTransition(zoned) {
     return earliestTransitionBeforeMaximum(zoned);
 }
 /**
- * `ZonedDateTime#getTimeZoneTransition("previous")`, correct before 1847.
+ * `ZonedDateTime#getTimeZoneTransition("next")`: TC39 `GetNamedTimeZoneNextTransition`, the first
+ * offset change strictly after `zoned`.
  *
- * 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.
+ * - While the D13 probe fails (two changes inside one of the polyfill's 14-day search steps are
+ *   skipped, or stall it for ever), a named zone is searched by GMT's own bounded search
+ *   (`zonedTransitionSearch.ts`) and the polyfill's search is never called.
+ * - Otherwise the polyfill answers, corrected before 1847 (defect 3: it never searches there, so
+ *   the change is found by bisection first) and within its three-year horizon of the maximum
+ *   instant (defect 2: its forward scan gives up once a step would pass the maximum, so a `null`
+ *   is re-checked by walking back from the maximum).
  *
- * @param zoned the instant to search before (exclusive)
- * @returns the previous transition, or null when there is none
+ * @param zoned the instant to search after (exclusive)
+ * @param until optional: the last instant to search, in epoch nanoseconds (inclusive). A caller
+ *   that needs only changes up to there passes it so the search reads no further
+ * @returns the next transition, or null when there is none up to `until` or, without it, none
+ *   that Temporal reports
  */
-export function zonedPreviousTransition(zoned) {
+export function zonedNextTransition(zoned, until) {
+    if (isNamedTimeZone(zoned.timeZoneId) && isTransitionSearchCompatNeeded()) {
+        const found = nextTransitionAfter(zoned.timeZoneId, zoned.epochNanoseconds, until);
+        return found === null ? null : inZoneOf(found, zoned);
+    }
+    const next = polyfillNextTransition(zoned);
+    return until === undefined
+        ? next
+        : withinLimit(next, (epochNanoseconds) => epochNanoseconds <= until);
+}
+function polyfillPreviousTransition(zoned) {
     const previous = zoned.getTimeZoneTransition("previous");
     if (previous !== null || !isNamedTimeZone(zoned.timeZoneId)) {
         return previous;
@@ -273,6 +297,31 @@ export function zonedPreviousTransition(zoned) {
     const missed = missedPreviousTransition(zoned.timeZoneId, zoned.epochNanoseconds);
     return missed === null ? null : inZoneOf(missed, zoned);
 }
+/**
+ * `ZonedDateTime#getTimeZoneTransition("previous")`: TC39 `GetNamedTimeZonePreviousTransition`,
+ * the last offset change strictly before `zoned`.
+ *
+ * - While the D13 probe fails, a named zone is searched by GMT's own bounded search and the
+ *   polyfill's search is never called (see `zonedNextTransition`).
+ * - Otherwise the polyfill answers, corrected before 1847 (defect 3): when it finds nothing in a
+ *   named zone, the span from the minimum instant to its floor is checked by comparing offsets
+ *   and bisecting.
+ *
+ * @param zoned the instant to search before (exclusive)
+ * @param since optional: where the search stops, in epoch nanoseconds (exclusive). A caller that
+ *   needs only changes after there passes it so the search reads no further back
+ * @returns the previous transition, or null when there is none after `since` or, without it, none
+ */
+export function zonedPreviousTransition(zoned, since) {
+    if (isNamedTimeZone(zoned.timeZoneId) && isTransitionSearchCompatNeeded()) {
+        const found = previousTransitionBefore(zoned.timeZoneId, zoned.epochNanoseconds, since);
+        return found === null ? null : inZoneOf(found, zoned);
+    }
+    const previous = polyfillPreviousTransition(zoned);
+    return since === undefined
+        ? previous
+        : withinLimit(previous, (epochNanoseconds) => epochNanoseconds > since);
+}
 // ---------------------------------------------------------------------------------------------
 // add / subtract
 // ---------------------------------------------------------------------------------------------
@@ -403,6 +452,7 @@ export function subtractFromZoned(zoned, duration, options) {
  *   "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.
+ * - Each option is converted to a string once, as Temporal GetOption converts it.
  *
  * @param zoned the starting value
  * @param duration the duration to add or subtract
@@ -411,7 +461,13 @@ export function subtractFromZoned(zoned, duration, options) {
  * @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;
+    // Temporal GetOption converts each option once (ToString). The steps below check an option and
+    // then use it, some more than once, so both are converted here and every step sees the same
+    // string: an option given as an object cannot answer the check one way and the use another.
+    const overflow = options.overflow === undefined
+        ? undefined
+        : `${options.overflow}`;
+    const disambiguation = `${options.disambiguation}`;
     // Validates `disambiguation` even when no wall clock is resolved below.
     DISAMBIGUATION_PROBE.toZonedDateTime("UTC", { disambiguation });
     const parsed = Temporal.Duration.from(duration);
@@ -424,35 +480,30 @@ export function addToZonedDisambiguated(zoned, duration, sign, options) {
 /** 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),
-        };
+            .with(fields, { overflow: options?.overflow });
     }
     catch {
         return null;
     }
+    // `fields` holds no offset, so the merged wall clock keeps the receiver's (ZonedDateTime#with).
+    const offset = {
+        nanoseconds: BigInt(zoned.offsetNanoseconds),
+    };
     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);
+    const epoch = interpretISODateTimeOffset(zoned.timeZoneId, wall, offset, optionOrDefault(options?.disambiguation, "compatible"), optionOrDefault(options?.offset, "prefer"), 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 fields the date and time fields to set
  * @param options Temporal `overflow` / `disambiguation` / `offset` (default `"prefer"`)
  * @returns the changed value; throws where TC39 Temporal throws
  */
@@ -538,8 +589,7 @@ function roundAtEdge(zoned, roundTo) {
  * @returns the rounded value; throws where TC39 Temporal throws
  */
 export function roundZonedDateTime(zoned, roundTo) {
-    if (isDayUnit(roundTo.smallestUnit) &&
-        needsOwnStartOfDay(zoned.timeZoneId, zoned)) {
+    if (isDayUnit(roundTo.smallestUnit) && needsOwnDayBounds(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");

package/dist/interval/validate/isValidInterval.d.ts

@@ -4,9 +4,12 @@ import type { Interval } from "../../types/index.js";
  *
  * - True when `start` and `end` are ISO 8601 instant strings (offset required, no leap second)
  *   and `start` is not after `end`.
- * - Annotations are read as `Temporal.Instant.from` reads them: a bracketed zone, a calendar
- *   annotation (`[u-ca=hebrew]`, critical or not) and an elective unknown annotation
- *   (`[foo=bar]`) are ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
+ * - A calendar annotation (`[u-ca=hebrew]`, critical or not) and an elective unknown annotation
+ *   (`[foo=bar]`) are ignored, as `Temporal.Instant.from` ignores them; an unknown critical
+ *   annotation (`[!foo=bar]`) is rejected. A bracketed zone is not validated. It is read for
+ *   one thing: an offset written to the minute that is the zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it.
  * - Compares instants, not text: `{ start: "2024-01-01T10:00:00+01:00", end: "2024-01-01T09:30:00Z" }`
  *   is valid even though it sorts backwards as a string.
  * - `start === end` is valid — an empty interval.

package/dist/interval/validate/isValidInterval.js

@@ -4,9 +4,12 @@ import { parseIntervalNanoseconds } from "../../internal/index.js";
  *
  * - True when `start` and `end` are ISO 8601 instant strings (offset required, no leap second)
  *   and `start` is not after `end`.
- * - Annotations are read as `Temporal.Instant.from` reads them: a bracketed zone, a calendar
- *   annotation (`[u-ca=hebrew]`, critical or not) and an elective unknown annotation
- *   (`[foo=bar]`) are ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
+ * - A calendar annotation (`[u-ca=hebrew]`, critical or not) and an elective unknown annotation
+ *   (`[foo=bar]`) are ignored, as `Temporal.Instant.from` ignores them; an unknown critical
+ *   annotation (`[!foo=bar]`) is rejected. A bracketed zone is not validated. It is read for
+ *   one thing: an offset written to the minute that is the zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it.
  * - Compares instants, not text: `{ start: "2024-01-01T10:00:00+01:00", end: "2024-01-01T09:30:00Z" }`
  *   is valid even though it sorts backwards as a string.
  * - `start === end` is valid — an empty interval.

package/dist/plain/calculate/addDate.d.ts

@@ -10,18 +10,15 @@ import type { DateDurationUnit, Overflow } from "../../types/index.js";
  *   string is the `"iso8601"` calendar and returns a bare ISO string.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
  *   calendar ids); see `isValidCalendarDate`.
+ * - Whether `overflow: "reject"` returns "" is calendar-dependent: adding 1 year from Hebrew
+ *   Adar I (a leap-only month) does not (Temporal remaps to the non-leap year's Adar instead of
+ *   rejecting), while adding 1 month from the Ethiopic 30-day 12th month into the 5/6-day
+ *   Pagumen does.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in ""). Whether `reject`
- * actually throws is calendar-dependent: adding 1 year from Hebrew Adar I (a leap-only month)
- * does NOT throw even with `overflow: "reject"` (Temporal remaps to the non-leap year's Adar
- * instead of rejecting), while adding 1 month from the Ethiopic 30-day 12th month into the
- * 5/6-day Pagumen DOES throw.
- *
  * @param value ISO PlainDate string, optionally calendar-annotated
  * @param units Partial<Record<DateDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDate string after addition, or "" on invalid input
  *
  * @example addDate("2024-03-10", { days: 5 }) // "2024-03-15"
@@ -32,5 +29,11 @@ import type { DateDurationUnit, Overflow } from "../../types/index.js";
  * @example addDate("2024-10-03[u-ca=japanese;era=reiwa]", { days: 1 }) // "" (not RFC 9557)
  */
 export declare function addDate(value: string, units: Partial<Record<DateDurationUnit, number>>, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Jan 31 + 1 month is Feb 29 or 28; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/addDate.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, plainDateAdd, resolveOverflow, } from "../../internal/index.js";
+import { calendarSystemOfDateValue, formatDateInCalendar, parseCalendarDateValue, plainDateAdd, readDurationUnits, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -13,18 +13,15 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   string is the `"iso8601"` calendar and returns a bare ISO string.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
  *   calendar ids); see `isValidCalendarDate`.
+ * - Whether `overflow: "reject"` returns "" is calendar-dependent: adding 1 year from Hebrew
+ *   Adar I (a leap-only month) does not (Temporal remaps to the non-leap year's Adar instead of
+ *   rejecting), while adding 1 month from the Ethiopic 30-day 12th month into the 5/6-day
+ *   Pagumen does.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in ""). Whether `reject`
- * actually throws is calendar-dependent: adding 1 year from Hebrew Adar I (a leap-only month)
- * does NOT throw even with `overflow: "reject"` (Temporal remaps to the non-leap year's Adar
- * instead of rejecting), while adding 1 month from the Ethiopic 30-day 12th month into the
- * 5/6-day Pagumen DOES throw.
- *
  * @param value ISO PlainDate string, optionally calendar-annotated
  * @param units Partial<Record<DateDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDate string after addition, or "" on invalid input
  *
  * @example addDate("2024-03-10", { days: 5 }) // "2024-03-15"
@@ -40,11 +37,8 @@ export function addDate(value /* ISO 8601 date */, units, options) {
             return "";
         }
         const validDate = isValidCalendarDate(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDate || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateDurationUnit);
+        if (!validDate || amounts === null) {
             return "";
         }
         try {
@@ -53,7 +47,7 @@ export function addDate(value /* ISO 8601 date */, units, options) {
                 return "";
             }
             const date = parseCalendarDateValue(value);
-            const result = plainDateAdd(date, units, resolveOverflow(options?.overflow));
+            const result = plainDateAdd(date, amounts, resolveOverflow(options?.overflow));
             return formatDateInCalendar(result, calendar);
         }
         catch {

package/dist/plain/calculate/addDateTime.d.ts

@@ -5,12 +5,9 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * - Validates `value`, `units`, and `amount` before performing the add.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO PlainDateTime string
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDateTime string after addition, or "" on invalid input
  *
  * @example addDateTime("2024-03-10T12:00:00", { days: 5 }) // "2024-03-15T12:00:00"
@@ -18,5 +15,11 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * @example addDateTime("2024-01-31T12:00:00", { months: 1 }, { overflow: "reject" }) // ""
  */
 export declare function addDateTime(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Jan 31 + 1 month is Feb 29 or 28; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/addDateTime.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -9,12 +9,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates `value`, `units`, and `amount` before performing the add.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO PlainDateTime string
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDateTime string after addition, or "" on invalid input
  *
  * @example addDateTime("2024-03-10T12:00:00", { days: 5 }) // "2024-03-15T12:00:00"
@@ -27,17 +24,14 @@ export function addDateTime(value, units, options) {
             return "";
         }
         const validDateTime = isValidDateTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDateTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validDateTime || amounts === null) {
             return "";
         }
         try {
             const dateTime = Temporal.PlainDateTime.from(value);
             return dateTime
-                .add(units, { overflow: resolveOverflow(options?.overflow) })
+                .add(amounts, { overflow: resolveOverflow(options?.overflow) })
                 .toString();
         }
         catch {

package/dist/plain/calculate/addTime.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
+import { readDurationUnits } from "../../internal/index.js";
 import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
 /**
  * Return a PlainTime ISO string with `units` added to `value`.
@@ -22,16 +22,13 @@ import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
 export function addTime(value, units) {
     try {
         const validTime = isValidTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidTimeDurationUnit);
+        if (!validTime || amounts === null) {
             return "";
         }
         try {
             const time = Temporal.PlainTime.from(value);
-            return time.add(units).toString();
+            return time.add(amounts).toString();
         }
         catch {
             return "";

package/dist/plain/calculate/cycleDate.d.ts

@@ -8,24 +8,20 @@ import type { DateCycleField, Overflow } from "../../types/index.js";
  *   overflow into January of the *next* year. Reach for `addDate` when you want calendar
  *   arithmetic; reach for `cycleDate` when a single field (e.g. a datepicker segment) must stay
  *   isolated from the others.
- * - `year` has no upper/lower wrap — cycling it is plain addition (or rounding, see below).
+ * - `year` has no upper/lower wrap — cycling it is plain addition (or a step to a multiple, with
+ *   `round`): `2022` by `+5` with `round: true` lands on `2025`, the next multiple of 5.
  *   `month` wraps `1–12`. `day` wraps `1`–the **current** month's day count, so cycling `day`
  *   never changes `month`.
  * - Cycling `month` or `year` can still shift `day` via `overflow` — e.g. cycling `month` from a
  *   31st into a shorter month clamps under the default `"constrain"` (or returns `""` under
  *   `"reject"`) exactly the way `setDate`'s own `.with()` call does; this is the same clamping
  *   `addDate`'s Jan 31 + 1 month case produces, not new behavior.
- * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
- *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
- *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling `year` `2022` by `+5` with
- *   `round: true` lands on `2025` (the next multiple of 5 above 2022), not `2020` (the nearest
- *   multiple).
  * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDate string
  * @param field the field to cycle: "year" | "month" | "day"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @param options How the field is stepped and an out-of-range day is handled
  * @returns ISO PlainDate string with `field` cycled, or "" on invalid input
  *
  * @example cycleDate("2024-06-15", "month", 1) // "2024-07-15"
@@ -39,6 +35,19 @@ import type { DateCycleField, Overflow } from "../../types/index.js";
  * @example cycleDate("invalid", "month", 1) // ""
  */
 export declare function cycleDate(value: string, field: DateCycleField, amount: number, options?: {
+    /**
+     * Whether to step to a multiple of `amount` instead of adding it. `true` moves to the next
+     * multiple in the direction of the sign of `amount` (the ceiling for a positive amount, the
+     * floor for a negative one), not to the nearest one; `false` adds `amount`.
+     *
+     * @defaultValue `false`
+     */
     round?: boolean;
+    /**
+     * What to do when the cycled `month` or `year` leaves `day` past the end of its month.
+     * `"constrain"` clamps `day` to the last day of that month; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;