@northguild/gmt 1.14.2 → 1.16.0

package/dist/unix/calculate/endOfQuarterForUnix.js

@@ -1,56 +1,37 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUnixUnit } from "../../unix/validate/isValidUnixUnit.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { startOrEndOfUnix } from "../../internal/startOrEndOfUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the end of the quarter for a Unix timestamp.
  *
  * - Converts to ZonedDateTime, calculates quarter end, converts back to epoch.
  * - Q1 ends month 3, Q2 ends month 6, Q3 ends month 9, Q4 ends month 12.
- * - `disambiguation` controls DST gap/overlap resolution when a quarter boundary lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in null).
- * - `offset` controls whether the source's existing UTC offset is kept when computing a new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** in the (rare) common-zone case since quarter boundaries don't fall on DST transitions), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Returns the last millisecond before the next local quarter starts in `timeZone` (see `floorToZone`), so the result is never before `value`: a quarter whose last local hour repeats (`Africa/Cairo`, 2010-09-30) ends with the second pass.
+ * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
+ *   takes neither. Those ignored options were removed in 1.16.0.
  * - Returns null for invalid input.
+ * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
+ *   null.
  *
- * @param value Unix timestamp (number)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param value Unix epoch: 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")
  * @returns Unix epoch number representing the end of the quarter, or null on invalid input
  *
- * @example endOfQuarterForUnix(1706659200000) // 1711977599999
- * @example endOfQuarterForUnix(-86400000) // -1 (Q4 1969 ends Dec 31)
+ * @example endOfQuarterForUnix(1706659200000, { timeZone: "UTC" }) // 1711929599999
+ * @example endOfQuarterForUnix(-86400000, { timeZone: "UTC" }) // -1 (Q4 1969 ends Dec 31)
+ * @example endOfQuarterForUnix(1285882200000, { timeZone: "Africa/Cairo" }) // 1285883999999 (the second pass of Q3 2010's repeated last hour; the quarter ends after it)
+ * @example endOfQuarterForUnix(NaN) // null
  */
 export function endOfQuarterForUnix(value, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    const disambiguation = options?.disambiguation ?? "compatible";
-    const offset = options?.offset ?? "ignore";
-    if (!timeZone || !isValidTimeZone(timeZone) || !isValidUnixUnit(epochUnit)) {
-        return null;
-    }
-    if (!Number.isFinite(value) || !Number.isInteger(value)) {
-        return null;
-    }
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value * 1000 : value);
-        const zdt = instant.toZonedDateTimeISO(timeZone);
-        const month = zdt.month;
-        const quarterEndMonth = Math.floor((month - 1) / 3) * 3 + 3;
-        const quarterStart = zdt.with({ month: quarterEndMonth, day: 1, hour: 0, minute: 0, second: 0 }, { disambiguation, offset });
-        const nextQuarterStart = quarterStart.add({ months: 1 });
-        const lastDayOfQuarter = nextQuarterStart.subtract({ days: 1 });
-        const result = lastDayOfQuarter.with({
-            hour: 23,
-            minute: 59,
-            second: 59,
-            millisecond: 999,
-            microsecond: 999,
-            nanosecond: 999,
-        }, { disambiguation, offset });
-        const epoch = epochUnit === "seconds"
-            ? Math.floor(result.epochMilliseconds / 1000)
-            : result.epochMilliseconds;
-        return epoch;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        return startOrEndOfUnix(value, "quarter", options ?? {}, true);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/unix/calculate/endOfUnix.d.ts

@@ -1,30 +1,35 @@
-import { Temporal } from "@js-temporal/polyfill";
-import type { Disambiguation, Offset } from "../../types/index.js";
+import type { Temporal } from "@js-temporal/polyfill";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return the end of the specified unit for a Unix timestamp.
  *
- * - Converts to ZonedDateTime, sets to end of unit, converts back to epoch.
- * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - `disambiguation` controls DST gap/overlap resolution when the boundary jump lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in null).
- * - `offset` controls whether the source's existing UTC offset is kept when computing the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Converts to ZonedDateTime, finds the end of the unit, converts back to epoch.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", singular or plural. For quarters use `startOfQuarterForUnix` / `endOfQuarterForUnix`; `"quarter"` returns null.
+ * - Returns the last millisecond of the real local `unit` containing `value` in `timeZone` — just before the next bucket `floorToZone` would return — so the result is never before `value`: the second pass of a repeated fall-back hour ends at its own 1:59:59.999.
+ * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
+ *   takes neither. Those ignored options were removed in 1.16.0.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null, for every unit.
  * - Returns null for invalid input.
+ * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
+ *   null.
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
  * @returns Unix epoch number representing the end of the unit, or null on invalid input
  *
- * @example endOfUnix(1706659200000, "year") // 1735689600000
- * @example endOfUnix(1706659200000, "month") // 1708012800000
- * @example endOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706736000
- * @example endOfUnix(-86400000, "year") // -1 (end of 1969)
- * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; end-of-hour is ambiguous)
- * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730617199999 (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ * @example endOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1735689599999
+ * @example endOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1706745599999
+ * @example endOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706745599
+ * @example endOfUnix(-86400000, "year", { timeZone: "UTC" }) // -1 (end of 1969)
+ * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730617199999 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour ends at the second 1:59:59.999)
+ * @example endOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706831999 (plural unit, singular epochUnit, UTC by default)
+ * @example endOfUnix(1706659200000, "quarter") // null (use endOfQuarterForUnix)
+ * @example endOfUnix(NaN, "day") // null
  */
-export declare function endOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function endOfUnix(value: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
     weekStartsOn?: "monday" | "sunday";
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): number | null;

package/dist/unix/calculate/endOfUnix.js

@@ -1,26 +1,48 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { startOrEndOfUnix } from "./startOrEndOfUnix.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { startOrEndOfUnix } from "../../internal/startOrEndOfUnix.js";
+import { isValidDateTimeUnit } from "../../plain/validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the end of the specified unit for a Unix timestamp.
  *
- * - Converts to ZonedDateTime, sets to end of unit, converts back to epoch.
- * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - `disambiguation` controls DST gap/overlap resolution when the boundary jump lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in null).
- * - `offset` controls whether the source's existing UTC offset is kept when computing the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Converts to ZonedDateTime, finds the end of the unit, converts back to epoch.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", singular or plural. For quarters use `startOfQuarterForUnix` / `endOfQuarterForUnix`; `"quarter"` returns null.
+ * - Returns the last millisecond of the real local `unit` containing `value` in `timeZone` — just before the next bucket `floorToZone` would return — so the result is never before `value`: the second pass of a repeated fall-back hour ends at its own 1:59:59.999.
+ * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
+ *   takes neither. Those ignored options were removed in 1.16.0.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null, for every unit.
  * - Returns null for invalid input.
+ * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
+ *   null.
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
  * @returns Unix epoch number representing the end of the unit, or null on invalid input
  *
- * @example endOfUnix(1706659200000, "year") // 1735689600000
- * @example endOfUnix(1706659200000, "month") // 1708012800000
- * @example endOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706736000
- * @example endOfUnix(-86400000, "year") // -1 (end of 1969)
- * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; end-of-hour is ambiguous)
- * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730617199999 (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ * @example endOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1735689599999
+ * @example endOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1706745599999
+ * @example endOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706745599
+ * @example endOfUnix(-86400000, "year", { timeZone: "UTC" }) // -1 (end of 1969)
+ * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730617199999 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour ends at the second 1:59:59.999)
+ * @example endOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706831999 (plural unit, singular epochUnit, UTC by default)
+ * @example endOfUnix(1706659200000, "quarter") // null (use endOfQuarterForUnix)
+ * @example endOfUnix(NaN, "day") // null
  */
 export function endOfUnix(value, unit, options) {
-    return startOrEndOfUnix(value, unit, options ?? {}, true);
+    try {
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const resolvedUnit = typeof unit === "string" ? resolveDateTimeUnit(unit) : unit;
+        if (!isValidDateTimeUnit(resolvedUnit))
+            return null;
+        return startOrEndOfUnix(value, resolvedUnit, options ?? {}, true);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
 }

package/dist/unix/calculate/isBetweenUnix.d.ts

@@ -1,22 +1,28 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return true when the Unix timestamp is between start and end (inclusive by default).
  *
  * - Uses Temporal.Instant.compare for comparison.
  * - Returns false if start > end or inputs are invalid.
  * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
+ * - Each value is a safe integer or a digit string (`"1705000000000"`); anything else returns false.
+ * - `timeZone` is only validated (the comparison is on exact instants): omitted is UTC, `"local"`
+ *   the system zone, and an unknown zone returns false.
  *
- * @param value Unix timestamp to check
- * @param start Unix timestamp for range start
- * @param end Unix timestamp for range end
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param value Unix epoch to check: a safe integer, or a string of optionally negative ASCII digits
+ * @param start Unix epoch for range start, in the same form and unit
+ * @param end Unix epoch for range end, in the same form and unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC" — only validated, the comparison is on exact instants), inclusiveStart (boolean), inclusiveEnd (boolean)
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000) // true
  * @example isBetweenUnix(1705000000, 1704000000, 1706000000, { epochUnit: "seconds" }) // true
  * @example isBetweenUnix(1703000000000, 1704000000000, 1706000000000) // false
+ * @example isBetweenUnix("1705000000", "1704000000", "1706000000", { epochUnit: "second" }) // true (digit strings)
+ * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000, { timeZone: "Mars/Olympus" }) // false (unknown zone)
  */
-export declare function isBetweenUnix(value: number, start: number, end: number, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function isBetweenUnix(value: number | string, start: number | string, end: number | string, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
     inclusiveStart?: boolean;
     inclusiveEnd?: boolean;

package/dist/unix/calculate/isBetweenUnix.js

@@ -1,42 +1,51 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true when the Unix timestamp is between start and end (inclusive by default).
  *
  * - Uses Temporal.Instant.compare for comparison.
  * - Returns false if start > end or inputs are invalid.
  * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
+ * - Each value is a safe integer or a digit string (`"1705000000000"`); anything else returns false.
+ * - `timeZone` is only validated (the comparison is on exact instants): omitted is UTC, `"local"`
+ *   the system zone, and an unknown zone returns false.
  *
- * @param value Unix timestamp to check
- * @param start Unix timestamp for range start
- * @param end Unix timestamp for range end
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param value Unix epoch to check: a safe integer, or a string of optionally negative ASCII digits
+ * @param start Unix epoch for range start, in the same form and unit
+ * @param end Unix epoch for range end, in the same form and unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC" — only validated, the comparison is on exact instants), inclusiveStart (boolean), inclusiveEnd (boolean)
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000) // true
  * @example isBetweenUnix(1705000000, 1704000000, 1706000000, { epochUnit: "seconds" }) // true
  * @example isBetweenUnix(1703000000000, 1704000000000, 1706000000000) // false
+ * @example isBetweenUnix("1705000000", "1704000000", "1706000000", { epochUnit: "second" }) // true (digit strings)
+ * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000, { timeZone: "Mars/Olympus" }) // false (unknown zone)
  */
 export function isBetweenUnix(value, start, end, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    const inclusiveStart = options?.inclusiveStart ?? true;
-    const inclusiveEnd = options?.inclusiveEnd ?? true;
-    if (!timeZone || !isValidTimeZone(timeZone))
-        return false;
-    if (!Number.isFinite(value) ||
-        !Number.isInteger(value) ||
-        !Number.isFinite(start) ||
-        !Number.isInteger(start) ||
-        !Number.isFinite(end) ||
-        !Number.isInteger(end)) {
-        return false;
-    }
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value * 1000 : value);
-        const startInstant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? start * 1000 : start);
-        const endInstant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? end * 1000 : end);
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        // Only an omitted flag takes the `true` default. An explicit `null` is a value, and every
+        // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
+        // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
+        // behaves here exactly as `0` and `""` already do.
+        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
+        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        if (!timeZone || epochUnit === null)
+            return false;
+        const instant = unixEpochToInstant(value, epochUnit);
+        const startInstant = unixEpochToInstant(start, epochUnit);
+        const endInstant = unixEpochToInstant(end, epochUnit);
+        if (instant === null || startInstant === null || endInstant === null) {
+            return false;
+        }
         if (Temporal.Instant.compare(startInstant, endInstant) === 1) {
             return false;
         }
@@ -49,6 +58,8 @@ export function isBetweenUnix(value, start, end, options) {
         return startCheck && endCheck;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/unix/calculate/maxUnix.d.ts

@@ -1,13 +1,16 @@
 /**
  * Return the latest (maximum) of the given Unix timestamp values.
  *
- * - Filters invalid values before finding maximum.
+ * - Drops values that are not unix epochs first: anything that is not a safe integer or a string of optionally negative ASCII digits, and values outside
+ *   the Temporal instant range (±8.64e15, which contains every seconds and milliseconds epoch).
  * - Returns null if array is empty or has no valid values.
  *
- * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @param unixValues Array of Unix epochs as numbers or digit strings (e.g. 1699531200 or "1699531200"); digit strings are returned as numbers
  * @returns The latest Unix timestamp, or null on invalid input
  *
  * @example maxUnix([1706659200000, 1704067200000, 1700000000000]) // 1706659200000
  * @example maxUnix([]) // null
+ * @example maxUnix([1, 1e20]) // 1 (1e20 is outside the instant range)
+ * @example maxUnix(["-86400", "-1"]) // -1
  */
-export declare function maxUnix(unixValues: number[]): number | null;
+export declare function maxUnix(unixValues: Array<number | string>): number | null;

package/dist/unix/calculate/maxUnix.js

@@ -1,21 +1,30 @@
-import { isValidAmount } from "../../internal/index.js";
+import { parseUnixEpochsInInstantRange } from "../../internal/unixEpochValue.js";
 /**
  * Return the latest (maximum) of the given Unix timestamp values.
  *
- * - Filters invalid values before finding maximum.
+ * - Drops values that are not unix epochs first: anything that is not a safe integer or a string of optionally negative ASCII digits, and values outside
+ *   the Temporal instant range (±8.64e15, which contains every seconds and milliseconds epoch).
  * - Returns null if array is empty or has no valid values.
  *
- * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @param unixValues Array of Unix epochs as numbers or digit strings (e.g. 1699531200 or "1699531200"); digit strings are returned as numbers
  * @returns The latest Unix timestamp, or null on invalid input
  *
  * @example maxUnix([1706659200000, 1704067200000, 1700000000000]) // 1706659200000
  * @example maxUnix([]) // null
+ * @example maxUnix([1, 1e20]) // 1 (1e20 is outside the instant range)
+ * @example maxUnix(["-86400", "-1"]) // -1
  */
 export function maxUnix(unixValues) {
-    if (!unixValues.length)
+    try {
+        const valid = parseUnixEpochsInInstantRange(unixValues);
+        if (!valid.length)
+            return null;
+        // Pairwise, not `Math.max(...valid)`: spreading a long list overflows the call stack.
+        return valid.reduce((a, b) => Math.max(a, b));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
-    const valid = unixValues.filter(isValidAmount);
-    if (!valid.length)
-        return null;
-    return Math.max(...valid);
+    }
 }

package/dist/unix/calculate/minUnix.d.ts

@@ -1,13 +1,16 @@
 /**
  * Return the earliest (minimum) of the given Unix timestamp values.
  *
- * - Filters invalid values before finding minimum.
+ * - Drops values that are not unix epochs first: anything that is not a safe integer or a string of optionally negative ASCII digits, and values outside
+ *   the Temporal instant range (±8.64e15, which contains every seconds and milliseconds epoch).
  * - Returns null if array is empty or has no valid values.
  *
- * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @param unixValues Array of Unix epochs as numbers or digit strings (e.g. 1699531200 or "1699531200"); digit strings are returned as numbers
  * @returns The earliest Unix timestamp, or null on invalid input
  *
  * @example minUnix([1706659200000, 1704067200000, 1700000000000]) // 1700000000000
  * @example minUnix([]) // null
+ * @example minUnix([1.5, 2]) // 2 (1.5 is not an integer epoch)
+ * @example minUnix(["1700000000000", "1e3"]) // 1700000000000 ("1e3" is not a digit string)
  */
-export declare function minUnix(unixValues: number[]): number | null;
+export declare function minUnix(unixValues: Array<number | string>): number | null;

package/dist/unix/calculate/minUnix.js

@@ -1,21 +1,30 @@
-import { isValidAmount } from "../../internal/index.js";
+import { parseUnixEpochsInInstantRange } from "../../internal/unixEpochValue.js";
 /**
  * Return the earliest (minimum) of the given Unix timestamp values.
  *
- * - Filters invalid values before finding minimum.
+ * - Drops values that are not unix epochs first: anything that is not a safe integer or a string of optionally negative ASCII digits, and values outside
+ *   the Temporal instant range (±8.64e15, which contains every seconds and milliseconds epoch).
  * - Returns null if array is empty or has no valid values.
  *
- * @param unixValues Array of Unix timestamps (e.g. 1699531200)
+ * @param unixValues Array of Unix epochs as numbers or digit strings (e.g. 1699531200 or "1699531200"); digit strings are returned as numbers
  * @returns The earliest Unix timestamp, or null on invalid input
  *
  * @example minUnix([1706659200000, 1704067200000, 1700000000000]) // 1700000000000
  * @example minUnix([]) // null
+ * @example minUnix([1.5, 2]) // 2 (1.5 is not an integer epoch)
+ * @example minUnix(["1700000000000", "1e3"]) // 1700000000000 ("1e3" is not a digit string)
  */
 export function minUnix(unixValues) {
-    if (!unixValues.length)
+    try {
+        const valid = parseUnixEpochsInInstantRange(unixValues);
+        if (!valid.length)
+            return null;
+        // Pairwise, not `Math.min(...valid)`: spreading a long list overflows the call stack.
+        return valid.reduce((a, b) => Math.min(a, b));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
-    const valid = unixValues.filter(isValidAmount);
-    if (!valid.length)
-        return null;
-    return Math.min(...valid);
+    }
 }

package/dist/unix/calculate/roundUnix.d.ts

@@ -1,27 +1,41 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Round a Unix timestamp to the specified unit.
  *
  * - Converts to ZonedDateTime, rounds, converts back to epoch.
  * - Supports: "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return null.
+ * - Each unit is accepted in its singular or plural form ("hour" or "hours"), as Temporal's
+ *   GetTemporalUnitValuedOption accepts both (§13.17).
+ * - Date units ("year", "month", "week", in either form) return null: Temporal's
+ *   ZonedDateTime.prototype.round accepts no unit larger than "day".
+ * - Follows TC39 `ZonedDateTime.round`, which rounds the wall clock and re-resolves it in the
+ *   zone. Across a transition the result can land after the input — in `Pacific/Chatham`,
+ *   1727532300000 (03:50+13:45) truncated to the hour gives 1727532900000, 15 minutes later.
+ *   Use `floorToZone` for a boundary that never exceeds the instant.
+ * - `value` is a safe integer or a digit string (`"1706661000000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
+ *   null.
  * - Returns null for invalid input.
  *
- * @param value Unix timestamp (number)
- * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, epochUnit, timeZone
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
+ * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns Rounded Unix epoch number, or null on invalid input
  *
- * @example roundUnix(1706659200000, { smallestUnit: "hour" }) // 1706662800000 (rounded up to next hour)
- * @example roundUnix(1706659200000, { smallestUnit: "day", epochUnit: "seconds" }) // 1706640000 (start of day in seconds)
- * @example roundUnix(1706659200000, { smallestUnit: "hour", roundingIncrement: 2 }) // 1706662800000 (rounded to nearest 2-hour mark)
- * @example roundUnix(-86400000, { smallestUnit: "day" }) // -86400000 (start of day for negative timestamp)
+ * @example roundUnix(1706661000000, { smallestUnit: "hour", timeZone: "UTC" }) // 1706662800000 (00:30 is a tie; halfExpand rounds up)
+ * @example roundUnix(1706700000, { smallestUnit: "day", epochUnit: "seconds", timeZone: "UTC" }) // 1706659200 (11:20 rounds down to the day)
+ * @example roundUnix(1706659200000, { smallestUnit: "hour", roundingIncrement: 2, timeZone: "UTC" }) // 1706659200000 (00:00 is already a 2-hour mark)
+ * @example roundUnix(-86400000, { smallestUnit: "day", timeZone: "UTC" }) // -86400000 (start of day for negative timestamp)
+ * @example roundUnix(1727532300000, { smallestUnit: "hour", roundingMode: "trunc", timeZone: "Pacific/Chatham" }) // 1727532900000 (after the input — TC39 wall-clock rounding)
+ * @example roundUnix(1715779905500, { smallestUnit: "minutes", timeZone: "UTC" }) // 1715779920000 (plural unit name; 13:31:45.5 rounds up to 13:32)
+ * @example roundUnix("1706700000", { smallestUnit: "day", epochUnit: "second" }) // 1706659200 (digit string, singular epochUnit, UTC by default)
  * @example roundUnix("invalid", { smallestUnit: "hour" }) // null
  * @example roundUnix(NaN, { smallestUnit: "hour" }) // null
  */
-export declare function roundUnix(value: number, options: {
+export declare function roundUnix(value: number | string, options: {
     smallestUnit: Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
     roundingIncrement?: number;
     roundingMode?: Temporal.RoundingMode;
-    epochUnit?: "seconds" | "milliseconds";
+    epochUnit?: UnixUnit;
     timeZone?: string;
 }): number | null;