@northguild/gmt 1.14.2 → 1.16.0

package/dist/zoned/interval/splitIntervalByUnitZoned.js

@@ -1,77 +1,110 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { formatZonedInCalendar, parseCalendarZonedPairForArithmetic, resolveDurationUnit, } from "../../internal/index.js";
+import { addToZoned, formatZonedInCalendar, parseCalendarZonedPairForArithmetic, resolveDurationUnit, tileByUnit, } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/isValidCalendarZonedDateTime.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
+import { minSlicesForSpan } from "../../internal/splitStep.js";
 /**
  * Split a zoned interval into sub-intervals of `amount × unit`.
  *
- * - Returns an array of `{ start, end }` records that tile the interval.
+ * - Returns an array of half-open `[start, end)` records that tile the interval: 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.
  * - 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.
+ * - 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 `[]`.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - 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
- *   against the endpoints' shared calendar when both tags match, and falls back to Gregorian/ISO
- *   when they mismatch or either endpoint is bare (E7's D5-zoned). Sub-interval boundaries are
+ *   against the endpoints' shared calendar; when they name different calendars (a bare string
+ *   names `iso8601`) the result is `[]`, as Temporal's `until` throws when `CalendarEquals` is
+ *   false (before 1.16.0 it stepped in ISO). Sub-interval boundaries are
  *   re-derived in the resolved calendar via `formatZonedInCalendar`, never copied from an input
  *   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 `[]`.
+ * - 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`.
  *
  * @param start ISO 8601 zoned datetime string for the interval start
  * @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`)
  * @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]" }]
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T01:30:00+00:00[UTC]", "hour", 1) // [{ 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]" }]
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "hour", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T00:00:00+00:00[UTC]" }]
+ * @example splitIntervalByUnitZoned("2011-12-29T12:00:00-10:00[Pacific/Apia]", "2012-01-01T12:00:00+14:00[Pacific/Apia]", "day", 1) // [{ start: "2011-12-29T12:00:00-10:00[Pacific/Apia]", end: "2011-12-31T12:00:00+14:00[Pacific/Apia]" }, { start: "2011-12-31T12:00:00+14:00[Pacific/Apia]", end: "2012-01-01T12:00:00+14:00[Pacific/Apia]" }]
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 0) // []
  * @example splitIntervalByUnitZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "hour", 1) // []
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T01:30:00+00:00[UTC]", "hour", 1, { maxPieces: 1 }) // [] (2 slices exceed the limit)
+ * @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 function splitIntervalByUnitZoned(start, end, unit, amount) {
-    if (!isValidCalendarZonedDateTime(start) ||
-        !isValidCalendarZonedDateTime(end)) {
-        return [];
-    }
-    if (typeof unit !== "string") {
-        return [];
-    }
-    const resolvedUnit = resolveDurationUnit(unit);
-    if (!resolvedUnit) {
-        return [];
-    }
-    if (!Number.isFinite(amount) || amount <= 0) {
-        return [];
-    }
+export function splitIntervalByUnitZoned(start, end, unit, amount, options) {
     try {
-        const { calendar, a: startVal, b: endVal, } = parseCalendarZonedPairForArithmetic(start, end);
-        if (Temporal.ZonedDateTime.compare(startVal, endVal) > 0) {
+        if (!isValidCalendarZonedDateTime(start) ||
+            !isValidCalendarZonedDateTime(end)) {
+            return [];
+        }
+        if (typeof unit !== "string") {
             return [];
         }
-        if (Temporal.ZonedDateTime.compare(startVal, endVal) === 0) {
-            return [
-                {
-                    start: formatZonedInCalendar(startVal, calendar),
-                    end: formatZonedInCalendar(endVal, calendar),
-                },
-            ];
+        const resolvedUnit = resolveDurationUnit(unit);
+        // An unknown unit is invalid whatever the span, a zero-length one included.
+        if (!isValidDateTimeDurationUnit(resolvedUnit)) {
+            return [];
+        }
+        if (!Number.isFinite(amount) || amount <= 0) {
+            return [];
+        }
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null) {
+            return [];
         }
-        const result = [];
-        for (let current = startVal; Temporal.ZonedDateTime.compare(current, endVal) < 0;) {
-            const next = current.add({ [resolvedUnit]: amount });
-            if (Temporal.ZonedDateTime.compare(next, current) === 0) {
+        try {
+            const { calendar, a: startVal, b: endVal, } = parseCalendarZonedPairForArithmetic(start, end);
+            if (Temporal.ZonedDateTime.compare(startVal, endVal) > 0) {
                 return [];
             }
-            const sliceEnd = Temporal.ZonedDateTime.compare(next, endVal) > 0 ? endVal : next;
-            result.push({
-                start: formatZonedInCalendar(current, calendar),
+            if (Temporal.ZonedDateTime.compare(startVal, endVal) === 0) {
+                return [
+                    {
+                        start: formatZonedInCalendar(startVal, calendar),
+                        end: formatZonedInCalendar(endVal, calendar),
+                    },
+                ];
+            }
+            const spanNs = Number(endVal.epochNanoseconds - startVal.epochNanoseconds);
+            if (exceedsPieceLimit(minSlicesForSpan(spanNs, resolvedUnit, amount, true), maxPieces)) {
+                return [];
+            }
+            // `addToZoned` runs calendar units through the Temporal compat layer (CORE-6).
+            const slices = tileByUnit(startVal, endVal, Temporal.ZonedDateTime.compare, resolvedUnit, amount, maxPieces, (value, duration) => addToZoned(value, duration));
+            return (slices ?? []).map(([sliceStart, sliceEnd]) => ({
+                start: formatZonedInCalendar(sliceStart, calendar),
                 end: formatZonedInCalendar(sliceEnd, calendar),
-            });
-            current = next;
+            }));
+        }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/zoned/interval/validate/isValidCalendarZonedInterval.d.ts

@@ -1,10 +1,10 @@
 /**
  * Return true if `start` and `end` form a valid GMT zoned interval — both parseable as bare ISO
- * or GMT calendar-annotated ZonedDateTime strings, and the instant at `start` is <= the instant
+ * or RFC 9557 calendar-annotated ZonedDateTime strings, and the instant at `start` is <= the instant
  * at `end`.
  *
- * - Parallel to `isValidZonedInterval`, which is deliberately left unchanged and still rejects
- *   every `[u-ca=...]` annotation (E7, issue #152). Only the calendar-aware `zoned/interval/*`
+ * - Parallel to `isValidZonedInterval`, which accepts only ISO-calendar endpoints and rejects
+ *   every non-ISO `[u-ca=...]` annotation (E7, issue #152). Only the calendar-aware `zoned/interval/*`
  *   functions gate on this one.
  * - **Mixed calendars are accepted** (E7's D4-zoned, matching E5's D4): ordering is
  *   calendar-independent. Verified against `@js-temporal/polyfill@0.5.1` —
@@ -14,18 +14,21 @@
  * - Equal `start === end` is valid.
  * - Comparison is done by instant, so intervals spanning DST transitions are compared by
  *   absolute time.
- * - Rejects Temporal's `[timeZone][u-ca=...]` ordering, leap seconds, non-strings, and any
- *   unparseable endpoint.
+ * - Rejects a calendar annotation before the zone (not RFC 9557), leap seconds, non-strings, and
+ *   any unparseable endpoint.
+ * - 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`.
  *
- * @param start ISO or GMT calendar-annotated ZonedDateTime string (interval start)
- * @param end ISO or GMT calendar-annotated ZonedDateTime string (interval end)
+ * @param start ISO or RFC 9557 calendar-annotated ZonedDateTime string (interval start)
+ * @param end ISO or RFC 9557 calendar-annotated ZonedDateTime string (interval end)
  * @returns true if start and end form a valid zoned interval, or false on invalid input
  *
  * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
- * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]") // true
- * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "1445-09-15T14:30:00-04:00[u-ca=islamic-civil][America/New_York]") // true (mixed calendars accepted)
+ * @example isValidCalendarZonedInterval("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]", "2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]") // true
+ * @example isValidCalendarZonedInterval("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]", "2024-03-25T14:30:00-04:00[America/New_York][u-ca=islamic-civil]") // true (mixed calendars accepted)
  * @example isValidCalendarZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false (start after end)
- * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (Temporal's segment ordering)
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // true (RFC 9557; mixed calendars accepted)
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[u-ca=hebrew][UTC]", "2024-12-31T23:59:59+00:00[UTC]") // false (calendar before the zone)
  * @example isValidCalendarZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
  */
 export declare function isValidCalendarZonedInterval(start: string, end: string): boolean;

package/dist/zoned/interval/validate/isValidCalendarZonedInterval.js

@@ -2,11 +2,11 @@ import { Temporal } from "@js-temporal/polyfill";
 import { parseCalendarZonedValue } from "../../../internal/index.js";
 /**
  * Return true if `start` and `end` form a valid GMT zoned interval — both parseable as bare ISO
- * or GMT calendar-annotated ZonedDateTime strings, and the instant at `start` is <= the instant
+ * or RFC 9557 calendar-annotated ZonedDateTime strings, and the instant at `start` is <= the instant
  * at `end`.
  *
- * - Parallel to `isValidZonedInterval`, which is deliberately left unchanged and still rejects
- *   every `[u-ca=...]` annotation (E7, issue #152). Only the calendar-aware `zoned/interval/*`
+ * - Parallel to `isValidZonedInterval`, which accepts only ISO-calendar endpoints and rejects
+ *   every non-ISO `[u-ca=...]` annotation (E7, issue #152). Only the calendar-aware `zoned/interval/*`
  *   functions gate on this one.
  * - **Mixed calendars are accepted** (E7's D4-zoned, matching E5's D4): ordering is
  *   calendar-independent. Verified against `@js-temporal/polyfill@0.5.1` —
@@ -16,18 +16,21 @@ import { parseCalendarZonedValue } from "../../../internal/index.js";
  * - Equal `start === end` is valid.
  * - Comparison is done by instant, so intervals spanning DST transitions are compared by
  *   absolute time.
- * - Rejects Temporal's `[timeZone][u-ca=...]` ordering, leap seconds, non-strings, and any
- *   unparseable endpoint.
+ * - Rejects a calendar annotation before the zone (not RFC 9557), leap seconds, non-strings, and
+ *   any unparseable endpoint.
+ * - 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`.
  *
- * @param start ISO or GMT calendar-annotated ZonedDateTime string (interval start)
- * @param end ISO or GMT calendar-annotated ZonedDateTime string (interval end)
+ * @param start ISO or RFC 9557 calendar-annotated ZonedDateTime string (interval start)
+ * @param end ISO or RFC 9557 calendar-annotated ZonedDateTime string (interval end)
  * @returns true if start and end form a valid zoned interval, or false on invalid input
  *
  * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
- * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]") // true
- * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "1445-09-15T14:30:00-04:00[u-ca=islamic-civil][America/New_York]") // true (mixed calendars accepted)
+ * @example isValidCalendarZonedInterval("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]", "2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]") // true
+ * @example isValidCalendarZonedInterval("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]", "2024-03-25T14:30:00-04:00[America/New_York][u-ca=islamic-civil]") // true (mixed calendars accepted)
  * @example isValidCalendarZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false (start after end)
- * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (Temporal's segment ordering)
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // true (RFC 9557; mixed calendars accepted)
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[u-ca=hebrew][UTC]", "2024-12-31T23:59:59+00:00[UTC]") // false (calendar before the zone)
  * @example isValidCalendarZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
  */
 export function isValidCalendarZonedInterval(start, end) {

package/dist/zoned/interval/validate/isValidZonedInterval.d.ts

@@ -1,13 +1,14 @@
 /**
- * Return true if `start` and `end` form a valid zoned interval — both parseable as
- * ISO ZonedDateTime strings and the instant at `start` is <= the instant at `end`.
+ * Return true if `start` and `end` form a valid zoned interval — both valid ISO ZonedDateTime
+ * strings (`isValidZonedDateTime`) and the instant at `start` is <= the instant at `end`.
  *
  * - Both inputs must be valid ISO 8601 zoned datetime strings.
  * - Equal `start === end` is valid.
  * - Comparison is done by instant, so intervals spanning DST transitions are compared
  *   by absolute time.
- * - Rejects any `[u-ca=...]` calendar annotation (E5 issue #78, decision of record D2) — see
- *   `isValidZonedDateTime`'s JSDoc for why.
+ * - Reads RFC 9557 annotations as `isValidZonedDateTime` does: `[u-ca=iso8601]` and elective
+ *   annotations (`[foo=bar]`) are accepted, an unknown critical annotation (`[!foo=bar]`) is
+ *   rejected, and a non-ISO calendar is `isValidCalendarZonedInterval`'s input.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
  * @param start ISO ZonedDateTime string (interval start)
@@ -17,7 +18,8 @@
  * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
  * @example isValidZonedInterval("2024-06-15T12:00:00-04:00[America/New_York]", "2024-06-15T12:00:00-04:00[America/New_York]") // true
  * @example isValidZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false
- * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (calendar annotation rejected)
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=iso8601]", "2024-12-31T23:59:59+00:00[UTC][foo=bar]") // true (ISO calendar and elective annotations)
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (non-ISO calendar: use isValidCalendarZonedInterval)
  * @example isValidZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
  */
 export declare function isValidZonedInterval(start: string, end: string): boolean;

package/dist/zoned/interval/validate/isValidZonedInterval.js

@@ -1,16 +1,17 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { hasCalendarAnnotation } from "../../../internal/index.js";
-import { isLeapSecond } from "../../../plain/validate/isLeapSecond.js";
+import { zonedDateTimeFrom } from "../../../internal/index.js";
+import { isValidZonedDateTime } from "../../validate/isValidZonedDateTime.js";
 /**
- * Return true if `start` and `end` form a valid zoned interval — both parseable as
- * ISO ZonedDateTime strings and the instant at `start` is <= the instant at `end`.
+ * Return true if `start` and `end` form a valid zoned interval — both valid ISO ZonedDateTime
+ * strings (`isValidZonedDateTime`) and the instant at `start` is <= the instant at `end`.
  *
  * - Both inputs must be valid ISO 8601 zoned datetime strings.
  * - Equal `start === end` is valid.
  * - Comparison is done by instant, so intervals spanning DST transitions are compared
  *   by absolute time.
- * - Rejects any `[u-ca=...]` calendar annotation (E5 issue #78, decision of record D2) — see
- *   `isValidZonedDateTime`'s JSDoc for why.
+ * - Reads RFC 9557 annotations as `isValidZonedDateTime` does: `[u-ca=iso8601]` and elective
+ *   annotations (`[foo=bar]`) are accepted, an unknown critical annotation (`[!foo=bar]`) is
+ *   rejected, and a non-ISO calendar is `isValidCalendarZonedInterval`'s input.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
  * @param start ISO ZonedDateTime string (interval start)
@@ -20,22 +21,17 @@ import { isLeapSecond } from "../../../plain/validate/isLeapSecond.js";
  * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
  * @example isValidZonedInterval("2024-06-15T12:00:00-04:00[America/New_York]", "2024-06-15T12:00:00-04:00[America/New_York]") // true
  * @example isValidZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false
- * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (calendar annotation rejected)
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=iso8601]", "2024-12-31T23:59:59+00:00[UTC][foo=bar]") // true (ISO calendar and elective annotations)
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (non-ISO calendar: use isValidCalendarZonedInterval)
  * @example isValidZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
  */
 export function isValidZonedInterval(start, end) {
-    if (typeof start !== "string" || typeof end !== "string") {
-        return false;
-    }
-    if (isLeapSecond(start) ||
-        isLeapSecond(end) ||
-        hasCalendarAnnotation(start) ||
-        hasCalendarAnnotation(end)) {
+    if (!isValidZonedDateTime(start) || !isValidZonedDateTime(end)) {
         return false;
     }
     try {
-        const startInstant = Temporal.ZonedDateTime.from(start).toInstant();
-        const endInstant = Temporal.ZonedDateTime.from(end).toInstant();
+        const startInstant = zonedDateTimeFrom(start).toInstant();
+        const endInstant = zonedDateTimeFrom(end).toInstant();
         return Temporal.Instant.compare(startInstant, endInstant) <= 0;
     }
     catch {

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

@@ -3,14 +3,30 @@
  *
  * - 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 `[]`.
+ * - 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
+ *   range covers, so the end date is one of them; an interval bounds a span as `[start, end)`, so
+ *   its `end` is not. The same pair therefore yields one more date here than `intervalCountZoned`
+ *   counts.
  *
  * @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`)
  * @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)
  * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]") // ["2024-02-28", "2024-02-29", "2024-03-01", "2024-03-02"]
  * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 2) // ["2024-02-28", "2024-03-01"]
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-01T12:00:00+00:00[UTC]", undefined) // ["2024-02-28", "2024-02-29", "2024-03-01"] (undefined is the default step)
  * @example mapZonedDatesInRange("invalid", "2024-03-02T12:00:00+00:00[UTC]") // []
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 1, { maxPieces: 3 }) // [] (more dates than the limit)
+ * @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, ...stepDaysInput: [stepDays?: number]): string[];
+export declare function mapZonedDatesInRange(startZonedDateTime: string, endZonedDateTime: string, stepDays?: number, options?: {
+    maxPieces?: number;
+}): string[];

package/dist/zoned/map/mapZonedDatesInRange.js

@@ -1,56 +1,92 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
 /**
  * Return an array of plain ISO date strings covering the inclusive date range between two zoned datetimes.
  *
  * - 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 `[]`.
+ * - 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
+ *   range covers, so the end date is one of them; an interval bounds a span as `[start, end)`, so
+ *   its `end` is not. The same pair therefore yields one more date here than `intervalCountZoned`
+ *   counts.
  *
  * @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`)
  * @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)
  * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]") // ["2024-02-28", "2024-02-29", "2024-03-01", "2024-03-02"]
  * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 2) // ["2024-02-28", "2024-03-01"]
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-01T12:00:00+00:00[UTC]", undefined) // ["2024-02-28", "2024-02-29", "2024-03-01"] (undefined is the default step)
  * @example mapZonedDatesInRange("invalid", "2024-03-02T12:00:00+00:00[UTC]") // []
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 1, { maxPieces: 3 }) // [] (more dates than the limit)
+ * @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 function mapZonedDatesInRange(startZonedDateTime, endZonedDateTime, ...stepDaysInput) {
-    const resolvedStepDays = stepDaysInput.length === 0 ? 1 : stepDaysInput[0];
-    if (typeof resolvedStepDays !== "number" ||
-        !Number.isInteger(resolvedStepDays) ||
-        resolvedStepDays <= 0) {
-        return [];
-    }
-    if (!isValidZonedDateTime(startZonedDateTime) ||
-        !isValidZonedDateTime(endZonedDateTime)) {
-        return [];
-    }
+export function mapZonedDatesInRange(startZonedDateTime, endZonedDateTime, stepDays, options) {
     try {
-        let start;
-        let end;
-        try {
-            start = Temporal.ZonedDateTime.from(startZonedDateTime);
-            end = Temporal.ZonedDateTime.from(endZonedDateTime);
-        }
-        catch {
+        // An explicit undefined is the omitted argument, as TC39 GetOption treats it.
+        const resolvedStepDays = stepDays === undefined ? 1 : stepDays;
+        if (typeof resolvedStepDays !== "number" ||
+            !Number.isInteger(resolvedStepDays) ||
+            resolvedStepDays <= 0) {
             return [];
         }
-        if (start.timeZoneId !== end.timeZoneId) {
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null) {
             return [];
         }
-        const startDate = start.toPlainDate();
-        const endDate = end.toPlainDate();
-        if (Temporal.PlainDate.compare(startDate, endDate) === 1) {
+        if (!isValidZonedDateTime(startZonedDateTime) ||
+            !isValidZonedDateTime(endZonedDateTime)) {
             return [];
         }
-        const result = [];
-        for (let current = startDate; Temporal.PlainDate.compare(current, endDate) <= 0; current = current.add({ days: resolvedStepDays })) {
-            result.push(current.toString());
+        try {
+            let start;
+            let end;
+            try {
+                start = zonedDateTimeFrom(startZonedDateTime);
+                end = zonedDateTimeFrom(endZonedDateTime);
+            }
+            catch {
+                return [];
+            }
+            if (start.timeZoneId !== end.timeZoneId) {
+                return [];
+            }
+            const startDate = start.toPlainDate();
+            const endDate = end.toPlainDate();
+            if (Temporal.PlainDate.compare(startDate, endDate) === 1) {
+                return [];
+            }
+            const count = Math.floor(startDate.until(endDate).days / resolvedStepDays) + 1;
+            if (exceedsPieceLimit(count, maxPieces)) {
+                return [];
+            }
+            // Each date is anchored at the start (start + k·step) and only the `count` in-range dates are
+            // built, so no step past the end is taken — a range ending on Temporal's date limit keeps its
+            // dates instead of throwing on the step after the last one.
+            const result = [];
+            for (let index = 0; index < count; index++) {
+                result.push(startDate.add({ days: index * resolvedStepDays }).toString());
+            }
+            return result;
+        }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

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

@@ -1,23 +1,20 @@
-import type { Disambiguation, Offset } from "../../types/index.js";
 /**
- * Return an array of zoned datetime strings representing each hour boundary for the 24-hour window starting at midnight of the anchor's local day.
+ * Return an array of zoned datetime strings representing each hour boundary of the anchor's local day.
  *
- * - Handles DST transitions by skipping non-existent hours in the loop (independent of `disambiguation`/`offset` below — arithmetic `.add()` never consults either option, it always resolves as Temporal's default).
- * - `disambiguation` controls DST gap/overlap resolution only for the midnight anchor itself, on the rare zone/date where local midnight is itself ambiguous (most IANA zones transition at 2am/3am, not midnight): "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in `[]`).
- * - `offset` controls whether the source's existing UTC offset is kept when computing the midnight anchor: "prefer" (Temporal's own default — keeps the source offset whenever still valid for the target midnight, which **makes `disambiguation` inert in that case**; note this is not universal — if the source's offset isn't valid for midnight at all (e.g. midnight itself falls inside a gap), `"prefer"` still throws/resolves via `disambiguation` same as `"ignore"` would), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset), or "reject" (throws if the source offset is invalid for midnight, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Steps hourly from the day's `startOfDay()` up to (not including) the next day's `startOfDay()`, so the result always stays on the anchor's date. A day whose local midnight is skipped (e.g. `America/Santiago` on 2024-09-08) starts at 01:00 and has 23 entries.
+ * - Handles DST transitions: hourly steps are exact elapsed hours, so a spring-forward day has 23 entries and a fall-back day 25.
+ * - In zones with a 30-minute shift (`Australia/Lord_Howe`), entries after the transition land on :30 — hourly steps are exact elapsed hours, not wall-clock hour marks (2024-10-06 gives `00:00`, `01:00`, `02:30`, … `23:30`).
+ * - The day is the anchor's calendar date, as TC39's `startOfDay()`/`hoursInDay` define it. This differs from `startOfZoned(…, "day")` only where a fall-back re-enters the previous date: `America/Goose_Bay` fell back at 00:01 on 2010-11-07, so an anchor at `2010-11-06T23:30:00-04:00` maps 6 November's 24 hours (ending at 00:00-03:00 on the 7th, before the anchor), while `startOfZoned` puts that anchor in a reopened 59-minute day.
+ * - Takes no options: the day's window is always real instants, as TC39's `startOfDay()` gives. The
+ *   ignored `disambiguation`/`offset` options argument was removed in 1.16.0.
  * - Returns [] for invalid input.
  *
  * @param anchor zoned ISO 8601 datetime string used as anchor
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
  * @returns array of zoned ISO 8601 strings for each hour in the day
  *
  * @example mapZonedHoursInDay("2024-02-29T12:34:56.789+00:00[UTC]") // ["2024-02-29T00:00:00+00:00[UTC]", "2024-02-29T01:00:00+00:00[UTC]", ..., "2024-02-29T23:00:00+00:00[UTC]"]
- * @example mapZonedHoursInDay("2024-03-10T12:34:56.789-05:00[America/New_York]") // ["2024-03-10T00:00:00-05:00[America/New_York]", ...] (skips 2 AM due to DST; unaffected by `disambiguation` since this gap is inside the loop's arithmetic, not the anchor)
- * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject" }) // [] (midnight itself is the DST transition in this historical Brazil zone/date, so the anchor is ambiguous and "reject" throws)
- * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject", offset: "prefer" }) // [] (the source's -02:00 offset is also invalid at midnight here, so even "prefer" falls through to disambiguation and "reject" still throws — contrast with startOfZoned's Nov 3 America/New_York example, where "prefer" IS valid at the target time and suppresses disambiguation)
+ * @example mapZonedHoursInDay("2024-03-10T12:34:56.789-04:00[America/New_York]") // ["2024-03-10T00:00:00-05:00[America/New_York]", ...] (23 entries; 2 AM is skipped — the anchor is after the spring-forward, so its offset is -04:00)
+ * @example mapZonedHoursInDay("2024-09-08T12:00:00-03:00[America/Santiago]") // ["2024-09-08T01:00:00-03:00[America/Santiago]", ..., "2024-09-08T23:00:00-03:00[America/Santiago]"] (23 entries; midnight is skipped)
  * @example mapZonedHoursInDay("invalid") // []
  */
-export declare function mapZonedHoursInDay(anchor: string, optionsArg?: {
-    disambiguation?: Disambiguation;
-    offset?: Offset;
-}): string[];
+export declare function mapZonedHoursInDay(anchor: string): string[];

package/dist/zoned/map/mapZonedHoursInDay.js

@@ -1,40 +1,32 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { addToZoned, zonedDateTimeFrom, zonedStartOfDay } from "../../internal/index.js";
 /**
- * Return an array of zoned datetime strings representing each hour boundary for the 24-hour window starting at midnight of the anchor's local day.
+ * Return an array of zoned datetime strings representing each hour boundary of the anchor's local day.
  *
- * - Handles DST transitions by skipping non-existent hours in the loop (independent of `disambiguation`/`offset` below — arithmetic `.add()` never consults either option, it always resolves as Temporal's default).
- * - `disambiguation` controls DST gap/overlap resolution only for the midnight anchor itself, on the rare zone/date where local midnight is itself ambiguous (most IANA zones transition at 2am/3am, not midnight): "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in `[]`).
- * - `offset` controls whether the source's existing UTC offset is kept when computing the midnight anchor: "prefer" (Temporal's own default — keeps the source offset whenever still valid for the target midnight, which **makes `disambiguation` inert in that case**; note this is not universal — if the source's offset isn't valid for midnight at all (e.g. midnight itself falls inside a gap), `"prefer"` still throws/resolves via `disambiguation` same as `"ignore"` would), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset), or "reject" (throws if the source offset is invalid for midnight, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Steps hourly from the day's `startOfDay()` up to (not including) the next day's `startOfDay()`, so the result always stays on the anchor's date. A day whose local midnight is skipped (e.g. `America/Santiago` on 2024-09-08) starts at 01:00 and has 23 entries.
+ * - Handles DST transitions: hourly steps are exact elapsed hours, so a spring-forward day has 23 entries and a fall-back day 25.
+ * - In zones with a 30-minute shift (`Australia/Lord_Howe`), entries after the transition land on :30 — hourly steps are exact elapsed hours, not wall-clock hour marks (2024-10-06 gives `00:00`, `01:00`, `02:30`, … `23:30`).
+ * - The day is the anchor's calendar date, as TC39's `startOfDay()`/`hoursInDay` define it. This differs from `startOfZoned(…, "day")` only where a fall-back re-enters the previous date: `America/Goose_Bay` fell back at 00:01 on 2010-11-07, so an anchor at `2010-11-06T23:30:00-04:00` maps 6 November's 24 hours (ending at 00:00-03:00 on the 7th, before the anchor), while `startOfZoned` puts that anchor in a reopened 59-minute day.
+ * - Takes no options: the day's window is always real instants, as TC39's `startOfDay()` gives. The
+ *   ignored `disambiguation`/`offset` options argument was removed in 1.16.0.
  * - Returns [] for invalid input.
  *
  * @param anchor zoned ISO 8601 datetime string used as anchor
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
  * @returns array of zoned ISO 8601 strings for each hour in the day
  *
  * @example mapZonedHoursInDay("2024-02-29T12:34:56.789+00:00[UTC]") // ["2024-02-29T00:00:00+00:00[UTC]", "2024-02-29T01:00:00+00:00[UTC]", ..., "2024-02-29T23:00:00+00:00[UTC]"]
- * @example mapZonedHoursInDay("2024-03-10T12:34:56.789-05:00[America/New_York]") // ["2024-03-10T00:00:00-05:00[America/New_York]", ...] (skips 2 AM due to DST; unaffected by `disambiguation` since this gap is inside the loop's arithmetic, not the anchor)
- * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject" }) // [] (midnight itself is the DST transition in this historical Brazil zone/date, so the anchor is ambiguous and "reject" throws)
- * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject", offset: "prefer" }) // [] (the source's -02:00 offset is also invalid at midnight here, so even "prefer" falls through to disambiguation and "reject" still throws — contrast with startOfZoned's Nov 3 America/New_York example, where "prefer" IS valid at the target time and suppresses disambiguation)
+ * @example mapZonedHoursInDay("2024-03-10T12:34:56.789-04:00[America/New_York]") // ["2024-03-10T00:00:00-05:00[America/New_York]", ...] (23 entries; 2 AM is skipped — the anchor is after the spring-forward, so its offset is -04:00)
+ * @example mapZonedHoursInDay("2024-09-08T12:00:00-03:00[America/Santiago]") // ["2024-09-08T01:00:00-03:00[America/Santiago]", ..., "2024-09-08T23:00:00-03:00[America/Santiago]"] (23 entries; midnight is skipped)
  * @example mapZonedHoursInDay("invalid") // []
  */
-export function mapZonedHoursInDay(anchor, optionsArg) {
+export function mapZonedHoursInDay(anchor) {
     if (!isValidZonedDateTime(anchor)) {
         return [];
     }
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(anchor);
-        const start = zonedDateTime.with({
-            hour: 0,
-            minute: 0,
-            second: 0,
-            millisecond: 0,
-            microsecond: 0,
-            nanosecond: 0,
-        }, { disambiguation, offset });
-        const nextDay = start.add({ days: 1 });
+        const start = zonedStartOfDay(zonedDateTimeFrom(anchor));
+        const nextDay = zonedStartOfDay(addToZoned(start, { days: 1 }));
         const result = [];
         for (let current = start; Temporal.Instant.compare(current.toInstant(), nextDay.toInstant()) < 0; current = current.add({ hours: 1 })) {
             result.push(current.toString());

package/dist/zoned/parse/getZonedOffset.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Extract the UTC offset from an ISO 8601 zoned datetime string.
  *
@@ -21,7 +21,7 @@ export function getZonedOffset(value) {
         return "";
     }
     try {
-        return Temporal.ZonedDateTime.from(value).offset;
+        return zonedDateTimeFrom(value).offset;
     }
     catch {
         return "";