@northguild/gmt 1.15.0 → 1.17.0

package/dist/zoned/interval/intervalXorZoned.js

@@ -1,18 +1,27 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { calendarOfAllZonedValues, formatZonedInCalendar, halfOpenXor, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return the symmetric difference of two zoned intervals — time covered by exactly one interval.
+ * Return the symmetric difference of two half-open zoned intervals `[start, end)` — the instants
+ * covered by exactly one interval.
  *
- * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
- * - Returns `[]` when intervals are identical or both invalid.
- * - Returns `[{ start, end }]` when the intervals share exactly one boundary — one starts (or
- *   ends) precisely where the other ends (or starts), so only one remainder piece exists.
- * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap, and also when
- *   one interval strictly contains the other (the piece before B and the piece after B).
+ * - Compares instants (`Temporal.ZonedDateTime.compare`, calendar- and zone-blind).
+ * - The result is every maximal run covered by exactly one interval, sorted by start instant — the
+ *   same as `mergeIntervals` of `subtractIntervals(a, [b])` and `subtractIntervals(b, [a])`, and
+ *   the same as `intervalXorAllZoned([a, b])`.
+ * - Every boundary is an input's own `start` or `end`, in that input's time zone (the first
+ *   interval's on a tie); no boundary is stepped by a nanosecond.
+ * - Touching intervals share no instant, so they join into one run. An empty interval (`start`
+ *   and `end` the same instant) holds no instant and changes nothing.
+ * - Returns `[]` when the intervals are identical.
+ * - Returns `[{ start, end }]` when the intervals share a start or an end, or touch.
+ * - Returns `[{ start, end }, { start, end }]` when they partially overlap, when one strictly
+ *   contains the other (the piece before B and the piece after B), or when they are disjoint with
+ *   a gap.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
- * - 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) — but **rejects a mismatched pair**: every endpoint
  *   must name the same calendar system (E7's D4-zoned). Unlike the ordering functions, this one
  *   returns a *value* the caller reads back as a datetime, and there is no principled way to pick
@@ -24,8 +33,7 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  *   answer.) A mismatch returns the sentinel.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering — see
- *   `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
  *
  * @param aStart ISO 8601 zoned datetime string for the first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -33,15 +41,16 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
  *
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // partial overlap — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-04-01T10:59:59.999999999+00:00[UTC]" }, { start: "2024-06-30T12:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-02-01T08:00:00+00:00[UTC]", "2024-03-01T10:00:00+00:00[UTC]") // B strictly inside A — two remainder pieces — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-02-01T07:59:59.999999999+00:00[UTC]" }, { start: "2024-03-01T10:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // partial overlap — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-04-01T11:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-02-01T08:00:00+00:00[UTC]", "2024-03-01T10:00:00+00:00[UTC]") // B strictly inside A — two remainder pieces — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-02-01T08:00:00+00:00[UTC]" }, { start: "2024-03-01T10:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // touching intervals join — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
  * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  * @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 function intervalXorZoned(aStart, aEnd, bStart, bEnd) {
     // One gate for all four endpoints: `isValidCalendarZonedDateTime` covers non-strings, empty
     // strings, leap seconds (which Temporal would otherwise silently clamp to :59), unknown zones
-    // and Temporal's forbidden segment ordering, while accepting GMT's calendar-annotated grammar.
+    // and a calendar annotation before the zone, while accepting RFC 9557 calendar annotations.
     if (!isValidCalendarZonedDateTime(aStart) ||
         !isValidCalendarZonedDateTime(aEnd) ||
         !isValidCalendarZonedDateTime(bStart) ||
@@ -59,60 +68,21 @@ export function intervalXorZoned(aStart, aEnd, bStart, bEnd) {
         const aEZdt = parseCalendarZonedValue(aEnd);
         const bSZdt = parseCalendarZonedValue(bStart);
         const bEZdt = parseCalendarZonedValue(bEnd);
-        const aS = aSZdt.toInstant();
-        const aE = aEZdt.toInstant();
-        const bS = bSZdt.toInstant();
-        const bE = bEZdt.toInstant();
-        if (Temporal.Instant.compare(aS, aE) > 0) {
+        if (Temporal.ZonedDateTime.compare(aSZdt, aEZdt) > 0) {
             return [];
         }
-        if (Temporal.Instant.compare(bS, bE) > 0) {
+        if (Temporal.ZonedDateTime.compare(bSZdt, bEZdt) > 0) {
             return [];
         }
-        const result = [];
-        // If intervals don't overlap, return both as-is
-        if (Temporal.Instant.compare(aE, bS) < 0 ||
-            Temporal.Instant.compare(bE, aS) < 0) {
-            return [
-                {
-                    start: formatZonedInCalendar(aSZdt, calendar),
-                    end: formatZonedInCalendar(aEZdt, calendar),
-                },
-                {
-                    start: formatZonedInCalendar(bSZdt, calendar),
-                    end: formatZonedInCalendar(bEZdt, calendar),
-                },
-            ];
-        }
-        // Left piece: A before B starts
-        if (Temporal.Instant.compare(aS, bS) < 0) {
-            result.push({
-                start: formatZonedInCalendar(aSZdt, calendar),
-                end: formatZonedInCalendar(bS.subtract({ nanoseconds: 1 }).toZonedDateTimeISO(aEZdt.timeZoneId), calendar),
-            });
-        }
-        // Right piece: A after B ends
-        if (Temporal.Instant.compare(aE, bE) > 0) {
-            result.push({
-                start: formatZonedInCalendar(bE.add({ nanoseconds: 1 }).toZonedDateTimeISO(aEZdt.timeZoneId), calendar),
-                end: formatZonedInCalendar(aEZdt, calendar),
-            });
-        }
-        // Left piece: B before A starts
-        if (Temporal.Instant.compare(bS, aS) < 0) {
-            result.push({
-                start: formatZonedInCalendar(bSZdt, calendar),
-                end: formatZonedInCalendar(aS.subtract({ nanoseconds: 1 }).toZonedDateTimeISO(bEZdt.timeZoneId), calendar),
-            });
-        }
-        // Right piece: B after A ends
-        if (Temporal.Instant.compare(bE, aE) > 0) {
-            result.push({
-                start: formatZonedInCalendar(aE.add({ nanoseconds: 1 }).toZonedDateTimeISO(bEZdt.timeZoneId), calendar),
-                end: formatZonedInCalendar(bEZdt, calendar),
-            });
-        }
-        return result;
+        // Maximal runs covered exactly once. Each boundary is the ZonedDateTime that supplied it (the
+        // first interval's on a tie), so it keeps that input's zone.
+        return halfOpenXor([
+            { start: aSZdt, end: aEZdt },
+            { start: bSZdt, end: bEZdt },
+        ], Temporal.ZonedDateTime.compare).map(({ start, end }) => ({
+            start: formatZonedInCalendar(start, calendar),
+            end: formatZonedInCalendar(end, calendar),
+        }));
     }
     catch {
         return [];

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

@@ -1,18 +1,25 @@
 /**
- * Return true when intervals `[aStart, aEnd]` and `[bStart, bEnd]` share at least one instant.
+ * Return true when the half-open intervals `[aStart, aEnd)` and `[bStart, bEnd)` share at least
+ * one instant.
  *
- * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
- * - Adjacent intervals (e.g. `aEnd === bStart`) do NOT overlap — returns `false`.
+ * - Uses `Temporal.Instant.compare` for comparison (same instant semantics):
+ *   `aStart < bEnd && bStart < aEnd`, the same rule as `intervalsOverlap` (SQL:2011 `OVERLAPS` on
+ *   closed-open periods).
+ * - An interval excludes its `end`, so touching intervals (`aEnd` the same instant as `bStart`) do
+ *   NOT overlap — returns `false`.
+ * - An empty interval (`start` and `end` the same instant) overlaps an interval only when it lies
+ *   strictly inside it; at either edge, or against another empty interval, it returns `false`.
  * - Returns `false` if either interval is invalid (`start > end`).
  * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
  * - **Accepts mixed calendar systems** (E7's D4-zoned, issue #152): both bare ISO zoned strings
- *   and GMT calendar-annotated ones (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`),
+ *   and RFC 9557 calendar-annotated ones (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`),
  *   and the two endpoints need not agree on a calendar. Ordering is calendar-independent —
  *   verified that `Temporal.Instant` carries no calendar field at all and that
  *   `Instant.compare`/`ZonedDateTime.compare` both return `0` for the same instant expressed in
  *   hebrew, islamic-civil, japanese and iso8601.
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering, which reads GMT's
- *   calendar-native digits as ISO digits — see `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
+ * - 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 aStart ISO 8601 zoned datetime string for the first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -21,7 +28,8 @@
  * @returns true if intervals overlap, or false on invalid input
  *
  * @example intervalsOverlapZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
- * @example intervalsOverlapZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // false (adjacent)
+ * @example intervalsOverlapZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T00:00:00+00:00[UTC]") // false (touching: the first interval excludes 07-01T00:00)
+ * @example intervalsOverlapZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T07:00:00-05:00[America/New_York]", "2024-01-01T17:00:00+00:00[UTC]") // false (touching across zones)
  * @example intervalsOverlapZoned("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]") // false
  */
 export declare function intervalsOverlapZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;

package/dist/zoned/interval/intervalsOverlapZoned.js

@@ -1,21 +1,29 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { parseCalendarZonedValue } from "../../internal/index.js";
+import { halfOpenOverlap, parseCalendarZonedValue } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return true when intervals `[aStart, aEnd]` and `[bStart, bEnd]` share at least one instant.
+ * Return true when the half-open intervals `[aStart, aEnd)` and `[bStart, bEnd)` share at least
+ * one instant.
  *
- * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
- * - Adjacent intervals (e.g. `aEnd === bStart`) do NOT overlap — returns `false`.
+ * - Uses `Temporal.Instant.compare` for comparison (same instant semantics):
+ *   `aStart < bEnd && bStart < aEnd`, the same rule as `intervalsOverlap` (SQL:2011 `OVERLAPS` on
+ *   closed-open periods).
+ * - An interval excludes its `end`, so touching intervals (`aEnd` the same instant as `bStart`) do
+ *   NOT overlap — returns `false`.
+ * - An empty interval (`start` and `end` the same instant) overlaps an interval only when it lies
+ *   strictly inside it; at either edge, or against another empty interval, it returns `false`.
  * - Returns `false` if either interval is invalid (`start > end`).
  * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
  * - **Accepts mixed calendar systems** (E7's D4-zoned, issue #152): both bare ISO zoned strings
- *   and GMT calendar-annotated ones (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`),
+ *   and RFC 9557 calendar-annotated ones (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`),
  *   and the two endpoints need not agree on a calendar. Ordering is calendar-independent —
  *   verified that `Temporal.Instant` carries no calendar field at all and that
  *   `Instant.compare`/`ZonedDateTime.compare` both return `0` for the same instant expressed in
  *   hebrew, islamic-civil, japanese and iso8601.
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering, which reads GMT's
- *   calendar-native digits as ISO digits — see `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
+ * - 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 aStart ISO 8601 zoned datetime string for the first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -24,14 +32,15 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @returns true if intervals overlap, or false on invalid input
  *
  * @example intervalsOverlapZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
- * @example intervalsOverlapZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // false (adjacent)
+ * @example intervalsOverlapZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T00:00:00+00:00[UTC]") // false (touching: the first interval excludes 07-01T00:00)
+ * @example intervalsOverlapZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T07:00:00-05:00[America/New_York]", "2024-01-01T17:00:00+00:00[UTC]") // false (touching across zones)
  * @example intervalsOverlapZoned("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]") // false
  */
 export function intervalsOverlapZoned(aStart, aEnd, bStart, bEnd) {
     // One gate for all four endpoints: `isValidCalendarZonedDateTime` already covers non-strings,
     // empty strings, leap seconds (which Temporal would otherwise silently clamp to :59), unknown
-    // zones and Temporal's forbidden segment ordering — and, unlike `isValidZonedDateTime`, accepts
-    // GMT's calendar-annotated grammar.
+    // zones and a calendar annotation before the zone — and, unlike `isValidZonedDateTime`, accepts
+    // RFC 9557 calendar annotations.
     if (!isValidCalendarZonedDateTime(aStart) ||
         !isValidCalendarZonedDateTime(aEnd) ||
         !isValidCalendarZonedDateTime(bStart) ||
@@ -53,8 +62,8 @@ export function intervalsOverlapZoned(aStart, aEnd, bStart, bEnd) {
         if (Temporal.Instant.compare(bSI, bEI) > 0) {
             return false;
         }
-        return (Temporal.Instant.compare(aEI, bSI) >= 0 &&
-            Temporal.Instant.compare(bEI, aSI) >= 0);
+        // Each interval starts before the other's exclusive end.
+        return halfOpenOverlap({ start: aSI, end: aEI }, { start: bSI, end: bEI }, Temporal.Instant.compare);
     }
     catch {
         return false;

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

@@ -4,8 +4,13 @@
  * - List-form generalization of `intervalUnionZoned`, which is pairwise only.
  * - Comparison and merging use each interval's instant, so intervals may carry different time
  *   zones.
- * - Intervals are merged when they overlap or share an instant exactly (adjacent intervals
- *   ARE merged).
+ * - Intervals are half-open `[start, end)`, the same rule as `mergeIntervals`. They are merged
+ *   when they overlap or touch (one's `end` is the same instant as the other's `start`), so the
+ *   runs returned never touch.
+ * - An empty interval (`start` and `end` the same instant) holds no instant: it is absorbed when
+ *   it touches or lies inside a run and dropped otherwise, so it never bridges a gap. A list of
+ *   only empty intervals returns `[]`, the same value as invalid input — use
+ *   `isValidCalendarZonedInterval` to tell them apart.
  * - Order of the input list does not matter; the result is sorted by start instant. Each merged
  *   record's `start`/`end` strings carry the time zone of whichever input interval contributed
  *   that boundary.
@@ -13,7 +18,7 @@
  * - Returns `[]` when `intervals` is not an array, when any element is not a
  *   `{ start, end }` record of valid ISO ZonedDateTime strings, or when any element has
  *   `start > end` or a leap-second string.
- * - 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) — but **rejects a mismatched set**: every endpoint in
  *   the list must name the same calendar system (E7's D4-zoned). This function returns *values*
  *   the caller reads back as datetimes, and an array whose elements carried different calendar
@@ -25,6 +30,8 @@
  * @returns the minimum set of non-overlapping `{ start, end }` records, sorted by start, or `[]` on invalid input
  *
  * @example mergeIntervalsZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
+ * @example mergeIntervalsZoned([{ start: "2024-01-01T09: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-01T17:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-01-01T17:00:00+00:00[UTC]" }] (touching)
+ * @example mergeIntervalsZoned([{ start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }]) // [] (an empty interval holds no instant)
  * @example mergeIntervalsZoned([]) // []
  */
 export declare function mergeIntervalsZoned(intervals: Array<{

package/dist/zoned/interval/mergeIntervalsZoned.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { calendarOfAllZonedValues, formatZonedInCalendar, halfOpenMerge, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedInterval } from "./validate/index.js";
 /**
  * Collapse a list of zoned intervals into the minimum set of non-overlapping intervals.
@@ -7,8 +8,13 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * - List-form generalization of `intervalUnionZoned`, which is pairwise only.
  * - Comparison and merging use each interval's instant, so intervals may carry different time
  *   zones.
- * - Intervals are merged when they overlap or share an instant exactly (adjacent intervals
- *   ARE merged).
+ * - Intervals are half-open `[start, end)`, the same rule as `mergeIntervals`. They are merged
+ *   when they overlap or touch (one's `end` is the same instant as the other's `start`), so the
+ *   runs returned never touch.
+ * - An empty interval (`start` and `end` the same instant) holds no instant: it is absorbed when
+ *   it touches or lies inside a run and dropped otherwise, so it never bridges a gap. A list of
+ *   only empty intervals returns `[]`, the same value as invalid input — use
+ *   `isValidCalendarZonedInterval` to tell them apart.
  * - Order of the input list does not matter; the result is sorted by start instant. Each merged
  *   record's `start`/`end` strings carry the time zone of whichever input interval contributed
  *   that boundary.
@@ -16,7 +22,7 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * - Returns `[]` when `intervals` is not an array, when any element is not a
  *   `{ start, end }` record of valid ISO ZonedDateTime strings, or when any element has
  *   `start > end` or a leap-second string.
- * - 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) — but **rejects a mismatched set**: every endpoint in
  *   the list must name the same calendar system (E7's D4-zoned). This function returns *values*
  *   the caller reads back as datetimes, and an array whose elements carried different calendar
@@ -28,50 +34,47 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * @returns the minimum set of non-overlapping `{ start, end }` records, sorted by start, or `[]` on invalid input
  *
  * @example mergeIntervalsZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
+ * @example mergeIntervalsZoned([{ start: "2024-01-01T09: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-01T17:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-01-01T17:00:00+00:00[UTC]" }] (touching)
+ * @example mergeIntervalsZoned([{ start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }]) // [] (an empty interval holds no instant)
  * @example mergeIntervalsZoned([]) // []
  */
 export function mergeIntervalsZoned(intervals) {
-    if (!Array.isArray(intervals) || intervals.length === 0) {
-        return [];
-    }
-    if (!intervals.every((interval) => interval &&
-        typeof interval === "object" &&
-        typeof interval.start === "string" &&
-        typeof interval.end === "string" &&
-        isValidCalendarZonedInterval(interval.start, interval.end))) {
-        return [];
-    }
-    // D4-zoned reject gate: every endpoint across every interval must agree on a calendar, or there
-    // is no calendar to express the merged boundaries in.
-    const calendar = calendarOfAllZonedValues(intervals.flatMap((interval) => [interval.start, interval.end]));
-    if (!calendar) {
-        return [];
-    }
     try {
-        const parsed = intervals.map((interval) => ({
-            start: parseCalendarZonedValue(interval.start),
-            end: parseCalendarZonedValue(interval.end),
-        }));
-        parsed.sort((a, b) => Temporal.Instant.compare(a.start.toInstant(), b.start.toInstant()));
-        const merged = [];
-        for (const interval of parsed) {
-            const last = merged[merged.length - 1];
-            if (last &&
-                Temporal.Instant.compare(interval.start.toInstant(), last.end.toInstant()) <= 0) {
-                if (Temporal.Instant.compare(interval.end.toInstant(), last.end.toInstant()) > 0) {
-                    last.end = interval.end;
-                }
-            }
-            else {
-                merged.push({ start: interval.start, end: interval.end });
-            }
+        if (!Array.isArray(intervals) || intervals.length === 0) {
+            return [];
+        }
+        if (!intervals.every((interval) => interval &&
+            typeof interval === "object" &&
+            typeof interval.start === "string" &&
+            typeof interval.end === "string" &&
+            isValidCalendarZonedInterval(interval.start, interval.end))) {
+            return [];
+        }
+        // D4-zoned reject gate: every endpoint across every interval must agree on a calendar, or there
+        // is no calendar to express the merged boundaries in.
+        const calendar = calendarOfAllZonedValues(intervals.flatMap((interval) => [interval.start, interval.end]));
+        if (!calendar) {
+            return [];
+        }
+        try {
+            const parsed = intervals.map((interval) => ({
+                start: parseCalendarZonedValue(interval.start),
+                end: parseCalendarZonedValue(interval.end),
+            }));
+            // Sorted, disjoint, non-touching, non-empty runs; each boundary keeps the ZonedDateTime (and
+            // so the zone) of the interval that contributed it.
+            return halfOpenMerge(parsed, Temporal.ZonedDateTime.compare).map((interval) => ({
+                start: formatZonedInCalendar(interval.start, calendar),
+                end: formatZonedInCalendar(interval.end, calendar),
+            }));
+        }
+        catch {
+            return [];
         }
-        return merged.map((interval) => ({
-            start: formatZonedInCalendar(interval.start, calendar),
-            end: formatZonedInCalendar(interval.end, calendar),
-        }));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

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

@@ -1,31 +1,54 @@
 /**
  * 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 declare function splitIntervalByUnitZoned(start: string, end: string, unit: string, amount: number): Array<{
+export declare function splitIntervalByUnitZoned(start: string, end: string, unit: string, amount: number, options?: {
+    maxPieces?: number;
+}): Array<{
     start: string;
     end: string;
 }>;