@northguild/gmt 1.17.0 → 1.18.0

package/dist/zoned/calculate/addZoned.d.ts

@@ -16,13 +16,9 @@ import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types
  *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  * - Follows Temporal's AddZonedDateTime: the date portion of the duration (years, months, weeks,
  *   days) moves the wall-clock date, then the time portion (hours and smaller) is added in exact
- *   time. `disambiguation` ("compatible" (default), "earlier", "later", or "reject" (returns
- *   "")) applies ONLY to the intermediate wall-clock date-time after the date portion, exactly as
- *   Temporal's GetEpochNanosecondsFor resolves it: in a fall-back (DST-end) overlap "compatible"
- *   and "earlier" take the earlier instant and "later" the later one; in a spring-forward
- *   (DST-start) gap "compatible" and "later" move the wall clock forward by the gap length and
- *   "earlier" back by it; "reject" returns "" for both. It never re-resolves the exact-time
- *   result, so a time-only duration ignores it.
+ *   time. `disambiguation` applies ONLY to the intermediate wall-clock date-time after the date
+ *   portion, exactly as Temporal's GetEpochNanosecondsFor resolves it. It never re-resolves the
+ *   exact-time result.
  * - Compatibility: before 1.16.0 a date portion landing in a spring-forward gap was always moved
  *   forward, whatever `disambiguation` said, so "earlier" matched "compatible" and "reject" did not
  *   fail. Pass "compatible" (or omit it) to keep the forward result.
@@ -33,13 +29,11 @@ import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types
  * - There is no `offset` option (removed in 1.16.0): the intermediate wall clock is resolved from
  *   a plain date-time, which has no UTC offset for it to act on (Temporal
  *   `PlainDateTime#toZonedDateTime` reads only `disambiguation`).
- * - `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 "").
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), overflow ("constrain" | "reject")
+ * @param optionsArg optional settings for resolving a DST gap or overlap and an out-of-range date
  * @returns zoned ISO 8601 string on success, or "" on invalid input
  *
  * @example addZoned("2024-02-29T14:30:45.123-05:00[America/New_York]", { days: 1 }) // "2024-03-01T14:30:45.123-05:00[America/New_York]"
@@ -58,6 +52,22 @@ import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types
  * @example addZoned("2024-01-31T12:00:00-05:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""
  */
 export declare function addZoned(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, optionsArg?: {
+    /**
+     * How the intermediate wall-clock date-time, reached after the date portion of the duration is
+     * applied, resolves when it falls in a DST gap or overlap. In a fall-back overlap
+     * `"compatible"` and `"earlier"` take the earlier instant and `"later"` the later one; in a
+     * spring-forward gap `"compatible"` and `"later"` move the wall clock forward by the gap length
+     * and `"earlier"` back by it. `"reject"` returns `""` for both, and a time-only duration
+     * ignores the option.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
     disambiguation?: Disambiguation;
+    /**
+     * What happens when the result names a day its month does not have, such as adding 1 month to
+     * 31 January. `"constrain"` clamps to the last valid day; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/zoned/calculate/addZoned.js

@@ -3,6 +3,7 @@ import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalen
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Add a temporal amount to a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.
  *
@@ -20,13 +21,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  * - Follows Temporal's AddZonedDateTime: the date portion of the duration (years, months, weeks,
  *   days) moves the wall-clock date, then the time portion (hours and smaller) is added in exact
- *   time. `disambiguation` ("compatible" (default), "earlier", "later", or "reject" (returns
- *   "")) applies ONLY to the intermediate wall-clock date-time after the date portion, exactly as
- *   Temporal's GetEpochNanosecondsFor resolves it: in a fall-back (DST-end) overlap "compatible"
- *   and "earlier" take the earlier instant and "later" the later one; in a spring-forward
- *   (DST-start) gap "compatible" and "later" move the wall clock forward by the gap length and
- *   "earlier" back by it; "reject" returns "" for both. It never re-resolves the exact-time
- *   result, so a time-only duration ignores it.
+ *   time. `disambiguation` applies ONLY to the intermediate wall-clock date-time after the date
+ *   portion, exactly as Temporal's GetEpochNanosecondsFor resolves it. It never re-resolves the
+ *   exact-time result.
  * - Compatibility: before 1.16.0 a date portion landing in a spring-forward gap was always moved
  *   forward, whatever `disambiguation` said, so "earlier" matched "compatible" and "reject" did not
  *   fail. Pass "compatible" (or omit it) to keep the forward result.
@@ -37,13 +34,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - There is no `offset` option (removed in 1.16.0): the intermediate wall clock is resolved from
  *   a plain date-time, which has no UTC offset for it to act on (Temporal
  *   `PlainDateTime#toZonedDateTime` reads only `disambiguation`).
- * - `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 "").
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), overflow ("constrain" | "reject")
+ * @param optionsArg optional settings for resolving a DST gap or overlap and an out-of-range date
  * @returns zoned ISO 8601 string on success, or "" on invalid input
  *
  * @example addZoned("2024-02-29T14:30:45.123-05:00[America/New_York]", { days: 1 }) // "2024-03-01T14:30:45.123-05:00[America/New_York]"
@@ -75,9 +70,7 @@ export function addZoned(value, units, optionsArg) {
             // TODO descriptive messages of what failed - likely could be GMT offset for historical changes and DST
             return "";
         }
-        const disambiguation = optionsArg?.disambiguation === undefined
-            ? "compatible"
-            : optionsArg.disambiguation;
+        const disambiguation = optionOrDefault(optionsArg?.disambiguation, "compatible");
         const overflow = resolveOverflow(optionsArg?.overflow);
         try {
             const calendar = calendarSystemOfZonedValue(value);

package/dist/zoned/calculate/cycleZoned.d.ts

@@ -13,21 +13,14 @@ import type { DateTimeCycleField, Disambiguation, Offset, Overflow } from "../..
  *   whatever DST edge case results (the wrapped local time landing in a gap or an overlap) exactly
  *   the way it resolves any other field-set call. This is deliberately simpler than deriving
  *   DST-aware wrap boundaries directly.
- * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"prefer"`, as Temporal's
- *   `ZonedDateTime#with` does: when the source's offset is still valid for the cycled wall time
- *   (a repeated fall-back hour), it is kept and `disambiguation` is not consulted. Pass
- *   `offset: "ignore"` to resolve the cycled wall time through `disambiguation` instead.
  * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
  *   to keep that resolution.
- * - `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 zoned ISO 8601 datetime 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"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
+ * @param options optional settings for rounding the step and resolving the cycled wall-clock time
  * @returns zoned ISO 8601 string with `field` cycled, or "" on invalid input
  *
  * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "hour", 1) // "2024-06-15T10:30:00-05:00[America/Chicago]"
@@ -40,8 +33,40 @@ import type { DateTimeCycleField, Disambiguation, Offset, Overflow } from "../..
  * @example cycleZoned("invalid", "hour", 1) // ""
  */
 export declare function cycleZoned(value: string, field: DateTimeCycleField, amount: number, options?: {
+    /**
+     * Whether to step to the next multiple of `amount` in the direction of its sign (up for a
+     * positive amount, down for a negative one) instead of adding `amount` to the current value. It
+     * is the next multiple, not the nearest one; see `cycleDate` and `cycleTime` for worked examples.
+     *
+     * @defaultValue `false`
+     */
     round?: boolean;
+    /**
+     * What happens when the result names a day its month does not have, such as cycling `month`
+     * from 31 January to February. `"constrain"` clamps to the last valid day; `"reject"` returns
+     * `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
+    /**
+     * How the new wall-clock time resolves when it falls in a DST gap or overlap and `offset` does
+     * not settle it. In a fall-back overlap `"compatible"` and `"earlier"` take the earlier instant
+     * and `"later"` the later one; in a spring-forward gap `"compatible"` and `"later"` move the
+     * wall clock forward by the gap length and `"earlier"` back by it. `"reject"` returns `""` for
+     * both.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
     disambiguation?: Disambiguation;
+    /**
+     * How the source's UTC offset is treated at the new wall-clock time, as in Temporal's
+     * `ZonedDateTime#with`. `"prefer"` keeps it while it is still valid there (a repeated fall-back
+     * hour) and otherwise resolves through `disambiguation`; `"ignore"` always resolves through
+     * `disambiguation`. `"use"` keeps the offset even when that moves the wall clock, and
+     * `"reject"` returns `""` when the offset is not valid for the new wall time.
+     *
+     * @defaultValue `"prefer"`, Temporal's default.
+     */
     offset?: Offset;
 }): string;

package/dist/zoned/calculate/cycleZoned.js

@@ -17,21 +17,14 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   whatever DST edge case results (the wrapped local time landing in a gap or an overlap) exactly
  *   the way it resolves any other field-set call. This is deliberately simpler than deriving
  *   DST-aware wrap boundaries directly.
- * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"prefer"`, as Temporal's
- *   `ZonedDateTime#with` does: when the source's offset is still valid for the cycled wall time
- *   (a repeated fall-back hour), it is kept and `disambiguation` is not consulted. Pass
- *   `offset: "ignore"` to resolve the cycled wall time through `disambiguation` instead.
  * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
  *   to keep that resolution.
- * - `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 zoned ISO 8601 datetime 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"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
+ * @param options optional settings for rounding the step and resolving the cycled wall-clock time
  * @returns zoned ISO 8601 string with `field` cycled, or "" on invalid input
  *
  * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "hour", 1) // "2024-06-15T10:30:00-05:00[America/Chicago]"

package/dist/zoned/calculate/diffZoned.d.ts

@@ -43,7 +43,7 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * @param value2 zoned ISO 8601 datetime string (end), optionally calendar-annotated
  * @param units date-time 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 diffZoned("2024-02-28T14:30:00+00:00[UTC]", "2024-03-01T15:30:00+00:00[UTC]", "days") // 2

package/dist/zoned/calculate/diffZoned.js

@@ -48,7 +48,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value2 zoned ISO 8601 datetime string (end), optionally calendar-annotated
  * @param units date-time 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 diffZoned("2024-02-28T14:30:00+00:00[UTC]", "2024-03-01T15:30:00+00:00[UTC]", "days") // 2

package/dist/zoned/calculate/diffZonedAsDuration.d.ts

@@ -32,7 +32,7 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * @param value1 zoned ISO 8601 datetime string (start), optionally calendar-annotated
  * @param value2 zoned ISO 8601 datetime string (end), optionally calendar-annotated
  * @param unit date-time unit to use as the duration's largestUnit, singular or plural (`"day"` or `"days"`)
- * @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 diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days") // "P2D" (wall-clock days; 47 elapsed hours)

package/dist/zoned/calculate/diffZonedAsDuration.js

@@ -35,7 +35,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 zoned ISO 8601 datetime string (start), optionally calendar-annotated
  * @param value2 zoned ISO 8601 datetime string (end), optionally calendar-annotated
  * @param unit date-time unit to use as the duration's largestUnit, singular or plural (`"day"` or `"days"`)
- * @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 diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days") // "P2D" (wall-clock days; 47 elapsed hours)

package/dist/zoned/calculate/endOfQuarterForZoned.d.ts

@@ -4,13 +4,13 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * - Calculates which quarter (1-4) the date falls into and returns the last moment of that quarter.
  * - Returns one nanosecond before the next local quarter starts in `value`'s own zone (see `floorToZone`), so the result is never before `value`: a quarter whose last local hour repeats (`Africa/Cairo`, 2010-09-30) ends with the second pass.
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
+ * - The end is written at nanosecond precision by default, so the string names the end itself.
  * - Validation is performed on the input.
  * - **Compatibility:** before 1.16.0 the default printed no fractional digits, which wrote a moment
  *   earlier than the end. Pass `{ fractionalSecondDigits: 0 }` to keep the previous string.
  *
  * @param value ISO ZonedDateTime string
- * @param optionsArg optional: fractionalSecondDigits (0 | 3 | 6 | 9, default 9)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns ISO ZonedDateTime string for the end of the quarter, or "" on invalid input
  *
  * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-03-31T23:59:59.999999999+00:00[UTC]"
@@ -21,5 +21,12 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example endOfQuarterForZoned("invalid") // ""
  */
 export declare function endOfQuarterForZoned(value: string, optionsArg?: {
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer than 9 digits truncate the string, as Temporal's `toString` does,
+     * so it names a moment before the end.
+     *
+     * @defaultValue `9`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/zoned/calculate/endOfQuarterForZoned.js

@@ -1,18 +1,19 @@
 import { zonedDateTimeFrom, zonedUnitEnd } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return the end of the quarter for a given zoned ISO datetime.
  *
  * - Calculates which quarter (1-4) the date falls into and returns the last moment of that quarter.
  * - Returns one nanosecond before the next local quarter starts in `value`'s own zone (see `floorToZone`), so the result is never before `value`: a quarter whose last local hour repeats (`Africa/Cairo`, 2010-09-30) ends with the second pass.
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
+ * - The end is written at nanosecond precision by default, so the string names the end itself.
  * - Validation is performed on the input.
  * - **Compatibility:** before 1.16.0 the default printed no fractional digits, which wrote a moment
  *   earlier than the end. Pass `{ fractionalSecondDigits: 0 }` to keep the previous string.
  *
  * @param value ISO ZonedDateTime string
- * @param optionsArg optional: fractionalSecondDigits (0 | 3 | 6 | 9, default 9)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns ISO ZonedDateTime string for the end of the quarter, or "" on invalid input
  *
  * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-03-31T23:59:59.999999999+00:00[UTC]"
@@ -32,9 +33,7 @@ export function endOfQuarterForZoned(value, optionsArg) {
         }
         // An end is next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
         // print an earlier instant than the end (Calendar & zone semantics §3).
-        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
-            ? 9
-            : optionsArg.fractionalSecondDigits;
+        const fractionalSecondDigits = optionOrDefault(optionsArg?.fractionalSecondDigits, 9);
         try {
             const end = zonedUnitEnd(zonedDateTimeFrom(value), "quarter");
             return end ? end.toString({ fractionalSecondDigits }) : "";

package/dist/zoned/calculate/endOfZoned.d.ts

@@ -4,13 +4,12 @@ import type { DateTimeUnit, FractionalDigit } from "../../types/index.js";
  * Return the end of the specified date-time `unit` for a given zoned ISO 8601 datetime string.
  *
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns the last instant of the real local `unit` containing `value` in its own zone — one nanosecond before the next bucket `floorToZone` would return — so the result is never before `value`. The second pass of New York's repeated fall-back hour ends at 01:59:59.999999999 −05:00, and `Australia/Lord_Howe`'s 90-minute fall-back hour ends in its new offset.
  * - A transition that reopens the previous local date makes that stretch its own bucket: `America/Goose_Bay`'s 00:01 fall-back on 7 November 2010 re-entered 6 November for 59 minutes, so the day holding `2010-11-06T23:30:00-04:00` ends at 23:59:59.999999999 −04:00.
  * - A midnight repeated on the same date stays one day: `America/Havana`'s 25-hour 2024-11-03 ends at 23:59:59.999999999 −05:00 from either pass of its repeated first hour.
  * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
  *   takes neither. Those ignored options were removed in 1.16.0.
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
+ * - The end is written at nanosecond precision by default, so the string names the end itself.
  * - Returns "" for invalid input.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
  *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
@@ -18,7 +17,7 @@ import type { DateTimeUnit, FractionalDigit } from "../../types/index.js";
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param optionsArg optional settings for the week's first day and the precision of the output string
  * @returns zoned ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-29T23:59:59.999999999+00:00[UTC]"
@@ -30,6 +29,20 @@ import type { DateTimeUnit, FractionalDigit } from "../../types/index.js";
  * @example endOfZoned("2024-11-03T00:30:00-04:00[America/Havana]", "day") // "2024-11-03T23:59:59.999999999-05:00[America/Havana]" (midnight repeated on the same date: one 25-hour day)
  */
 export declare function endOfZoned(value: string, unit: Temporal.SmallestUnit<DateTimeUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer than 9 digits truncate the string, as Temporal's `toString` does,
+     * so it names a moment before the end.
+     *
+     * @defaultValue `9`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/zoned/calculate/endOfZoned.js

@@ -4,13 +4,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the end of the specified date-time `unit` for a given zoned ISO 8601 datetime string.
  *
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns the last instant of the real local `unit` containing `value` in its own zone — one nanosecond before the next bucket `floorToZone` would return — so the result is never before `value`. The second pass of New York's repeated fall-back hour ends at 01:59:59.999999999 −05:00, and `Australia/Lord_Howe`'s 90-minute fall-back hour ends in its new offset.
  * - A transition that reopens the previous local date makes that stretch its own bucket: `America/Goose_Bay`'s 00:01 fall-back on 7 November 2010 re-entered 6 November for 59 minutes, so the day holding `2010-11-06T23:30:00-04:00` ends at 23:59:59.999999999 −04:00.
  * - A midnight repeated on the same date stays one day: `America/Havana`'s 25-hour 2024-11-03 ends at 23:59:59.999999999 −05:00 from either pass of its repeated first hour.
  * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
  *   takes neither. Those ignored options were removed in 1.16.0.
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
+ * - The end is written at nanosecond precision by default, so the string names the end itself.
  * - Returns "" for invalid input.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
  *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
@@ -18,7 +17,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param optionsArg optional settings for the week's first day and the precision of the output string
  * @returns zoned ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-29T23:59:59.999999999+00:00[UTC]"

package/dist/zoned/calculate/getLocaleZonedEndOfWeek.d.ts

@@ -11,8 +11,8 @@ import type { FractionalDigit } from "../../types/index.js";
  *   its own zone — one nanosecond before the next week bucket starts — so
  *   the result is never before `value`.
  * - The end is written at nanosecond precision by default (`.999999999`), like `endOfZoned`, so the
- *   string names the end itself. An explicit `fractionalSecondDigits` truncates it, as Temporal's
- *   `toString` does; pass `{ fractionalSecondDigits: 0 }` to keep the previous whole-second string.
+ *   string names the end itself. Pass `{ fractionalSecondDigits: 0 }` to keep the previous
+ *   whole-second string.
  * - Distinct from `endOfZoned(value, "week", { weekStartsOn })`, which
  *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
  *   it from a locale.
@@ -23,7 +23,7 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * @param value zoned ISO 8601 datetime string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: fractionalSecondDigits (number, default 9)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 string for the end of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59.999999999+00:00[UTC]" (Saturday)
@@ -34,5 +34,12 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example getLocaleZonedEndOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["fr-FR", "en-US"]) // "2024-05-19T23:59:59.999999999+02:00[Europe/Berlin]"
  */
 export declare function getLocaleZonedEndOfWeek(value: string, locale: string | string[], optionsArg?: {
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer than 9 digits truncate the string, as Temporal's `toString` does,
+     * so it names a moment before the end.
+     *
+     * @defaultValue `9`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/zoned/calculate/getLocaleZonedEndOfWeek.js

@@ -1,6 +1,7 @@
 import { getLocaleFirstDayOfWeek, zonedDateTimeFrom, zonedUnitEnd, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return the end of the week containing `value`, using `locale`'s first
  * day of week (e.g. en-US: week ends Saturday, fr-FR: week ends Sunday).
@@ -13,8 +14,8 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   its own zone — one nanosecond before the next week bucket starts — so
  *   the result is never before `value`.
  * - The end is written at nanosecond precision by default (`.999999999`), like `endOfZoned`, so the
- *   string names the end itself. An explicit `fractionalSecondDigits` truncates it, as Temporal's
- *   `toString` does; pass `{ fractionalSecondDigits: 0 }` to keep the previous whole-second string.
+ *   string names the end itself. Pass `{ fractionalSecondDigits: 0 }` to keep the previous
+ *   whole-second string.
  * - Distinct from `endOfZoned(value, "week", { weekStartsOn })`, which
  *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
  *   it from a locale.
@@ -25,7 +26,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value zoned ISO 8601 datetime string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: fractionalSecondDigits (number, default 9)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 string for the end of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59.999999999+00:00[UTC]" (Saturday)
@@ -40,9 +41,7 @@ export function getLocaleZonedEndOfWeek(value, locale, optionsArg) {
         if (!isOptionsArgument(optionsArg)) {
             return "";
         }
-        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
-            ? 9
-            : optionsArg.fractionalSecondDigits;
+        const fractionalSecondDigits = optionOrDefault(optionsArg?.fractionalSecondDigits, 9);
         if (!isValidZonedDateTime(value))
             return "";
         const firstDay = getLocaleFirstDayOfWeek(locale);

package/dist/zoned/calculate/getLocaleZonedStartOfWeek.d.ts

@@ -21,7 +21,7 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * @param value zoned ISO 8601 datetime string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: fractionalSecondDigits (number)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 string for the start of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
@@ -32,5 +32,11 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example getLocaleZonedStartOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["en-US", "fr-FR"]) // "2024-05-12T00:00:00+02:00[Europe/Berlin]"
  */
 export declare function getLocaleZonedStartOfWeek(value: string, locale: string | string[], optionsArg?: {
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. A start has no sub-second part, so any digits written are zeros.
+     *
+     * @defaultValue `0`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/zoned/calculate/getLocaleZonedStartOfWeek.js

@@ -1,6 +1,7 @@
 import { getLocaleFirstDayOfWeek, zonedDateTimeFrom, zonedUnitStart, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return the start of the week containing `value`, using `locale`'s
  * first day of week (e.g. en-US: Sunday, fr-FR: Monday).
@@ -23,7 +24,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value zoned ISO 8601 datetime string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: fractionalSecondDigits (number)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 string for the start of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
@@ -38,9 +39,7 @@ export function getLocaleZonedStartOfWeek(value, locale, optionsArg) {
         if (!isOptionsArgument(optionsArg)) {
             return "";
         }
-        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
-            ? 0
-            : optionsArg.fractionalSecondDigits;
+        const fractionalSecondDigits = optionOrDefault(optionsArg?.fractionalSecondDigits, 0);
         if (!isValidZonedDateTime(value))
             return "";
         const firstDay = getLocaleFirstDayOfWeek(locale);

package/dist/zoned/calculate/roundZoned.d.ts

@@ -3,9 +3,6 @@ import { Temporal } from "@js-temporal/polyfill";
  * Round an ISO 8601 zoned datetime string to the specified unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts "day" and time units: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Date units ("year", "month", "week") return "". This is the Temporal spec, not a polyfill
  *   limitation: `ZonedDateTime.prototype.round` accepts time units and "day" only
  *   (ValidateTemporalUnitValue with ~time~ and « day »).
@@ -20,7 +17,7 @@ import { Temporal } from "@js-temporal/polyfill";
  *   minutes later. Use `floorToZone` for a boundary that never exceeds the instant.
  *
  * @param value ISO 8601 zoned datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode
+ * @param options the unit to round to, with an optional increment and rounding mode
  * @returns Rounded ISO 8601 zoned datetime string, or "" on invalid input
  *
  * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-04:00[America/New_York]"
@@ -31,7 +28,27 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example roundZoned("invalid", { smallestUnit: "hour" }) // ""
  */
 export declare function roundZoned(value: string, options: {
+    /**
+     * The unit to round to: `"day"` or a time unit from `"hour"` to `"nanosecond"`, in its singular
+     * or plural form, as Temporal's GetTemporalUnitValuedOption accepts both. It also sets how many
+     * fractional-second digits the result is written with.
+     */
     smallestUnit: Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+    /**
+     * The size of the step, in `smallestUnit`s, that the value is rounded to a multiple of, such as
+     * `15` for quarter hours. It must divide evenly into the next larger unit and be smaller than it,
+     * and must be `1` for `"day"`; any other value returns `""`. A non-integer is truncated first,
+     * as Temporal does.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a value between two multiples goes. `"halfExpand"` picks the nearest multiple and
+     * sends a tie up; `"floor"` and `"trunc"` always go down, `"ceil"` and `"expand"` always up. The
+     * other `half` modes differ from `"halfExpand"` only in how a tie breaks.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
 }): string;

package/dist/zoned/calculate/roundZoned.js

@@ -18,9 +18,6 @@ function isZonedRoundingUnit(unit) {
  * Round an ISO 8601 zoned datetime string to the specified unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts "day" and time units: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Date units ("year", "month", "week") return "". This is the Temporal spec, not a polyfill
  *   limitation: `ZonedDateTime.prototype.round` accepts time units and "day" only
  *   (ValidateTemporalUnitValue with ~time~ and « day »).
@@ -35,7 +32,7 @@ function isZonedRoundingUnit(unit) {
  *   minutes later. Use `floorToZone` for a boundary that never exceeds the instant.
  *
  * @param value ISO 8601 zoned datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode
+ * @param options the unit to round to, with an optional increment and rounding mode
  * @returns Rounded ISO 8601 zoned datetime string, or "" on invalid input
  *
  * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-04:00[America/New_York]"
@@ -50,9 +47,8 @@ export function roundZoned(value, options) {
         if (!isObject(options))
             return "";
         const { roundingIncrement, roundingMode } = options;
-        const smallestUnit = typeof options.smallestUnit === "string"
-            ? resolveDateTimeUnit(options.smallestUnit)
-            : options.smallestUnit;
+        // One read (GetOption): resolveDateTimeUnit returns a value that is not a string unchanged.
+        const smallestUnit = resolveDateTimeUnit(options.smallestUnit);
         if (!isValidZonedDateTime(value))
             return "";
         // Temporal ZonedDateTime.prototype.round: ValidateTemporalUnitValue(smallestUnit, ~time~, « day »)