@northguild/gmt 1.15.0 → 1.16.0

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;
 }>;

package/dist/unix/interval/splitIntervalByUnitUnix.js

@@ -1,22 +1,46 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
-import { resolveDurationUnit } from "../../internal/index.js";
+import { resolveDurationUnit, tileByUnit } from "../../internal/index.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
+import { resolveUnixIntervalPair } from "../../internal/resolveUnixIntervalPair.js";
+import { minSlicesForSpan } from "../../internal/splitStep.js";
+import { toUnixEpoch } from "../../internal/unixEpochValue.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 }]
@@ -24,62 +48,54 @@ import { resolveDurationUnit } from "../../internal/index.js";
  * @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 function splitIntervalByUnitUnix(start, end, unit, amount) {
-    if (typeof start !== "number" && typeof start !== "string") {
-        return [];
-    }
-    if (typeof end !== "number" && typeof end !== "string") {
-        return [];
-    }
-    const startMs = typeof start === "number" ? start : Number(start);
-    const endMs = typeof end === "number" ? end : Number(end);
-    if (!Number.isFinite(startMs) || !Number.isInteger(startMs)) {
-        return [];
-    }
-    if (!Number.isFinite(endMs) || !Number.isInteger(endMs)) {
-        return [];
-    }
-    if (startMs > endMs) {
-        return [];
-    }
-    if (typeof unit !== "string") {
-        return [];
-    }
-    const resolvedUnit = resolveDurationUnit(unit);
-    if (!resolvedUnit) {
-        return [];
-    }
-    if (!Number.isFinite(amount) || amount <= 0) {
-        return [];
-    }
+export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
     try {
-        const timeZone = getSystemTimeZone();
-        if (!timeZone || !isValidTimeZone(timeZone)) {
+        const pair = resolveUnixIntervalPair(start, end, unit, options);
+        if (pair === null) {
             return [];
         }
-        if (startMs === endMs) {
-            return [{ start: startMs, end: endMs }];
+        if (!Number.isFinite(amount) || amount <= 0) {
+            return [];
         }
-        const result = [];
-        for (let currentMs = startMs; currentMs < endMs;) {
-            const instant = Temporal.Instant.fromEpochMilliseconds(currentMs);
-            const zoned = instant.toZonedDateTimeISO(timeZone);
-            const next = zoned.add({ [resolvedUnit]: amount }).toInstant();
-            const nextMs = next.epochMilliseconds;
-            if (nextMs === currentMs) {
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null) {
+            return [];
+        }
+        const { startVal, endVal, epochUnit } = pair;
+        // Temporal's plural duration field name, as the tiling steps add `{ [unit]: amount }`.
+        const resolvedUnit = resolveDurationUnit(pair.resolvedUnit);
+        if (startVal.epochNanoseconds === endVal.epochNanoseconds) {
+            return [
+                {
+                    start: toUnixEpoch(startVal, epochUnit),
+                    end: toUnixEpoch(endVal, epochUnit),
+                },
+            ];
+        }
+        try {
+            const spanNs = Number(endVal.epochNanoseconds - startVal.epochNanoseconds);
+            if (exceedsPieceLimit(minSlicesForSpan(spanNs, resolvedUnit, amount, true), maxPieces)) {
                 return [];
             }
-            const sliceEndMs = nextMs > endMs ? endMs : nextMs;
-            result.push({
-                start: currentMs,
-                end: sliceEndMs,
-            });
-            currentMs = nextMs;
+            // Boundaries stay ZonedDateTime (nanosecond) values; only the output is floored to epochUnit.
+            const slices = tileByUnit(startVal, endVal, Temporal.ZonedDateTime.compare, resolvedUnit, amount, maxPieces);
+            return (slices ?? []).map(([sliceStart, sliceEnd]) => ({
+                start: toUnixEpoch(sliceStart, epochUnit),
+                end: toUnixEpoch(sliceEnd, epochUnit),
+            }));
+        }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/unix/interval/validate/isValidUnixInterval.d.ts

@@ -1,18 +1,24 @@
 /**
- * Return true if `start` and `end` form a valid Unix interval — both finite numbers
+ * Return true if `start` and `end` form a valid Unix interval — both safe-integer epochs
  * and `start <= end`.
  *
- * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
+ * - Each input must be a safe integer (`Number.isSafeInteger`) or a string of optionally negative
+ *   ASCII digits naming one — the epoch grammar every `unix/` function shares.
+ * - Fractional values, `NaN`, `±Infinity` and anything beyond ±(2^53 − 1) return `false`.
+ * - Strings with whitespace, `+`, a decimal point, an exponent or hex digits return `false`, and an
+ *   empty string is not epoch 0.
  * - Equal `start === end` is valid.
- * - Non-finite values (NaN, Infinity) return `false`.
  *
- * @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
  * @returns true if start and end form a valid Unix interval, or false on invalid input
  *
  * @example isValidUnixInterval(0, 1700000000) // true
  * @example isValidUnixInterval(1000, 1000) // true
- * @example isValidUnixInterval(1700000000, 0) // false
  * @example isValidUnixInterval("0", "1700000000") // true
+ * @example isValidUnixInterval(1700000000, 0) // false (reversed)
+ * @example isValidUnixInterval(0, 1.5) // false (fractional)
+ * @example isValidUnixInterval("", 1000) // false (empty string is not epoch 0)
+ * @example isValidUnixInterval("0", " 1000") // false (a padded string is not an epoch)
  */
 export declare function isValidUnixInterval(start: number | string, end: number | string): boolean;

package/dist/unix/interval/validate/isValidUnixInterval.js

@@ -1,31 +1,32 @@
+import { parseUnixEpochValue } from "../../../internal/index.js";
 /**
- * Return true if `start` and `end` form a valid Unix interval — both finite numbers
+ * Return true if `start` and `end` form a valid Unix interval — both safe-integer epochs
  * and `start <= end`.
  *
- * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
+ * - Each input must be a safe integer (`Number.isSafeInteger`) or a string of optionally negative
+ *   ASCII digits naming one — the epoch grammar every `unix/` function shares.
+ * - Fractional values, `NaN`, `±Infinity` and anything beyond ±(2^53 − 1) return `false`.
+ * - Strings with whitespace, `+`, a decimal point, an exponent or hex digits return `false`, and an
+ *   empty string is not epoch 0.
  * - Equal `start === end` is valid.
- * - Non-finite values (NaN, Infinity) return `false`.
  *
- * @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
  * @returns true if start and end form a valid Unix interval, or false on invalid input
  *
  * @example isValidUnixInterval(0, 1700000000) // true
  * @example isValidUnixInterval(1000, 1000) // true
- * @example isValidUnixInterval(1700000000, 0) // false
  * @example isValidUnixInterval("0", "1700000000") // true
+ * @example isValidUnixInterval(1700000000, 0) // false (reversed)
+ * @example isValidUnixInterval(0, 1.5) // false (fractional)
+ * @example isValidUnixInterval("", 1000) // false (empty string is not epoch 0)
+ * @example isValidUnixInterval("0", " 1000") // false (a padded string is not an epoch)
  */
 export function isValidUnixInterval(start, end) {
-    if (typeof start !== "number" && typeof start !== "string") {
+    const startValue = parseUnixEpochValue(start);
+    const endValue = parseUnixEpochValue(end);
+    if (startValue === null || endValue === null) {
         return false;
     }
-    if (typeof end !== "number" && typeof end !== "string") {
-        return false;
-    }
-    const n1 = typeof start === "number" ? start : Number(start);
-    const n2 = typeof end === "number" ? end : Number(end);
-    if (!Number.isFinite(n1) || !Number.isFinite(n2)) {
-        return false;
-    }
-    return n1 <= n2;
+    return startValue <= endValue;
 }

package/dist/unix/parse/index.d.ts

@@ -3,6 +3,8 @@ export * from "./parseDayFromUnix.js";
 export * from "./parseDayOfWeekFromUnix.js";
 export * from "./parseHourFromUnix.js";
 export * from "./parseMicrosecondFromUnix.js";
+export * from "./parseMillisecondFromUnix.js";
+export * from "./parseMinuteFromUnix.js";
 export * from "./parseMonthFromUnix.js";
 export * from "./parseNanosecondFromUnix.js";
 export * from "./parseSecondFromUnix.js";

package/dist/unix/parse/index.js

@@ -3,6 +3,8 @@ export * from "./parseDayFromUnix.js";
 export * from "./parseDayOfWeekFromUnix.js";
 export * from "./parseHourFromUnix.js";
 export * from "./parseMicrosecondFromUnix.js";
+export * from "./parseMillisecondFromUnix.js";
+export * from "./parseMinuteFromUnix.js";
 export * from "./parseMonthFromUnix.js";
 export * from "./parseNanosecondFromUnix.js";
 export * from "./parseSecondFromUnix.js";

package/dist/unix/parse/parseDateFromUnix.d.ts

@@ -1,20 +1,22 @@
-import { type UnixUnit } from "../validate/index.js";
+import type { UnixUnit } from "../validate/index.js";
 /**
  * Extract the date portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainDate.
- * - Uses system timezone if not specified.
+ * - Uses UTC if `timeZone` is not specified; `"local"` is the system time zone.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
- * @example parseDateFromUnix(1700000000000) // "2023-11-15"
- * @example parseDateFromUnix(1700000000, { epochUnit: "seconds" }) // "2023-11-15"
- * @example parseDateFromUnix(-86400, { epochUnit: "seconds" }) // "1969-12-31"
+ * @example parseDateFromUnix(1700000000000, { timeZone: "UTC" }) // "2023-11-14"
+ * @example parseDateFromUnix(1700000000, { epochUnit: "seconds", timeZone: "UTC" }) // "2023-11-14"
+ * @example parseDateFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "1969-12-31"
+ * @example parseDateFromUnix("1700000000000", { timeZone: "Asia/Tokyo" }) // "2023-11-15" (digit string)
+ * @example parseDateFromUnix(1.5) // "" (not an integer epoch)
  */
-export declare function parseDateFromUnix(value: number, options?: {
+export declare function parseDateFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseDateFromUnix.js

@@ -1,45 +1,33 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { convertUnixToZoned } from "../convert/index.js";
-import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the date portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainDate.
- * - Uses system timezone if not specified.
+ * - Uses UTC if `timeZone` is not specified; `"local"` is the system time zone.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
- * @example parseDateFromUnix(1700000000000) // "2023-11-15"
- * @example parseDateFromUnix(1700000000, { epochUnit: "seconds" }) // "2023-11-15"
- * @example parseDateFromUnix(-86400, { epochUnit: "seconds" }) // "1969-12-31"
+ * @example parseDateFromUnix(1700000000000, { timeZone: "UTC" }) // "2023-11-14"
+ * @example parseDateFromUnix(1700000000, { epochUnit: "seconds", timeZone: "UTC" }) // "2023-11-14"
+ * @example parseDateFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "1969-12-31"
+ * @example parseDateFromUnix("1700000000000", { timeZone: "Asia/Tokyo" }) // "2023-11-15" (digit string)
+ * @example parseDateFromUnix(1.5) // "" (not an integer epoch)
  */
 export function parseDateFromUnix(value, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    if (epochUnit === "seconds") {
-        if (!isValidUnixSeconds(value))
-            return "";
-    }
-    else {
-        if (!isValidUnixMilliseconds(value))
-            return "";
-    }
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    if (!timeZone)
-        return "";
-    const zoned = epochUnit
-        ? convertUnixToZoned(value, timeZone, epochUnit)
-        : convertUnixToZoned(value, timeZone);
-    if (!zoned)
-        return "";
     try {
-        const zdt = Temporal.ZonedDateTime.from(zoned);
-        return zdt.toPlainDate().toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const zdt = unixZonedDateTime(value, options);
+        return zdt === null ? "" : zdt.toPlainDate().toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }