@northguild/gmt 1.14.2 → 1.16.0

package/dist/unix/interval/intervalAbutsUnix.js

@@ -1,54 +1,36 @@
+import { halfOpenAbuts, parseUnixEpochInterval } from "../../internal/index.js";
 /**
- * Return true when two Unix intervals are exactly adjacent — one's end equals the other's
- * start minus 1 (no gap, no overlap).
+ * Return true when two half-open Unix intervals `[start, end)` are exactly adjacent — one ends
+ * where the other starts, so they share no value and leave no gap (Allen's "meets", either order).
  *
  * - Compares numeric Unix epoch values directly.
- * - Returns `true` when `aEnd + 1 === bStart` or `bEnd + 1 === aStart`.
- * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
- * - Returns `false` on invalid input (non-numeric types, non-finite values).
+ * - Returns `true` when `aEnd === bStart` or `bEnd === aStart` and neither interval is empty. No
+ *   value is stepped by an epoch unit.
+ * - Returns `false` when intervals overlap, are disjoint with a gap (even one epoch unit), or when
+ *   either is empty (`start === end`): an empty interval abuts nothing.
+ * - 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 are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // true
- * @example intervalAbutsUnix(1500000001, 1700000000, 0, 1500000000) // true
- * @example intervalAbutsUnix(0, 1500000000, 1500000002, 1700000000) // false (gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1700000000) // true
+ * @example intervalAbutsUnix(1500000000, 1700000000, 0, 1500000000) // true
+ * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // false (one-unit gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1500000000) // false (an empty interval abuts nothing)
  * @example intervalAbutsUnix(0, 1500000001, 1500000000, 1700000000) // false (overlap)
  * @example intervalAbutsUnix(NaN, 1500000000, 1500000001, 1700000000) // false
+ * @example intervalAbutsUnix(0, 1.5, 1.5, 3) // false (fractional epochs)
  */
 export function intervalAbutsUnix(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 a = parseUnixEpochInterval(aStart, aEnd);
+    const b = parseUnixEpochInterval(bStart, bEnd);
+    if (a === null || b === null) {
         return false;
     }
-    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 false;
-    }
-    if (n1 > n2) {
-        return false;
-    }
-    if (n3 > n4) {
-        return false;
-    }
-    // aEnd + 1 === bStart
-    if (n2 + 1 === n3) {
-        return true;
-    }
-    // bEnd + 1 === aStart
-    if (n4 + 1 === n1) {
-        return true;
-    }
-    return false;
+    // aEnd === bStart, or bEnd === aStart, between two non-empty intervals.
+    return halfOpenAbuts(a, b, (left, right) => left - right);
 }

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

@@ -1,25 +1,35 @@
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` falls within the half-open interval
+ * `[intervalStart, intervalEnd)` (3-arg), or when the inner interval `[innerStart, innerEnd)` lies
+ * within the outer interval `[intervalStart, intervalEnd)` (4-arg).
  *
  * - Compares numeric Unix epoch values directly.
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Point mode: `start <= point < end`, the same rule as `intervalContains`. The `end` is
+ *   excluded, so a point at `end` returns `false`, and an empty interval (`start === end`)
+ *   contains no point.
+ * - Interval mode: the intervals overlap and `start <= innerStart` and `innerEnd <= end`. An inner
+ *   interval may share the outer `end`. An empty inner interval counts only strictly inside the
+ *   outer interval, the same edge rule as `clampInterval`, and an empty outer interval contains
+ *   nothing.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
- * - 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 intervalStart Unix epoch value (seconds or milliseconds) — outer interval start
- * @param intervalEnd Unix epoch value (seconds or milliseconds) — outer interval end
+ * @param intervalStart Unix epoch value, in the one unit all epoch arguments share — outer interval start
+ * @param intervalEnd Unix epoch value, in the one unit all epoch arguments share — outer interval end
  * @param pointOrStart Unix epoch value for the point (3-arg) or inner start (4-arg)
  * @param pointEnd optional Unix epoch value for the inner interval end (4-arg mode)
  * @returns true if the point or inner interval is contained, or false on invalid input
  *
  * @example intervalContainsUnix(0, 1700000000, 170000000) // true
+ * @example intervalContainsUnix(0, 1700000000, 1700000000) // false (the end is excluded)
+ * @example intervalContainsUnix(0, 1700000000, 1500000000, 1700000000) // true (the inner interval shares the end)
  * @example intervalContainsUnix(0, 1700000000, 170000000, 1500000000) // true
  * @example intervalContainsUnix(1700000000, 0, 170000000) // false
  * @example intervalContainsUnix(0, 1700000000, 170000000, 15000000) // false
  * @example intervalContainsUnix(NaN, 1700000000, 170000000) // false
  * @example intervalContainsUnix("0", "1700000000", "170000000") // true
+ * @example intervalContainsUnix(0, 10, 0.5) // false (fractional epoch)
  */
 export declare function intervalContainsUnix(intervalStart: number | string, intervalEnd: number | string, pointOrStart: number | string, pointEnd?: number | string): boolean;

package/dist/unix/interval/intervalContainsUnix.js

@@ -1,60 +1,48 @@
+import { halfOpenContainsPoint, halfOpenContainsSpan, parseUnixEpochInterval, parseUnixEpochValue, } from "../../internal/index.js";
+const compareEpoch = (left, right) => left - right;
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` falls within the half-open interval
+ * `[intervalStart, intervalEnd)` (3-arg), or when the inner interval `[innerStart, innerEnd)` lies
+ * within the outer interval `[intervalStart, intervalEnd)` (4-arg).
  *
  * - Compares numeric Unix epoch values directly.
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Point mode: `start <= point < end`, the same rule as `intervalContains`. The `end` is
+ *   excluded, so a point at `end` returns `false`, and an empty interval (`start === end`)
+ *   contains no point.
+ * - Interval mode: the intervals overlap and `start <= innerStart` and `innerEnd <= end`. An inner
+ *   interval may share the outer `end`. An empty inner interval counts only strictly inside the
+ *   outer interval, the same edge rule as `clampInterval`, and an empty outer interval contains
+ *   nothing.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
- * - 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 intervalStart Unix epoch value (seconds or milliseconds) — outer interval start
- * @param intervalEnd Unix epoch value (seconds or milliseconds) — outer interval end
+ * @param intervalStart Unix epoch value, in the one unit all epoch arguments share — outer interval start
+ * @param intervalEnd Unix epoch value, in the one unit all epoch arguments share — outer interval end
  * @param pointOrStart Unix epoch value for the point (3-arg) or inner start (4-arg)
  * @param pointEnd optional Unix epoch value for the inner interval end (4-arg mode)
  * @returns true if the point or inner interval is contained, or false on invalid input
  *
  * @example intervalContainsUnix(0, 1700000000, 170000000) // true
+ * @example intervalContainsUnix(0, 1700000000, 1700000000) // false (the end is excluded)
+ * @example intervalContainsUnix(0, 1700000000, 1500000000, 1700000000) // true (the inner interval shares the end)
  * @example intervalContainsUnix(0, 1700000000, 170000000, 1500000000) // true
  * @example intervalContainsUnix(1700000000, 0, 170000000) // false
  * @example intervalContainsUnix(0, 1700000000, 170000000, 15000000) // false
  * @example intervalContainsUnix(NaN, 1700000000, 170000000) // false
  * @example intervalContainsUnix("0", "1700000000", "170000000") // true
+ * @example intervalContainsUnix(0, 10, 0.5) // false (fractional epoch)
  */
 export function intervalContainsUnix(intervalStart, intervalEnd, pointOrStart, pointEnd) {
-    if (typeof intervalStart !== "number" && typeof intervalStart !== "string") {
-        return false;
-    }
-    if (typeof intervalEnd !== "number" && typeof intervalEnd !== "string") {
-        return false;
-    }
-    if (typeof pointOrStart !== "number" && typeof pointOrStart !== "string") {
-        return false;
-    }
-    if (pointEnd !== undefined &&
-        typeof pointEnd !== "number" &&
-        typeof pointEnd !== "string") {
-        return false;
-    }
-    const n1 = typeof intervalStart === "number" ? intervalStart : Number(intervalStart);
-    const n2 = typeof intervalEnd === "number" ? intervalEnd : Number(intervalEnd);
-    const n3 = typeof pointOrStart === "number" ? pointOrStart : Number(pointOrStart);
-    if (!Number.isFinite(n1) || !Number.isFinite(n2) || !Number.isFinite(n3)) {
-        return false;
-    }
-    if (n1 > n2) {
+    const outer = parseUnixEpochInterval(intervalStart, intervalEnd);
+    if (outer === null) {
         return false;
     }
     if (pointEnd === undefined) {
-        return n1 <= n3 && n3 <= n2;
-    }
-    const n4 = typeof pointEnd === "number" ? pointEnd : Number(pointEnd);
-    if (!Number.isFinite(n4)) {
-        return false;
-    }
-    if (n3 > n4) {
-        return false;
+        const point = parseUnixEpochValue(pointOrStart);
+        return point !== null && halfOpenContainsPoint(outer, point, compareEpoch);
     }
-    return n1 <= n3 && n4 <= n2;
+    const inner = parseUnixEpochInterval(pointOrStart, pointEnd);
+    return inner !== null && halfOpenContainsSpan(outer, inner, compareEpoch);
 }

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

@@ -1,28 +1,45 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Count how many `unit` boundaries a Unix epoch interval crosses.
  *
  * - Counts local calendar boundaries touched by the half-open interval `[start, end)` —
  *   distinct from `diffUnix`, which measures exact elapsed duration.
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
- * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
- *   unit boundary.
- * - Uses the system timeZone for calendar-unit boundaries (consistent with `addUnix` and
- *   `splitIntervalByUnitUnix`), so day/week/month/year counts are host-dependent.
+ * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
+ *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
+ * - Reads `start` and `end` in `options.epochUnit` (`"milliseconds"` by default, `"seconds"`; singular
+ *   accepted). Each is a safe integer or a string of optionally negative ASCII digits.
+ * - Uses `options.timeZone` for calendar-unit boundaries: omitted is `"UTC"`, `"local"` is the
+ *   system zone, and an unknown zone returns `null`.
+ * - Counts the real local buckets `floorToZone`/`bucketRange` walk in that zone: a bucket
+ *   shorter than its unit still counts once (a 15-minute `Pacific/Chatham` hour on its
+ *   spring-forward), and a local day the zone deleted counts not at all
+ *   (`Pacific/Apia`'s 2011-12-30).
+ * - The count equals `bucketRange(...).length` wherever `bucketRange` is within its 10,000-bucket
+ *   cap. Counting has its own, separate cap of 10,000 zone transitions, so it keeps answering past
+ *   `bucketRange`'s: two years by hour counts 17,544 while `bucketRange` returns `[]`.
+ * - Returns `null` when the span crosses more than 10,000 zone transitions.
  * - Weeks start on Monday (ISO 8601).
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
- * - Returns `null` on invalid input (non-finite/non-integer start/end, `start > end`,
- *   unsupported unit, or invalid timeZone).
+ * - Returns `null` on invalid input (`start`/`end` that is not a safe integer or numeric string of
+ *   one, or lies outside the Temporal instant range, `start > end`, an unsupported unit, an invalid
+ *   `epochUnit` or an unknown `timeZone`).
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
- * @param unit unit string — any `DateTimeUnit`
+ * @param start Unix epoch in `epochUnit` — interval start
+ * @param end Unix epoch in `epochUnit` — interval end
+ * @param unit unit string — any `DateTimeUnit`, singular or plural
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns number of unit boundaries touched, or null on invalid input
  *
  * @example intervalCountUnix(0, 86400000, "hour") // 24
- * @example intervalCountUnix(1704153540000, 1704153660000, "day") // 2 (23:59 to 00:01 UTC)
- * @example intervalCountUnix(0, 0, "hour") // 0 (zero-length, on the boundary)
- * @example intervalCountUnix(1800000, 1800000, "hour") // 1 (zero-length, mid-hour)
+ * @example intervalCountUnix(1704153540000, 1704153660000, "day") // 2 (23:59 to 00:01 UTC crosses midnight)
+ * @example intervalCountUnix(1800000, 1800000, "hour") // 0 (zero-length: holds no instant)
  * @example intervalCountUnix(86400000, 0, "hour") // null
+ * @example intervalCountUnix(1704151800000, 1704155400000, "day", { timeZone: "Asia/Tokyo" }) // 1 (08:30 to 09:30 on one Tokyo day)
+ * @example intervalCountUnix("1704151800", "1704155400", "days", { epochUnit: "second" }) // 2
  * @example intervalCountUnix(NaN, 86400000, "hour") // null
  */
-export declare function intervalCountUnix(start: number | string, end: number | string, unit: string): number | null;
+export declare function intervalCountUnix(start: number | string, end: number | string, unit: string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): number | null;

package/dist/unix/interval/intervalCountUnix.js

@@ -1,44 +1,70 @@
-import { getStartOfZonedUnit, getUnitSpan } from "../../internal/index.js";
-import { resolveUnixIntervalPair } from "./resolveUnixIntervalPair.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { countZonedBuckets } from "../../internal/index.js";
+import { resolveUnixIntervalPair } from "../../internal/resolveUnixIntervalPair.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Count how many `unit` boundaries a Unix epoch interval crosses.
  *
  * - Counts local calendar boundaries touched by the half-open interval `[start, end)` —
  *   distinct from `diffUnix`, which measures exact elapsed duration.
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
- * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
- *   unit boundary.
- * - Uses the system timeZone for calendar-unit boundaries (consistent with `addUnix` and
- *   `splitIntervalByUnitUnix`), so day/week/month/year counts are host-dependent.
+ * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
+ *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
+ * - Reads `start` and `end` in `options.epochUnit` (`"milliseconds"` by default, `"seconds"`; singular
+ *   accepted). Each is a safe integer or a string of optionally negative ASCII digits.
+ * - Uses `options.timeZone` for calendar-unit boundaries: omitted is `"UTC"`, `"local"` is the
+ *   system zone, and an unknown zone returns `null`.
+ * - Counts the real local buckets `floorToZone`/`bucketRange` walk in that zone: a bucket
+ *   shorter than its unit still counts once (a 15-minute `Pacific/Chatham` hour on its
+ *   spring-forward), and a local day the zone deleted counts not at all
+ *   (`Pacific/Apia`'s 2011-12-30).
+ * - The count equals `bucketRange(...).length` wherever `bucketRange` is within its 10,000-bucket
+ *   cap. Counting has its own, separate cap of 10,000 zone transitions, so it keeps answering past
+ *   `bucketRange`'s: two years by hour counts 17,544 while `bucketRange` returns `[]`.
+ * - Returns `null` when the span crosses more than 10,000 zone transitions.
  * - Weeks start on Monday (ISO 8601).
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
- * - Returns `null` on invalid input (non-finite/non-integer start/end, `start > end`,
- *   unsupported unit, or invalid timeZone).
+ * - Returns `null` on invalid input (`start`/`end` that is not a safe integer or numeric string of
+ *   one, or lies outside the Temporal instant range, `start > end`, an unsupported unit, an invalid
+ *   `epochUnit` or an unknown `timeZone`).
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
- * @param unit unit string — any `DateTimeUnit`
+ * @param start Unix epoch in `epochUnit` — interval start
+ * @param end Unix epoch in `epochUnit` — interval end
+ * @param unit unit string — any `DateTimeUnit`, singular or plural
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns number of unit boundaries touched, or null on invalid input
  *
  * @example intervalCountUnix(0, 86400000, "hour") // 24
- * @example intervalCountUnix(1704153540000, 1704153660000, "day") // 2 (23:59 to 00:01 UTC)
- * @example intervalCountUnix(0, 0, "hour") // 0 (zero-length, on the boundary)
- * @example intervalCountUnix(1800000, 1800000, "hour") // 1 (zero-length, mid-hour)
+ * @example intervalCountUnix(1704153540000, 1704153660000, "day") // 2 (23:59 to 00:01 UTC crosses midnight)
+ * @example intervalCountUnix(1800000, 1800000, "hour") // 0 (zero-length: holds no instant)
  * @example intervalCountUnix(86400000, 0, "hour") // null
+ * @example intervalCountUnix(1704151800000, 1704155400000, "day", { timeZone: "Asia/Tokyo" }) // 1 (08:30 to 09:30 on one Tokyo day)
+ * @example intervalCountUnix("1704151800", "1704155400", "days", { epochUnit: "second" }) // 2
  * @example intervalCountUnix(NaN, 86400000, "hour") // null
  */
-export function intervalCountUnix(start, end, unit) {
-    const resolved = resolveUnixIntervalPair(start, end, unit);
-    if (!resolved)
-        return null;
+export function intervalCountUnix(start, end, unit, options) {
     try {
-        const { startVal, endVal, resolvedUnit } = resolved;
-        const startOfStart = getStartOfZonedUnit(startVal, resolvedUnit);
-        const startOfEnd = getStartOfZonedUnit(endVal, resolvedUnit);
-        const spanned = getUnitSpan(startOfStart.until(startOfEnd, { largestUnit: resolvedUnit }), resolvedUnit);
-        return spanned + (startOfEnd.equals(endVal) ? 0 : 1);
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const resolved = resolveUnixIntervalPair(start, end, unit, options);
+        if (!resolved)
+            return null;
+        try {
+            const { startVal, endVal, resolvedUnit } = resolved;
+            // An empty interval [t, t) holds no instant, so it touches no unit (CORE-6 empty-interval rule).
+            if (startVal.epochNanoseconds === endVal.epochNanoseconds) {
+                return 0;
+            }
+            return countZonedBuckets(startVal, endVal, resolvedUnit);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,22 +1,31 @@
 /**
- * Return the portion(s) of interval A not covered by interval B.
+ * Return the portion(s) of the half-open interval A `[aStart, aEnd)` not covered by the half-open
+ * interval B `[bStart, bEnd)`.
  *
- * - Compares numeric Unix epoch values directly.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Compares numeric Unix epoch values directly, with the same rule as `subtractIntervals`.
+ * - Every cut lands exactly on B's own `start` or `end`: the piece before B ends at `bStart`, which
+ *   it excludes, and the piece after B starts at `bEnd`, which B excludes. No boundary is stepped
+ *   by an epoch unit.
+ * - Returns `[]` when B fully covers A, and when A is empty (`aStart === aEnd`).
+ * - Returns `[{ start, end }]` when B overlaps one edge of A.
  * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns A unchanged when B lies entirely before or after it, touches it, or is empty.
  * - 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 A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceUnix(0, 1700000000, 1500000000, 1600000000) // [{ start: 0, end: 1499999999 }]
+ * @example intervalDifferenceUnix(0, 1700000000, 1500000000, 1600000000) // [{ start: 0, end: 1500000000 }, { start: 1600000000, end: 1700000000 }]
+ * @example intervalDifferenceUnix(0, 1500000000, 1500000000, 1700000000) // [{ start: 0, end: 1500000000 }] (touching: B removes nothing)
  * @example intervalDifferenceUnix(0, 1700000000, 0, 1700000000) // []
  * @example intervalDifferenceUnix(NaN, 1700000000, 1500000000, 1600000000) // []
+ * @example intervalDifferenceUnix(0, 2, 0.5, 1) // [] (fractional epoch)
+ * @example intervalDifferenceUnix(5, 10, 0, 5) // [{ start: 5, end: 10 }] (B ends where A starts)
  */
 export declare function intervalDifferenceUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): Array<{
     start: number;

package/dist/unix/interval/intervalDifferenceUnix.js

@@ -1,57 +1,39 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { halfOpenDifference, parseUnixEpochIntervalPair } from "../../internal/index.js";
 /**
- * Return the portion(s) of interval A not covered by interval B.
+ * Return the portion(s) of the half-open interval A `[aStart, aEnd)` not covered by the half-open
+ * interval B `[bStart, bEnd)`.
  *
- * - Compares numeric Unix epoch values directly.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Compares numeric Unix epoch values directly, with the same rule as `subtractIntervals`.
+ * - Every cut lands exactly on B's own `start` or `end`: the piece before B ends at `bStart`, which
+ *   it excludes, and the piece after B starts at `bEnd`, which B excludes. No boundary is stepped
+ *   by an epoch unit.
+ * - Returns `[]` when B fully covers A, and when A is empty (`aStart === aEnd`).
+ * - Returns `[{ start, end }]` when B overlaps one edge of A.
  * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns A unchanged when B lies entirely before or after it, touches it, or is empty.
  * - 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 A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceUnix(0, 1700000000, 1500000000, 1600000000) // [{ start: 0, end: 1499999999 }]
+ * @example intervalDifferenceUnix(0, 1700000000, 1500000000, 1600000000) // [{ start: 0, end: 1500000000 }, { start: 1600000000, end: 1700000000 }]
+ * @example intervalDifferenceUnix(0, 1500000000, 1500000000, 1700000000) // [{ start: 0, end: 1500000000 }] (touching: B removes nothing)
  * @example intervalDifferenceUnix(0, 1700000000, 0, 1700000000) // []
  * @example intervalDifferenceUnix(NaN, 1700000000, 1500000000, 1600000000) // []
+ * @example intervalDifferenceUnix(0, 2, 0.5, 1) // [] (fractional epoch)
+ * @example intervalDifferenceUnix(5, 10, 0, 5) // [{ start: 5, end: 10 }] (B ends where A starts)
  */
 export function intervalDifferenceUnix(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 = [];
-    // Left piece: A before B starts
-    if (n1 < n3) {
-        const leftEnd = n2 < n3 ? n2 : n3 - 1;
-        if (leftEnd >= n1) {
-            result.push({ start: n1, end: leftEnd });
-        }
-    }
-    // Right piece: A after B ends
-    if (n2 > n4) {
-        result.push({ start: n4 + 1, end: n2 });
-    }
-    return result;
+    // The non-empty parts of A before B starts and after B ends; an empty B removes nothing.
+    return halfOpenDifference(pair[0], [pair[1]], (left, right) => left - right);
 }

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

@@ -1,18 +1,28 @@
 /**
  * Split a Unix epoch interval into `n` equal-length sub-intervals.
  *
- * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
- *   record's `end` equal to the next record's `start`.
- * - Boundaries are computed as plain numeric arithmetic on the epoch values — no timeZone is
- *   involved, so the split is exact whenever the total divides evenly by `n`.
+ * - Returns an array of `n` half-open `[start, end)` records that tile the original 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.
+ * - Each boundary is `start + round((end - start) · i / n)` in integers of the arguments' own epoch
+ *   unit (there is no `epochUnit` option: seconds in give seconds out, milliseconds give
+ *   milliseconds), taken in `bigint` so no product past 2^53 loses a unit: the split is exact
+ *   whenever the total divides evenly by `n`, and within half a unit of the exact cut otherwise (an
+ *   exact half rounds up). No time zone is involved.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
- * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
- * - Returns `[]` when `n` is not a positive integer, or on invalid input (non-finite/non-integer
- *   start/end, `start > end`).
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
+ *   an empty `[start, start)` that holds no instant.
+ * - Returns `[]` when `n` is not a positive integer, or 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 — or `start > end`).
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
+ *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
+ *   before building any piece. 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 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 n number of equal sub-intervals to produce (positive integer)
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyUnix(0, 90000000, 3) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
@@ -20,8 +30,12 @@
  * @example intervalDivideEquallyUnix(0, 90000000, 1) // [{ start: 0, end: 90000000 }]
  * @example intervalDivideEquallyUnix(0, 90000000, 0) // []
  * @example intervalDivideEquallyUnix(NaN, 90000000, 3) // []
+ * @example intervalDivideEquallyUnix(0, 90000000, 3, { maxPieces: 2 }) // [] (3 pieces exceed the limit)
+ * @example intervalDivideEquallyUnix(0, 90000000, 3, { maxPieces: 3 }) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
  */
-export declare function intervalDivideEquallyUnix(start: number | string, end: number | string, n: number): Array<{
+export declare function intervalDivideEquallyUnix(start: number | string, end: number | string, n: number, options?: {
+    maxPieces?: number;
+}): Array<{
     start: number;
     end: number;
 }>;