@northguild/gmt 1.14.2 → 1.16.0

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

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

@@ -3,14 +3,16 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the day of month (1-31) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "day".
+ * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Day (01-31) or "" on invalid input
  *
- * @example parseDayFromUnix(1700000000000) // "15"
- * @example parseDayFromUnix(-86400, { epochUnit: "seconds" }) // "31"
+ * @example parseDayFromUnix(1700000000000, { timeZone: "UTC" }) // "14"
+ * @example parseDayFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "31"
+ * @example parseDayFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseDayFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseDayFromUnix.js

@@ -1,17 +1,30 @@
 import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of month (1-31) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "day".
+ * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Day (01-31) or "" on invalid input
  *
- * @example parseDayFromUnix(1700000000000) // "15"
- * @example parseDayFromUnix(-86400, { epochUnit: "seconds" }) // "31"
+ * @example parseDayFromUnix(1700000000000, { timeZone: "UTC" }) // "14"
+ * @example parseDayFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "31"
+ * @example parseDayFromUnix("") // "" (a blank string is not epoch 0)
  */
 export function parseDayFromUnix(value, options) {
-    return parseUnitFromUnix(value, "day", options);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return parseUnitFromUnix(value, "day", options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

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

@@ -1,16 +1,19 @@
-import { type UnixUnit } from "../validate/index.js";
+import type { UnixUnit } from "../validate/index.js";
 /**
  * Return the day of week (1-7) from a unix epoch value.
  *
  * - Monday=1 through Sunday=7.
  * - Returns null for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Day of week (1-7) or null on invalid input
  *
- * @example parseDayOfWeekFromUnix(1704067200000) // 1
- * @example parseDayOfWeekFromUnix(-86400, { epochUnit: "seconds" }) // 2
+ * @example parseDayOfWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
+ * @example parseDayOfWeekFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // 3
+ * @example parseDayOfWeekFromUnix("1704067200000") // 1 (digit string, UTC by default)
+ * @example parseDayOfWeekFromUnix(" 1704067200000") // null (a padded string is not an epoch)
+ * @example parseDayOfWeekFromUnix("") // null (a blank string is not epoch 0)
  */
 export declare function parseDayOfWeekFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseDayOfWeekFromUnix.js

@@ -1,44 +1,31 @@
-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";
 /**
  * Return the day of week (1-7) from a unix epoch value.
  *
  * - Monday=1 through Sunday=7.
  * - Returns null for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Day of week (1-7) or null on invalid input
  *
- * @example parseDayOfWeekFromUnix(1704067200000) // 1
- * @example parseDayOfWeekFromUnix(-86400, { epochUnit: "seconds" }) // 2
+ * @example parseDayOfWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
+ * @example parseDayOfWeekFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // 3
+ * @example parseDayOfWeekFromUnix("1704067200000") // 1 (digit string, UTC by default)
+ * @example parseDayOfWeekFromUnix(" 1704067200000") // null (a padded string is not an epoch)
+ * @example parseDayOfWeekFromUnix("") // null (a blank string is not epoch 0)
  */
 export function parseDayOfWeekFromUnix(value, options) {
-    const numValue = typeof value === "string" ? Number(value) : value;
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    if (epochUnit === "seconds") {
-        if (!isValidUnixSeconds(numValue))
-            return null;
-    }
-    else {
-        if (!isValidUnixMilliseconds(numValue))
-            return null;
-    }
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    if (!timeZone)
-        return null;
-    const zoned = typeof options?.epochUnit === "undefined"
-        ? convertUnixToZoned(numValue, timeZone)
-        : convertUnixToZoned(numValue, timeZone, options.epochUnit);
-    if (!zoned)
-        return null;
     try {
-        const zdt = Temporal.ZonedDateTime.from(zoned);
-        return zdt.dayOfWeek;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        return unixZonedDateTime(value, options)?.dayOfWeek ?? null;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -3,14 +3,16 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the hour (0-23) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "hour".
+ * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Hour (00-23) or "" on invalid input
  *
- * @example parseHourFromUnix(1700000000000) // "05"
- * @example parseHourFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ * @example parseHourFromUnix(1700000000000, { timeZone: "UTC" }) // "22"
+ * @example parseHourFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00"
+ * @example parseHourFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseHourFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseHourFromUnix.js

@@ -1,17 +1,30 @@
 import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the hour (0-23) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "hour".
+ * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Hour (00-23) or "" on invalid input
  *
- * @example parseHourFromUnix(1700000000000) // "05"
- * @example parseHourFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ * @example parseHourFromUnix(1700000000000, { timeZone: "UTC" }) // "22"
+ * @example parseHourFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00"
+ * @example parseHourFromUnix("") // "" (a blank string is not epoch 0)
  */
 export function parseHourFromUnix(value, options) {
-    return parseUnitFromUnix(value, "hour", options);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return parseUnitFromUnix(value, "hour", options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

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

@@ -3,14 +3,16 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the microsecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "microsecond".
+ * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Microsecond (000-999) or "" on invalid input
  *
  * @example parseMicrosecondFromUnix(1700000000000) // "000"
  * @example parseMicrosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ * @example parseMicrosecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMicrosecondFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseMicrosecondFromUnix.js

@@ -1,17 +1,30 @@
 import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the microsecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "microsecond".
+ * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @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 Microsecond (000-999) or "" on invalid input
  *
  * @example parseMicrosecondFromUnix(1700000000000) // "000"
  * @example parseMicrosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ * @example parseMicrosecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export function parseMicrosecondFromUnix(value, options) {
-    return parseUnitFromUnix(value, "microsecond", options);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return parseUnitFromUnix(value, "microsecond", options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }