@northguild/gmt 1.17.0 → 1.19.0

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;

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

@@ -34,6 +34,15 @@ export declare function intervalXorAllZoned(intervals: Array<{
     start: string;
     end: 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/intervalXorAllZoned.js

@@ -2,6 +2,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { calendarOfAllZonedValues, formatZonedInCalendar, halfOpenXor, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Return the symmetric difference across a list of zoned intervals — the set of instants
  * covered by an odd number of the input intervals.
@@ -39,8 +40,7 @@ export function intervalXorAllZoned(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             typeof interval.start === "string" &&
             typeof interval.end === "string" &&
             isValidCalendarZonedInterval(interval.start, interval.end))) {

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

@@ -44,6 +44,15 @@
  * @example intervalXorZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  */
 export declare function intervalXorZoned(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/mergeIntervalsZoned.d.ts

@@ -38,6 +38,15 @@ export declare function mergeIntervalsZoned(intervals: Array<{
     start: string;
     end: 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/mergeIntervalsZoned.js

@@ -2,6 +2,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { calendarOfAllZonedValues, formatZonedInCalendar, halfOpenMerge, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Collapse a list of zoned intervals into the minimum set of non-overlapping intervals.
  *
@@ -43,8 +44,7 @@ export function mergeIntervalsZoned(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             typeof interval.start === "string" &&
             typeof interval.end === "string" &&
             isValidCalendarZonedInterval(interval.start, interval.end))) {

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

@@ -6,14 +6,20 @@
  *   no instant and together cover `[start, end)` exactly once.
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
  * - A calendar step that resolves to the same instant as the previous boundary (a deleted local
  *   day, such as 30 December 2011 in `Pacific/Apia`) is skipped, so no empty slice is produced.
  *   A step that goes backwards returns `[]`.
+ * - `start` and `end` may name different time zones. Steps are taken from `start`, so 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 `[{ start, end }]` when `start === end` (zero-length interval).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152). Stepping by a calendar unit ("1 month") resolves
@@ -24,9 +30,8 @@
  *   string (E7's D7-zoned).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
+ * - A split into more than `options.maxPieces` slices returns `[]`, decided from the span before
+ *   stepping where it can be, and otherwise as soon as slice `maxPieces + 1` is due.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the `[u-ca=<id>]`
  *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  *
@@ -34,7 +39,7 @@
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 6) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T06:00:00+00:00[UTC]" }, { start: "2024-01-01T06:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }, { start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T18:00:00+00:00[UTC]" }, { start: "2024-01-01T18:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }]
@@ -47,8 +52,24 @@
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T01:30:00+00:00[UTC]", "hour", 1, { maxPieces: 2 }) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T01:00:00+00:00[UTC]" }, { start: "2024-01-01T01:00:00+00:00[UTC]", end: "2024-01-01T01:30:00+00:00[UTC]" }]
  */
 export declare function splitIntervalByUnitZoned(start: string, end: string, unit: string, amount: 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/splitIntervalByUnitZoned.js

@@ -13,14 +13,20 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   no instant and together cover `[start, end)` exactly once.
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
  * - A calendar step that resolves to the same instant as the previous boundary (a deleted local
  *   day, such as 30 December 2011 in `Pacific/Apia`) is skipped, so no empty slice is produced.
  *   A step that goes backwards returns `[]`.
+ * - `start` and `end` may name different time zones. Steps are taken from `start`, so 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 `[{ start, end }]` when `start === end` (zero-length interval).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152). Stepping by a calendar unit ("1 month") resolves
@@ -31,9 +37,8 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   string (E7's D7-zoned).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
+ * - A split into more than `options.maxPieces` slices returns `[]`, decided from the span before
+ *   stepping where it can be, and otherwise as soon as slice `maxPieces + 1` is due.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the `[u-ca=<id>]`
  *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  *
@@ -41,7 +46,7 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 6) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T06:00:00+00:00[UTC]" }, { start: "2024-01-01T06:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }, { start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T18:00:00+00:00[UTC]" }, { start: "2024-01-01T18:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }]

package/dist/zoned/map/mapZonedDatesInRange.d.ts

@@ -3,9 +3,7 @@
  *
  * - Both datetimes must have the same timezone.
  * - Returns [] for invalid inputs, mismatched timezones, start > end, or invalid step.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when the
- *   range holds more dates than that, it returns `[]` without generating any. An invalid
- *   `maxPieces` also returns `[]`.
+ * - A range holding more dates than `options.maxPieces` returns `[]` without generating any.
  * - An explicit `undefined` `stepDays` is the default step, so `(start, end, undefined, options)`
  *   reaches `options`. **Compatibility:** before 1.16.0 it returned `[]`.
  * - **End-inclusive, where the `interval*` functions are half-open.** This enumerates the dates a
@@ -16,7 +14,7 @@
  * @param startZonedDateTime start zoned ISO 8601 datetime string
  * @param endZonedDateTime end zoned ISO 8601 datetime string
  * @param stepDays optional positive integer step in days
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of ISO date strings or [] when invalid
  *
  * @example mapZonedDatesInRange("+275760-09-12T00:00:00+00:00[UTC]", "+275760-09-13T00:00:00+00:00[UTC]") // ["+275760-09-12", "+275760-09-13"] (a range ending on the maximum instant)
@@ -28,5 +26,12 @@
  * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 1, { maxPieces: 10 }) // ["2024-02-28", "2024-02-29", "2024-03-01", "2024-03-02"]
  */
 export declare function mapZonedDatesInRange(startZonedDateTime: string, endZonedDateTime: string, stepDays?: number, options?: {
+    /**
+     * The most dates 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;
 }): string[];

package/dist/zoned/map/mapZonedDatesInRange.js

@@ -8,9 +8,7 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *
  * - Both datetimes must have the same timezone.
  * - Returns [] for invalid inputs, mismatched timezones, start > end, or invalid step.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when the
- *   range holds more dates than that, it returns `[]` without generating any. An invalid
- *   `maxPieces` also returns `[]`.
+ * - A range holding more dates than `options.maxPieces` returns `[]` without generating any.
  * - An explicit `undefined` `stepDays` is the default step, so `(start, end, undefined, options)`
  *   reaches `options`. **Compatibility:** before 1.16.0 it returned `[]`.
  * - **End-inclusive, where the `interval*` functions are half-open.** This enumerates the dates a
@@ -21,7 +19,7 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  * @param startZonedDateTime start zoned ISO 8601 datetime string
  * @param endZonedDateTime end zoned ISO 8601 datetime string
  * @param stepDays optional positive integer step in days
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of ISO date strings or [] when invalid
  *
  * @example mapZonedDatesInRange("+275760-09-12T00:00:00+00:00[UTC]", "+275760-09-13T00:00:00+00:00[UTC]") // ["+275760-09-12", "+275760-09-13"] (a range ending on the maximum instant)

package/dist/zoned/parse/parseRfc2822.d.ts

@@ -3,7 +3,7 @@
  * `Date:` headers use — into a zoned ISO 8601 datetime string.
  *
  * - **Decoding, not display.** Weekday and month names are English, per the
- *   fixed grammar (see `formatRfc2822`'s JSDoc and roadmap Decision 1); like
+ *   fixed grammar (see `formatRfc2822`'s JSDoc); like
  *   every ABNF literal they match in any case (RFC 5234 §2.3).
  * - **Reads what a conformant receiver must.** RFC 5322 §3.3 syntax: folding
  *   white space (spaces, tabs, folded lines), nested comments such as a

package/dist/zoned/parse/parseRfc2822.js

@@ -5,7 +5,7 @@ import { readRfc5322DateTime } from "../../internal/rfc5322DateTime.js";
  * `Date:` headers use — into a zoned ISO 8601 datetime string.
  *
  * - **Decoding, not display.** Weekday and month names are English, per the
- *   fixed grammar (see `formatRfc2822`'s JSDoc and roadmap Decision 1); like
+ *   fixed grammar (see `formatRfc2822`'s JSDoc); like
  *   every ABNF literal they match in any case (RFC 5234 §2.3).
  * - **Reads what a conformant receiver must.** RFC 5322 §3.3 syntax: folding
  *   white space (spaces, tabs, folded lines), nested comments such as a

package/dist/zoned/parse/parseUnitFromZoned.d.ts

@@ -8,7 +8,7 @@ import type { Temporal } from "@js-temporal/polyfill";
  *
  * | Member | Description |
  * | --- | --- |
- * | `year` | Full year, no padding (e.g. `2024`). |
+ * | `year` | Four digits (e.g. `2024`, `0005`); a sign and six digits outside 0000–9999 (e.g. `+010000`). |
  * | `month` | Zero-padded 2 (e.g. `03`). |
  * | `week` | Week-of-year, 1–53 (`weekStartsOn`-controlled). |
  * | `day` | Zero-padded 2. |
@@ -33,20 +33,29 @@ export type ZonedParseUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "
  * - Uses Temporal.ZonedDateTime.from to parse.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit unit to extract
- * @param optionsArg optional settings (e.g. weekStartsOn for week calculations); a non-object value (such as `null`) is invalid
+ * @param optionsArg optional setting for the week's first day; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" when invalid
  *
  * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"
+ * @example parseUnitFromZoned("0005-06-01T12:30:00+00:00[UTC]", "year") // "0005"
  * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "milliseconds") // "789"
  * @example parseUnitFromZoned("2024-12-31T12:00:00+00:00[UTC]", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromZoned("invalid", "year") // ""
  */
 export declare function parseUnitFromZoned(value: string, unit: ZonedParseUnit, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/zoned/parse/parseUnitFromZoned.js

@@ -4,6 +4,7 @@ import { zonedDateTimeFrom } from "../../internal/index.js";
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 function isValidZonedUnit(unit) {
     return [
         "year",
@@ -27,16 +28,17 @@ function isValidZonedUnit(unit) {
  * - Uses Temporal.ZonedDateTime.from to parse.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit unit to extract
- * @param optionsArg optional settings (e.g. weekStartsOn for week calculations); a non-object value (such as `null`) is invalid
+ * @param optionsArg optional setting for the week's first day; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" when invalid
  *
  * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"
+ * @example parseUnitFromZoned("0005-06-01T12:30:00+00:00[UTC]", "year") // "0005"
  * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "milliseconds") // "789"
  * @example parseUnitFromZoned("2024-12-31T12:00:00+00:00[UTC]", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromZoned("invalid", "year") // ""
@@ -58,7 +60,7 @@ export function parseUnitFromZoned(value, unit, optionsArg) {
             const zonedDateTime = zonedDateTimeFrom(value);
             switch (resolvedUnit) {
                 case "year":
-                    return zonedDateTime.year.toString();
+                    return isoYearString(zonedDateTime.year);
                 case "month":
                     return zonedDateTime.month.toString().padStart(2, "0");
                 case "week":

package/dist/zoned/parse/parseWeekFromZoned.d.ts

@@ -1,18 +1,17 @@
 /**
  * Return the week of the year for a given ISO 8601 zoned datetime string.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ * - `"monday"` is the ISO 8601 week of the week-year: week 1 is the week containing the
  *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
  *   → 1). The result is 1–53.
  * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
  *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
  *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The week is read from the value's own date on its own wall clock.
  * - Returns null for invalid input.
  *
  * @param value ISO zoned datetime string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional setting for the week's first day
  * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromZoned("2024-01-01T14:30:45.123+00:00[UTC]") // 1
@@ -23,5 +22,13 @@
  * @example parseWeekFromZoned("invalid") // null
  */
 export declare function parseWeekFromZoned(value: string, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the week is numbered. `"monday"` gives the ISO 8601
+     * week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS #35 week
+     * number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other
+     * value returns `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/zoned/parse/parseWeekFromZoned.js

@@ -6,18 +6,17 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week of the year for a given ISO 8601 zoned datetime string.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ * - `"monday"` is the ISO 8601 week of the week-year: week 1 is the week containing the
  *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
  *   → 1). The result is 1–53.
  * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
  *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
  *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The week is read from the value's own date on its own wall clock.
  * - Returns null for invalid input.
  *
  * @param value ISO zoned datetime string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional setting for the week's first day
  * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromZoned("2024-01-01T14:30:45.123+00:00[UTC]") // 1