@northguild/gmt 1.15.0 → 1.17.0

package/dist/utc/interval/intervalIntersectionUtc.js

@@ -1,13 +1,20 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { canonicalInstantIntervals } from "../../internal/index.js";
+import { intersectIntervals } from "../../interval/calculate/index.js";
+import { isValidUtc } from "../validate/index.js";
 /**
  * Return the overlapping span of two UTC intervals, or null when they do not overlap.
  *
- * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no instant and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
+ * - Delegates to CORE-6's `intersectIntervals` once the arguments pass the UTC-string gate, and
+ *   re-serialises the result, so it always equals that function's answer in canonical `Z` form.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `null` on invalid input (wrong type, non-`Z` strings, 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
@@ -15,9 +22,9 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @param bEnd ISO 8601 UTC datetime string for the second interval end
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
  *
- * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // { start: "2024-04-01T00:00:00Z", end: "2024-06-30T23:59:59Z" }
- * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
- * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-02T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ * @example intervalIntersectionUtc("2024-01-01T09:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" }
+ * @example intervalIntersectionUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // null (touching)
+ * @example intervalIntersectionUtc("2024-01-01T09:00:00.000Z", "2024-01-01T13:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T13:00:00Z" } (re-serialised)
  * @example intervalIntersectionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
  */
 export function intervalIntersectionUtc(aStart, aEnd, bStart, bEnd) {
@@ -27,38 +34,14 @@ export function intervalIntersectionUtc(aStart, aEnd, bStart, bEnd) {
         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 {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return null;
     }
+    const shared = intersectIntervals({ start: aStart, end: aEnd }, { start: bStart, end: bEnd });
+    return shared === null
+        ? null
+        : (canonicalInstantIntervals([shared])?.[0] ?? null);
 }

package/dist/utc/interval/intervalLengthUtc.js

@@ -1,7 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveDateTimeUnit } from "../../internal/index.js";
+import { durationTotal, resolveDateTimeUnit, zonedUntil } from "../../internal/index.js";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
 import { isValidUtcInterval } from "./validate/index.js";
 /**
  * Return the exact length of a UTC interval in `unit`, as a real (possibly fractional) number.
@@ -32,19 +31,18 @@ export function intervalLengthUtc(start, end, unit) {
     if (!isValidDateTimeUnit(resolvedUnit)) {
         return null;
     }
-    if (isLeapSecond(start) || isLeapSecond(end)) {
-        return null;
-    }
     if (!isValidUtcInterval(start, end)) {
         return null;
     }
     try {
         const startVal = Temporal.Instant.from(start).toZonedDateTimeISO("UTC");
         const endVal = Temporal.Instant.from(end).toZonedDateTimeISO("UTC");
-        const duration = startVal.until(endVal, { largestUnit: resolvedUnit });
+        const duration = zonedUntil(startVal, endVal, {
+            largestUnit: resolvedUnit,
+        });
         // total() gives the exact elapsed length, unlike intervalCountUtc's boundary-crossing
         // count — 23:59 -> 00:01 is 2 day boundaries via intervalCountUtc but ~0.0014 days here.
-        return duration.total({ unit: resolvedUnit, relativeTo: startVal });
+        return durationTotal(duration, resolvedUnit, startVal);
     }
     catch {
         return null;

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

@@ -1,19 +1,13 @@
 /**
  * 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).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The count is the number of
+ *   calendar days holding at least one instant of the intersection `[max(aStart, bStart),
+ *   min(aEnd, bEnd))`. An intersection ending exactly at midnight does not reach that day.
+ * - Touching intervals (`aEnd === bStart`) share no instant and count `0`; so does an empty interval.
+ * - Returns `0` when the intervals share nothing (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
@@ -22,8 +16,8 @@
  * @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("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z") // 1
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z") // 0 (touching)
  * @example intervalOverlappingDaysUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
  */
 export declare function intervalOverlappingDaysUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): number | null;

package/dist/utc/interval/intervalOverlappingDaysUtc.js

@@ -1,22 +1,17 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+import { halfOpenIntersection } from "../../internal/index.js";
+import { isValidUtc } from "../validate/index.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).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The count is the number of
+ *   calendar days holding at least one instant of the intersection `[max(aStart, bStart),
+ *   min(aEnd, bEnd))`. An intersection ending exactly at midnight does not reach that day.
+ * - Touching intervals (`aEnd === bStart`) share no instant and count `0`; so does an empty interval.
+ * - Returns `0` when the intervals share nothing (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
@@ -25,8 +20,8 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @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("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z") // 1
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z") // 0 (touching)
  * @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) {
@@ -36,16 +31,10 @@ export function intervalOverlappingDaysUtc(aStart, aEnd, bStart, bEnd) {
         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)) {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return null;
     }
     try {
@@ -53,21 +42,21 @@ export function intervalOverlappingDaysUtc(aStart, aEnd, bStart, bEnd) {
         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) {
+        if (Temporal.Instant.compare(aS, aE) > 0 ||
+            Temporal.Instant.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.Instant.compare(aE, bS) < 0 ||
-            Temporal.Instant.compare(bE, aS) < 0) {
+        const shared = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.Instant.compare);
+        if (shared === null || shared.start.equals(shared.end)) {
             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;
+        const start = shared.start.toZonedDateTimeISO("UTC");
+        const end = shared.end.toZonedDateTimeISO("UTC");
+        const endsAtMidnight = end.toPlainTime().equals(new Temporal.PlainTime());
+        const days = start
+            .toPlainDate()
+            .until(end.toPlainDate(), { largestUnit: "day" }).days;
+        return endsAtMidnight ? days : days + 1;
     }
     catch {
         return null;

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

@@ -2,11 +2,16 @@
  * 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 before `start` or after `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 consecutive `{ start, end }` records, each record's `end` equal to the next
+ *   record's `start`.
+ * - Every piece is half-open `[start, end)`: a boundary belongs only to the piece that starts
+ *   there, so the pieces share no value and together cover the interval exactly once (the rule
+ *   CORE-6's `splitIntervalAt` uses).
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
  * - 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

package/dist/utc/interval/intervalSplitAtUtc.js

@@ -1,16 +1,20 @@
 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";
+import { isValidUtc } 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 before `start` or after `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 consecutive `{ start, end }` records, each record's `end` equal to the next
+ *   record's `start`.
+ * - Every piece is half-open `[start, end)`: a boundary belongs only to the piece that starts
+ *   there, so the pieces share no value and together cover the interval exactly once (the rule
+ *   CORE-6's `splitIntervalAt` uses).
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
  * - 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
@@ -26,39 +30,41 @@ import { isValidUtcInterval } from "./validate/index.js";
  * @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(),
-            });
+        if (!Array.isArray(points)) {
+            return [];
+        }
+        if (!isValidUtcInterval(start, end)) {
+            return [];
+        }
+        if (!points.every((point) => typeof point === "string" && isValidUtc(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 [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

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

@@ -1,11 +1,19 @@
 /**
  * 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.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The union is returned only
+ *   when it is one non-empty interval — the single run CORE-6's `mergeIntervals` would give.
+ * - Overlapping intervals, and touching intervals (`aEnd === bStart`), return their combined span.
+ * - Two **non-empty** intervals with any gap between them return `null`, even a one-unit gap.
+ *   The caveat matters: an empty interval is the empty set, so it is never “separated” from
+ *   anything. A non-empty interval unioned with an empty one far away is still that non-empty
+ *   interval — see the next bullet — not `null`.
+ * - An empty interval (`start === end`) is the empty set: it adds nothing, so the union is the
+ *   other interval. Two empty intervals have no non-empty union and return `null`.
+ * - Delegates to CORE-6's `mergeIntervals` once the arguments pass the UTC-string gate, and
+ *   re-serialises the run to canonical `Z` strings.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `null` on invalid input (wrong type, non-`Z` strings, 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
@@ -13,9 +21,9 @@
  * @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("2024-01-01T09:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }
+ * @example intervalUnionUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" } (touching)
+ * @example intervalUnionUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00.000000001Z", "2024-01-01T17:00:00Z") // null (1 ns gap)
  * @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): {

package/dist/utc/interval/intervalUnionUtc.js

@@ -1,14 +1,23 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { canonicalInstantIntervals } from "../../internal/index.js";
+import { mergeIntervals } from "../../interval/calculate/index.js";
+import { isValidUtc } from "../validate/index.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.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The union is returned only
+ *   when it is one non-empty interval — the single run CORE-6's `mergeIntervals` would give.
+ * - Overlapping intervals, and touching intervals (`aEnd === bStart`), return their combined span.
+ * - Two **non-empty** intervals with any gap between them return `null`, even a one-unit gap.
+ *   The caveat matters: an empty interval is the empty set, so it is never “separated” from
+ *   anything. A non-empty interval unioned with an empty one far away is still that non-empty
+ *   interval — see the next bullet — not `null`.
+ * - An empty interval (`start === end`) is the empty set: it adds nothing, so the union is the
+ *   other interval. Two empty intervals have no non-empty union and return `null`.
+ * - Delegates to CORE-6's `mergeIntervals` once the arguments pass the UTC-string gate, and
+ *   re-serialises the run to canonical `Z` strings.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `null` on invalid input (wrong type, non-`Z` strings, 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
@@ -16,9 +25,9 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @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("2024-01-01T09:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }
+ * @example intervalUnionUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" } (touching)
+ * @example intervalUnionUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00.000000001Z", "2024-01-01T17:00:00Z") // null (1 ns gap)
  * @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) {
@@ -28,38 +37,18 @@ export function intervalUnionUtc(aStart, aEnd, bStart, bEnd) {
         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 {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return null;
     }
+    const runs = mergeIntervals([
+        { start: aStart, end: aEnd },
+        { start: bStart, end: bEnd },
+    ]);
+    // mergeIntervals returns [] for an invalid (reversed) interval, so that also gives null.
+    return runs.length === 1
+        ? (canonicalInstantIntervals(runs)?.[0] ?? null)
+        : null;
 }

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

@@ -3,9 +3,12 @@
  * 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.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The result is every maximal
+ *   run covered an odd number of times, computed as a coverage-parity sweep over the start and
+ *   end boundaries. Runs end exactly at a boundary; no boundary is ever stepped by one unit, so
+ *   an interval may end on the type's last value without overflow or midnight wrap.
+ * - Touching odd runs join into one run; an empty interval (`start === end`) contributes nothing.
+ *   For two intervals this is 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).
@@ -16,7 +19,7 @@
  * @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([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T13:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
  * @example intervalXorAllUtc([]) // []
  */
 export declare function intervalXorAllUtc(intervals: Array<{