@northguild/gmt 1.15.0 → 1.17.0

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

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

@@ -3,14 +3,16 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the millisecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "millisecond".
+ * - `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 Millisecond (000-999) or "" on invalid input
  *
  * @example parseMillisecondFromUnix(1700000000000) // "000"
  * @example parseMillisecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ * @example parseMillisecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMillisecondFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseMillisecondFromUnix.js

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

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

@@ -3,14 +3,16 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the minute (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "minute".
+ * - `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 Minute (00-59) or "" on invalid input
  *
- * @example parseMinuteFromUnix(1700000000000) // "26"
- * @example parseMinuteFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ * @example parseMinuteFromUnix(1700000000000, { timeZone: "UTC" }) // "13"
+ * @example parseMinuteFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00"
+ * @example parseMinuteFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMinuteFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseMinuteFromUnix.js

@@ -1,17 +1,30 @@
 import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the minute (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "minute".
+ * - `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 Minute (00-59) or "" on invalid input
  *
- * @example parseMinuteFromUnix(1700000000000) // "26"
- * @example parseMinuteFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ * @example parseMinuteFromUnix(1700000000000, { timeZone: "UTC" }) // "13"
+ * @example parseMinuteFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00"
+ * @example parseMinuteFromUnix("") // "" (a blank string is not epoch 0)
  */
 export function parseMinuteFromUnix(value, options) {
-    return parseUnitFromUnix(value, "minute", options);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return parseUnitFromUnix(value, "minute", options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

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

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

package/dist/unix/parse/parseMonthFromUnix.js

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

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

@@ -3,14 +3,17 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the nanosecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
+ * - `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)
- * @returns Nanosecond (000-999) or "" 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)
+ * @returns Nanosecond field (0-999), zero-padded to 3 digits ("000") as Temporal's `nanosecond` field, or "" on invalid input
  *
- * @example parseNanosecondFromUnix(1700000000000) // "000000000"
- * @example parseNanosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000000000"
+ * @example parseNanosecondFromUnix(1700000000000) // "000"
+ * @example parseNanosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ * @example parseNanosecondFromUnix("1700000000000") // "000" (digit string)
+ * @example parseNanosecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseNanosecondFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseNanosecondFromUnix.js

@@ -1,17 +1,31 @@
 import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the nanosecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
+ * - `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)
- * @returns Nanosecond (000-999) or "" 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)
+ * @returns Nanosecond field (0-999), zero-padded to 3 digits ("000") as Temporal's `nanosecond` field, or "" on invalid input
  *
- * @example parseNanosecondFromUnix(1700000000000) // "000000000"
- * @example parseNanosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000000000"
+ * @example parseNanosecondFromUnix(1700000000000) // "000"
+ * @example parseNanosecondFromUnix(-86400, { epochUnit: "seconds" }) // "000"
+ * @example parseNanosecondFromUnix("1700000000000") // "000" (digit string)
+ * @example parseNanosecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export function parseNanosecondFromUnix(value, options) {
-    return parseUnitFromUnix(value, "nanosecond", options);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return parseUnitFromUnix(value, "nanosecond", options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

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

@@ -3,14 +3,16 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the second (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "second".
+ * - `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 Second (00-59) or "" on invalid input
  *
- * @example parseSecondFromUnix(1700000000000) // "26"
+ * @example parseSecondFromUnix(1700000000000, { timeZone: "UTC" }) // "20"
  * @example parseSecondFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ * @example parseSecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseSecondFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;

package/dist/unix/parse/parseSecondFromUnix.js

@@ -1,17 +1,30 @@
 import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the second (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "second".
+ * - `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 Second (00-59) or "" on invalid input
  *
- * @example parseSecondFromUnix(1700000000000) // "26"
+ * @example parseSecondFromUnix(1700000000000, { timeZone: "UTC" }) // "20"
  * @example parseSecondFromUnix(-86400, { epochUnit: "seconds" }) // "00"
+ * @example parseSecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export function parseSecondFromUnix(value, options) {
-    return parseUnitFromUnix(value, "second", options);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return parseUnitFromUnix(value, "second", options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

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

@@ -1,20 +1,22 @@
-import { type UnixUnit } from "../validate/index.js";
+import type { UnixUnit } from "../validate/index.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 declare function parseTimeFromUnix(value: number, options?: {
+export declare function parseTimeFromUnix(value: number | string, options?: {
     epochUnit?: UnixUnit;
     timeZone?: string;
 }): string;