@northguild/gmt 1.16.0 → 1.18.0

package/dist/zoned/format/formatZonedRange.js

@@ -1,6 +1,7 @@
 import { normalizeDateTime, zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Format a zoned datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
@@ -61,7 +62,7 @@ export function formatZonedRange(from, to, locale, options) {
         // an Instant format resolves to (GetDateTimeFormat ~any~, ~all~, ~all~), so
         // the requested fields and widths are kept. A `timeZone` option is rejected
         // rather than silently overridden.
-        const formatOptions = instantFormatOptions(options ?? {}, zdt1.timeZoneId, "all");
+        const formatOptions = instantFormatOptions(readDateTimeFormatOptions(options), zdt1.timeZoneId, "all");
         if (formatOptions === null) {
             return "";
         }

package/dist/zoned/format/formatZonedToParts.d.ts

@@ -5,8 +5,7 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
@@ -24,8 +23,11 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   whitespace normalisation.
  * - A ZonedDateTime is formatted in its own zone: a `timeZone` option returns
  *   `[]`, as `ZonedDateTime#toLocaleString` throws a TypeError for one.
- * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
- *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
+ * - The literal before the day period depends on the runtime. CLDR 42 (ICU 72) put U+202F NARROW
+ *   NO-BREAK SPACE there for `en-US`; Node 22 and 24 return it in the parts, and Node 26 returns
+ *   an ordinary space (U+0020) instead. Both were checked on those runtimes. The examples show the
+ *   Node 22 and 24 form, written as `"\u202f"` so the difference is visible. Treat the two
+ *   characters as equal when you compare parts.
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts, with
  *   no time zone name. Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
@@ -48,6 +50,15 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * @example formatZonedToParts("2024-02-03T14:30:00-05:00[America/New_York]", "en-US", null as never) // [] (null options, as ECMA-402 rejects them)
  */
 export declare function formatZonedToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
+    /**
+     * The kind of part, named as ECMA-402 `Intl.DateTimeFormat.prototype.formatToParts` names it: a
+     * field such as `"year"`, `"month"` or `"day"`, or `"literal"` for the separator text between
+     * fields.
+     */
     type: string;
+    /**
+     * The text of the part in the requested locale, exactly as the formatter wrote it. Joining every
+     * `value` in array order gives the whole formatted text.
+     */
     value: string;
 }>;

package/dist/zoned/format/formatZonedToParts.js

@@ -1,14 +1,14 @@
 import { isValidZonedDateTime } from "../validate/index.js";
 import { zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return the locale-formatted parts of a ZonedDateTime.
  *
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
@@ -26,8 +26,11 @@ import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
  *   whitespace normalisation.
  * - A ZonedDateTime is formatted in its own zone: a `timeZone` option returns
  *   `[]`, as `ZonedDateTime#toLocaleString` throws a TypeError for one.
- * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
- *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
+ * - The literal before the day period depends on the runtime. CLDR 42 (ICU 72) put U+202F NARROW
+ *   NO-BREAK SPACE there for `en-US`; Node 22 and 24 return it in the parts, and Node 26 returns
+ *   an ordinary space (U+0020) instead. Both were checked on those runtimes. The examples show the
+ *   Node 22 and 24 form, written as `"\u202f"` so the difference is visible. Treat the two
+ *   characters as equal when you compare parts.
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts, with
  *   no time zone name. Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
@@ -63,7 +66,7 @@ export function formatZonedToParts(value, locale, options) {
         // formatter's timeZone, with the options ZonedDateTime#toLocaleString
         // resolves to (GetDateTimeFormat ~any~, ~zoned-date-time~, ~all~).
         const zonedDateTime = zonedDateTimeFrom(value);
-        const resolved = instantFormatOptions(options ?? {}, zonedDateTime.timeZoneId, "zoned-date-time");
+        const resolved = instantFormatOptions(readDateTimeFormatOptions(options), zonedDateTime.timeZoneId, "zoned-date-time");
         if (resolved === null) {
             return [];
         }

package/dist/zoned/get/getDstTransitions.d.ts

@@ -2,14 +2,6 @@
  * A single DST transition instant: the UTC instant of an offset change plus the
  * offset in effect immediately before and after it.
  *
- * @remarks Members:
- *
- * | Member | Type | Description |
- * | --- | --- | --- |
- * | `instant` | `string` | UTC instant of the offset change, ISO 8601 ending in `Z` (e.g. `2024-03-10T07:00:00Z`). |
- * | `offsetBefore` | `string` | UTC offset in effect immediately before the transition (e.g. `-05:00`). |
- * | `offsetAfter` | `string` | UTC offset in effect immediately after the transition (e.g. `-04:00`). |
- *
  * @example
  * import { DstTransition } from "@northguild/gmt/zoned";
  * const t: DstTransition = {
@@ -19,12 +11,16 @@
  * };
  */
 export interface DstTransition {
+    /** The UTC instant of the offset change, ISO 8601 ending in `Z` (e.g. `2024-03-10T07:00:00Z`). */
     instant: string;
+    /** The UTC offset in effect immediately before the transition (e.g. `-05:00`). */
     offsetBefore: string;
+    /** The UTC offset in effect immediately after the transition (e.g. `-04:00`). */
     offsetAfter: string;
 }
 /**
- * List every DST transition instant for an IANA timezone within a given year.
+ * List every DST transition instant for a time zone (an IANA name or a UTC offset) within a
+ * given year.
  *
  * - A "transition" is any UTC offset change: a spring-forward gap (nonexistent
  *   local time) or a fall-back overlap (ambiguous local time) — see
@@ -39,8 +35,10 @@ export interface DstTransition {
  * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
  *   with zero transitions in that year (not an error case), and when the scan
  *   exhausts its internal bound — never a partial list.
+ * - A UTC offset such as `"+05:30"` is a valid zone whose offset never changes,
+ *   so it has no transitions and returns `[]` for every year.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @param year calendar year to scan (must be an integer)
  * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
  *
@@ -52,6 +50,7 @@ export interface DstTransition {
  * @example getDstTransitions("Asia/Singapore", 1982)
  * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]
  * @example getDstTransitions("Asia/Tokyo", 2024) // []
+ * @example getDstTransitions("+05:30", 2024) // [] (a fixed offset has no transitions)
  * @example getDstTransitions("Invalid/Zone", 2024) // []
  */
 export declare function getDstTransitions(timeZone: string, year: number): DstTransition[];

package/dist/zoned/get/getDstTransitions.js

@@ -1,8 +1,11 @@
 import { isValidTimeZone } from "../validate/index.js";
 import { zonedDateTimeFrom, zonedNextTransition, zonedStartOfDay, } from "../../internal/index.js";
 const MAX_TRANSITIONS_PER_YEAR = 20;
+/** 368 days: a 366-day year plus a day at each end for the zone's offset. */
+const SEARCH_SPAN_NANOSECONDS = 368n * 86400000000000n;
 /**
- * List every DST transition instant for an IANA timezone within a given year.
+ * List every DST transition instant for a time zone (an IANA name or a UTC offset) within a
+ * given year.
  *
  * - A "transition" is any UTC offset change: a spring-forward gap (nonexistent
  *   local time) or a fall-back overlap (ambiguous local time) — see
@@ -17,8 +20,10 @@ const MAX_TRANSITIONS_PER_YEAR = 20;
  * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
  *   with zero transitions in that year (not an error case), and when the scan
  *   exhausts its internal bound — never a partial list.
+ * - A UTC offset such as `"+05:30"` is a valid zone whose offset never changes,
+ *   so it has no transitions and returns `[]` for every year.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @param year calendar year to scan (must be an integer)
  * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
  *
@@ -30,6 +35,7 @@ const MAX_TRANSITIONS_PER_YEAR = 20;
  * @example getDstTransitions("Asia/Singapore", 1982)
  * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]
  * @example getDstTransitions("Asia/Tokyo", 2024) // []
+ * @example getDstTransitions("+05:30", 2024) // [] (a fixed offset has no transitions)
  * @example getDstTransitions("Invalid/Zone", 2024) // []
  */
 export function getDstTransitions(timeZone, year) {
@@ -40,11 +46,14 @@ export function getDstTransitions(timeZone, year) {
         // getTimeZoneTransition("next") is strictly after its receiver, so start 1ns before the
         // year opens to catch a transition landing exactly on local January 1 00:00.
         let cur = zonedStartOfDay(zonedDateTimeFrom({ year, month: 1, day: 1, timeZone })).subtract({ nanoseconds: 1 });
+        // A calendar year is at most 366 days and an offset is under a day, so no search needs to
+        // read past this.
+        const searchEnd = cur.epochNanoseconds + SEARCH_SPAN_NANOSECONDS;
         const transitions = [];
         // `<=`: up to MAX in-year transitions are pushed, plus one more lookup to observe the scan
         // leaving the year.
         for (let i = 0; i <= MAX_TRANSITIONS_PER_YEAR; i++) {
-            const next = zonedNextTransition(cur);
+            const next = zonedNextTransition(cur, searchEnd);
             if (!next || next.year > year) {
                 return transitions;
             }

package/dist/zoned/get/getTimeZoneOffset.d.ts

@@ -14,8 +14,11 @@
  * - The instant is ISO 8601 extended format before any annotation (`<date>T<time>`, then `Z` or
  *   `±HH:MM[:SS[.fraction]]`): basic format, a `t` or space separator, a lower-case `z` and an
  *   hour-only offset return "".
+ * - Only the instant is read from `instant`, as `isValidInstant` describes it: a bracketed zone
+ *   in it is not validated, and an offset written to the minute that is that zone's sub-minute
+ *   offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
  * @returns offset string (e.g. "-04:00"), or "" on invalid input
  *

package/dist/zoned/get/getTimeZoneOffset.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { instantFrom } from "../../internal/instantNanoseconds.js";
 import { hasInstantShape } from "../../internal/isoStringBody.js";
 import { instantLeapSecond } from "../../regex/index.js";
 import { isValidTimeZone } from "../validate/index.js";
@@ -18,8 +18,11 @@ import { isValidTimeZone } from "../validate/index.js";
  * - The instant is ISO 8601 extended format before any annotation (`<date>T<time>`, then `Z` or
  *   `±HH:MM[:SS[.fraction]]`): basic format, a `t` or space separator, a lower-case `z` and an
  *   hour-only offset return "".
+ * - Only the instant is read from `instant`, as `isValidInstant` describes it: a bracketed zone
+ *   in it is not validated, and an offset written to the minute that is that zone's sub-minute
+ *   offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
  * @returns offset string (e.g. "-04:00"), or "" on invalid input
  *
@@ -42,7 +45,7 @@ export function getTimeZoneOffset(timeZone, instant) {
         return "";
     }
     try {
-        return Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone).offset;
+        return instantFrom(instant).toZonedDateTimeISO(timeZone).offset;
     }
     catch {
         return "";

package/dist/zoned/get/getZonedNow.d.ts

@@ -4,14 +4,26 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
+ * - `smallestUnit` is the only option read. Any other key on `optionsArg` is ignored, so the
+ *   string always carries the offset and the bracketed time zone, and smaller units are always
+ *   truncated.
  *
  * @param ianaTimezone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond")
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 datetime string or "" on invalid input
  *
  * @example getZonedNow("America/New_York") // "2024-02-29T09:30:45.123-05:00[America/New_York]"
+ * @example getZonedNow("America/New_York", { smallestUnit: "second" }) // "2024-02-29T09:30:45-05:00[America/New_York]"
  * @example getZonedNow("Invalid/Zone") // ""
+ * @example getZonedNow("America/New_York", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
  */
 export declare function getZonedNow(ianaTimezone: string, optionsArg?: {
+    /**
+     * The smallest unit written in the output string, from `"minute"` to `"nanosecond"`, singular
+     * or plural. Anything smaller is truncated, as Temporal's `toString` does with its `"trunc"`
+     * rounding mode.
+     *
+     * @defaultValue `"millisecond"`
+     */
     smallestUnit?: Temporal.ZonedDateTimeToStringOptions["smallestUnit"];
 }): string;

package/dist/zoned/get/getZonedNow.js

@@ -1,27 +1,36 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return the current zoned datetime for the specified IANA timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
+ * - `smallestUnit` is the only option read. Any other key on `optionsArg` is ignored, so the
+ *   string always carries the offset and the bracketed time zone, and smaller units are always
+ *   truncated.
  *
  * @param ianaTimezone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond")
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 datetime string or "" on invalid input
  *
  * @example getZonedNow("America/New_York") // "2024-02-29T09:30:45.123-05:00[America/New_York]"
+ * @example getZonedNow("America/New_York", { smallestUnit: "second" }) // "2024-02-29T09:30:45-05:00[America/New_York]"
  * @example getZonedNow("Invalid/Zone") // ""
+ * @example getZonedNow("America/New_York", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
  */
 export function getZonedNow(ianaTimezone, optionsArg) {
     try {
         if (!isOptionsArgument(optionsArg)) {
             return "";
         }
+        // ECMA-402 GetOption (the Temporal specification defines the same operation): the option is
+        // read once, and a value of undefined is absent, so the default applies.
+        // Only smallestUnit is read: any other key on the caller's object (roundingMode, offset,
+        // timeZoneName, calendarName, fractionalSecondDigits) never reaches Temporal's toString.
         const options = {
-            smallestUnit: "millisecond",
-            ...optionsArg,
+            smallestUnit: optionOrDefault(optionsArg?.smallestUnit, "millisecond"),
         };
         if (!isValidTimeZone(ianaTimezone)) {
             return "";

package/dist/zoned/interval/intervalDifferenceZoned.d.ts

@@ -39,6 +39,15 @@
  * @example intervalDifferenceZoned("invalid", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // []
  */
 export declare function intervalDifferenceZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/zoned/interval/intervalDivideEquallyZoned.d.ts

@@ -7,9 +7,13 @@
  * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds (real
  *   elapsed time, exact at any span length), so a spring-forward day split in half lands exactly
  *   on the DST transition's real midpoint rather than the local-clock midpoint.
+ * - When `n` is larger than the number of nanoseconds in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
  *   an empty `[start, start)` that holds no instant.
+ * - `start` and `end` may name different time zones. The first `start` and every inner boundary
+ *   are written in `start`'s zone; the last `end` is the `end` argument, in its own zone.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
@@ -19,14 +23,12 @@
  *   unreadable as a set. A mismatch returns `[]`.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - An `n` over `options.maxPieces` returns `[]` before any piece is built.
  *
  * @param start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)
@@ -37,8 +39,24 @@
  * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 3, { maxPieces: 3 }) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }, { start: "2024-01-02T00:00:00+00:00[UTC]", end: "2024-01-03T00:00:00+00:00[UTC]" }, { start: "2024-01-03T00:00:00+00:00[UTC]", end: "2024-01-04T00:00:00+00:00[UTC]" }]
  */
 export declare function intervalDivideEquallyZoned(start: string, end: string, n: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/zoned/interval/intervalDivideEquallyZoned.js

@@ -13,9 +13,13 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds (real
  *   elapsed time, exact at any span length), so a spring-forward day split in half lands exactly
  *   on the DST transition's real midpoint rather than the local-clock midpoint.
+ * - When `n` is larger than the number of nanoseconds in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
  *   an empty `[start, start)` that holds no instant.
+ * - `start` and `end` may name different time zones. The first `start` and every inner boundary
+ *   are written in `start`'s zone; the last `end` is the `end` argument, in its own zone.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
@@ -25,14 +29,12 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *   unreadable as a set. A mismatch returns `[]`.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - An `n` over `options.maxPieces` returns `[]` before any piece is built.
  *
  * @param start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)

package/dist/zoned/interval/intervalFromDurationZoned.d.ts

@@ -8,13 +8,9 @@ import type { Disambiguation, Overflow } from "../../types/index.js";
  *   resolve against `value` itself — no separate `relativeTo` is needed.
  * - 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 (subtracted
- *   for `anchor: "end"`) in exact time. `disambiguation` ("compatible" (default), "earlier",
- *   "later", or "reject" (returns null)) 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 null for both. It never re-resolves
- *   the exact-time result, so a time-only duration ignores it.
+ *   for `anchor: "end"`) in exact 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. Pass "compatible" (or omit it) to keep that result.
  * - Compatibility: before 1.16.0 a non-"compatible" `disambiguation` re-resolved the final wall
@@ -25,8 +21,6 @@ import type { Disambiguation, Overflow } from "../../types/index.js";
  *   from a plain date-time, which has no UTC offset for it to act on.
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionZoned`'s `start > end` rejection.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
  * - Accepts a RFC 9557 calendar-annotated zoned string (as produced by `convertZonedToCalendar`) as
  *   well as a bare ISO one — E7 (issue #152). Calendar units in `duration` resolve against that
  *   calendar, and both returned endpoints are re-derived in it via `formatZonedInCalendar`. There
@@ -37,7 +31,7 @@ import type { Disambiguation, Overflow } from "../../types/index.js";
  * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), overflow ("constrain" | "reject")
+ * @param options optional settings for resolving a DST gap or overlap and an out-of-range date
  * @returns `{ start, end }` with the constructed span, or null on invalid input
  *
  * @example intervalFromDurationZoned("2024-01-01T00:00:00+00:00[UTC]", "P1D", "start") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }
@@ -51,9 +45,34 @@ import type { Disambiguation, Overflow } from "../../types/index.js";
  * @example intervalFromDurationZoned("invalid", "P1D", "start") // null
  */
 export declare function intervalFromDurationZoned(value: string, duration: string, anchor: "start" | "end", options?: {
+    /**
+     * 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 `null` 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 `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): {
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 } | null;

package/dist/zoned/interval/intervalFromDurationZoned.js

@@ -3,6 +3,7 @@ import { isValidDuration } from "../../duration/validate/index.js";
 import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalendar, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Construct a zoned interval from a single point plus an ISO 8601 duration, anchored at either end.
  *
@@ -12,13 +13,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   resolve against `value` itself — no separate `relativeTo` is needed.
  * - 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 (subtracted
- *   for `anchor: "end"`) in exact time. `disambiguation` ("compatible" (default), "earlier",
- *   "later", or "reject" (returns null)) 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 null for both. It never re-resolves
- *   the exact-time result, so a time-only duration ignores it.
+ *   for `anchor: "end"`) in exact 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. Pass "compatible" (or omit it) to keep that result.
  * - Compatibility: before 1.16.0 a non-"compatible" `disambiguation` re-resolved the final wall
@@ -29,8 +26,6 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   from a plain date-time, which has no UTC offset for it to act on.
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionZoned`'s `start > end` rejection.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
  * - Accepts a RFC 9557 calendar-annotated zoned string (as produced by `convertZonedToCalendar`) as
  *   well as a bare ISO one — E7 (issue #152). Calendar units in `duration` resolve against that
  *   calendar, and both returned endpoints are re-derived in it via `formatZonedInCalendar`. There
@@ -41,7 +36,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), overflow ("constrain" | "reject")
+ * @param options optional settings for resolving a DST gap or overlap and an out-of-range date
  * @returns `{ start, end }` with the constructed span, or null on invalid input
  *
  * @example intervalFromDurationZoned("2024-01-01T00:00:00+00:00[UTC]", "P1D", "start") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }
@@ -68,9 +63,7 @@ export function intervalFromDurationZoned(value, duration, anchor, options) {
         if (anchor !== "start" && anchor !== "end") {
             return null;
         }
-        const disambiguation = options?.disambiguation === undefined
-            ? "compatible"
-            : options.disambiguation;
+        const disambiguation = optionOrDefault(options?.disambiguation, "compatible");
         const overflow = resolveOverflow(options?.overflow);
         try {
             const calendar = calendarSystemOfZonedValue(value);

package/dist/zoned/interval/intervalIntersectionZoned.d.ts

@@ -37,6 +37,15 @@
  * @example intervalIntersectionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export declare function intervalIntersectionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 } | null;

package/dist/zoned/interval/intervalSplitAtZoned.d.ts

@@ -13,6 +13,8 @@
  *   each record's `end` is the next record's `start` and belongs only to that next record, so the
  *   pieces share no instant and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
+ * - A piece's `end` equals its `start` only when the interval itself is zero-length (`start`
+ *   equal to `end`): the result is then that one empty piece, whatever the points.
  * - Returns `[]` when `points` is not an array, when any element is not a valid ISO
  *   ZonedDateTime string, or on invalid input (unparseable start/end, `start > end`,
  *   leap-second strings).
@@ -34,6 +36,15 @@
  * @example intervalSplitAtZoned("invalid", "2024-01-10T00:00:00+00:00[UTC]", ["2024-01-05T00:00:00+00:00[UTC]"]) // []
  */
 export declare function intervalSplitAtZoned(start: string, end: string, points: string[]): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/zoned/interval/intervalSplitAtZoned.js

@@ -17,6 +17,8 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  *   each record's `end` is the next record's `start` and belongs only to that next record, so the
  *   pieces share no instant and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
+ * - A piece's `end` equals its `start` only when the interval itself is zero-length (`start`
+ *   equal to `end`): the result is then that one empty piece, whatever the points.
  * - Returns `[]` when `points` is not an array, when any element is not a valid ISO
  *   ZonedDateTime string, or on invalid input (unparseable start/end, `start > end`,
  *   leap-second strings).

package/dist/zoned/interval/intervalUnionZoned.d.ts

@@ -39,6 +39,15 @@
  * @example intervalUnionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export declare function intervalUnionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 } | null;