@northguild/gmt 1.14.2

package/dist/utc/interval/intervalOverlappingDaysUtc.js

@@ -0,0 +1,75 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return how many distinct UTC calendar dates two UTC intervals share.
+ *
+ * - Counts the number of UTC dates touched by the closed intersection
+ *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
+ * - Boundaries are UTC boundaries — no DST is involved.
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one date and count as `1`.
+ * - Returns `0` when the intervals do not overlap at all (a well-defined answer, not
+ *   invalid input).
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
+ *   24-hour periods instead of counting calendar dates (its own doc example — Jan 10-20 vs
+ *   Jan 17-21 — returns 3 there, 4 here). To reproduce date-fns's number, compose
+ *   `intervalIntersectionUtc` with `intervalCountUtc`:
+ *   `const span = intervalIntersectionUtc(aStart, aEnd, bStart, bEnd); span ? intervalCountUtc(span.start, span.end, "day") : 0;`
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
+ *
+ * @example intervalOverlappingDaysUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z") // 2
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z") // 1 (adjacent)
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z", "2024-01-04T00:00:00Z") // 0 (disjoint)
+ * @example intervalOverlappingDaysUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ */
+export function intervalOverlappingDaysUtc(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return null;
+    }
+    if (!utcDateTime.test(aStart) ||
+        !utcDateTime.test(aEnd) ||
+        !utcDateTime.test(bStart) ||
+        !utcDateTime.test(bEnd)) {
+        return null;
+    }
+    if (isLeapSecond(aStart) ||
+        isLeapSecond(aEnd) ||
+        isLeapSecond(bStart) ||
+        isLeapSecond(bEnd)) {
+        return null;
+    }
+    try {
+        const aS = Temporal.Instant.from(aStart);
+        const aE = Temporal.Instant.from(aEnd);
+        const bS = Temporal.Instant.from(bStart);
+        const bE = Temporal.Instant.from(bEnd);
+        if (Temporal.Instant.compare(aS, aE) > 0) {
+            return null;
+        }
+        if (Temporal.Instant.compare(bS, bE) > 0) {
+            return null;
+        }
+        if (Temporal.Instant.compare(aE, bS) < 0 ||
+            Temporal.Instant.compare(bE, aS) < 0) {
+            return 0;
+        }
+        const start = Temporal.Instant.compare(aS, bS) >= 0 ? aS : bS;
+        const end = Temporal.Instant.compare(aE, bE) <= 0 ? aE : bE;
+        const startDate = start.toZonedDateTimeISO("UTC").toPlainDate();
+        const endDate = end.toZonedDateTimeISO("UTC").toPlainDate();
+        return startDate.until(endDate, { largestUnit: "day" }).days + 1;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Split a UTC interval at arbitrary `points`, producing consecutive sub-intervals.
+ *
+ * - `points` need not be sorted — they are sorted internally before splitting.
+ * - Points outside `[start, end]` are dropped; they cannot introduce a boundary that isn't
+ *   inside the interval.
+ * - Points exactly on `start` or `end` are dropped too — they would only produce a
+ *   zero-length sub-interval at the edge.
+ * - Duplicate points 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 UTC
+ *   datetime string, or on invalid input (unparseable start/end, `start > end`, leap-second
+ *   strings).
+ *
+ * @param start ISO UTC datetime string for the interval start
+ * @param end ISO UTC datetime string for the interval end
+ * @param points array of ISO UTC datetime strings to split at
+ * @returns array of `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalSplitAtUtc("2024-01-01T00:00:00Z", "2024-01-10T00:00:00Z", ["2024-01-05T00:00:00Z"]) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-05T00:00:00Z" }, { start: "2024-01-05T00:00:00Z", end: "2024-01-10T00:00:00Z" }]
+ * @example intervalSplitAtUtc("2024-01-01T00:00:00Z", "2024-01-10T00:00:00Z", []) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-10T00:00:00Z" }]
+ * @example intervalSplitAtUtc("invalid", "2024-01-10T00:00:00Z", ["2024-01-05T00:00:00Z"]) // []
+ */
+export declare function intervalSplitAtUtc(start: string, end: string, points: string[]): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/utc/interval/intervalSplitAtUtc.js

@@ -0,0 +1,64 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+import { isValidUtcInterval } from "./validate/index.js";
+/**
+ * Split a UTC interval at arbitrary `points`, producing consecutive sub-intervals.
+ *
+ * - `points` need not be sorted — they are sorted internally before splitting.
+ * - Points outside `[start, end]` are dropped; they cannot introduce a boundary that isn't
+ *   inside the interval.
+ * - Points exactly on `start` or `end` are dropped too — they would only produce a
+ *   zero-length sub-interval at the edge.
+ * - Duplicate points 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 UTC
+ *   datetime string, or on invalid input (unparseable start/end, `start > end`, leap-second
+ *   strings).
+ *
+ * @param start ISO UTC datetime string for the interval start
+ * @param end ISO UTC datetime string for the interval end
+ * @param points array of ISO UTC datetime strings to split at
+ * @returns array of `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalSplitAtUtc("2024-01-01T00:00:00Z", "2024-01-10T00:00:00Z", ["2024-01-05T00:00:00Z"]) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-05T00:00:00Z" }, { start: "2024-01-05T00:00:00Z", end: "2024-01-10T00:00:00Z" }]
+ * @example intervalSplitAtUtc("2024-01-01T00:00:00Z", "2024-01-10T00:00:00Z", []) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-10T00:00:00Z" }]
+ * @example intervalSplitAtUtc("invalid", "2024-01-10T00:00:00Z", ["2024-01-05T00:00:00Z"]) // []
+ */
+export function intervalSplitAtUtc(start, end, points) {
+    if (!Array.isArray(points)) {
+        return [];
+    }
+    if (isLeapSecond(start) || isLeapSecond(end)) {
+        return [];
+    }
+    if (!isValidUtcInterval(start, end)) {
+        return [];
+    }
+    if (!points.every((point) => typeof point === "string" &&
+        utcDateTime.test(point) &&
+        !isLeapSecond(point))) {
+        return [];
+    }
+    try {
+        const startVal = Temporal.Instant.from(start);
+        const endVal = Temporal.Instant.from(end);
+        const parsedPoints = points.map((point) => Temporal.Instant.from(point));
+        const inRangePoints = parsedPoints.filter((point) => Temporal.Instant.compare(point, startVal) > 0 &&
+            Temporal.Instant.compare(point, endVal) < 0);
+        inRangePoints.sort(Temporal.Instant.compare);
+        const uniquePoints = inRangePoints.filter((point, index) => index === 0 || !point.equals(inRangePoints[index - 1]));
+        const boundaries = [startVal, ...uniquePoints, endVal];
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({
+                start: boundaries[i].toString(),
+                end: boundaries[i + 1].toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Return the combined span of two UTC intervals, or null when they are disjoint.
+ *
+ * - Uses `Temporal.Instant.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).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
+ *
+ * @example intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // { start: "2024-01-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }
+ * @example intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-06-30T23:59:59Z", "2024-12-31T23:59:59Z") // { start: "2024-01-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }
+ * @example intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ * @example intervalUnionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ */
+export declare function intervalUnionUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    start: string;
+    end: string;
+} | null;

package/dist/utc/interval/intervalUnionUtc.js

@@ -0,0 +1,65 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return the combined span of two UTC intervals, or null when they are disjoint.
+ *
+ * - Uses `Temporal.Instant.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).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
+ *
+ * @example intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // { start: "2024-01-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }
+ * @example intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-06-30T23:59:59Z", "2024-12-31T23:59:59Z") // { start: "2024-01-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }
+ * @example intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ * @example intervalUnionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ */
+export function intervalUnionUtc(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return null;
+    }
+    if (!utcDateTime.test(aStart) ||
+        !utcDateTime.test(aEnd) ||
+        !utcDateTime.test(bStart) ||
+        !utcDateTime.test(bEnd)) {
+        return null;
+    }
+    if (isLeapSecond(aStart) ||
+        isLeapSecond(aEnd) ||
+        isLeapSecond(bStart) ||
+        isLeapSecond(bEnd)) {
+        return null;
+    }
+    try {
+        const aSI = Temporal.Instant.from(aStart);
+        const aEI = Temporal.Instant.from(aEnd);
+        const bSI = Temporal.Instant.from(bStart);
+        const bEI = Temporal.Instant.from(bEnd);
+        if (Temporal.Instant.compare(aSI, aEI) > 0) {
+            return null;
+        }
+        if (Temporal.Instant.compare(bSI, bEI) > 0) {
+            return null;
+        }
+        if (Temporal.Instant.compare(aEI, bSI) < 0 ||
+            Temporal.Instant.compare(bEI, aSI) < 0) {
+            return null;
+        }
+        const start = Temporal.Instant.compare(aSI, bSI) <= 0 ? aSI : bSI;
+        const end = Temporal.Instant.compare(aEI, bEI) >= 0 ? aEI : bEI;
+        return { start: start.toString(), end: end.toString() };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Return the symmetric difference across a list of UTC intervals — the set of instants covered
+ * by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorUtc`, which is pairwise only.
+ * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
+ *   one nanosecond after its end; the result is every maximal run where the running coverage
+ *   count is odd. For two intervals this reduces to exactly `intervalXorUtc`'s pairwise result.
+ * - Order of the input list does not matter; the result is sorted by start.
+ * - 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 UTC datetime strings, or when any element has
+ *   `start > end` or a leap-second string.
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllUtc([{ start: "2024-01-01T00:00:00Z", end: "2024-01-10T00:00:00Z" }, { start: "2024-01-05T00:00:00Z", end: "2024-01-15T00:00:00Z" }]) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-04T23:59:59.999999999Z" }, { start: "2024-01-10T00:00:00.000000001Z", end: "2024-01-15T00:00:00Z" }]
+ * @example intervalXorAllUtc([]) // []
+ */
+export declare function intervalXorAllUtc(intervals: Array<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/utc/interval/intervalXorAllUtc.js

@@ -0,0 +1,81 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { isValidUtcInterval } from "./validate/index.js";
+/**
+ * Return the symmetric difference across a list of UTC intervals — the set of instants covered
+ * by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorUtc`, which is pairwise only.
+ * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
+ *   one nanosecond after its end; the result is every maximal run where the running coverage
+ *   count is odd. For two intervals this reduces to exactly `intervalXorUtc`'s pairwise result.
+ * - Order of the input list does not matter; the result is sorted by start.
+ * - 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 UTC datetime strings, or when any element has
+ *   `start > end` or a leap-second string.
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllUtc([{ start: "2024-01-01T00:00:00Z", end: "2024-01-10T00:00:00Z" }, { start: "2024-01-05T00:00:00Z", end: "2024-01-15T00:00:00Z" }]) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-04T23:59:59.999999999Z" }, { start: "2024-01-10T00:00:00.000000001Z", end: "2024-01-15T00:00:00Z" }]
+ * @example intervalXorAllUtc([]) // []
+ */
+export function intervalXorAllUtc(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" &&
+        !isLeapSecond(interval.start) &&
+        !isLeapSecond(interval.end) &&
+        isValidUtcInterval(interval.start, interval.end))) {
+        return [];
+    }
+    try {
+        const events = [];
+        for (const interval of intervals) {
+            const start = Temporal.Instant.from(interval.start);
+            const closesAfter = Temporal.Instant.from(interval.end).add({
+                nanoseconds: 1,
+            });
+            events.push({ point: start, delta: 1 });
+            events.push({ point: closesAfter, delta: -1 });
+        }
+        events.sort((a, b) => Temporal.Instant.compare(a.point, b.point));
+        const grouped = [];
+        for (const event of events) {
+            const last = grouped[grouped.length - 1];
+            if (last && last.point.equals(event.point)) {
+                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.point;
+            }
+            else if (previousCoverage % 2 === 1 && coverage % 2 === 0 && runStart) {
+                result.push({
+                    start: runStart.toString(),
+                    end: group.point.subtract({ nanoseconds: 1 }).toString(),
+                });
+                runStart = null;
+            }
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Return the symmetric difference of two UTC intervals — time covered by exactly one interval.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison.
+ * - 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).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
+ *
+ * @example intervalXorUtc("2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z", "2024-04-01T11:00:00Z", "2024-12-31T17:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-03-31T17:00:00Z" }, { start: "2024-06-30T12:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalXorUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-04-01T11:00:00Z", "2024-06-30T12:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-03-31T17:00:00Z" }, { start: "2024-06-30T12:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalXorUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // []
+ * @example intervalXorUtc("invalid", "2024-06-30T12:00:00Z", "2024-07-01T13:00:00Z", "2024-12-31T17:00:00Z") // []
+ */
+export declare function intervalXorUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/utc/interval/intervalXorUtc.js

@@ -0,0 +1,97 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return the symmetric difference of two UTC intervals — time covered by exactly one interval.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison.
+ * - 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).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
+ *
+ * @example intervalXorUtc("2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z", "2024-04-01T11:00:00Z", "2024-12-31T17:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-03-31T17:00:00Z" }, { start: "2024-06-30T12:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalXorUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-04-01T11:00:00Z", "2024-06-30T12:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-03-31T17:00:00Z" }, { start: "2024-06-30T12:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalXorUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // []
+ * @example intervalXorUtc("invalid", "2024-06-30T12:00:00Z", "2024-07-01T13:00:00Z", "2024-12-31T17:00:00Z") // []
+ */
+export function intervalXorUtc(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return [];
+    }
+    if (!utcDateTime.test(aStart) ||
+        !utcDateTime.test(aEnd) ||
+        !utcDateTime.test(bStart) ||
+        !utcDateTime.test(bEnd)) {
+        return [];
+    }
+    if (isLeapSecond(aStart) ||
+        isLeapSecond(aEnd) ||
+        isLeapSecond(bStart) ||
+        isLeapSecond(bEnd)) {
+        return [];
+    }
+    try {
+        const aS = Temporal.Instant.from(aStart);
+        const aE = Temporal.Instant.from(aEnd);
+        const bS = Temporal.Instant.from(bStart);
+        const bE = Temporal.Instant.from(bEnd);
+        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: aS.toString(), end: aE.toString() },
+                { start: bS.toString(), end: bE.toString() },
+            ];
+        }
+        // Left piece: A before B starts
+        if (Temporal.Instant.compare(aS, bS) < 0) {
+            result.push({
+                start: aS.toString(),
+                end: bS.subtract({ nanoseconds: 1 }).toString(),
+            });
+        }
+        // Right piece: A after B ends
+        if (Temporal.Instant.compare(aE, bE) > 0) {
+            result.push({
+                start: bE.add({ nanoseconds: 1 }).toString(),
+                end: aE.toString(),
+            });
+        }
+        // Left piece: B before A starts
+        if (Temporal.Instant.compare(bS, aS) < 0) {
+            result.push({
+                start: bS.toString(),
+                end: aS.subtract({ nanoseconds: 1 }).toString(),
+            });
+        }
+        // Right piece: B after A ends
+        if (Temporal.Instant.compare(bE, aE) > 0) {
+            result.push({
+                start: aE.add({ nanoseconds: 1 }).toString(),
+                end: bE.toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns true if intervals overlap, or false on invalid input
+ *
+ * @example intervalsOverlapUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // true
+ * @example intervalsOverlapUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // false (adjacent)
+ * @example intervalsOverlapUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-02T00:00:00Z", "2024-12-31T23:59:59Z") // false (disjoint)
+ * @example intervalsOverlapUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // false
+ */
+export declare function intervalsOverlapUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;

package/dist/utc/interval/intervalsOverlapUtc.js

@@ -0,0 +1,59 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.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).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns true if intervals overlap, or false on invalid input
+ *
+ * @example intervalsOverlapUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // true
+ * @example intervalsOverlapUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // false (adjacent)
+ * @example intervalsOverlapUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-02T00:00:00Z", "2024-12-31T23:59:59Z") // false (disjoint)
+ * @example intervalsOverlapUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // false
+ */
+export function intervalsOverlapUtc(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return false;
+    }
+    if (!utcDateTime.test(aStart) ||
+        !utcDateTime.test(aEnd) ||
+        !utcDateTime.test(bStart) ||
+        !utcDateTime.test(bEnd)) {
+        return false;
+    }
+    if (isLeapSecond(aStart) ||
+        isLeapSecond(aEnd) ||
+        isLeapSecond(bStart) ||
+        isLeapSecond(bEnd)) {
+        return false;
+    }
+    try {
+        const aSI = Temporal.Instant.from(aStart);
+        const aEI = Temporal.Instant.from(aEnd);
+        const bSI = Temporal.Instant.from(bStart);
+        const bEI = Temporal.Instant.from(bEnd);
+        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/utc/interval/mergeIntervalsUtc.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Collapse a list of UTC intervals into the minimum set of non-overlapping intervals.
+ *
+ * - List-form generalization of `intervalUnionUtc`, which is pairwise only.
+ * - 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.
+ * - Returns `[]` for an empty list.
+ * - Returns `[]` when `intervals` is not an array, when any element is not a
+ *   `{ start, end }` record of valid ISO UTC datetime strings, or when any element has
+ *   `start > end` or a leap-second string.
+ *
+ * @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 mergeIntervalsUtc([{ start: "2024-01-01T00:00:00Z", end: "2024-01-10T00:00:00Z" }, { start: "2024-01-05T00:00:00Z", end: "2024-01-15T00:00:00Z" }]) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-15T00:00:00Z" }]
+ * @example mergeIntervalsUtc([]) // []
+ */
+export declare function mergeIntervalsUtc(intervals: Array<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}>;