@northguild/gmt 1.17.0 → 1.19.0

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

@@ -10,24 +10,30 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  *   equivalent to `.with()`'s, because Temporal's `ZonedDateTime.prototype.add()` doesn't accept
  *   `disambiguation`/`offset` at all.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op. `calendar`, `timeZone`, and `offset` are
- *   deliberately excluded from `fields` — this function only sets date/time components, never
- *   the zone or calendar identity, and `offset` is controlled separately via `options.offset`.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- *   (resulting in "").
- * - `offset` defaults to `"prefer"`, as Temporal's `ZonedDateTime#with` does: when the source's
- *   offset is still valid for the new wall time (a repeated fall-back hour), it is kept and
- *   `disambiguation` is not consulted; pass `offset: "ignore"` to re-resolve the wall time through
- *   `disambiguation` instead. In a gap the source offset cannot hold, so `disambiguation` applies.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
+ * - `calendar`, `timeZone`, and `offset` are deliberately excluded from `fields` — this function
+ *   only sets date/time components, never the zone or calendar identity, and `offset` is
+ *   controlled separately via `options.offset`.
  * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
  *   to keep that resolution.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
+ * @param options optional settings for resolving an out-of-range date and the new wall-clock time
  * @returns zoned ISO 8601 string with fields set, or "" on invalid input
  *
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"
@@ -36,10 +42,35 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset defaults to "prefer": the source's -05:00 is still valid, so it is kept and "reject" never fires)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "ignore" }) // "" (offset "ignore" re-resolves the repeated 01:00, and "reject" throws)
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: "9" }) // "" (not converted)
  * @example setZoned("invalid", { hour: 9 }) // ""
  */
-export declare function setZoned(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+export declare function setZoned(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset" | "era" | "eraYear">, options?: {
+    /**
+     * What happens when the result names a day its month does not have, such as setting `month: 2`
+     * on 31 January. `"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/setZoned.js

@@ -1,7 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow, withZonedFields, zonedDateTimeFrom, } from "../../internal/index.js";
+import { DATE_TIME_FIELDS, readSetFields, resolveOverflow, withZonedFields, zonedDateTimeFrom, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return a zoned ISO 8601 datetime string with the given `fields` set on `value`.
  *
@@ -12,24 +13,30 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   equivalent to `.with()`'s, because Temporal's `ZonedDateTime.prototype.add()` doesn't accept
  *   `disambiguation`/`offset` at all.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op. `calendar`, `timeZone`, and `offset` are
- *   deliberately excluded from `fields` — this function only sets date/time components, never
- *   the zone or calendar identity, and `offset` is controlled separately via `options.offset`.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- *   (resulting in "").
- * - `offset` defaults to `"prefer"`, as Temporal's `ZonedDateTime#with` does: when the source's
- *   offset is still valid for the new wall time (a repeated fall-back hour), it is kept and
- *   `disambiguation` is not consulted; pass `offset: "ignore"` to re-resolve the wall time through
- *   `disambiguation` instead. In a gap the source offset cannot hold, so `disambiguation` applies.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
+ * - `calendar`, `timeZone`, and `offset` are deliberately excluded from `fields` — this function
+ *   only sets date/time components, never the zone or calendar identity, and `offset` is
+ *   controlled separately via `options.offset`.
  * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
  *   to keep that resolution.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
+ * @param options optional settings for resolving an out-of-range date and the new wall-clock time
  * @returns zoned ISO 8601 string with fields set, or "" on invalid input
  *
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"
@@ -38,6 +45,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset defaults to "prefer": the source's -05:00 is still valid, so it is kept and "reject" never fires)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "ignore" }) // "" (offset "ignore" re-resolves the repeated 01:00, and "reject" throws)
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: "9" }) // "" (not converted)
  * @example setZoned("invalid", { hour: 9 }) // ""
  */
 export function setZoned(value, fields, options) {
@@ -48,18 +56,19 @@ export function setZoned(value, fields, options) {
         if (!isValidZonedDateTime(value))
             return "";
         const overflow = resolveOverflow(options?.overflow);
-        const disambiguation = options?.disambiguation === undefined
-            ? "compatible"
-            : options.disambiguation;
+        const disambiguation = optionOrDefault(options?.disambiguation, "compatible");
         // Temporal ZonedDateTime#with's own default: keep the source offset while it is still valid.
-        const offset = options?.offset === undefined ? "prefer" : options.offset;
+        const offset = optionOrDefault(options?.offset, "prefer");
         try {
             const zoned = zonedDateTimeFrom(value);
-            // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
-            // properties found") rather than treating it as a no-op, so short-circuit here.
-            if (Object.keys(fields).length === 0)
+            const set = readSetFields(fields, DATE_TIME_FIELDS);
+            if (set === null)
+                return "";
+            // Only the values readSetFields checked reach Temporal, on both paths of withZonedFields. An
+            // empty result sets nothing: a no-op here, where Temporal's with() would throw.
+            if (Object.keys(set).length === 0)
                 return zoned.toString();
-            return withZonedFields(zoned, fields, {
+            return withZonedFields(zoned, set, {
                 overflow,
                 disambiguation,
                 offset,

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

@@ -4,11 +4,10 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * - Calculates which quarter (1-4) the date falls into and returns the first instant of that quarter, with every field below the day reset — milliseconds, microseconds and nanoseconds included.
  * - Returns the real start of the local quarter in `value`'s own zone (see `floorToZone`), so the result is never after `value`: a skipped first midnight starts at the quarter's first real instant, and a repeated one (`Africa/Tunis`, 1978-10-01) at its first pass.
- * - `fractionalSecondDigits` controls how many fractional seconds are included in the output: 0 (default — no fractional seconds), 3 (milliseconds), 6 (microseconds), or 9 (nanoseconds).
  * - Validation is performed on the input.
  *
  * @param value ISO ZonedDateTime string
- * @param optionsArg optional: fractionalSecondDigits (0 | 3 | 6 | 9, default 0)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns ISO ZonedDateTime string for the start of the quarter, or "" on invalid input
  *
  * @example startOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-01-01T00:00:00+00:00[UTC]"
@@ -18,5 +17,11 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example startOfQuarterForZoned("invalid") // ""
  */
 export declare function startOfQuarterForZoned(value: 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/startOfQuarterForZoned.js

@@ -1,16 +1,16 @@
 import { 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 quarter for a given zoned ISO datetime.
  *
  * - Calculates which quarter (1-4) the date falls into and returns the first instant of that quarter, with every field below the day reset — milliseconds, microseconds and nanoseconds included.
  * - Returns the real start of the local quarter in `value`'s own zone (see `floorToZone`), so the result is never after `value`: a skipped first midnight starts at the quarter's first real instant, and a repeated one (`Africa/Tunis`, 1978-10-01) at its first pass.
- * - `fractionalSecondDigits` controls how many fractional seconds are included in the output: 0 (default — no fractional seconds), 3 (milliseconds), 6 (microseconds), or 9 (nanoseconds).
  * - Validation is performed on the input.
  *
  * @param value ISO ZonedDateTime string
- * @param optionsArg optional: fractionalSecondDigits (0 | 3 | 6 | 9, default 0)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns ISO ZonedDateTime string for the start of the quarter, or "" on invalid input
  *
  * @example startOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-01-01T00:00:00+00:00[UTC]"
@@ -27,9 +27,7 @@ export function startOfQuarterForZoned(value, optionsArg) {
         if (!isValidZonedDateTime(value)) {
             return "";
         }
-        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
-            ? 0
-            : optionsArg.fractionalSecondDigits;
+        const fractionalSecondDigits = optionOrDefault(optionsArg?.fractionalSecondDigits, 0);
         try {
             const start = zonedUnitStart(zonedDateTimeFrom(value), "quarter");
             return start ? start.toString({ fractionalSecondDigits }) : "";

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

@@ -4,18 +4,16 @@ import type { DateTimeUnit, FractionalDigit } from "../../types/index.js";
  * Return the start 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 real start of the local `unit` containing `value` in its own zone — the same bucket `floorToZone` uses — so the result is never after `value`. A local hour `Pacific/Chatham`'s spring-forward leaves only 15 minutes long starts at 03:45, the second pass of New York's repeated fall-back hour starts at its own 01:00 (−05:00), and a day whose midnight was skipped starts at its first real instant.
  * - A transition that reopens the previous local date makes that stretch its own bucket. `America/Goose_Bay` fell back at 00:01 on 7 November 2010, re-entering 6 November for 59 minutes, so `2010-11-06T23:30:00-04:00` has a day that starts at 23:01 — consistent with `floorToZone`, `bucketRange` and `intervalCountZoned`.
  * - A midnight repeated on the same date stays one day: `America/Havana`'s 2024-11-03 starts at its first 00:00 (−04:00) and runs 25 hours, matching Temporal's `startOfDay()`.
  * - 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.
- * - `fractionalSecondDigits` defaults to 3, 6 or 9 for "millisecond", "microsecond" or "nanosecond", and 0 otherwise.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the start
- * @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 start of the specified unit, or "" on invalid input
  *
  * @example startOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-01T00:00:00+00:00[UTC]"
@@ -26,6 +24,20 @@ import type { DateTimeUnit, FractionalDigit } from "../../types/index.js";
  * @example startOfZoned("2024-11-03T00:30:00-05:00[America/Havana]", "day") // "2024-11-03T00:00:00-04:00[America/Havana]" (midnight repeated on the same date: one 25-hour day)
  */
 export declare function startOfZoned(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 digits than `unit` names truncate, as Temporal's `toString` does.
+     *
+     * @defaultValue The digits `unit` names: `3` for `"millisecond"`, `6` for `"microsecond"`, `9`
+     * for `"nanosecond"` and `0` for any coarser unit.
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/zoned/calculate/startOfZoned.js

@@ -4,18 +4,16 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the start 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 real start of the local `unit` containing `value` in its own zone — the same bucket `floorToZone` uses — so the result is never after `value`. A local hour `Pacific/Chatham`'s spring-forward leaves only 15 minutes long starts at 03:45, the second pass of New York's repeated fall-back hour starts at its own 01:00 (−05:00), and a day whose midnight was skipped starts at its first real instant.
  * - A transition that reopens the previous local date makes that stretch its own bucket. `America/Goose_Bay` fell back at 00:01 on 7 November 2010, re-entering 6 November for 59 minutes, so `2010-11-06T23:30:00-04:00` has a day that starts at 23:01 — consistent with `floorToZone`, `bucketRange` and `intervalCountZoned`.
  * - A midnight repeated on the same date stays one day: `America/Havana`'s 2024-11-03 starts at its first 00:00 (−04:00) and runs 25 hours, matching Temporal's `startOfDay()`.
  * - 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.
- * - `fractionalSecondDigits` defaults to 3, 6 or 9 for "millisecond", "microsecond" or "nanosecond", and 0 otherwise.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the start
- * @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 start of the specified unit, or "" on invalid input
  *
  * @example startOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-01T00:00:00+00:00[UTC]"

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

@@ -13,13 +13,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 subtracted 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.
@@ -31,13 +27,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. subtracting
- *   1 month from Mar 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 subtract
- * @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 subtractZoned("2024-03-10T12:00:00-04:00[America/New_York]", { days: 5 }) // "2024-03-05T12:00:00-05:00[America/New_York]"
@@ -54,6 +48,22 @@ import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types
  * @example subtractZoned("2024-03-10T14:30:00-04:00[u-ca=hebrew][America/New_York]", { days: 1 }) // "" (calendar before zone is not RFC 9557)
  */
 export declare function subtractZoned(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 subtracting 1 month
+     * from 31 March. `"constrain"` clamps to the last valid day; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/zoned/calculate/subtractZoned.js

@@ -1,8 +1,9 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalendar, isValidAmount, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
+import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalendar, parseCalendarZonedValue, readDurationUnits, resolveOverflow, } from "../../internal/index.js";
 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";
 /**
  * Subtract a temporal amount from a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.
  *
@@ -17,13 +18,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 subtracted 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.
@@ -35,13 +32,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. subtracting
- *   1 month from Mar 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 subtract
- * @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 subtractZoned("2024-03-10T12:00:00-04:00[America/New_York]", { days: 5 }) // "2024-03-05T12:00:00-05:00[America/New_York]"
@@ -63,16 +58,11 @@ export function subtractZoned(value, units, optionsArg) {
             return "";
         }
         const validZonedDateTime = isValidCalendarZonedDateTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validZonedDateTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validZonedDateTime || amounts === null) {
             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);
@@ -80,7 +70,7 @@ export function subtractZoned(value, units, optionsArg) {
                 return "";
             }
             const zoned = parseCalendarZonedValue(value);
-            const subtracted = addToZonedDisambiguated(zoned, units, -1, {
+            const subtracted = addToZonedDisambiguated(zoned, amounts, -1, {
                 overflow,
                 disambiguation,
             });

package/dist/zoned/compare/areZonedEqualBy.d.ts

@@ -6,8 +6,11 @@ import type { DateTimeUnit } from "../../types/index.js";
  * - Equality is measured on each value's own local wall-clock fields (its own
  *   time zone), not on the underlying instant or time zone identifier — the
  *   same instant can be "the same day" in one zone and a different day in
- *   another, and this function answers per each value's own zone, the way
- *   Luxon's `dt.hasSame(other, unit)` does for zoned `DateTime`s.
+ *   another, and this function answers per each value's own zone, because a
+ *   `Temporal.ZonedDateTime` reads its calendar and clock fields in its own
+ *   time zone.
+ * - Comparison: Luxon's `dt.hasSame(other, unit)` also compares the two values'
+ *   local times.
  * - Each value's start-of-unit is its real local bucket (see `startOfZoned`), so a bucket a
  *   zone transition shortened is still its own unit: in `Pacific/Chatham` on its 2024
  *   spring-forward, 03:50 and 04:05 are different hours, because the 03:00 hour lasted only
@@ -18,10 +21,9 @@ import type { DateTimeUnit } from "../../types/index.js";
  *   compared by their buckets' local labels, since their instants never line up.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areZonedEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areZonedEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areZonedEqualBy(a, b, "year")`
@@ -29,7 +31,7 @@ import type { DateTimeUnit } from "../../types/index.js";
  * @param value1 first zoned ISO datetime string
  * @param value2 second zoned ISO datetime string
  * @param unit date or time unit, singular or plural, to compare by
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg optional setting for the week's first day
  * @returns true if both values share the same local start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areZonedEqualBy("2024-03-15T10:00:00-04:00[America/New_York]", "2024-03-15T20:00:00+01:00[Europe/Berlin]", "day") // true (both are local March 15 in their own zone)
@@ -39,5 +41,12 @@ import type { DateTimeUnit } from "../../types/index.js";
  * @example areZonedEqualBy("invalid", "2024-03-15T10:00:00-04:00[America/New_York]", "day") // false
  */
 export declare function areZonedEqualBy(value1: string, value2: 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
+     * false, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): boolean;

package/dist/zoned/compare/areZonedEqualBy.js

@@ -12,8 +12,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Equality is measured on each value's own local wall-clock fields (its own
  *   time zone), not on the underlying instant or time zone identifier — the
  *   same instant can be "the same day" in one zone and a different day in
- *   another, and this function answers per each value's own zone, the way
- *   Luxon's `dt.hasSame(other, unit)` does for zoned `DateTime`s.
+ *   another, and this function answers per each value's own zone, because a
+ *   `Temporal.ZonedDateTime` reads its calendar and clock fields in its own
+ *   time zone.
+ * - Comparison: Luxon's `dt.hasSame(other, unit)` also compares the two values'
+ *   local times.
  * - Each value's start-of-unit is its real local bucket (see `startOfZoned`), so a bucket a
  *   zone transition shortened is still its own unit: in `Pacific/Chatham` on its 2024
  *   spring-forward, 03:50 and 04:05 are different hours, because the 03:00 hour lasted only
@@ -24,10 +27,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   compared by their buckets' local labels, since their instants never line up.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areZonedEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areZonedEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areZonedEqualBy(a, b, "year")`
@@ -35,7 +37,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 first zoned ISO datetime string
  * @param value2 second zoned ISO datetime string
  * @param unit date or time unit, singular or plural, to compare by
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg optional setting for the week's first day
  * @returns true if both values share the same local start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areZonedEqualBy("2024-03-15T10:00:00-04:00[America/New_York]", "2024-03-15T20:00:00+01:00[Europe/Berlin]", "day") // true (both are local March 15 in their own zone)

package/dist/zoned/compare/isBetweenZoned.d.ts

@@ -7,13 +7,25 @@
  * @param zoned ISO ZonedDateTime string to check
  * @param start ISO ZonedDateTime string for the start of the range
  * @param end ISO ZonedDateTime string for the end of the range
- * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param options optional settings for whether each end of the range is included
  * @returns boolean indicating whether zoned is between start and end
  *
  * @example isBetweenZoned("2024-02-29T12:00:00+00:00[UTC]", "2024-02-29T11:00:00+00:00[UTC]", "2024-02-29T13:00:00+00:00[UTC]") // true
  * @example isBetweenZoned("invalid", "2024-02-29T11:00:00+00:00[UTC]", "2024-02-29T13:00:00+00:00[UTC]") // false
  */
 export declare function isBetweenZoned(zoned: string, start: string, end: string, options?: {
+    /**
+     * Whether `zoned` at the same instant as `start` counts as inside the range. `false` requires
+     * it to be after `start`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveStart?: boolean;
+    /**
+     * Whether `zoned` at the same instant as `end` counts as inside the range. `false` requires it
+     * to be before `end`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveEnd?: boolean;
 }): boolean;

package/dist/zoned/compare/isBetweenZoned.js

@@ -3,6 +3,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { zonedDateTimeFrom } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return true when `zoned` is between `start` and `end` (inclusive by default).
  *
@@ -12,7 +13,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param zoned ISO ZonedDateTime string to check
  * @param start ISO ZonedDateTime string for the start of the range
  * @param end ISO ZonedDateTime string for the end of the range
- * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param options optional settings for whether each end of the range is included
  * @returns boolean indicating whether zoned is between start and end
  *
  * @example isBetweenZoned("2024-02-29T12:00:00+00:00[UTC]", "2024-02-29T11:00:00+00:00[UTC]", "2024-02-29T13:00:00+00:00[UTC]") // true
@@ -27,8 +28,8 @@ export function isBetweenZoned(zoned, start, end, options) {
         // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
         // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
         // behaves here exactly as `0` and `""` already do.
-        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
-        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
+        const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
         if (!isValidZonedDateTime(zoned) ||
             !isValidZonedDateTime(start) ||
             !isValidZonedDateTime(end)) {