@northguild/gmt 1.14.2

package/dist/zoned/interval/intervalSplitAtZoned.js

@@ -0,0 +1,84 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { isValidCalendarZonedDateTime } from "../validate/isValidCalendarZonedDateTime.js";
+import { isValidCalendarZonedInterval } from "./validate/index.js";
+/**
+ * Split a zoned interval at arbitrary `points`, producing consecutive sub-intervals.
+ *
+ * - `points` need not be sorted — they are sorted internally (by instant) before splitting.
+ * - Comparison and boundary placement use the instant each point represents, so points may
+ *   carry a different time zone than `start`/`end`.
+ * - Points outside `[start, end]` are dropped; they cannot introduce a boundary that isn't
+ *   inside the interval.
+ * - Points on the same instant as `start` or `end` are dropped too — they would only produce a
+ *   zero-length sub-interval at the edge.
+ * - Duplicate points (same instant) collapse to a single boundary.
+ * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
+ * - Returns `[]` when `points` is not an array, when any element is not a valid ISO
+ *   ZonedDateTime string, or on invalid input (unparseable start/end, `start > end`,
+ *   leap-second strings).
+ * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched set**: `start`, `end`
+ *   and every element of `points` must name the same calendar system (E7's D4-zoned), since the
+ *   returned sub-intervals are values the caller reads back as datetimes and an array of
+ *   differently-tagged records would be unreadable as a set. A mismatch returns `[]`.
+ * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
+ *   copied from an input string (E7's D7-zoned).
+ *
+ * @param start ISO 8601 zoned datetime string for the interval start
+ * @param end ISO 8601 zoned datetime string for the interval end
+ * @param points array of ISO 8601 zoned datetime strings to split at
+ * @returns array of `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalSplitAtZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-10T00:00:00+00:00[UTC]", ["2024-01-05T00:00:00+00:00[UTC]"]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-05T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }]
+ * @example intervalSplitAtZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-10T00:00:00+00:00[UTC]", []) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }]
+ * @example intervalSplitAtZoned("invalid", "2024-01-10T00:00:00+00:00[UTC]", ["2024-01-05T00:00:00+00:00[UTC]"]) // []
+ */
+export function intervalSplitAtZoned(start, end, points) {
+    if (!Array.isArray(points)) {
+        return [];
+    }
+    if (!isValidCalendarZonedInterval(start, end)) {
+        return [];
+    }
+    if (!points.every((point) => isValidCalendarZonedDateTime(point))) {
+        return [];
+    }
+    // D4-zoned reject gate: the interval's endpoints AND every split point must agree on a
+    // calendar, or there is no calendar to express the returned sub-intervals in.
+    const calendar = calendarOfAllZonedValues([start, end, ...points]);
+    if (!calendar) {
+        return [];
+    }
+    try {
+        const startVal = parseCalendarZonedValue(start);
+        const endVal = parseCalendarZonedValue(end);
+        const startInstant = startVal.toInstant();
+        const endInstant = endVal.toInstant();
+        const parsedPoints = points.map((point) => parseCalendarZonedValue(point));
+        const inRangePoints = parsedPoints.filter((point) => {
+            const instant = point.toInstant();
+            return (Temporal.Instant.compare(instant, startInstant) > 0 &&
+                Temporal.Instant.compare(instant, endInstant) < 0);
+        });
+        inRangePoints.sort((a, b) => Temporal.Instant.compare(a.toInstant(), b.toInstant()));
+        // Safe: `.equals()` here is `Temporal.Instant.prototype.equals`, and `Instant` carries no
+        // calendar field at all — verified calendar-blind. E7 re-audited this site rather than
+        // inheriting E5's "structurally unreachable" verdict, which depended on mixed calendars never
+        // reaching `zoned/` at all.
+        const uniquePoints = inRangePoints.filter((point, index) => index === 0 ||
+            !point.toInstant().equals(inRangePoints[index - 1].toInstant()));
+        const boundaries = [startVal, ...uniquePoints, endVal];
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({
+                start: formatZonedInCalendar(boundaries[i], calendar),
+                end: formatZonedInCalendar(boundaries[i + 1], calendar),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Return the combined span of two zoned intervals, or null when they are disjoint.
+ *
+ * - Uses `Temporal.ZonedDateTime.compare` for comparison (same instant semantics).
+ * - Overlapping intervals return their merged span.
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Accepts GMT 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
+ *   one endpoint's calendar as the answer's. Rejection also keeps a uniform policy across all
+ *   eight value-returning zoned set operations, four of which return arrays — a per-element
+ *   "winner's tag" would produce a result set whose members disagree about which calendar they
+ *   are in. (`intervalUnionZoned`'s existing "winning endpoint's *time zone* wins" is not
+ *   precedent: the zone is a property of the surviving point, the calendar is a property of the
+ *   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`.
+ *
+ * @param aStart ISO 8601 zoned datetime string for the first interval start
+ * @param aEnd ISO 8601 zoned datetime string for the first interval end
+ * @param bStart ISO 8601 zoned datetime string for the second interval start
+ * @param bEnd ISO 8601 zoned datetime string for the second interval end
+ * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
+ *
+ * @example intervalUnionZoned("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]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
+ * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
+ * @example intervalUnionZoned("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]") // null
+ * @example intervalUnionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
+ */
+export declare function intervalUnionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    start: string;
+    end: string;
+} | null;

package/dist/zoned/interval/intervalUnionZoned.js

@@ -0,0 +1,79 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { isValidCalendarZonedDateTime } from "../validate/index.js";
+/**
+ * Return the combined span of two zoned intervals, or null when they are disjoint.
+ *
+ * - Uses `Temporal.ZonedDateTime.compare` for comparison (same instant semantics).
+ * - Overlapping intervals return their merged span.
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Accepts GMT 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
+ *   one endpoint's calendar as the answer's. Rejection also keeps a uniform policy across all
+ *   eight value-returning zoned set operations, four of which return arrays — a per-element
+ *   "winner's tag" would produce a result set whose members disagree about which calendar they
+ *   are in. (`intervalUnionZoned`'s existing "winning endpoint's *time zone* wins" is not
+ *   precedent: the zone is a property of the surviving point, the calendar is a property of the
+ *   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`.
+ *
+ * @param aStart ISO 8601 zoned datetime string for the first interval start
+ * @param aEnd ISO 8601 zoned datetime string for the first interval end
+ * @param bStart ISO 8601 zoned datetime string for the second interval start
+ * @param bEnd ISO 8601 zoned datetime string for the second interval end
+ * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
+ *
+ * @example intervalUnionZoned("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]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
+ * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
+ * @example intervalUnionZoned("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]") // null
+ * @example intervalUnionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
+ */
+export function intervalUnionZoned(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.
+    if (!isValidCalendarZonedDateTime(aStart) ||
+        !isValidCalendarZonedDateTime(aEnd) ||
+        !isValidCalendarZonedDateTime(bStart) ||
+        !isValidCalendarZonedDateTime(bEnd)) {
+        return null;
+    }
+    // D4-zoned reject gate: all four endpoints must agree on a calendar, or there is no calendar to
+    // express the returned value in.
+    const calendar = calendarOfAllZonedValues([aStart, aEnd, bStart, bEnd]);
+    if (!calendar) {
+        return null;
+    }
+    try {
+        const aZdt = parseCalendarZonedValue(aStart);
+        const aZde = parseCalendarZonedValue(aEnd);
+        const bZdt = parseCalendarZonedValue(bStart);
+        const bZde = parseCalendarZonedValue(bEnd);
+        if (Temporal.ZonedDateTime.compare(aZdt, aZde) > 0) {
+            return null;
+        }
+        if (Temporal.ZonedDateTime.compare(bZdt, bZde) > 0) {
+            return null;
+        }
+        if (Temporal.ZonedDateTime.compare(aZde, bZdt) < 0 ||
+            Temporal.ZonedDateTime.compare(bZde, aZdt) < 0) {
+            return null;
+        }
+        const start = Temporal.ZonedDateTime.compare(aZdt, bZdt) <= 0 ? aZdt : bZdt;
+        const end = Temporal.ZonedDateTime.compare(aZde, bZde) >= 0 ? aZde : bZde;
+        return {
+            start: formatZonedInCalendar(start, calendar),
+            end: formatZonedInCalendar(end, calendar),
+        };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Return the symmetric difference across a list of zoned intervals — the set of instants
+ * covered by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorZoned`, which is pairwise only.
+ * - Implemented as a coverage sweep over instants: each interval contributes a `+1` at its
+ *   start instant and a `-1` one nanosecond after its end instant; the result is every maximal
+ *   run where the running coverage count is odd. For two intervals this reduces to exactly
+ *   `intervalXorZoned`'s pairwise result.
+ * - Output boundaries carry the time zone of whichever input interval contributed them.
+ * - Order of the input list does not matter; the result is sorted by start instant.
+ * - Returns `[]` for an empty list, and `[]` when every instant is covered an even number of
+ *   times (e.g. two identical intervals cancel out).
+ * - 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
+ *   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
+ *   tags would be unreadable as a set. A mismatch returns `[]`.
+ * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
+ *   copied from an input string (E7's D7-zoned).
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllZoned([{ 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-04T23:59:59.999999999+00:00[UTC]" }, { start: "2024-01-10T00:00:00.000000001+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
+ * @example intervalXorAllZoned([]) // []
+ */
+export declare function intervalXorAllZoned(intervals: Array<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/zoned/interval/intervalXorAllZoned.js

@@ -0,0 +1,108 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { isValidCalendarZonedInterval } from "./validate/index.js";
+/**
+ * Return the symmetric difference across a list of zoned intervals — the set of instants
+ * covered by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorZoned`, which is pairwise only.
+ * - Implemented as a coverage sweep over instants: each interval contributes a `+1` at its
+ *   start instant and a `-1` one nanosecond after its end instant; the result is every maximal
+ *   run where the running coverage count is odd. For two intervals this reduces to exactly
+ *   `intervalXorZoned`'s pairwise result.
+ * - Output boundaries carry the time zone of whichever input interval contributed them.
+ * - Order of the input list does not matter; the result is sorted by start instant.
+ * - Returns `[]` for an empty list, and `[]` when every instant is covered an even number of
+ *   times (e.g. two identical intervals cancel out).
+ * - 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
+ *   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
+ *   tags would be unreadable as a set. A mismatch returns `[]`.
+ * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
+ *   copied from an input string (E7's D7-zoned).
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllZoned([{ 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-04T23:59:59.999999999+00:00[UTC]" }, { start: "2024-01-10T00:00:00.000000001+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
+ * @example intervalXorAllZoned([]) // []
+ */
+export function intervalXorAllZoned(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 returned boundaries in.
+    const calendar = calendarOfAllZonedValues(intervals.flatMap((interval) => [interval.start, interval.end]));
+    if (!calendar) {
+        return [];
+    }
+    try {
+        const events = [];
+        for (const interval of intervals) {
+            const startVal = parseCalendarZonedValue(interval.start);
+            const endVal = parseCalendarZonedValue(interval.end);
+            const closesAfter = endVal.toInstant().add({ nanoseconds: 1 });
+            events.push({
+                instant: startVal.toInstant(),
+                boundary: startVal,
+                delta: 1,
+            });
+            events.push({
+                instant: closesAfter,
+                boundary: closesAfter.toZonedDateTimeISO(endVal.timeZoneId),
+                delta: -1,
+            });
+        }
+        events.sort((a, b) => Temporal.Instant.compare(a.instant, b.instant));
+        const grouped = [];
+        for (const event of events) {
+            const last = grouped[grouped.length - 1];
+            // Safe: `.equals()` here is `Temporal.Instant.prototype.equals`, and `Instant` carries no
+            // calendar field at all — verified calendar-blind (`heb.toInstant().equals(iso.toInstant())`
+            // is `true` for the same instant, while `ZonedDateTime.prototype.equals` is not). E7
+            // re-audited this site rather than inheriting E5's "structurally unreachable" verdict, which
+            // depended on mixed calendars never reaching `zoned/` at all.
+            if (last && last.instant.equals(event.instant)) {
+                last.delta += event.delta;
+            }
+            else {
+                grouped.push(event);
+            }
+        }
+        const result = [];
+        let coverage = 0;
+        let runStart = null;
+        for (const group of grouped) {
+            const previousCoverage = coverage;
+            coverage += group.delta;
+            if (previousCoverage % 2 === 0 && coverage % 2 === 1) {
+                runStart = group.boundary;
+            }
+            else if (previousCoverage % 2 === 1 && coverage % 2 === 0 && runStart) {
+                result.push({
+                    start: formatZonedInCalendar(runStart, calendar),
+                    end: formatZonedInCalendar(group.instant
+                        .subtract({ nanoseconds: 1 })
+                        .toZonedDateTimeISO(group.boundary.timeZoneId), calendar),
+                });
+                runStart = null;
+            }
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Return the symmetric difference of two zoned intervals — time 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 one interval fully contains the other.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - 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
+ *   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
+ *   one endpoint's calendar as the answer's. Rejection also keeps a uniform policy across all
+ *   eight value-returning zoned set operations, four of which return arrays — a per-element
+ *   "winner's tag" would produce a result set whose members disagree about which calendar they
+ *   are in. (`intervalUnionZoned`'s existing "winning endpoint's *time zone* wins" is not
+ *   precedent: the zone is a property of the surviving point, the calendar is a property of the
+ *   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`.
+ *
+ * @param aStart ISO 8601 zoned datetime string for the first interval start
+ * @param aEnd ISO 8601 zoned datetime string for the first interval end
+ * @param bStart ISO 8601 zoned datetime string for the second interval start
+ * @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]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+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-04-01T11:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+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 declare function intervalXorZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/zoned/interval/intervalXorZoned.js

@@ -0,0 +1,118 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllZonedValues, formatZonedInCalendar, 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.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
+ * - Returns `[]` when intervals are identical or both invalid.
+ * - Returns `[{ start, end }]` when one interval fully contains the other.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - 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
+ *   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
+ *   one endpoint's calendar as the answer's. Rejection also keeps a uniform policy across all
+ *   eight value-returning zoned set operations, four of which return arrays — a per-element
+ *   "winner's tag" would produce a result set whose members disagree about which calendar they
+ *   are in. (`intervalUnionZoned`'s existing "winning endpoint's *time zone* wins" is not
+ *   precedent: the zone is a property of the surviving point, the calendar is a property of the
+ *   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`.
+ *
+ * @param aStart ISO 8601 zoned datetime string for the first interval start
+ * @param aEnd ISO 8601 zoned datetime string for the first interval end
+ * @param bStart ISO 8601 zoned datetime string for the second interval start
+ * @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]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+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-04-01T11:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+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.
+    if (!isValidCalendarZonedDateTime(aStart) ||
+        !isValidCalendarZonedDateTime(aEnd) ||
+        !isValidCalendarZonedDateTime(bStart) ||
+        !isValidCalendarZonedDateTime(bEnd)) {
+        return [];
+    }
+    // D4-zoned reject gate: all four endpoints must agree on a calendar, or there is no calendar to
+    // express the returned value in.
+    const calendar = calendarOfAllZonedValues([aStart, aEnd, bStart, bEnd]);
+    if (!calendar) {
+        return [];
+    }
+    try {
+        const aSZdt = parseCalendarZonedValue(aStart);
+        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) {
+            return [];
+        }
+        if (Temporal.Instant.compare(bS, bE) > 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;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Return true when 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`.
+ * - 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 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`.
+ *
+ * @param aStart ISO 8601 zoned datetime string for the first interval start
+ * @param aEnd ISO 8601 zoned datetime string for the first interval end
+ * @param bStart ISO 8601 zoned datetime string for the second interval start
+ * @param bEnd ISO 8601 zoned datetime string for the second interval end
+ * @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("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

@@ -0,0 +1,62 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { 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.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
+ * - Adjacent intervals (e.g. `aEnd === bStart`) do NOT overlap — 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 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`.
+ *
+ * @param aStart ISO 8601 zoned datetime string for the first interval start
+ * @param aEnd ISO 8601 zoned datetime string for the first interval end
+ * @param bStart ISO 8601 zoned datetime string for the second interval start
+ * @param bEnd ISO 8601 zoned datetime string for the second interval end
+ * @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("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.
+    if (!isValidCalendarZonedDateTime(aStart) ||
+        !isValidCalendarZonedDateTime(aEnd) ||
+        !isValidCalendarZonedDateTime(bStart) ||
+        !isValidCalendarZonedDateTime(bEnd)) {
+        return false;
+    }
+    try {
+        const aZdt = parseCalendarZonedValue(aStart);
+        const aZde = parseCalendarZonedValue(aEnd);
+        const bZdt = parseCalendarZonedValue(bStart);
+        const bZde = parseCalendarZonedValue(bEnd);
+        const aSI = aZdt.toInstant();
+        const aEI = aZde.toInstant();
+        const bSI = bZdt.toInstant();
+        const bEI = bZde.toInstant();
+        if (Temporal.Instant.compare(aSI, aEI) > 0) {
+            return false;
+        }
+        if (Temporal.Instant.compare(bSI, bEI) > 0) {
+            return false;
+        }
+        return (Temporal.Instant.compare(aEI, bSI) >= 0 &&
+            Temporal.Instant.compare(bEI, aSI) >= 0);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Collapse a list of zoned intervals into the minimum set of non-overlapping intervals.
+ *
+ * - 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).
+ * - 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.
+ * - Returns `[]` for an empty list.
+ * - 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
+ *   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
+ *   tags would be unreadable as a set. A mismatch returns `[]`.
+ * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
+ *   copied from an input string (E7's D7-zoned).
+ *
+ * @param intervals array of `{ start, end }` records
+ * @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([]) // []
+ */
+export declare function mergeIntervalsZoned(intervals: Array<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}>;