@northguild/gmt 1.16.0 → 1.18.0

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, utcOffsetStringNanoseconds, } 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);
@@ -443,9 +499,7 @@ function withAtEdge(zoned, fields, options) {
     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);
 }
 /**
@@ -538,8 +592,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

@@ -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"

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

@@ -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"

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;

package/dist/plain/calculate/cycleDate.js

@@ -12,24 +12,20 @@ import { isOptionsArgument } from "../../internal/isObject.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"

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

@@ -14,15 +14,12 @@ import type { DateTimeCycleField, Overflow } from "../../types/index.js";
  *   why).
  * - Cycling `month` or `year` can still shift `day` via `overflow`, exactly as `setDateTime`'s
  *   `.with()` call does.
- * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
- *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
- *   docs for worked examples.
  * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDateTime string
  * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @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 PlainDateTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleDateTime("2024-06-15T09:30:00", "hour", 1) // "2024-06-15T10:30:00"
@@ -33,6 +30,19 @@ import type { DateTimeCycleField, Overflow } from "../../types/index.js";
  * @example cycleDateTime("invalid", "hour", 1) // ""
  */
 export declare function cycleDateTime(value: string, field: DateTimeCycleField, 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;

package/dist/plain/calculate/cycleDateTime.js

@@ -18,15 +18,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   why).
  * - Cycling `month` or `year` can still shift `day` via `overflow`, exactly as `setDateTime`'s
  *   `.with()` call does.
- * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
- *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
- *   docs for worked examples.
  * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDateTime string
  * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @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 PlainDateTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleDateTime("2024-06-15T09:30:00", "hour", 1) // "2024-06-15T10:30:00"

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

@@ -9,10 +9,8 @@ import type { TimeCycleField } from "../../types/index.js";
  *   is no ISO representation for "this hour, but staying AM" to round-trip through GMT's string
  *   contract.
  * - `minute`/`second` wrap `0–59`; `millisecond`/`microsecond`/`nanosecond` wrap `0–999`.
- * - `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 minute `22` by `+15` with
- *   `round: true` lands on `30` (the next multiple of 15 above 22), not `15` (the nearest one).
+ * - With `round: true`, minute `22` by `+15` lands on `30`, the next multiple of 15 above 22, not
+ *   on `15`, the nearest one.
  * - There is no `overflow` option (removed in 1.16.0): time fields don't share bounds the way `day`
  *   shares a month with `month`/`year`, so the wrapped value is always already valid and there is
  *   nothing to constrain or reject.
@@ -21,7 +19,7 @@ import type { TimeCycleField } from "../../types/index.js";
  * @param value ISO PlainTime string
  * @param field the field to cycle: "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false)
+ * @param options How the field is stepped
  * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"
@@ -32,5 +30,12 @@ import type { TimeCycleField } from "../../types/index.js";
  * @example cycleTime("invalid", "hour", 1) // ""
  */
 export declare function cycleTime(value: string, field: TimeCycleField, 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;
 }): string;

package/dist/plain/calculate/cycleTime.js

@@ -13,10 +13,8 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   is no ISO representation for "this hour, but staying AM" to round-trip through GMT's string
  *   contract.
  * - `minute`/`second` wrap `0–59`; `millisecond`/`microsecond`/`nanosecond` wrap `0–999`.
- * - `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 minute `22` by `+15` with
- *   `round: true` lands on `30` (the next multiple of 15 above 22), not `15` (the nearest one).
+ * - With `round: true`, minute `22` by `+15` lands on `30`, the next multiple of 15 above 22, not
+ *   on `15`, the nearest one.
  * - There is no `overflow` option (removed in 1.16.0): time fields don't share bounds the way `day`
  *   shares a month with `month`/`year`, so the wrapped value is always already valid and there is
  *   nothing to constrain or reject.
@@ -25,7 +23,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value ISO PlainTime string
  * @param field the field to cycle: "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false)
+ * @param options How the field is stepped
  * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"

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

@@ -34,7 +34,7 @@ import type { DateDurationUnit, RoundingOptions } from "../../types/index.js";
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unitArg date unit or units to measure the difference, singular or plural (`"day"` or
  *   `"days"`); a record result keeps the plural keys
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDate("2024-03-10", "2024-03-15", "days") // 5

package/dist/plain/calculate/diffDate.js

@@ -38,7 +38,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unitArg date unit or units to measure the difference, singular or plural (`"day"` or
  *   `"days"`); a record result keeps the plural keys
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDate("2024-03-10", "2024-03-15", "days") // 5

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

@@ -27,7 +27,7 @@ import type { DateDurationUnit, DurationStringOptions, RoundingOptions } from ".
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unit date unit, singular or plural (`"day"` or `"days"`), to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"

package/dist/plain/calculate/diffDateAsDuration.js

@@ -29,7 +29,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unit date unit, singular or plural (`"day"` or `"days"`), to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"

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

@@ -27,7 +27,7 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "days") // 5

package/dist/plain/calculate/diffDateTime.js

@@ -33,7 +33,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "days") // 5

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

@@ -21,7 +21,7 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"