@northguild/gmt 1.17.0 → 1.18.0

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

@@ -14,20 +14,13 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  *   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.
  * - **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]"
@@ -39,7 +32,31 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  * @example setZoned("invalid", { hour: 9 }) // ""
  */
 export declare function setZoned(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, 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

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { 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`.
  *
@@ -16,20 +17,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   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.
  * - **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]"
@@ -48,11 +42,9 @@ 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

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

@@ -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";
 /**
  * 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]"
@@ -70,9 +65,7 @@ export function subtractZoned(value, units, optionsArg) {
         if (!validZonedDateTime || !validUnits || !validAmounts) {
             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/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)) {

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

@@ -1,17 +1,38 @@
 /**
  * Check whether a zoned value's instant falls within daylight saving time.
  *
- * - The third DST-related function in the roadmap, and distinct from the
- *   other two — see docs/dst-disambiguation.md for the full four-way split:
- *   `hasDaylightSaving(timeZone)` asks whether a zone observes DST *at all*
- *   (zone-level, no instant); `listDstTransitions(timeZone, year)` asks
- *   *where* a zone's transitions fall (enumerates instants);
- *   `isInDaylightSaving(value)` asks whether *this particular instant* is
- *   currently in DST. `disambiguation`/`offset` (Group C) are a fourth,
- *   orthogonal concern: what to do when construction lands on an ambiguous
- *   or nonexistent instant.
- * - Returns false for invalid input, and false for a zone that doesn't
- *   observe DST at all.
+ * - The rule is GMT's own definition, not the tz database's daylight flag. No JavaScript API
+ *   exposes that flag, and it cannot be worked out from offsets.
+ * - The rule: daylight time runs from a forward change of the zone's clocks to the backward
+ *   change that undoes it. A backward change undoes the most recent forward change of the same
+ *   size not yet undone, if it comes less than 365 days after it. The instant is in daylight
+ *   time when it is at or after such a forward change and before its backward change.
+ * - Read from the zone's offset changes in the runtime's time zone data
+ *   (`getTimeZoneTransition`); GMT holds no zone data. The answer changes only at a clock
+ *   change, and the answer for a past instant can change when the runtime's data learns that a
+ *   zone stopped changing its clocks.
+ * - A forward change never undone, or undone 365 days or more later, is a change of standard
+ *   time: `Europe/Istanbul` is on standard time from its last advance in March 2016.
+ * - The higher of two alternating offsets is the daylight one, as in the tz database's rearguard
+ *   form. Its main form reverses `Europe/Dublin` (winter is its daylight time, a negative save)
+ *   and `Africa/Casablanca` (the Ramadan weeks are); here Dublin's summer and Casablanca's
+ *   months at `+01:00` are daylight time.
+ * - Read as standard time, because the offsets do not show otherwise:
+ *   - the last summer before a zone kept its daylight offset for good (the tz database dates
+ *     Istanbul's switch 2016-09-07, with no clock change);
+ *   - a daylight period held 365 days or longer (`America/Santiago` 2014 to 2016);
+ *   - a daylight period that began, ended or was interrupted by a move of standard time, so the
+ *     clocks went back by another amount or not at all (`America/Kentucky/Monticello` 2000), or
+ *     the offset changed part-way through and the rest, or all, of the period is not paired
+ *     (`Asia/Tomsk` 2002, `Asia/Jerusalem` 1948);
+ *   - a daylight period whose end is past the last instant Temporal can represent.
+ * - Read as daylight time: a move of standard time reversed by the same amount less than 365
+ *   days later (`America/Metlakatla` 2018 to 2019).
+ * - The other DST functions answer other questions: `hasDaylightSaving(timeZone, { at })` whether
+ *   a zone observes DST at an instant, `getDstTransitions(timeZone, year)` where its offset
+ *   changes fall, and `classifyLocal` whether a wall time is ambiguous. See
+ *   docs/dst-disambiguation.md.
+ * - Returns false for invalid input, and for a zone with a fixed offset.
  *
  * @param value zoned ISO 8601 datetime string
  * @returns true if the instant is in daylight saving time, false otherwise or on invalid input
@@ -20,6 +41,12 @@
  * @example isInDaylightSaving("2024-01-15T12:00:00-05:00[America/New_York]") // false
  * @example isInDaylightSaving("2024-01-15T12:00:00+11:00[Australia/Sydney]") // true (southern-hemisphere summer)
  * @example isInDaylightSaving("2024-07-15T12:00:00+09:00[Asia/Tokyo]") // false (Asia/Tokyo has no DST)
+ * @example isInDaylightSaving("2015-07-01T12:00:00+03:00[Europe/Istanbul]") // true (undone 2015-11-08)
+ * @example isInDaylightSaving("2016-07-01T12:00:00+03:00[Europe/Istanbul]") // false (the March 2016 advance was never undone)
+ * @example isInDaylightSaving("2016-12-01T12:00:00+03:00[Europe/Istanbul]") // false (permanent +03:00)
+ * @example isInDaylightSaving("2019-07-15T12:00:00+01:00[Europe/Dublin]") // true
+ * @example isInDaylightSaving("2019-12-01T12:00:00+01:00[Africa/Casablanca]") // true (put back 2020-04-19)
+ * @example isInDaylightSaving("2019-07-15T12:00:00+00:00[UTC]") // false
  * @example isInDaylightSaving("invalid") // false
  */
 export declare function isInDaylightSaving(value: string): boolean;