@northguild/gmt 1.15.0 → 1.16.0

package/dist/unix/interval/intervalSplitAtUnix.d.ts

@@ -2,23 +2,28 @@
  * Split a Unix epoch 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 half-open `[start, end)` records, the same tiling as `splitIntervalAt`:
+ *   each record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no value and together cover `[start, end)` exactly once.
  * - 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 finite number (or
- *   numeric string), or on invalid input (non-finite/non-integer start/end, `start > end`).
+ * - Returns `[]` when `points` is not an array, or when `start`, `end` or any point is not a safe
+ *   integer (or numeric string of one) — fractions, empty strings and values beyond ±(2^53 − 1)
+ *   are invalid even when they would fall outside the interval — or when `start > end`.
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
+ * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
  * @param points array of Unix epoch values to split at
  * @returns array of `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalSplitAtUnix(0, 100000, [50000]) // [{ start: 0, end: 50000 }, { start: 50000, end: 100000 }]
  * @example intervalSplitAtUnix(0, 100000, []) // [{ start: 0, end: 100000 }]
  * @example intervalSplitAtUnix(NaN, 100000, [50000]) // []
+ * @example intervalSplitAtUnix(0, 100000, [50000.5]) // [] (fractional point)
  */
 export declare function intervalSplitAtUnix(start: number | string, end: number | string, points: Array<number | string>): Array<{
     start: number;

package/dist/unix/interval/intervalSplitAtUnix.js

@@ -1,55 +1,62 @@
-import { isValidUnixEpochPair } from "../../internal/resolveUnixTimeZone.js";
+import { parseUnixEpochInterval, parseUnixEpochValue } from "../../internal/index.js";
 /**
  * Split a Unix epoch 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 half-open `[start, end)` records, the same tiling as `splitIntervalAt`:
+ *   each record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no value and together cover `[start, end)` exactly once.
  * - 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 finite number (or
- *   numeric string), or on invalid input (non-finite/non-integer start/end, `start > end`).
+ * - Returns `[]` when `points` is not an array, or when `start`, `end` or any point is not a safe
+ *   integer (or numeric string of one) — fractions, empty strings and values beyond ±(2^53 − 1)
+ *   are invalid even when they would fall outside the interval — or when `start > end`.
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
+ * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
  * @param points array of Unix epoch values to split at
  * @returns array of `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalSplitAtUnix(0, 100000, [50000]) // [{ start: 0, end: 50000 }, { start: 50000, end: 100000 }]
  * @example intervalSplitAtUnix(0, 100000, []) // [{ start: 0, end: 100000 }]
  * @example intervalSplitAtUnix(NaN, 100000, [50000]) // []
+ * @example intervalSplitAtUnix(0, 100000, [50000.5]) // [] (fractional point)
  */
 export function intervalSplitAtUnix(start, end, points) {
-    if (!Array.isArray(points)) {
-        return [];
-    }
-    if (typeof start !== "number" && typeof start !== "string") {
-        return [];
-    }
-    if (typeof end !== "number" && typeof end !== "string") {
-        return [];
+    try {
+        if (!Array.isArray(points)) {
+            return [];
+        }
+        const interval = parseUnixEpochInterval(start, end);
+        if (interval === null) {
+            return [];
+        }
+        const { start: startMs, end: endMs } = interval;
+        const parsedPoints = [];
+        for (const point of points) {
+            const parsed = parseUnixEpochValue(point);
+            if (parsed === null) {
+                return [];
+            }
+            parsedPoints.push(parsed);
+        }
+        const inRangePoints = parsedPoints.filter((point) => point > startMs && point < endMs);
+        inRangePoints.sort((a, b) => a - b);
+        const uniquePoints = inRangePoints.filter((point, index) => index === 0 || point !== inRangePoints[index - 1]);
+        const boundaries = [startMs, ...uniquePoints, endMs];
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({ start: boundaries[i], end: boundaries[i + 1] });
+        }
+        return result;
     }
-    const startMs = typeof start === "number" ? start : Number(start);
-    const endMs = typeof end === "number" ? end : Number(end);
-    if (!isValidUnixEpochPair(startMs, endMs) || startMs > endMs) {
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
-    if (!points.every((point) => typeof point === "number" || typeof point === "string")) {
-        return [];
-    }
-    const parsedPoints = points.map((point) => typeof point === "number" ? point : Number(point));
-    if (!parsedPoints.every((point) => Number.isFinite(point))) {
-        return [];
-    }
-    const inRangePoints = parsedPoints.filter((point) => point > startMs && point < endMs);
-    inRangePoints.sort((a, b) => a - b);
-    const uniquePoints = inRangePoints.filter((point, index) => index === 0 || point !== inRangePoints[index - 1]);
-    const boundaries = [startMs, ...uniquePoints, endMs];
-    const result = [];
-    for (let i = 0; i < boundaries.length - 1; i++) {
-        result.push({ start: boundaries[i], end: boundaries[i + 1] });
-    }
-    return result;
 }

package/dist/unix/interval/intervalUnionUnix.d.ts

@@ -1,20 +1,26 @@
 /**
- * Return the combined span of two Unix epoch intervals, or null when they are disjoint.
+ * Return the combined span of two half-open Unix epoch intervals `[start, end)`, or null when
+ * their union is not one non-empty span.
  *
  * - Compares numeric Unix epoch values directly.
- * - Overlapping intervals return their merged span.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - The result is the single run `mergeIntervalsUnix([a, b])` produces, the same rule as
+ *   `mergeIntervals`. Overlapping intervals return their merged span.
+ * - Touching intervals (e.g. `aEnd === bStart`) leave no gap between them and ARE merged.
+ * - An empty interval (`start === end`) holds no instant, so it never changes the result: with a
+ *   non-empty interval the answer is that interval, and two empty intervals give `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (non-numeric types, non-finite values).
+ * - Returns `null` on invalid input: non-numeric types, empty strings, and values that are not
+ *   safe integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
  *
  * @example intervalUnionUnix(0, 1700000000, 1000000, 2000000) // { start: 0, end: 1700000000 }
- * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 }
+ * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 } (touching)
+ * @example intervalUnionUnix(0, 1000000, 3000000, 3000000) // { start: 0, end: 1000000 } (an empty interval adds nothing)
  * @example intervalUnionUnix(0, 1000000, 1000001, 2000000) // null
  * @example intervalUnionUnix(NaN, 1700000000, 1000000, 2000000) // null
  * @example intervalUnionUnix("0", "1700000000", "1000000", "2000000") // { start: 0, end: 1700000000 }

package/dist/unix/interval/intervalUnionUnix.js

@@ -1,58 +1,36 @@
+import { halfOpenUnion, parseUnixEpochIntervalPair } from "../../internal/index.js";
 /**
- * Return the combined span of two Unix epoch intervals, or null when they are disjoint.
+ * Return the combined span of two half-open Unix epoch intervals `[start, end)`, or null when
+ * their union is not one non-empty span.
  *
  * - Compares numeric Unix epoch values directly.
- * - Overlapping intervals return their merged span.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - The result is the single run `mergeIntervalsUnix([a, b])` produces, the same rule as
+ *   `mergeIntervals`. Overlapping intervals return their merged span.
+ * - Touching intervals (e.g. `aEnd === bStart`) leave no gap between them and ARE merged.
+ * - An empty interval (`start === end`) holds no instant, so it never changes the result: with a
+ *   non-empty interval the answer is that interval, and two empty intervals give `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (non-numeric types, non-finite values).
+ * - Returns `null` on invalid input: non-numeric types, empty strings, and values that are not
+ *   safe integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
  *
  * @example intervalUnionUnix(0, 1700000000, 1000000, 2000000) // { start: 0, end: 1700000000 }
- * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 }
+ * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 } (touching)
+ * @example intervalUnionUnix(0, 1000000, 3000000, 3000000) // { start: 0, end: 1000000 } (an empty interval adds nothing)
  * @example intervalUnionUnix(0, 1000000, 1000001, 2000000) // null
  * @example intervalUnionUnix(NaN, 1700000000, 1000000, 2000000) // null
  * @example intervalUnionUnix("0", "1700000000", "1000000", "2000000") // { start: 0, end: 1700000000 }
  */
 export function intervalUnionUnix(aStart, aEnd, bStart, bEnd) {
-    if (typeof aStart !== "number" && typeof aStart !== "string") {
+    const pair = parseUnixEpochIntervalPair(aStart, aEnd, bStart, bEnd);
+    if (pair === null) {
         return null;
     }
-    if (typeof aEnd !== "number" && typeof aEnd !== "string") {
-        return null;
-    }
-    if (typeof bStart !== "number" && typeof bStart !== "string") {
-        return null;
-    }
-    if (typeof bEnd !== "number" && typeof bEnd !== "string") {
-        return null;
-    }
-    const a1 = typeof aStart === "number" ? aStart : Number(aStart);
-    const a2 = typeof aEnd === "number" ? aEnd : Number(aEnd);
-    const b1 = typeof bStart === "number" ? bStart : Number(bStart);
-    const b2 = typeof bEnd === "number" ? bEnd : Number(bEnd);
-    if (!Number.isFinite(a1) ||
-        !Number.isFinite(a2) ||
-        !Number.isFinite(b1) ||
-        !Number.isFinite(b2)) {
-        return null;
-    }
-    if (a1 > a2) {
-        return null;
-    }
-    if (b1 > b2) {
-        return null;
-    }
-    if (a2 < b1 || b2 < a1) {
-        return null;
-    }
-    return {
-        start: Math.min(a1, b1),
-        end: Math.max(a2, b2),
-    };
+    // One merged run, or null when a gap (or no instant at all) leaves no single span.
+    return halfOpenUnion(pair[0], pair[1], (left, right) => left - right);
 }

package/dist/unix/interval/intervalXorAllUnix.d.ts

@@ -3,20 +3,22 @@
  * values covered by an odd number of the input intervals.
  *
  * - List-form generalization of `intervalXorUnix`, which is pairwise only.
- * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
- *   one epoch unit after its end; the result is every maximal run where the running coverage
- *   count is odd. For two intervals this reduces to exactly `intervalXorUnix`'s pairwise result.
+ * - Intervals are half-open `[start, end)`. The result is every maximal run where the coverage
+ *   count is odd, so touching runs join and an empty interval (`start === end`) changes nothing.
+ *   Every boundary is an input's own `start` or `end`; none is stepped by an epoch unit. For two
+ *   intervals this is exactly `intervalXorUnix`'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 value 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 finite numeric (or numeric-string) values, or when any element
- *   has `start > end`.
+ *   `{ start, end }` record of safe-integer (or numeric-string) values — fractions, empty
+ *   strings and values beyond ±(2^53 − 1) are invalid — or when any element has `start > end`.
  *
  * @param intervals array of `{ start, end }` records
  * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
  *
- * @example intervalXorAllUnix([{ start: 0, end: 1500000000 }, { start: 1400000000, end: 1700000000 }]) // [{ start: 0, end: 1399999999 }, { start: 1500000001, end: 1700000000 }]
+ * @example intervalXorAllUnix([{ start: 0, end: 1500000000 }, { start: 1400000000, end: 1700000000 }]) // [{ start: 0, end: 1400000000 }, { start: 1500000000, end: 1700000000 }]
+ * @example intervalXorAllUnix([{ start: 0, end: 5 }, { start: 5, end: 10 }]) // [{ start: 0, end: 10 }] (touching runs join)
  * @example intervalXorAllUnix([]) // []
  */
 export declare function intervalXorAllUnix(intervals: Array<{

package/dist/unix/interval/intervalXorAllUnix.js

@@ -1,77 +1,42 @@
-import { isValidUnixEpochPair } from "../../internal/resolveUnixTimeZone.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { halfOpenXor, parseUnixEpochIntervalList } from "../../internal/index.js";
 /**
  * Return the symmetric difference across a list of Unix epoch intervals — the set of epoch
  * values covered by an odd number of the input intervals.
  *
  * - List-form generalization of `intervalXorUnix`, which is pairwise only.
- * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
- *   one epoch unit after its end; the result is every maximal run where the running coverage
- *   count is odd. For two intervals this reduces to exactly `intervalXorUnix`'s pairwise result.
+ * - Intervals are half-open `[start, end)`. The result is every maximal run where the coverage
+ *   count is odd, so touching runs join and an empty interval (`start === end`) changes nothing.
+ *   Every boundary is an input's own `start` or `end`; none is stepped by an epoch unit. For two
+ *   intervals this is exactly `intervalXorUnix`'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 value 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 finite numeric (or numeric-string) values, or when any element
- *   has `start > end`.
+ *   `{ start, end }` record of safe-integer (or numeric-string) values — fractions, empty
+ *   strings and values beyond ±(2^53 − 1) are invalid — or when any element has `start > end`.
  *
  * @param intervals array of `{ start, end }` records
  * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
  *
- * @example intervalXorAllUnix([{ start: 0, end: 1500000000 }, { start: 1400000000, end: 1700000000 }]) // [{ start: 0, end: 1399999999 }, { start: 1500000001, end: 1700000000 }]
+ * @example intervalXorAllUnix([{ start: 0, end: 1500000000 }, { start: 1400000000, end: 1700000000 }]) // [{ start: 0, end: 1400000000 }, { start: 1500000000, end: 1700000000 }]
+ * @example intervalXorAllUnix([{ start: 0, end: 5 }, { start: 5, end: 10 }]) // [{ start: 0, end: 10 }] (touching runs join)
  * @example intervalXorAllUnix([]) // []
  */
 export function intervalXorAllUnix(intervals) {
-    if (!Array.isArray(intervals) || intervals.length === 0) {
-        return [];
-    }
-    if (!intervals.every((interval) => interval &&
-        typeof interval === "object" &&
-        (typeof interval.start === "number" ||
-            typeof interval.start === "string") &&
-        (typeof interval.end === "number" || typeof interval.end === "string"))) {
-        return [];
-    }
-    const parsed = intervals.map((interval) => ({
-        start: typeof interval.start === "number"
-            ? interval.start
-            : Number(interval.start),
-        end: typeof interval.end === "number" ? interval.end : Number(interval.end),
-    }));
-    if (!parsed.every((interval) => isValidUnixEpochPair(interval.start, interval.end) &&
-        interval.start <= interval.end)) {
-        return [];
-    }
-    const events = [];
-    for (const interval of parsed) {
-        events.push({ point: interval.start, delta: 1 });
-        events.push({ point: interval.end + 1, delta: -1 });
-    }
-    events.sort((a, b) => a.point - b.point);
-    const grouped = [];
-    for (const event of events) {
-        const last = grouped[grouped.length - 1];
-        if (last && last.point === event.point) {
-            last.delta += event.delta;
+    try {
+        if (!Array.isArray(intervals) || intervals.length === 0) {
+            return [];
         }
-        else {
-            grouped.push(event);
+        const parsed = parseUnixEpochIntervalList(intervals);
+        if (parsed === null) {
+            return [];
         }
+        return halfOpenXor(parsed, (left, right) => left - right);
     }
-    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 !== null) {
-            result.push({ start: runStart, end: group.point - 1 });
-            runStart = null;
-        }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
     }
-    return result;
 }

package/dist/unix/interval/intervalXorUnix.d.ts

@@ -1,23 +1,34 @@
 /**
- * Return the symmetric difference of two Unix intervals — time covered by exactly one interval.
+ * Return the symmetric difference of two half-open Unix intervals `[start, end)` — the values
+ * covered by exactly one interval.
  *
  * - Compares numeric Unix epoch values directly.
- * - 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.
+ * - The result is every maximal run covered by exactly one interval, sorted by start — the same
+ *   as `mergeIntervals` of `subtractIntervals(a, [b])` and `subtractIntervals(b, [a])`, and the
+ *   same as `intervalXorAllUnix([a, b])`.
+ * - Every boundary is an input's own `start` or `end`; no boundary is stepped by an epoch unit.
+ * - Touching intervals share no value, so they join into one run (`[0, 5)` xor `[5, 10)` is
+ *   `[0, 10)`). An empty interval (`start === end`) holds no value and changes nothing.
+ * - Returns `[]` when the intervals are identical.
+ * - Returns `[{ start, end }]` when the intervals share a start or an end, or touch.
+ * - Returns `[{ start, end }, { start, end }]` when they partially overlap, when one strictly
+ *   contains the other, or when they are disjoint with a gap.
  * - Returns `[]` if either interval is invalid (`start > end`).
- * - Returns `[]` on invalid input (non-numeric types, non-finite values).
+ * - Returns `[]` on invalid input: non-numeric types, empty strings, and values that are not safe
+ *   integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
  *
- * @example intervalXorUnix(0, 1500000000, 1400000000, 1700000000) // [{ start: 0, end: 1399999999 }, { start: 1500000001, end: 1700000000 }]
- * @example intervalXorUnix(0, 1700000000, 1400000000, 1500000000) // [{ start: 0, end: 1399999999 }, { start: 1500000001, end: 1700000000 }]
+ * @example intervalXorUnix(0, 1500000000, 1400000000, 1700000000) // [{ start: 0, end: 1400000000 }, { start: 1500000000, end: 1700000000 }]
+ * @example intervalXorUnix(0, 1700000000, 1400000000, 1500000000) // [{ start: 0, end: 1400000000 }, { start: 1500000000, end: 1700000000 }]
+ * @example intervalXorUnix(0, 1500000000, 1500000000, 1700000000) // [{ start: 0, end: 1700000000 }] (touching intervals join)
  * @example intervalXorUnix(0, 1700000000, 0, 1700000000) // []
  * @example intervalXorUnix(NaN, 1500000000, 1400000000, 1700000000) // []
+ * @example intervalXorUnix(0, 1, 0.5, 2) // [] (fractional epoch)
  */
 export declare function intervalXorUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): Array<{
     start: number;

package/dist/unix/interval/intervalXorUnix.js

@@ -1,70 +1,42 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { halfOpenXor, parseUnixEpochIntervalPair } from "../../internal/index.js";
 /**
- * Return the symmetric difference of two Unix intervals — time covered by exactly one interval.
+ * Return the symmetric difference of two half-open Unix intervals `[start, end)` — the values
+ * covered by exactly one interval.
  *
  * - Compares numeric Unix epoch values directly.
- * - 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.
+ * - The result is every maximal run covered by exactly one interval, sorted by start — the same
+ *   as `mergeIntervals` of `subtractIntervals(a, [b])` and `subtractIntervals(b, [a])`, and the
+ *   same as `intervalXorAllUnix([a, b])`.
+ * - Every boundary is an input's own `start` or `end`; no boundary is stepped by an epoch unit.
+ * - Touching intervals share no value, so they join into one run (`[0, 5)` xor `[5, 10)` is
+ *   `[0, 10)`). An empty interval (`start === end`) holds no value and changes nothing.
+ * - Returns `[]` when the intervals are identical.
+ * - Returns `[{ start, end }]` when the intervals share a start or an end, or touch.
+ * - Returns `[{ start, end }, { start, end }]` when they partially overlap, when one strictly
+ *   contains the other, or when they are disjoint with a gap.
  * - Returns `[]` if either interval is invalid (`start > end`).
- * - Returns `[]` on invalid input (non-numeric types, non-finite values).
+ * - Returns `[]` on invalid input: non-numeric types, empty strings, and values that are not safe
+ *   integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
  *
- * @example intervalXorUnix(0, 1500000000, 1400000000, 1700000000) // [{ start: 0, end: 1399999999 }, { start: 1500000001, end: 1700000000 }]
- * @example intervalXorUnix(0, 1700000000, 1400000000, 1500000000) // [{ start: 0, end: 1399999999 }, { start: 1500000001, end: 1700000000 }]
+ * @example intervalXorUnix(0, 1500000000, 1400000000, 1700000000) // [{ start: 0, end: 1400000000 }, { start: 1500000000, end: 1700000000 }]
+ * @example intervalXorUnix(0, 1700000000, 1400000000, 1500000000) // [{ start: 0, end: 1400000000 }, { start: 1500000000, end: 1700000000 }]
+ * @example intervalXorUnix(0, 1500000000, 1500000000, 1700000000) // [{ start: 0, end: 1700000000 }] (touching intervals join)
  * @example intervalXorUnix(0, 1700000000, 0, 1700000000) // []
  * @example intervalXorUnix(NaN, 1500000000, 1400000000, 1700000000) // []
+ * @example intervalXorUnix(0, 1, 0.5, 2) // [] (fractional epoch)
  */
 export function intervalXorUnix(aStart, aEnd, bStart, bEnd) {
-    if ((typeof aStart !== "number" && typeof aStart !== "string") ||
-        (typeof aEnd !== "number" && typeof aEnd !== "string") ||
-        (typeof bStart !== "number" && typeof bStart !== "string") ||
-        (typeof bEnd !== "number" && typeof bEnd !== "string")) {
+    const pair = parseUnixEpochIntervalPair(aStart, aEnd, bStart, bEnd);
+    if (pair === null) {
         return [];
     }
-    const n1 = typeof aStart === "number" ? aStart : Number(aStart);
-    const n2 = typeof aEnd === "number" ? aEnd : Number(aEnd);
-    const n3 = typeof bStart === "number" ? bStart : Number(bStart);
-    const n4 = typeof bEnd === "number" ? bEnd : Number(bEnd);
-    if (!Number.isFinite(n1) ||
-        !Number.isFinite(n2) ||
-        !Number.isFinite(n3) ||
-        !Number.isFinite(n4)) {
-        return [];
-    }
-    if (n1 > n2) {
-        return [];
-    }
-    if (n3 > n4) {
-        return [];
-    }
-    const result = [];
-    // If intervals don't overlap, return both as-is
-    if (n2 < n3 || n4 < n1) {
-        return [
-            { start: n1, end: n2 },
-            { start: n3, end: n4 },
-        ];
-    }
-    // Left piece: A before B starts
-    if (n1 < n3) {
-        result.push({ start: n1, end: n3 - 1 });
-    }
-    // Right piece: A after B ends
-    if (n2 > n4) {
-        result.push({ start: n4 + 1, end: n2 });
-    }
-    // Left piece: B before A starts
-    if (n3 < n1) {
-        result.push({ start: n3, end: n1 - 1 });
-    }
-    // Right piece: B after A ends
-    if (n4 > n2) {
-        result.push({ start: n2 + 1, end: n4 });
-    }
-    return result;
+    // Maximal runs covered an odd number of times (exactly once, for two intervals).
+    return halfOpenXor(pair, (left, right) => left - right);
 }

package/dist/unix/interval/intervalsOverlapUnix.d.ts

@@ -1,20 +1,26 @@
 /**
- * Return true when intervals `[aStart, aEnd]` and `[bStart, bEnd]` share at least one instant.
+ * Return true when the half-open intervals `[aStart, aEnd)` and `[bStart, bEnd)` share at least
+ * one instant.
  *
- * - Compares numeric Unix epoch values directly.
- * - Adjacent intervals (e.g. `aEnd === bStart`) do NOT overlap — returns `false`.
+ * - Compares numeric Unix epoch values directly: `aStart < bEnd && bStart < aEnd`, the same rule as
+ *   `intervalsOverlap` (SQL:2011 `OVERLAPS` on closed-open periods).
+ * - An interval excludes its `end`, so touching intervals (`aEnd` equal to `bStart`) do NOT
+ *   overlap — returns `false`.
+ * - An empty interval (`start === end`) overlaps an interval only when it lies strictly inside it;
+ *   at either edge, or against another empty interval, it returns `false`.
  * - Returns `false` if either interval is invalid (`start > end`).
- * - Returns `false` on invalid input (non-numeric types, non-finite values).
+ * - Returns `false` on invalid input: non-numeric types, empty strings, and values that are not
+ *   safe integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns true if intervals overlap, or false on invalid input
  *
  * @example intervalsOverlapUnix(0, 1700000000, 1000000, 2000000) // true
- * @example intervalsOverlapUnix(0, 1000000, 1000000, 2000000) // false (adjacent)
- * @example intervalsOverlapUnix(0, 1000000, 1000001, 2000000) // false (disjoint)
+ * @example intervalsOverlapUnix(0, 1000000, 1000000, 2000000) // false (touching: [0, 1000000) excludes 1000000)
+ * @example intervalsOverlapUnix(0, 1000001, 1000000, 2000000) // true (one unit shared)
  * @example intervalsOverlapUnix(NaN, 1700000000, 1000000, 2000000) // false
  * @example intervalsOverlapUnix("0", "1700000000", "1000000", "2000000") // true
  */