@northguild/gmt 1.14.2 → 1.16.0

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
  */

package/dist/unix/interval/intervalsOverlapUnix.js

@@ -1,51 +1,35 @@
+import { halfOpenOverlap, parseUnixEpochIntervalPair } from "../../internal/index.js";
 /**
- * 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
  */
 export function intervalsOverlapUnix(aStart, aEnd, bStart, bEnd) {
-    if (typeof aStart !== "number" && typeof aStart !== "string") {
+    const pair = parseUnixEpochIntervalPair(aStart, aEnd, bStart, bEnd);
+    if (pair === null) {
         return false;
     }
-    if (typeof aEnd !== "number" && typeof aEnd !== "string") {
-        return false;
-    }
-    if (typeof bStart !== "number" && typeof bStart !== "string") {
-        return false;
-    }
-    if (typeof bEnd !== "number" && typeof bEnd !== "string") {
-        return false;
-    }
-    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 false;
-    }
-    if (a1 > a2) {
-        return false;
-    }
-    if (b1 > b2) {
-        return false;
-    }
-    return a2 >= b1 && b2 >= a1;
+    // Each interval starts before the other's exclusive end.
+    return halfOpenOverlap(pair[0], pair[1], (left, right) => left - right);
 }

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

@@ -2,18 +2,24 @@
  * Collapse a list of Unix epoch intervals into the minimum set of non-overlapping intervals.
  *
  * - List-form generalization of `intervalUnionUnix`, which is pairwise only.
- * - Intervals are merged when they overlap or share an endpoint exactly (adjacent intervals
- *   ARE merged).
+ * - Intervals are half-open `[start, end)`, the same rule as `mergeIntervals`. They are merged
+ *   when they overlap or touch (one's `end` equals the other's `start`), so the runs returned
+ *   never touch.
+ * - An empty interval (`start === end`) holds no instant: it is absorbed when it touches or lies
+ *   inside a run and dropped otherwise, so it never bridges a gap. A list of only empty intervals
+ *   returns `[]`, the same value as invalid input — use `isValidUnixInterval` to tell them apart.
  * - Order of the input list does not matter; the result is sorted by start.
  * - Returns `[]` for an empty list.
  * - Returns `[]` when `intervals` is not an array, when any element is not a
- *   `{ start, end }` record of 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 the minimum set of non-overlapping `{ start, end }` records, sorted by start, or `[]` on invalid input
  *
  * @example mergeIntervalsUnix([{ start: 0, end: 1000000 }, { start: 500000, end: 1500000 }]) // [{ start: 0, end: 1500000 }]
+ * @example mergeIntervalsUnix([{ start: 0, end: 1000000 }, { start: 1000000, end: 2000000 }]) // [{ start: 0, end: 2000000 }] (touching)
+ * @example mergeIntervalsUnix([{ start: 5, end: 5 }]) // [] (an empty interval holds no instant)
  * @example mergeIntervalsUnix([]) // []
  */
 export declare function mergeIntervalsUnix(intervals: Array<{

package/dist/unix/interval/mergeIntervalsUnix.js

@@ -1,55 +1,44 @@
-import { isValidUnixEpochPair } from "../../internal/resolveUnixTimeZone.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { halfOpenMerge, parseUnixEpochIntervalList } from "../../internal/index.js";
 /**
  * Collapse a list of Unix epoch intervals into the minimum set of non-overlapping intervals.
  *
  * - List-form generalization of `intervalUnionUnix`, which is pairwise only.
- * - Intervals are merged when they overlap or share an endpoint exactly (adjacent intervals
- *   ARE merged).
+ * - Intervals are half-open `[start, end)`, the same rule as `mergeIntervals`. They are merged
+ *   when they overlap or touch (one's `end` equals the other's `start`), so the runs returned
+ *   never touch.
+ * - An empty interval (`start === end`) holds no instant: it is absorbed when it touches or lies
+ *   inside a run and dropped otherwise, so it never bridges a gap. A list of only empty intervals
+ *   returns `[]`, the same value as invalid input — use `isValidUnixInterval` to tell them apart.
  * - Order of the input list does not matter; the result is sorted by start.
  * - Returns `[]` for an empty list.
  * - Returns `[]` when `intervals` is not an array, when any element is not a
- *   `{ start, end }` record of 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 the minimum set of non-overlapping `{ start, end }` records, sorted by start, or `[]` on invalid input
  *
  * @example mergeIntervalsUnix([{ start: 0, end: 1000000 }, { start: 500000, end: 1500000 }]) // [{ start: 0, end: 1500000 }]
+ * @example mergeIntervalsUnix([{ start: 0, end: 1000000 }, { start: 1000000, end: 2000000 }]) // [{ start: 0, end: 2000000 }] (touching)
+ * @example mergeIntervalsUnix([{ start: 5, end: 5 }]) // [] (an empty interval holds no instant)
  * @example mergeIntervalsUnix([]) // []
  */
 export function mergeIntervalsUnix(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 [];
-    }
-    parsed.sort((a, b) => a.start - b.start);
-    const merged = [];
-    for (const interval of parsed) {
-        const last = merged[merged.length - 1];
-        if (last && interval.start <= last.end) {
-            if (interval.end > last.end) {
-                last.end = interval.end;
-            }
+    try {
+        if (!Array.isArray(intervals) || intervals.length === 0) {
+            return [];
         }
-        else {
-            merged.push({ start: interval.start, end: interval.end });
+        const parsed = parseUnixEpochIntervalList(intervals);
+        if (parsed === null) {
+            return [];
         }
+        // Sorted, disjoint, non-touching, non-empty runs.
+        return halfOpenMerge(parsed, (left, right) => left - right);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
     }
-    return merged;
 }

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

@@ -1,18 +1,40 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Split a Unix epoch interval into sub-intervals of `amount × unit`.
  *
- * - Returns an array of `{ start, end }` records that tile the interval.
+ * - Returns an array of half-open `[start, end)` records that tile the interval: 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.
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
+ * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
+ *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
+ *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
+ *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
+ *   `Number.MAX_SAFE_INTEGER` (boundaries are then floored to milliseconds).
+ * - A calendar step that resolves to the same instant as the previous boundary (a deleted local
+ *   day, such as 30 December 2011 in `Pacific/Apia`) is skipped, so no empty slice is produced.
+ *   A step that goes backwards returns `[]`.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
- * - Returns `[]` on invalid input (non-finite/non-integer start/end, unsupported unit,
- *   non-positive amount, or invalid timeZone).
+ * - Returns `[]` on invalid input (`start`/`end` that is not a safe integer or numeric string of
+ *   one — fractions, empty strings and values beyond ±(2^53 − 1) are invalid — unsupported unit,
+ *   non-positive amount, an invalid `epochUnit` or an unknown `timeZone`).
  *
- * Uses the system timeZone for calendar-unit arithmetic (consistent with `addUnix`).
+ * - Reads `start` and `end`, and returns every boundary, in `options.epochUnit` (`"milliseconds"`
+ *   by default, `"seconds"`; singular accepted). Each input is a safe integer or a string of
+ *   optionally negative ASCII digits.
+ * - Calendar-unit arithmetic runs in `options.timeZone`: omitted is `"UTC"`, `"local"` is the
+ *   system zone, and an unknown zone returns `[]`.
+ * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
+ *   into more slices returns `[]`, decided from the span before stepping where it can be, and
+ *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
- * @param unit duration unit string — any `DateTimeDurationUnit`
+ * @param start Unix epoch in `epochUnit` — interval start
+ * @param end Unix epoch in `epochUnit` — interval end
+ * @param unit duration unit string — any `DateTimeDurationUnit`, singular or plural
  * @param amount positive number of units per step
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`), `epochUnit` ("seconds" | "milliseconds", singular accepted; default "milliseconds"), `timeZone` (IANA, or "local" for the system zone; default "UTC")
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
@@ -20,8 +42,16 @@
  * @example splitIntervalByUnitUnix(0, 0, "hour", 1) // [{ start: 0, end: 0 }]
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 0) // []
  * @example splitIntervalByUnitUnix("invalid", 86400000, "hour", 1) // []
+ * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6, { maxPieces: 3 }) // [] (4 slices exceed the limit)
+ * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6, { maxPieces: 4 }) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
+ * @example splitIntervalByUnitUnix(1710046800000, 1710216000000, "day", 1, { timeZone: "America/New_York" }) // [{ start: 1710046800000, end: 1710129600000 }, { start: 1710129600000, end: 1710216000000 }] (the first local day is 23 hours)
+ * @example splitIntervalByUnitUnix("0", "86400", "hours", 12, { epochUnit: "second" }) // [{ start: 0, end: 43200 }, { start: 43200, end: 86400 }]
  */
-export declare function splitIntervalByUnitUnix(start: number | string, end: number | string, unit: string, amount: number): Array<{
+export declare function splitIntervalByUnitUnix(start: number | string, end: number | string, unit: string, amount: number, options?: {
+    maxPieces?: number;
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): Array<{
     start: number;
     end: number;
 }>;