@northguild/gmt 1.14.2 → 1.16.0

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;

package/dist/unix/validate/isValidUnixSeconds.js

@@ -1,19 +1,20 @@
+import { unixEpochToInstant } from "../../internal/unixEpochValue.js";
 /**
- * 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 function isValidUnixSeconds(timestamp) {
-    if (typeof timestamp === "number") {
-        return Number.isInteger(timestamp);
-    }
-    return false;
+    return unixEpochToInstant(timestamp, "seconds") !== null;
 }

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

@@ -1,16 +1,33 @@
-export type UnixUnit = "seconds" | "milliseconds";
+/**
+ * Unit accepted by `epochUnit` in unix-epoch functions. Determines whether a
+ * numeric value is interpreted as milliseconds or seconds.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `seconds` / `second` | Value is Unix epoch seconds (e.g. `1700000000`). |
+ * | `milliseconds` / `millisecond` | Value is Unix epoch milliseconds (e.g. `1700000000000`). |
+ *
+ * Singular and plural names are the same unit, as in Temporal's unit-valued options.
+ *
+ * @example
+ * import { isValidUnixUnit } from "@northguild/gmt/unix";
+ * isValidUnixUnit("milliseconds"); // true
+ */
+export type UnixUnit = "seconds" | "second" | "milliseconds" | "millisecond";
 /**
  * Return true when `unit` is a valid UnixUnit.
  *
- * - Valid units are: "seconds", "milliseconds".
- * - Accepts any input type and returns false for non-string values.
- * - Uses type assertion to narrow the type.
+ * - Valid units are `"seconds"`, `"milliseconds"` and their singular forms `"second"`,
+ *   `"millisecond"` (Temporal §13.17 GetTemporalUnitValuedOption accepts both).
+ * - Names are case-sensitive; any non-string input returns false.
  *
  * @param unit candidate value of any type
  * @returns boolean indicating whether the unit is a valid UnixUnit
  *
  * @example isValidUnixUnit("seconds") // true
- * @example isValidUnixUnit("milliseconds") // true
+ * @example isValidUnixUnit("millisecond") // true
  * @example isValidUnixUnit("invalid") // false
  * @example isValidUnixUnit(123) // false
  * @example isValidUnixUnit(null) // false

package/dist/unix/validate/isValidUnixUnit.js

@@ -1,22 +1,20 @@
+import { resolveUnixEpochUnit } from "../../internal/unixEpochValue.js";
 /**
  * Return true when `unit` is a valid UnixUnit.
  *
- * - Valid units are: "seconds", "milliseconds".
- * - Accepts any input type and returns false for non-string values.
- * - Uses type assertion to narrow the type.
+ * - Valid units are `"seconds"`, `"milliseconds"` and their singular forms `"second"`,
+ *   `"millisecond"` (Temporal §13.17 GetTemporalUnitValuedOption accepts both).
+ * - Names are case-sensitive; any non-string input returns false.
  *
  * @param unit candidate value of any type
  * @returns boolean indicating whether the unit is a valid UnixUnit
  *
  * @example isValidUnixUnit("seconds") // true
- * @example isValidUnixUnit("milliseconds") // true
+ * @example isValidUnixUnit("millisecond") // true
  * @example isValidUnixUnit("invalid") // false
  * @example isValidUnixUnit(123) // false
  * @example isValidUnixUnit(null) // false
  */
 export function isValidUnixUnit(unit) {
-    if (typeof unit !== "string") {
-        return false;
-    }
-    return unit === "seconds" || unit === "milliseconds";
+    return unit !== undefined && resolveUnixEpochUnit(unit) !== null;
 }

package/dist/utc/calculate/addUtc.js

@@ -1,7 +1,9 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidAmount, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Add a temporal amount to a UTC datetime string and return a new UTC Instant string.
  *
@@ -22,21 +24,33 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example addUtc("invalid", { days: 5 }) // ""
  */
 export function addUtc(value, units, options) {
-    const validUtc = isValidUtc(value);
-    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validUtc || !validUnits || !validAmounts) {
-        return "";
-    }
     try {
-        const instant = Temporal.Instant.from(value);
-        const zoned = instant.toZonedDateTimeISO("UTC");
-        const result = zoned.add(units, {
-            overflow: resolveOverflow(options?.overflow),
-        });
-        return result.toInstant().toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const validUtc = isValidUtc(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateTimeDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validUtc || !validUnits || !validAmounts) {
+            return "";
+        }
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zoned = instant.toZonedDateTimeISO("UTC");
+            const result = zoned.add(units, {
+                overflow: resolveOverflow(options?.overflow),
+            });
+            return result.toInstant().toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/calculate/diffUtc.d.ts

@@ -3,7 +3,10 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
 /**
  * Return the difference between two UTC datetimes measured in the given date-time unit.
  *
- * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Converts both values to a `Temporal.ZonedDateTime` in UTC and uses its `until()`, so calendar
+ *   units (days, weeks, months, years) are measured on the UTC wall clock — which has no DST, so
+ *   every day is 24 hours — while time units are exact elapsed time.
+ *   `Temporal.Instant.until()` is not used: it rejects every calendar `largestUnit`.
  * - Supports single unit or array of units.
  * - Returns null for invalid input.
  *
@@ -11,17 +14,29 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest hour before extracting the requested unit.
  * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   array (e.g. `["days", "hours"]` with `smallestUnit: "week"`) — this combination is rejected by
  *   Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["years", "days"]` over
+ *   1 year 59 days returns `{ years: 1, days: 59 }`.
+ * - Nanosecond precision: the result is a JavaScript `number`, so it stops being exact once it
+ *   passes `Number.MAX_SAFE_INTEGER` — about 104 days in nanoseconds and about 285 years in
+ *   microseconds. `diffUtc("2024-01-01T00:00:00Z", "2024-04-15T00:00:00.000000001Z", "nanoseconds")`
+ *   returns `9072000000000000` rather than `9072000000000001`. For an exact count use the `bigint` APIs: `spanNs`
+ *   in `span/`, or `toNanoseconds` in `precision/`.
  *
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
- * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hour") // 24
- * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["year", "month"]) // { year: 1, month: 1 }
- * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hour") // null
+ * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // 24
+ * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["years", "months"]) // { years: 1, months: 1 }
+ * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hours") // null
+ * @example diffUtc("2024-01-01T00:00:00Z", "2025-03-01T00:00:00Z", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
-export declare function diffUtc(value1: string, value2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;
+export declare function diffUtc(value1: string, value2: string, units: DateTimeDurationUnit | Temporal.DateTimeUnit | Array<DateTimeDurationUnit | Temporal.DateTimeUnit>, options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;