@northguild/gmt 1.17.0 → 1.18.0

package/dist/utc/format/formatUtc.d.ts

@@ -1,33 +1,35 @@
 /**
  * Options for `formatUtc`. Extends `Intl.DateTimeFormatOptions`; only the
- * added/overridden members are listed below. All `Intl.DateTimeFormatOptions`
+ * added/overridden members are declared here. All `Intl.DateTimeFormatOptions`
  * (`dateStyle`, `timeStyle`, etc.) apply to the time-of-day portion.
  *
- * @remarks Members:
- *
- * | Member | Type | Default | Description |
- * | --- | --- | --- | --- |
- * | `timeZone` | `string` | `"UTC"` | IANA zone for rendering; omitted is UTC, `"local"` is the system zone, and an unknown zone makes `formatUtc` return `""`. |
- * | `includeTimeZoneName` | `boolean` | `false` | Appends the localized zone name (style via `Intl`) when true. |
- *
  * @example
  * import { FormatUtcOptions } from "@northguild/gmt/utc";
  * const opts: FormatUtcOptions = { includeTimeZoneName: true };
  */
 export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
+    /**
+     * The time zone the value is rendered in: an IANA name, a UTC offset, or `"local"` for the system
+     * time zone. An unknown zone returns `""`, as ECMA-402 throws RangeError for it.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * Whether the localized time zone name is appended. When true the value is formatted as Temporal's
+     * ECMA-402 ZonedDateTime format does, which adds a short zone name to the defaults; when false, as
+     * the PlainDateTime format does, and `timeZoneName` is ignored.
+     *
+     * @defaultValue `false`
+     */
     includeTimeZoneName?: boolean;
 }
 /**
  * Format a UTC ISO string as a localized date/time string.
  *
  * - Returns `""` if the input is not a valid UTC string.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
- * - `includeTimeZoneName` appends the localized timezone name when true.
- * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
- *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
- *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
- *   and `era` alone still gets the date and time defaults.
+ * - The requested fields and style widths are kept, and `era` alone still gets the date and time
+ *   defaults.
  * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
  *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
  *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
@@ -36,7 +38,7 @@ export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { timeZone, includeTimeZoneName }
+ * @param options The time zone, the zone-name switch and any `Intl.DateTimeFormatOptions`
  * @returns the formatted date/time string, or "" on invalid input
  *
  * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"

package/dist/utc/format/formatUtc.js

@@ -4,16 +4,14 @@ import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
 import { isValidUtc } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Format a UTC ISO string as a localized date/time string.
  *
  * - Returns `""` if the input is not a valid UTC string.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
- * - `includeTimeZoneName` appends the localized timezone name when true.
- * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
- *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
- *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
- *   and `era` alone still gets the date and time defaults.
+ * - The requested fields and style widths are kept, and `era` alone still gets the date and time
+ *   defaults.
  * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
  *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
  *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
@@ -22,7 +20,7 @@ import { isValidUtc } from "../validate/index.js";
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { timeZone, includeTimeZoneName }
+ * @param options The time zone, the zone-name switch and any `Intl.DateTimeFormatOptions`
  * @returns the formatted date/time string, or "" on invalid input
  *
  * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
@@ -45,7 +43,9 @@ export function formatUtc(value, locale, options) {
             return "";
         if (!isValidUtc(value))
             return "";
-        const { timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        // Each option is read once (GetOption), inherited ones included.
+        const includeTimeZoneName = optionOrDefault(options?.includeTimeZoneName, false);
+        const { timeZone, ...intlOptions } = readDateTimeFormatOptions(options);
         const instant = toInstantFromUtc(value);
         if (instant === null)
             return "";

package/dist/utc/interval/intervalDifferenceUtc.d.ts

@@ -27,6 +27,12 @@
  * @example intervalDifferenceUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // []
  */
 export declare function intervalDifferenceUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/intervalDivideEquallyUtc.d.ts

@@ -10,18 +10,19 @@
  *   split is exact whenever the span divides evenly by `n` and within half a nanosecond of the
  *   exact cut otherwise, at any span length (no double arithmetic) — no DST is involved, since
  *   UTC has no time zone offset.
+ * - 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.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
- * - `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 `[]`.
+ * - Returns `[]` before building any piece when `n` exceeds the longest possible array
+ *   (2^32 - 1).
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC 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 A limit on the size of the result
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
@@ -32,8 +33,21 @@
  * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3, { maxPieces: 3 }) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
  */
 export declare function intervalDivideEquallyUtc(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 an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/intervalDivideEquallyUtc.js

@@ -15,18 +15,19 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *   split is exact whenever the span divides evenly by `n` and within half a nanosecond of the
  *   exact cut otherwise, at any span length (no double arithmetic) — no DST is involved, since
  *   UTC has no time zone offset.
+ * - 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.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
- * - `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 `[]`.
+ * - Returns `[]` before building any piece when `n` exceeds the longest possible array
+ *   (2^32 - 1).
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC 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 A limit on the size of the result
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]

package/dist/utc/interval/intervalFromDurationUtc.d.ts

@@ -10,15 +10,13 @@ import type { Overflow } from "../../types/index.js";
  *   reference point (mirrors `addUtc`).
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionUtc`'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.
  * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
  *   than `"start"`/`"end"`).
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns `{ start, end }` with the constructed span (UTC Instant strings), or null on invalid input
  *
  * @example intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
@@ -28,8 +26,20 @@ import type { Overflow } from "../../types/index.js";
  * @example intervalFromDurationUtc("invalid", "P1D", "start") // null
  */
 export declare function intervalFromDurationUtc(value: string, duration: string, anchor: "start" | "end", options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Jan 31 + 1 month is Feb 29/28 (TC39 Temporal); `"reject"` returns `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): {
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/intervalFromDurationUtc.js

@@ -15,15 +15,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   reference point (mirrors `addUtc`).
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionUtc`'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.
  * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
  *   than `"start"`/`"end"`).
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns `{ start, end }` with the constructed span (UTC Instant strings), or null on invalid input
  *
  * @example intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }

package/dist/utc/interval/intervalIntersectionUtc.d.ts

@@ -24,6 +24,12 @@
  * @example intervalIntersectionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
  */
 export declare function intervalIntersectionUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/intervalSplitAtUtc.d.ts

@@ -13,6 +13,8 @@
  *   there, so the pieces share no value and together cover the interval exactly once (the rule
  *   CORE-6's `splitIntervalAt` uses).
  * - 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 UTC
  *   datetime string, or on invalid input (unparseable start/end, `start > end`, leap-second
  *   strings).
@@ -27,6 +29,12 @@
  * @example intervalSplitAtUtc("invalid", "2024-01-10T00:00:00Z", ["2024-01-05T00:00:00Z"]) // []
  */
 export declare function intervalSplitAtUtc(start: string, end: string, points: string[]): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/intervalSplitAtUtc.js

@@ -16,6 +16,8 @@ import { isValidUtc } from "../validate/index.js";
  *   there, so the pieces share no value and together cover the interval exactly once (the rule
  *   CORE-6's `splitIntervalAt` uses).
  * - 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 UTC
  *   datetime string, or on invalid input (unparseable start/end, `start > end`, leap-second
  *   strings).

package/dist/utc/interval/intervalUnionUtc.d.ts

@@ -27,6 +27,12 @@
  * @example intervalUnionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
  */
 export declare function intervalUnionUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/intervalXorAllUtc.d.ts

@@ -26,6 +26,12 @@ export declare function intervalXorAllUtc(intervals: Array<{
     start: string;
     end: string;
 }>): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/intervalXorUtc.d.ts

@@ -22,6 +22,12 @@
  * @example intervalXorUtc("invalid", "2024-06-30T12:00:00Z", "2024-07-01T13:00:00Z", "2024-12-31T17:00:00Z") // []
  */
 export declare function intervalXorUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/mergeIntervalsUtc.d.ts

@@ -27,6 +27,12 @@ export declare function mergeIntervalsUtc(intervals: Array<{
     start: string;
     end: string;
 }>): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/splitIntervalByUnitUtc.d.ts

@@ -8,8 +8,11 @@
  *   CORE-6's `splitIntervalAt` uses).
  * - 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`.
@@ -18,15 +21,12 @@
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - 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 `[]`.
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC 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 A limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "hour", 6) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T06:00:00Z" }, { start: "2024-01-01T06:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, { start: "2024-01-01T18:00:00Z", end: "2024-01-02T00:00:00Z" }]
@@ -39,8 +39,21 @@
  * @example splitIntervalByUnitUtc("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "hour", 2) // [{ start: "+275760-09-12T23:00:00Z", end: "+275760-09-13T00:00:00Z" }] (the step past the last instant is trimmed to `end`)
  */
 export declare function splitIntervalByUnitUtc(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 an ISO 8601 UTC string ending in `Z`. */
     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/utc/interval/splitIntervalByUnitUtc.js

@@ -15,8 +15,11 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   CORE-6's `splitIntervalAt` uses).
  * - 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`.
@@ -25,15 +28,12 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - 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 `[]`.
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC 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 A limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "hour", 6) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T06:00:00Z" }, { start: "2024-01-01T06:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, { start: "2024-01-01T18:00:00Z", end: "2024-01-02T00:00:00Z" }]

package/dist/utc/parse/parseDateFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Extract the date portion from a UTC datetime string.
  *
  * - Uses Temporal.Instant.from to parse, converts to UTC date.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUtc("2024-03-17T14:30:45Z") // "2024-03-17"
@@ -15,5 +13,11 @@
  * @example parseDateFromUtc("invalid") // ""
  */
 export declare function parseDateFromUtc(value: string, options?: {
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseDateFromUtc.js

@@ -4,12 +4,10 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Extract the date portion from a UTC datetime string.
  *
  * - Uses Temporal.Instant.from to parse, converts to UTC date.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUtc("2024-03-17T14:30:45Z") // "2024-03-17"

package/dist/utc/parse/parseDayFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the day of month (1-31) from a UTC datetime string.
  *
  * - Returns zero-padded string for day.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUtc("2024-03-17T14:30:45Z") // "17"
@@ -15,5 +13,11 @@
  * @example parseDayFromUtc("invalid") // ""
  */
 export declare function parseDayFromUtc(value: string, options?: {
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseDayFromUtc.js

@@ -4,12 +4,10 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the day of month (1-31) from a UTC datetime string.
  *
  * - Returns zero-padded string for day.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUtc("2024-03-17T14:30:45Z") // "17"

package/dist/utc/parse/parseDayOfWeekFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the day of week (1-7) from a UTC datetime string.
  *
  * - Monday=1 through Sunday=7.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUtc("2024-03-17T14:30:45Z") // 7
@@ -16,5 +14,11 @@
  * @example parseDayOfWeekFromUtc("invalid") // null
  */
 export declare function parseDayOfWeekFromUtc(value: string, options?: {
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/utc/parse/parseDayOfWeekFromUtc.js

@@ -1,17 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of week (1-7) from a UTC datetime string.
  *
  * - Monday=1 through Sunday=7.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUtc("2024-03-17T14:30:45Z") // 7
@@ -26,8 +24,8 @@ export function parseDayOfWeekFromUtc(value, options) {
         }
         if (!isValidUtc(value))
             return null;
-        const timeZone = resolveReadingTimeZone(options?.timeZone);
-        if (timeZone === null)
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (timeZone === "")
             return null;
         try {
             const dateTime = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);

package/dist/utc/parse/parseHourFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the hour (0-23) from a UTC datetime string.
  *
  * - Returns zero-padded string for hour.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUtc("2024-03-17T14:30:45Z") // "14"
@@ -15,5 +13,11 @@
  * @example parseHourFromUtc("invalid") // ""
  */
 export declare function parseHourFromUtc(value: string, options?: {
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseHourFromUtc.js

@@ -4,12 +4,10 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the hour (0-23) from a UTC datetime string.
  *
  * - Returns zero-padded string for hour.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUtc("2024-03-17T14:30:45Z") // "14"

package/dist/utc/parse/parseHttp.d.ts

@@ -3,7 +3,7 @@
  * `Last-Modified`/`Date`/`Expires` use — into a UTC ISO 8601 datetime string.
  *
  * - **Decoding, not display.** Accepts English weekday/month names only, per
- *   the fixed grammar (see `formatHttp`'s JSDoc and roadmap Decision 1).
+ *   the fixed grammar (see `formatHttp`'s JSDoc).
  * - **All three HTTP-date formats**, as RFC 9110 §5.6.7 requires ("A
  *   recipient that parses a timestamp value in an HTTP field MUST accept all
  *   three"): IMF-fixdate (`Sun, 06 Nov 1994 08:49:37 GMT`), the obsolete