@northguild/gmt 1.15.0 → 1.16.0

package/dist/plain/interval/intervalOverlappingDaysDateTime.js

@@ -1,20 +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 { plainDateTime } from "../../regex/index.js";
+import { halfOpenIntersection } from "../../internal/index.js";
+import { isValidDateTime } from "../validate/index.js";
 /**
  * Return how many distinct calendar dates two datetime intervals share.
  *
- * - Counts the number of local dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
- * - 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 moment 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 moment 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).
- * - 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
- *   `intervalIntersectionDateTime` with `intervalCountDateTime`:
- *   `const span = intervalIntersectionDateTime(aStart, aEnd, bStart, bEnd); span ? intervalCountDateTime(span.start, span.end, "day") : 0;`
  *
  * @param aStart ISO 8601 datetime string for the first interval start
  * @param aEnd ISO 8601 datetime string for the first interval end
@@ -23,8 +20,8 @@ import { plainDateTime } from "../../regex/index.js";
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
  * @example intervalOverlappingDaysDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "2024-01-01T23:59:00", "2024-01-02T00:01:00") // 2
- * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-02T00:00:00", "2024-01-02T00:00:00", "2024-01-03T00:00:00") // 1 (adjacent)
- * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-02T00:00:00", "2024-01-02T00:00:00.001", "2024-01-03T00:00:00") // 0 (disjoint)
+ * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-05T00:00:00", "2024-01-03T12:00:00", "2024-01-09T00:00:00") // 2 (01-03 and 01-04; 01-05T00:00 is excluded)
+ * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-02T00:00:00", "2024-01-02T00:00:00", "2024-01-03T00:00:00") // 0 (touching)
  * @example intervalOverlappingDaysDateTime("invalid", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // null
  */
 export function intervalOverlappingDaysDateTime(aStart, aEnd, bStart, bEnd) {
@@ -34,10 +31,10 @@ export function intervalOverlappingDaysDateTime(aStart, aEnd, bStart, bEnd) {
         typeof bEnd !== "string") {
         return null;
     }
-    if (!plainDateTime.test(aStart) ||
-        !plainDateTime.test(aEnd) ||
-        !plainDateTime.test(bStart) ||
-        !plainDateTime.test(bEnd)) {
+    if (!isValidDateTime(aStart) ||
+        !isValidDateTime(aEnd) ||
+        !isValidDateTime(bStart) ||
+        !isValidDateTime(bEnd)) {
         return null;
     }
     try {
@@ -51,15 +48,18 @@ export function intervalOverlappingDaysDateTime(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainDateTime.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.PlainDateTime.compare(aE, bS) < 0 ||
-            Temporal.PlainDateTime.compare(bE, aS) < 0) {
+        const shared = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.PlainDateTime.compare);
+        if (shared === null ||
+            Temporal.PlainDateTime.compare(shared.start, shared.end) === 0) {
             return 0;
         }
-        const start = Temporal.PlainDateTime.compare(aS, bS) >= 0 ? aS : bS;
-        const end = Temporal.PlainDateTime.compare(aE, bE) <= 0 ? aE : bE;
-        const startDate = start.toPlainDate();
-        const endDate = end.toPlainDate();
-        return startDate.until(endDate, { largestUnit: "day" }).days + 1;
+        const endsAtMidnight = shared.end
+            .toPlainTime()
+            .equals(new Temporal.PlainTime());
+        const days = shared.start
+            .toPlainDate()
+            .until(shared.end.toPlainDate(), { largestUnit: "day" }).days;
+        return endsAtMidnight ? days : days + 1;
     }
     catch {
         return null;

package/dist/plain/interval/intervalSplitAtDate.d.ts

@@ -2,16 +2,21 @@
  * Split a date 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, which `divideEqually`'s zero-length case is the
- *   deliberate way to express, not `splitAt`'s.
+ *   zero-length sub-interval at the edge; `intervalDivideEquallyDate`'s zero-length case is the
+ *   deliberate way to express one, not `intervalSplitAtDate`.
  * - 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 PlainDate
  *   string, or on invalid input (unparseable start/end, `start > end`).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). `start`, `end`, and
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). `start`, `end`, and
  *   every element of `points` must carry the *same* calendar tag (or all be bare ISO); any
  *   mismatch returns `[]` (E5 decision of record D4) — this also makes `.equals()`'s dedup of
  *   duplicate points safe, since same-calendar `PlainDate`s compare equal correctly.

package/dist/plain/interval/intervalSplitAtDate.js

@@ -6,16 +6,21 @@ import { isValidDateInterval } from "./validate/index.js";
  * Split a date 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, which `divideEqually`'s zero-length case is the
- *   deliberate way to express, not `splitAt`'s.
+ *   zero-length sub-interval at the edge; `intervalDivideEquallyDate`'s zero-length case is the
+ *   deliberate way to express one, not `intervalSplitAtDate`.
  * - 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 PlainDate
  *   string, or on invalid input (unparseable start/end, `start > end`).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). `start`, `end`, and
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). `start`, `end`, and
  *   every element of `points` must carry the *same* calendar tag (or all be bare ISO); any
  *   mismatch returns `[]` (E5 decision of record D4) — this also makes `.equals()`'s dedup of
  *   duplicate points safe, since same-calendar `PlainDate`s compare equal correctly.
@@ -33,41 +38,48 @@ import { isValidDateInterval } from "./validate/index.js";
  * @example intervalSplitAtDate("2024-01-01", "2024-01-10", ["not-a-date"]) // []
  */
 export function intervalSplitAtDate(start, end, points) {
-    if (!Array.isArray(points)) {
-        return [];
-    }
-    if (!isValidDateInterval(start, end)) {
-        return [];
-    }
-    if (!points.every((point) => typeof point === "string")) {
-        return [];
-    }
-    if (!points.every((point) => isValidCalendarDate(point))) {
-        return [];
-    }
-    const calendar = calendarOfAllDateValues([start, end, ...points]);
-    if (!calendar) {
-        return [];
-    }
     try {
-        const startVal = parseCalendarDateValue(start);
-        const endVal = parseCalendarDateValue(end);
-        const parsedPoints = points.map((point) => parseCalendarDateValue(point));
-        const inRangePoints = parsedPoints.filter((point) => Temporal.PlainDate.compare(point, startVal) > 0 &&
-            Temporal.PlainDate.compare(point, endVal) < 0);
-        inRangePoints.sort(Temporal.PlainDate.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: formatDateInCalendar(boundaries[i], calendar),
-                end: formatDateInCalendar(boundaries[i + 1], calendar),
-            });
+        if (!Array.isArray(points)) {
+            return [];
+        }
+        if (!isValidDateInterval(start, end)) {
+            return [];
+        }
+        if (!points.every((point) => typeof point === "string")) {
+            return [];
+        }
+        if (!points.every((point) => isValidCalendarDate(point))) {
+            return [];
+        }
+        const calendar = calendarOfAllDateValues([start, end, ...points]);
+        if (!calendar) {
+            return [];
+        }
+        try {
+            const startVal = parseCalendarDateValue(start);
+            const endVal = parseCalendarDateValue(end);
+            const parsedPoints = points.map((point) => parseCalendarDateValue(point));
+            const inRangePoints = parsedPoints.filter((point) => Temporal.PlainDate.compare(point, startVal) > 0 &&
+                Temporal.PlainDate.compare(point, endVal) < 0);
+            inRangePoints.sort(Temporal.PlainDate.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: formatDateInCalendar(boundaries[i], calendar),
+                    end: formatDateInCalendar(boundaries[i + 1], calendar),
+                });
+            }
+            return result;
+        }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/plain/interval/intervalSplitAtDateTime.d.ts

@@ -2,12 +2,17 @@
  * Split a datetime 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, which `divideEqually`'s zero-length case is the
- *   deliberate way to express, not `splitAt`'s.
+ *   zero-length sub-interval at the edge; `intervalDivideEquallyDateTime`'s zero-length case is the
+ *   deliberate way to express one, not `intervalSplitAtDateTime`.
  * - 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
  *   PlainDateTime string, or on invalid input (unparseable start/end, `start > end`).

package/dist/plain/interval/intervalSplitAtDateTime.js

@@ -1,16 +1,21 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { plainDateTime } from "../../regex/index.js";
 import { isValidDateTimeInterval } from "./validate/index.js";
+import { isValidDateTime } from "../validate/index.js";
 /**
  * Split a datetime 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, which `divideEqually`'s zero-length case is the
- *   deliberate way to express, not `splitAt`'s.
+ *   zero-length sub-interval at the edge; `intervalDivideEquallyDateTime`'s zero-length case is the
+ *   deliberate way to express one, not `intervalSplitAtDateTime`.
  * - 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
  *   PlainDateTime string, or on invalid input (unparseable start/end, `start > end`).
@@ -26,37 +31,44 @@ import { isValidDateTimeInterval } from "./validate/index.js";
  * @example intervalSplitAtDateTime("2024-01-01T00:00:00", "2024-01-10T00:00:00", ["not-a-datetime"]) // []
  */
 export function intervalSplitAtDateTime(start, end, points) {
-    if (!Array.isArray(points)) {
-        return [];
-    }
-    if (!isValidDateTimeInterval(start, end)) {
-        return [];
-    }
-    if (!points.every((point) => typeof point === "string")) {
-        return [];
-    }
-    if (!points.every((point) => plainDateTime.test(point))) {
-        return [];
-    }
     try {
-        const startVal = Temporal.PlainDateTime.from(start);
-        const endVal = Temporal.PlainDateTime.from(end);
-        const parsedPoints = points.map((point) => Temporal.PlainDateTime.from(point));
-        const inRangePoints = parsedPoints.filter((point) => Temporal.PlainDateTime.compare(point, startVal) > 0 &&
-            Temporal.PlainDateTime.compare(point, endVal) < 0);
-        inRangePoints.sort(Temporal.PlainDateTime.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 (!isValidDateTimeInterval(start, end)) {
+            return [];
+        }
+        if (!points.every((point) => typeof point === "string")) {
+            return [];
+        }
+        if (!points.every((point) => isValidDateTime(point))) {
+            return [];
+        }
+        try {
+            const startVal = Temporal.PlainDateTime.from(start);
+            const endVal = Temporal.PlainDateTime.from(end);
+            const parsedPoints = points.map((point) => Temporal.PlainDateTime.from(point));
+            const inRangePoints = parsedPoints.filter((point) => Temporal.PlainDateTime.compare(point, startVal) > 0 &&
+                Temporal.PlainDateTime.compare(point, endVal) < 0);
+            inRangePoints.sort(Temporal.PlainDateTime.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/plain/interval/intervalSplitAtTime.d.ts

@@ -2,12 +2,17 @@
  * Split a time 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, which `divideEqually`'s zero-length case is the
- *   deliberate way to express, not `splitAt`'s.
+ *   zero-length sub-interval at the edge; `intervalDivideEquallyTime`'s zero-length case is the
+ *   deliberate way to express one, not `intervalSplitAtTime`.
  * - 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 PlainTime
  *   string, or on invalid input (unparseable start/end, `start > end`).

package/dist/plain/interval/intervalSplitAtTime.js

@@ -1,16 +1,21 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { plainTime } from "../../regex/index.js";
 import { isValidTimeInterval } from "./validate/index.js";
+import { isValidTime } from "../validate/index.js";
 /**
  * Split a time 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, which `divideEqually`'s zero-length case is the
- *   deliberate way to express, not `splitAt`'s.
+ *   zero-length sub-interval at the edge; `intervalDivideEquallyTime`'s zero-length case is the
+ *   deliberate way to express one, not `intervalSplitAtTime`.
  * - 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 PlainTime
  *   string, or on invalid input (unparseable start/end, `start > end`).
@@ -28,37 +33,44 @@ import { isValidTimeInterval } from "./validate/index.js";
  * @example intervalSplitAtTime("09:00:00", "17:00:00", ["not-a-time"]) // []
  */
 export function intervalSplitAtTime(start, end, points) {
-    if (!Array.isArray(points)) {
-        return [];
-    }
-    if (!isValidTimeInterval(start, end)) {
-        return [];
-    }
-    if (!points.every((point) => typeof point === "string")) {
-        return [];
-    }
-    if (!points.every((point) => plainTime.test(point))) {
-        return [];
-    }
     try {
-        const startVal = Temporal.PlainTime.from(start);
-        const endVal = Temporal.PlainTime.from(end);
-        const parsedPoints = points.map((point) => Temporal.PlainTime.from(point));
-        const inRangePoints = parsedPoints.filter((point) => Temporal.PlainTime.compare(point, startVal) > 0 &&
-            Temporal.PlainTime.compare(point, endVal) < 0);
-        inRangePoints.sort(Temporal.PlainTime.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 (!isValidTimeInterval(start, end)) {
+            return [];
+        }
+        if (!points.every((point) => typeof point === "string")) {
+            return [];
+        }
+        if (!points.every((point) => isValidTime(point))) {
+            return [];
+        }
+        try {
+            const startVal = Temporal.PlainTime.from(start);
+            const endVal = Temporal.PlainTime.from(end);
+            const parsedPoints = points.map((point) => Temporal.PlainTime.from(point));
+            const inRangePoints = parsedPoints.filter((point) => Temporal.PlainTime.compare(point, startVal) > 0 &&
+                Temporal.PlainTime.compare(point, endVal) < 0);
+            inRangePoints.sort(Temporal.PlainTime.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/plain/interval/intervalUnionDate.d.ts

@@ -2,11 +2,18 @@
  * Return the combined span of two date intervals, or null when they are disjoint.
  *
  * - Uses `Temporal.PlainDate.compare` for comparison.
- * - 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`.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
  *   date *value*, all four arguments must carry the *same* calendar tag (or all be bare ISO);
  *   a mismatch returns `null` rather than guessing an output calendar (E5 decision of record
  *   D4). The output's tag is re-derived from the merged span, never copied from an input.
@@ -18,10 +25,11 @@
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals / mismatched calendars
  *
  * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" }
- * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" }
- * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null
+ * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" } (touching)
+ * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null (06-30 is in neither)
+ * @example intervalUnionDate("2024-01-05", "2024-01-05", "2024-06-15", "2024-06-30") // { start: "2024-06-15", end: "2024-06-30" } (empty interval adds nothing)
  * @example intervalUnionDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
- * @example intervalUnionDate("5785-01-01[u-ca=hebrew]", "2024-06-30", "2024-04-01", "2024-12-31") // null (mismatched calendars)
+ * @example intervalUnionDate("2024-01-01[u-ca=hebrew]", "2024-06-30", "2024-04-01", "2024-12-31") // null (mismatched calendars)
  */
 export declare function intervalUnionDate(aStart: string, aEnd: string, bStart: string, bEnd: string): {
     start: string;

package/dist/plain/interval/intervalUnionDate.js

@@ -1,15 +1,23 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarOfAllDateValues, formatDateInCalendar, parseCalendarDateValue, } from "../../internal/index.js";
+import { calendarOfAllDateValues, formatDateInCalendar, halfOpenUnion, parseCalendarDateValue, } from "../../internal/index.js";
 import { isValidCalendarDate } from "../validate/index.js";
 /**
  * Return the combined span of two date intervals, or null when they are disjoint.
  *
  * - Uses `Temporal.PlainDate.compare` for comparison.
- * - 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`.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
  *   date *value*, all four arguments must carry the *same* calendar tag (or all be bare ISO);
  *   a mismatch returns `null` rather than guessing an output calendar (E5 decision of record
  *   D4). The output's tag is re-derived from the merged span, never copied from an input.
@@ -21,10 +29,11 @@ import { isValidCalendarDate } from "../validate/index.js";
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals / mismatched calendars
  *
  * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" }
- * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" }
- * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null
+ * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" } (touching)
+ * @example intervalUnionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null (06-30 is in neither)
+ * @example intervalUnionDate("2024-01-05", "2024-01-05", "2024-06-15", "2024-06-30") // { start: "2024-06-15", end: "2024-06-30" } (empty interval adds nothing)
  * @example intervalUnionDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
- * @example intervalUnionDate("5785-01-01[u-ca=hebrew]", "2024-06-30", "2024-04-01", "2024-12-31") // null (mismatched calendars)
+ * @example intervalUnionDate("2024-01-01[u-ca=hebrew]", "2024-06-30", "2024-04-01", "2024-12-31") // null (mismatched calendars)
  */
 export function intervalUnionDate(aStart, aEnd, bStart, bEnd) {
     if (typeof aStart !== "string" ||
@@ -54,12 +63,11 @@ export function intervalUnionDate(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainDate.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.PlainDate.compare(aE, bS) < 0 ||
-            Temporal.PlainDate.compare(bE, aS) < 0) {
+        const union = halfOpenUnion({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.PlainDate.compare);
+        if (union === null) {
             return null;
         }
-        const start = Temporal.PlainDate.compare(aS, bS) <= 0 ? aS : bS;
-        const end = Temporal.PlainDate.compare(aE, bE) >= 0 ? aE : bE;
+        const { start, end } = union;
         return {
             start: formatDateInCalendar(start, calendar),
             end: formatDateInCalendar(end, calendar),

package/dist/plain/interval/intervalUnionDateTime.d.ts

@@ -2,8 +2,15 @@
  * Return the combined span of two datetime intervals, or null when they are disjoint.
  *
  * - Uses `Temporal.PlainDateTime.compare` for comparison.
- * - 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`.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
  *
@@ -13,9 +20,9 @@
  * @param bEnd ISO 8601 datetime string for the second interval end
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
  *
- * @example intervalUnionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // { start: "2024-01-01T10:00:00", end: "2024-12-31T23:59:59" }
- * @example intervalUnionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-06-30T23:59:59", "2024-12-31T23:59:59") // { start: "2024-01-01T10:00:00", end: "2024-12-31T23:59:59" }
- * @example intervalUnionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-07-01T00:00:00", "2024-12-31T23:59:59") // null
+ * @example intervalUnionDateTime("2024-01-01T09:00:00", "2024-01-01T13:00:00", "2024-01-01T12:00:00", "2024-01-01T17:00:00") // { start: "2024-01-01T09:00:00", end: "2024-01-01T17:00:00" }
+ * @example intervalUnionDateTime("2024-01-01T09:00:00", "2024-01-01T12:00:00", "2024-01-01T12:00:00", "2024-01-01T17:00:00") // { start: "2024-01-01T09:00:00", end: "2024-01-01T17:00:00" } (touching)
+ * @example intervalUnionDateTime("2024-01-01T09:00:00", "2024-01-01T12:00:00", "2024-01-01T12:00:00.000000001", "2024-01-01T17:00:00") // null (1 ns gap)
  * @example intervalUnionDateTime("invalid", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // null
  */
 export declare function intervalUnionDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): {