@northguild/gmt 1.14.2 → 1.16.0

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;

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,24 +1,55 @@
-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.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `year` | Full year, no padding (e.g. `2024`). |
+ * | `month` | Zero-padded 2 (e.g. `03`). |
+ * | `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. |
+ * | `minute` | Zero-padded 2. |
+ * | `second` | Zero-padded 2. |
+ * | `millisecond` | Zero-padded 3. |
+ * | `microsecond` | Zero-padded 3. |
+ * | `nanosecond` | Zero-padded 3 (Temporal's `nanosecond` field is 0–999). |
+ *
+ * @example
+ * import { PlainNowUnit } from "@northguild/gmt/unix";
+ * const u: PlainNowUnit = "month";
+ */
 export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";
 /**
  * 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 "";
     }
 }