@northguild/gmt 1.15.0 → 1.17.0

package/dist/unix/parse/parseTimeFromUnix.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 time portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainTime.
- * - 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 time string (e.g., "14:30:45") or "" on invalid input
  *
- * @example parseTimeFromUnix(1700000000000) // "04:13:20"
- * @example parseTimeFromUnix(1700000000, { epochUnit: "seconds" }) // "04:13:20"
- * @example parseTimeFromUnix(-86400, { epochUnit: "seconds" }) // "00:00:00"
+ * @example parseTimeFromUnix(1700000000000, { timeZone: "UTC" }) // "22:13:20"
+ * @example parseTimeFromUnix(1700000000, { epochUnit: "seconds", timeZone: "UTC" }) // "22:13:20"
+ * @example parseTimeFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
+ * @example parseTimeFromUnix("1700000000", { epochUnit: "second" }) // "22:13:20" (digit string, UTC by default)
+ * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
  */
 export function parseTimeFromUnix(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 = options?.epochUnit
-        ? convertUnixToZoned(value, timeZone, options.epochUnit)
-        : convertUnixToZoned(value, timeZone);
-    if (!zoned)
-        return "";
     try {
-        const zdt = Temporal.ZonedDateTime.from(zoned);
-        return zdt.toPlainTime().toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const zdt = unixZonedDateTime(value, options);
+        return zdt === null ? "" : zdt.toPlainTime().toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,4 +1,5 @@
-import { type UnixUnit } from "../validate/index.js";
+import type { Temporal } from "@js-temporal/polyfill";
+import type { UnixUnit } from "../validate/index.js";
 /**
  * Units extractable from a unix epoch value via `parseUnitFromUnix`. Covers the
  * full set of date/time units plus sub-millisecond precision.
@@ -9,7 +10,7 @@ import { type UnixUnit } from "../validate/index.js";
  * | --- | --- |
  * | `year` | Full year, no padding (e.g. `2024`). |
  * | `month` | Zero-padded 2 (e.g. `03`). |
- * | `week` | Week-of-year, 1–53 (`weekStartsOn`-controlled). |
+ * | `week` | Week-of-year, 1–53: ISO 8601 for `weekStartsOn: "monday"`, UTS #35 (minimal days 1) for `"sunday"`, so late-December days can be week 1. |
  * | `day` | Zero-padded 2. |
  * | `dayOfWeek` | 1 (Mon)–7 (Sun). |
  * | `hour` | Zero-padded 2. |
@@ -17,7 +18,7 @@ import { type UnixUnit } from "../validate/index.js";
  * | `second` | Zero-padded 2. |
  * | `millisecond` | Zero-padded 3. |
  * | `microsecond` | Zero-padded 3. |
- * | `nanosecond` | Zero-padded 9. |
+ * | `nanosecond` | Zero-padded 3 (Temporal's `nanosecond` field is 0–999). |
  *
  * @example
  * import { PlainNowUnit } from "@northguild/gmt/unix";
@@ -27,22 +28,28 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
 /**
  * Extract a unit from a unix epoch value.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; an omitted `timeZone` is UTC and `"local"` is the system zone.
+ * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "", for every unit.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @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), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
- * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds" }) // "12"
- * @example parseUnitFromUnix(1704067200000, "week") // "1"
- * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday" }) // "1"
- * @example parseUnitFromUnix(-86400, { epochUnit: "seconds" }, "year") // "1969"
+ * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
+ * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
+ * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
+ * @example parseUnitFromUnix(-86400, "year", { epochUnit: "seconds", timeZone: "UTC" }) // "1969"
+ * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
+ * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
+ * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
  */
-export declare function parseUnitFromUnix(value: number | string, unit: PlainNowUnit, options?: {
+export declare function parseUnitFromUnix(value: number | string, unit: PlainNowUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     epochUnit?: UnixUnit;
     timeZone?: string;
     weekStartsOn?: "monday" | "sunday";

package/dist/unix/parse/parseUnitFromUnix.js

@@ -1,77 +1,79 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
+import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { convertUnixToZoned } from "../convert/index.js";
-import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract a unit from a unix epoch value.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; an omitted `timeZone` is UTC and `"local"` is the system zone.
+ * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "", for every unit.
  * - Returns "" for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @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), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
- * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds" }) // "12"
- * @example parseUnitFromUnix(1704067200000, "week") // "1"
- * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday" }) // "1"
- * @example parseUnitFromUnix(-86400, { epochUnit: "seconds" }, "year") // "1969"
+ * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
+ * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
+ * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
+ * @example parseUnitFromUnix(-86400, "year", { epochUnit: "seconds", timeZone: "UTC" }) // "1969"
+ * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
+ * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
+ * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
  */
 export function parseUnitFromUnix(value, unit, options) {
-    const numValue = typeof value === "string" ? Number(value) : value;
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    if (epochUnit === "seconds") {
-        if (!isValidUnixSeconds(numValue))
+    try {
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
             return "";
-    }
-    else {
-        if (!isValidUnixMilliseconds(numValue))
+        }
+        const zdt = unixZonedDateTime(value, options);
+        const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
+        if (zdt === null || typeof unit !== "string" || weekStartsOn === null) {
             return "";
-    }
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    if (!timeZone)
-        return "";
-    const zoned = typeof options?.epochUnit === "undefined"
-        ? convertUnixToZoned(numValue, timeZone)
-        : convertUnixToZoned(numValue, timeZone, options.epochUnit);
-    if (!zoned)
-        return "";
-    const weekStartsOn = options?.weekStartsOn ?? "monday";
-    try {
-        const zdt = Temporal.ZonedDateTime.from(zoned);
-        switch (unit) {
-            case "year":
-                return zdt.year.toString();
-            case "month":
-                return zdt.month.toString().padStart(2, "0");
-            case "week": {
-                return (getWeekNumber(`${zdt.year}-${zdt.month.toString().padStart(2, "0")}-${zdt.day.toString().padStart(2, "0")}`, weekStartsOn) ?? 0).toString();
+        }
+        try {
+            switch (resolveDateTimeUnit(unit)) {
+                case "year":
+                    return zdt.year.toString();
+                case "month":
+                    return zdt.month.toString().padStart(2, "0");
+                case "week": {
+                    return (getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
+                }
+                case "day":
+                    return zdt.day.toString().padStart(2, "0");
+                case "dayOfWeek":
+                    return zdt.dayOfWeek.toString();
+                case "hour":
+                    return zdt.hour.toString().padStart(2, "0");
+                case "minute":
+                    return zdt.minute.toString().padStart(2, "0");
+                case "second":
+                    return zdt.second.toString().padStart(2, "0");
+                case "millisecond":
+                    return zdt.millisecond.toString().padStart(3, "0");
+                case "microsecond":
+                    return zdt.microsecond.toString().padStart(3, "0");
+                case "nanosecond":
+                    return zdt.nanosecond.toString().padStart(3, "0");
+                default:
+                    return "";
             }
-            case "day":
-                return zdt.day.toString().padStart(2, "0");
-            case "dayOfWeek":
-                return zdt.dayOfWeek.toString();
-            case "hour":
-                return zdt.hour.toString().padStart(2, "0");
-            case "minute":
-                return zdt.minute.toString().padStart(2, "0");
-            case "second":
-                return zdt.second.toString().padStart(2, "0");
-            case "millisecond":
-                return zdt.millisecond.toString().padStart(3, "0");
-            case "microsecond":
-                return (zdt.microsecond ?? 0).toString().padStart(3, "0");
-            case "nanosecond":
-                return (zdt.nanosecond ?? 0).toString().padStart(9, "0");
-            default:
-                return "";
+        }
+        catch {
+            return "";
         }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,17 +1,25 @@
-import { type UnixUnit } from "../validate/index.js";
+import type { UnixUnit } from "../validate/index.js";
 /**
  * Return the week number from a unix epoch value.
  *
- * - By default uses ISO weeks (Monday-based).
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year. The result is 1–53.
+ * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
+ *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
+ *   next year. The result is 1–53 — see `getWeekNumber`.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - Returns null for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
- * @returns Week number (1-53) or null on invalid input
+ * @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), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @returns Week number (1-53 for "monday" and for "sunday") or null on invalid input
  *
- * @example parseWeekFromUnix(1704067200000) // 1
- * @example parseWeekFromUnix(1704067200000, { weekStartsOn: "sunday" }) // 1
+ * @example parseWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
+ * @example parseWeekFromUnix(1704067200000, { weekStartsOn: "sunday", timeZone: "UTC" }) // 1
  * @example parseWeekFromUnix(-86400, { epochUnit: "seconds" }) // 1
+ * @example parseWeekFromUnix("1704067200000") // 1 (digit string, UTC by default)
+ * @example parseWeekFromUnix("") // null (a blank string is not epoch 0)
+ * @example parseWeekFromUnix(1735646400000, { weekStartsOn: "sunday", timeZone: "UTC" }) // 1 (2024-12-31T12:00:00Z; its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseWeekFromUnix.js

@@ -1,47 +1,49 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { convertUnixToZoned } from "../convert/index.js";
-import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
+import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number from a unix epoch value.
  *
- * - By default uses ISO weeks (Monday-based).
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year. The result is 1–53.
+ * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
+ *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
+ *   next year. The result is 1–53 — see `getWeekNumber`.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - Returns null for invalid input.
  *
- * @param value unix epoch in milliseconds or seconds (number or string)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
- * @returns Week number (1-53) or null on invalid input
+ * @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), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @returns Week number (1-53 for "monday" and for "sunday") or null on invalid input
  *
- * @example parseWeekFromUnix(1704067200000) // 1
- * @example parseWeekFromUnix(1704067200000, { weekStartsOn: "sunday" }) // 1
+ * @example parseWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
+ * @example parseWeekFromUnix(1704067200000, { weekStartsOn: "sunday", timeZone: "UTC" }) // 1
  * @example parseWeekFromUnix(-86400, { epochUnit: "seconds" }) // 1
+ * @example parseWeekFromUnix("1704067200000") // 1 (digit string, UTC by default)
+ * @example parseWeekFromUnix("") // null (a blank string is not epoch 0)
+ * @example parseWeekFromUnix(1735646400000, { weekStartsOn: "sunday", timeZone: "UTC" }) // 1 (2024-12-31T12:00:00Z; its Sunday-first week holds 1 January 2025)
  */
 export function parseWeekFromUnix(value, options) {
-    const numValue = typeof value === "string" ? Number(value) : value;
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    if (epochUnit === "seconds") {
-        if (!isValidUnixSeconds(numValue))
+    try {
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
             return null;
-    }
-    else {
-        if (!isValidUnixMilliseconds(numValue))
+        }
+        const zdt = unixZonedDateTime(value, options);
+        const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
+        if (zdt === null || weekStartsOn === null)
             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;
-    const weekStartsOn = options?.weekStartsOn ?? "monday";
-    try {
-        const zdt = Temporal.ZonedDateTime.from(zoned);
-        return getWeekNumber(`${zdt.year}-${zdt.month.toString().padStart(2, "0")}-${zdt.day.toString().padStart(2, "0")}`, weekStartsOn);
+        try {
+            return getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -3,15 +3,17 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the year from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
+ * - `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 Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
- * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds" }) // "2024"
+ * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
+ * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseYearFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseYearFromUnix.js

@@ -1,18 +1,31 @@
 import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the year from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
+ * - `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 Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
- * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds" }) // "2024"
+ * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
+ * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)
  */
 export function parseYearFromUnix(value, options) {
-    return parseUnitFromUnix(value, "year", options);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return parseUnitFromUnix(value, "year", options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

package/dist/unix/validate/isValidUnixMilliseconds.d.ts

@@ -1,14 +1,17 @@
 /**
- * Return true when `timestamp` is a valid Unix milliseconds value.
+ * Return true when `timestamp` is a Unix milliseconds value every `unix/` function accepts.
  *
- * - Must be an integer (positive or negative, for dates before/after 1970).
- * - Returns false for non-numbers or non-integers.
+ * - A number must be a safe integer; a string must be an optionally negative run of ASCII digits
+ *   (`"1700000000000"`), with no whitespace, `+`, decimal point, exponent or hex.
+ * - The instant must lie in the Temporal range: ±8.64e15 milliseconds (10^8 days) from the epoch.
  *
- * @param timestamp number candidate
+ * @param timestamp candidate value of any type
  * @returns boolean indicating whether the timestamp is a valid Unix milliseconds value
  *
  * @example isValidUnixMilliseconds(1700000000000) // true
- * @example isValidUnixMilliseconds(-86400000) // true (1969-12-31)
+ * @example isValidUnixMilliseconds("-86400000") // true (1969-12-31)
  * @example isValidUnixMilliseconds(1.5) // false
+ * @example isValidUnixMilliseconds("1700000000000.0") // false (not a digit string)
+ * @example isValidUnixMilliseconds(8640000000000001) // false (past the last Temporal instant)
  */
 export declare function isValidUnixMilliseconds(timestamp: unknown): boolean;

package/dist/unix/validate/isValidUnixMilliseconds.js

@@ -1,19 +1,20 @@
+import { unixEpochToInstant } from "../../internal/unixEpochValue.js";
 /**
- * Return true when `timestamp` is a valid Unix milliseconds value.
+ * Return true when `timestamp` is a Unix milliseconds value every `unix/` function accepts.
  *
- * - Must be an integer (positive or negative, for dates before/after 1970).
- * - Returns false for non-numbers or non-integers.
+ * - A number must be a safe integer; a string must be an optionally negative run of ASCII digits
+ *   (`"1700000000000"`), with no whitespace, `+`, decimal point, exponent or hex.
+ * - The instant must lie in the Temporal range: ±8.64e15 milliseconds (10^8 days) from the epoch.
  *
- * @param timestamp number candidate
+ * @param timestamp candidate value of any type
  * @returns boolean indicating whether the timestamp is a valid Unix milliseconds value
  *
  * @example isValidUnixMilliseconds(1700000000000) // true
- * @example isValidUnixMilliseconds(-86400000) // true (1969-12-31)
+ * @example isValidUnixMilliseconds("-86400000") // true (1969-12-31)
  * @example isValidUnixMilliseconds(1.5) // false
+ * @example isValidUnixMilliseconds("1700000000000.0") // false (not a digit string)
+ * @example isValidUnixMilliseconds(8640000000000001) // false (past the last Temporal instant)
  */
 export function isValidUnixMilliseconds(timestamp) {
-    if (typeof timestamp === "number") {
-        return Number.isInteger(timestamp);
-    }
-    return false;
+    return unixEpochToInstant(timestamp, "milliseconds") !== null;
 }

package/dist/unix/validate/isValidUnixRange.d.ts

@@ -1,10 +1,13 @@
 /**
- * Return true if `value1` and `value2` form a valid Unix range — both finite numbers
- * and `value1 <= value2`.
+ * Return true if `value1` and `value2` form a valid Unix range — both safe-integer epochs
+ * and `value1 < value2` (or `<=` with `allowEqual`).
  *
- * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
- * - Non-finite values (NaN, Infinity) return `false`.
+ * - 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 `value1 === value2` is valid only when `options.allowEqual` is true.
  *
  * @param value1 first Unix epoch value (seconds or milliseconds)
  * @param value2 second Unix epoch value (seconds or milliseconds)
@@ -12,10 +15,13 @@
  * @returns boolean indicating whether the Unix range is valid
  *
  * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true
- * @example isValidUnixRange({ value1: 1700000000, value2: 0 }) // false
  * @example isValidUnixRange({ value1: 1000, value2: 1000, options: { allowEqual: true } }) // true
+ * @example isValidUnixRange({ value1: 1700000000, value2: 0 }) // false (reversed)
+ * @example isValidUnixRange({ value1: 0, value2: 1.5 }) // false (fractional)
+ * @example isValidUnixRange({ value1: "", value2: 1000 }) // false (empty string is not epoch 0)
+ * @example isValidUnixRange({ value1: "0", value2: "1e3" }) // false (exponent notation is not an epoch)
  */
-export declare function isValidUnixRange({ value1, value2, options, }: {
+export declare function isValidUnixRange(props: {
     value1: number | string;
     value2: number | string;
     options?: {

package/dist/unix/validate/isValidUnixRange.js

@@ -1,10 +1,14 @@
+import { isObject, isOptionsArgument, parseUnixEpochValue, } from "../../internal/index.js";
 /**
- * Return true if `value1` and `value2` form a valid Unix range — both finite numbers
- * and `value1 <= value2`.
+ * Return true if `value1` and `value2` form a valid Unix range — both safe-integer epochs
+ * and `value1 < value2` (or `<=` with `allowEqual`).
  *
- * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
- * - Non-finite values (NaN, Infinity) return `false`.
+ * - 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 `value1 === value2` is valid only when `options.allowEqual` is true.
  *
  * @param value1 first Unix epoch value (seconds or milliseconds)
  * @param value2 second Unix epoch value (seconds or milliseconds)
@@ -12,23 +16,29 @@
  * @returns boolean indicating whether the Unix range is valid
  *
  * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true
- * @example isValidUnixRange({ value1: 1700000000, value2: 0 }) // false
  * @example isValidUnixRange({ value1: 1000, value2: 1000, options: { allowEqual: true } }) // true
+ * @example isValidUnixRange({ value1: 1700000000, value2: 0 }) // false (reversed)
+ * @example isValidUnixRange({ value1: 0, value2: 1.5 }) // false (fractional)
+ * @example isValidUnixRange({ value1: "", value2: 1000 }) // false (empty string is not epoch 0)
+ * @example isValidUnixRange({ value1: "0", value2: "1e3" }) // false (exponent notation is not an epoch)
  */
-export function isValidUnixRange({ value1, value2, options, }) {
-    if (typeof value1 !== "number" && typeof value1 !== "string") {
-        return false;
-    }
-    if (typeof value2 !== "number" && typeof value2 !== "string") {
-        return false;
+export function isValidUnixRange(props) {
+    try {
+        if (!isObject(props))
+            return false;
+        const { value1, value2, options } = props;
+        if (!isOptionsArgument(options))
+            return false;
+        const first = parseUnixEpochValue(value1);
+        const second = parseUnixEpochValue(value2);
+        if (first === null || second === null) {
+            return false;
+        }
+        return options?.allowEqual ? first <= second : first < second;
     }
-    const n1 = typeof value1 === "number" ? value1 : Number(value1);
-    const n2 = typeof value2 === "number" ? value2 : Number(value2);
-    if (!Number.isFinite(n1) || !Number.isFinite(n2)) {
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
-    if (options?.allowEqual) {
-        return n1 <= n2;
-    }
-    return n1 < n2;
 }

package/dist/unix/validate/isValidUnixSeconds.d.ts

@@ -1,14 +1,17 @@
 /**
- * Return true when `timestamp` is a valid Unix seconds value.
+ * Return true when `timestamp` is a Unix seconds value every `unix/` function accepts.
  *
- * - Must be an integer (positive or negative, for dates before/after 1970).
- * - Returns false for non-numbers or non-integers.
+ * - A number must be a safe integer; a string must be an optionally negative run of ASCII digits
+ *   (`"1700000000"`, `"-86400"`), with no whitespace, `+`, decimal point, exponent or hex.
+ * - The instant must lie in the Temporal range: ±8.64e12 seconds (10^8 days) from the epoch.
  *
- * @param timestamp number candidate
+ * @param timestamp candidate value of any type
  * @returns boolean indicating whether the timestamp is a valid Unix seconds value
  *
  * @example isValidUnixSeconds(1700000000) // true
- * @example isValidUnixSeconds(-86400) // true (1969-12-31)
+ * @example isValidUnixSeconds("-86400") // true (1969-12-31)
  * @example isValidUnixSeconds(1.5) // false
+ * @example isValidUnixSeconds("1e9") // false (not a digit string)
+ * @example isValidUnixSeconds(8640000000001) // false (past the last Temporal instant)
  */
 export declare function isValidUnixSeconds(timestamp: unknown): boolean;