@northguild/gmt 1.14.2 → 1.16.0

package/dist/unix/calculate/roundUnix.js

@@ -1,62 +1,87 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTimeUnit } from "../../plain/index.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { isObject, resolveDateTimeUnit, roundZonedDateTime, } from "../../internal/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+const ZONED_ROUNDING_UNITS = [
+    "day",
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+function isZonedRoundingUnit(unit) {
+    return ZONED_ROUNDING_UNITS.includes(unit);
+}
 /**
  * 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 function roundUnix(value, options) {
-    const { smallestUnit, roundingIncrement, roundingMode, epochUnit = "milliseconds", timeZone = getSystemTimeZone(), } = options;
-    if (!timeZone ||
-        !isValidDateTimeUnit(smallestUnit) ||
-        !isValidTimeZone(timeZone)) {
-        return null;
-    }
-    if (!Number.isFinite(value) || !Number.isInteger(value)) {
-        return null;
-    }
-    // Polyfill limitation: year/month/week not supported for ZonedDateTime.round()
-    const supportedUnits = [
-        "day",
-        "hour",
-        "minute",
-        "second",
-        "millisecond",
-        "microsecond",
-        "nanosecond",
-    ];
-    if (!supportedUnits.includes(smallestUnit)) {
-        return null;
-    }
     try {
-        let epochMs = epochUnit === "seconds" ? value * 1000 : value;
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochMs);
-        const source = instant.toZonedDateTimeISO(timeZone);
-        const result = source.round({
-            smallestUnit,
-            roundingIncrement,
-            roundingMode,
-        });
-        epochMs = result.epochMilliseconds;
-        return epochUnit === "seconds" ? Math.floor(epochMs / 1000) : epochMs;
+        if (!isObject(options))
+            return null;
+        const { roundingIncrement, roundingMode } = options;
+        const epochUnit = resolveUnixEpochUnit(options.epochUnit);
+        const timeZone = normalizeTimeZone(options.timeZone);
+        const smallestUnit = typeof options.smallestUnit === "string"
+            ? resolveDateTimeUnit(options.smallestUnit)
+            : options.smallestUnit;
+        if (!timeZone || epochUnit === null || !isValidDateTimeUnit(smallestUnit)) {
+            return null;
+        }
+        // Temporal ZonedDateTime.prototype.round: ValidateTemporalUnitValue(smallestUnit, ~time~, « day »)
+        if (!isZonedRoundingUnit(smallestUnit)) {
+            return null;
+        }
+        const instant = unixEpochToInstant(value, epochUnit);
+        if (instant === null) {
+            return null;
+        }
+        try {
+            const result = roundZonedDateTime(instant.toZonedDateTimeISO(timeZone), {
+                smallestUnit,
+                roundingIncrement,
+                roundingMode,
+            });
+            return toUnixEpoch(result, epochUnit);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,5 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return a Unix epoch value with the given `fields` set on `value`, interpreted in `timeZone`.
  *
@@ -14,20 +15,28 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
  *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
  *   (resulting in null).
+ * - `value` is a safe integer or a digit string (`"1710072000000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
+ * - `offset` defaults to `"prefer"`, as `Temporal.ZonedDateTime.prototype.with`: the source's
+ *   offset is kept while it is still valid for the new wall-clock time, so a repeated hour stays on
+ *   the same side of a fall-back. Pass `offset: "ignore"` to re-resolve the wall clock with
+ *   `disambiguation`.
  * - Returns null for invalid input.
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject"), 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"; an unknown zone returns null), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
  * @returns Unix epoch number with fields set, or null on invalid input
  *
  * @example setUnix(1710072000000, { hour: 9 }, { timeZone: "UTC" }) // 1710061200000 (2024-03-10T09:00:00Z)
  * @example setUnix(1706659200000, { year: 2025 }, { timeZone: "UTC" }) // 1738281600000 (2025-01-31T00:00:00Z)
  * @example setUnix(1706659200000, {}, { timeZone: "UTC" }) // 1706659200000 (empty fields object is a no-op)
+ * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York" }) // 1730616300000 (the second 01:30 keeps -05:00)
+ * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York", offset: "ignore" }) // 1730612700000 (re-resolved: the earlier 01:45)
  * @example setUnix(NaN, { hour: 9 }) // null
  */
-export declare function setUnix(value: number, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function setUnix(value: number | string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
     overflow?: Overflow;
     disambiguation?: Disambiguation;

package/dist/unix/calculate/setUnix.js

@@ -1,7 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow } from "../../internal/index.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { resolveOverflow, withZonedFields } from "../../internal/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a Unix epoch value with the given `fields` set on `value`, interpreted in `timeZone`.
  *
@@ -16,45 +16,64 @@ import { isValidTimeZone } from "../../zoned/validate/index.js";
  * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
  *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
  *   (resulting in null).
+ * - `value` is a safe integer or a digit string (`"1710072000000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
+ * - `offset` defaults to `"prefer"`, as `Temporal.ZonedDateTime.prototype.with`: the source's
+ *   offset is kept while it is still valid for the new wall-clock time, so a repeated hour stays on
+ *   the same side of a fall-back. Pass `offset: "ignore"` to re-resolve the wall clock with
+ *   `disambiguation`.
  * - Returns null for invalid input.
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject"), 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"; an unknown zone returns null), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
  * @returns Unix epoch number with fields set, or null on invalid input
  *
  * @example setUnix(1710072000000, { hour: 9 }, { timeZone: "UTC" }) // 1710061200000 (2024-03-10T09:00:00Z)
  * @example setUnix(1706659200000, { year: 2025 }, { timeZone: "UTC" }) // 1738281600000 (2025-01-31T00:00:00Z)
  * @example setUnix(1706659200000, {}, { timeZone: "UTC" }) // 1706659200000 (empty fields object is a no-op)
+ * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York" }) // 1730616300000 (the second 01:30 keeps -05:00)
+ * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York", offset: "ignore" }) // 1730612700000 (re-resolved: the earlier 01:45)
  * @example setUnix(NaN, { hour: 9 }) // null
  */
 export function setUnix(value, fields, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    if (!timeZone || !isValidTimeZone(timeZone))
-        return null;
-    if (!Number.isFinite(value) || !Number.isInteger(value))
-        return null;
-    const overflow = resolveOverflow(options?.overflow);
-    const disambiguation = options?.disambiguation ?? "compatible";
-    // "ignore" (not Temporal's own "prefer" default) so `disambiguation` actually takes effect —
-    // see C3 / docs/dst-disambiguation.md: with "prefer", the source's still-valid offset is kept
-    // and disambiguation is silently never consulted.
-    const offset = options?.offset ?? "ignore";
     try {
-        const epochMs = epochUnit === "seconds" ? value * 1000 : value;
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochMs);
-        const zoned = instant.toZonedDateTimeISO(timeZone);
-        // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
-        // properties found") rather than treating it as a no-op, so short-circuit here.
-        const result = Object.keys(fields).length === 0
-            ? zoned
-            : zoned.with(fields, { overflow, disambiguation, offset });
-        return epochUnit === "seconds"
-            ? Math.floor(result.epochMilliseconds / 1000)
-            : result.epochMilliseconds;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (!timeZone || epochUnit === null)
+            return null;
+        const instant = unixEpochToInstant(value, epochUnit);
+        if (instant === null)
+            return null;
+        const overflow = resolveOverflow(options?.overflow);
+        const disambiguation = options?.disambiguation === undefined
+            ? "compatible"
+            : options.disambiguation;
+        // Temporal ZonedDateTime.prototype.with: GetTemporalOffsetOption(options, "prefer").
+        const offset = options?.offset === undefined ? "prefer" : options.offset;
+        try {
+            const zoned = instant.toZonedDateTimeISO(timeZone);
+            // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
+            // properties found") rather than treating it as a no-op, so short-circuit here.
+            const result = Object.keys(fields).length === 0
+                ? zoned
+                : withZonedFields(zoned, fields, {
+                    overflow,
+                    disambiguation,
+                    offset,
+                });
+            return toUnixEpoch(result, epochUnit);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,16 +1,19 @@
 /**
  * Sort an array of Unix timestamp values in ascending or descending order.
  *
- * - Filters invalid values before sorting.
+ * - Drops values that are not unix epochs before sorting: 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).
  * - Supports "asc" (earliest first) or "desc" (latest first).
  * - Returns [] 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
  * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
  * @returns Sorted array of Unix timestamps
  *
  * @example sortUnix([1706659200000, 1704067200000, 1700000000000]) // [1700000000000, 1704067200000, 1706659200000]
  * @example sortUnix([1704067200, 1700000000], "desc") // [1704067200, 1700000000]
  * @example sortUnix([]) // []
+ * @example sortUnix([3, 1.5, 1]) // [1, 3] (1.5 is not an integer epoch)
+ * @example sortUnix(["1704067200", 1700000000, " 1"]) // [1700000000, 1704067200] (digit string read as a number; a padded string is not an epoch)
  */
-export declare function sortUnix(unixValues: number[], order?: "asc" | "desc"): number[];
+export declare function sortUnix(unixValues: Array<number | string>, order?: "asc" | "desc"): number[];

package/dist/unix/calculate/sortUnix.js

@@ -1,28 +1,36 @@
-import { isValidAmount } from "../../internal/index.js";
+import { parseUnixEpochsInInstantRange } from "../../internal/unixEpochValue.js";
 /**
  * Sort an array of Unix timestamp values in ascending or descending order.
  *
- * - Filters invalid values before sorting.
+ * - Drops values that are not unix epochs before sorting: 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).
  * - Supports "asc" (earliest first) or "desc" (latest first).
  * - Returns [] 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
  * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
  * @returns Sorted array of Unix timestamps
  *
  * @example sortUnix([1706659200000, 1704067200000, 1700000000000]) // [1700000000000, 1704067200000, 1706659200000]
  * @example sortUnix([1704067200, 1700000000], "desc") // [1704067200, 1700000000]
  * @example sortUnix([]) // []
+ * @example sortUnix([3, 1.5, 1]) // [1, 3] (1.5 is not an integer epoch)
+ * @example sortUnix(["1704067200", 1700000000, " 1"]) // [1700000000, 1704067200] (digit string read as a number; a padded string is not an epoch)
  */
 export function sortUnix(unixValues, order = "asc") {
-    if (!unixValues.length)
-        return [];
-    const valid = unixValues.filter(isValidAmount);
-    if (!valid.length)
+    try {
+        const valid = parseUnixEpochsInInstantRange(unixValues);
+        if (!valid.length)
+            return [];
+        const sorted = valid.sort((a, b) => a - b);
+        if (order === "desc") {
+            return sorted.reverse();
+        }
+        return sorted;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
-    const sorted = valid.sort((a, b) => a - b);
-    if (order === "desc") {
-        return sorted.reverse();
     }
-    return sorted;
 }

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

@@ -1,23 +1,28 @@
-import type { Disambiguation, Offset } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return the start of the quarter for a Unix timestamp.
  *
  * - Converts to ZonedDateTime, calculates quarter start, converts back to epoch.
- * - Q1 returns month 1, Q2 returns month 4, Q3 returns month 7, Q4 returns month 10.
- * - `disambiguation` controls DST gap/overlap resolution when the quarter-start 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 the 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.
+ * - Q1 returns month 1, Q2 returns month 4, Q3 returns month 7, Q4 returns month 10, with every field below the day reset — milliseconds included.
+ * - Returns the real start of the local quarter in `timeZone` (see `floorToZone`), so the result is never after `value`.
+ * - 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 start of the quarter, or null on invalid input
  *
- * @example startOfQuarterForUnix(1706659200000) // 1704067200000
- * @example startOfQuarterForUnix(-86400000) // -25598400001 (Q1 1969 starts Jan 1)
+ * @example startOfQuarterForUnix(1706659200000, { timeZone: "UTC" }) // 1704067200000
+ * @example startOfQuarterForUnix(1715776496789, { timeZone: "UTC" }) // 1711929600000 (2024-05-15T12:34:56.789Z; the milliseconds are reset too)
+ * @example startOfQuarterForUnix(-86400000, { timeZone: "UTC" }) // -7948800000 (1969-12-31 is in Q4, which starts Oct 1)
+ * @example startOfQuarterForUnix(276046200000, { timeZone: "Africa/Tunis" }) // 276040800000 (the first pass of Q4 1978's repeated first hour)
+ * @example startOfQuarterForUnix(NaN) // null
  */
-export declare function startOfQuarterForUnix(value: number, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function startOfQuarterForUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): number | null;

package/dist/unix/calculate/startOfQuarterForUnix.js

@@ -1,46 +1,38 @@
-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 start of the quarter for a Unix timestamp.
  *
  * - Converts to ZonedDateTime, calculates quarter start, converts back to epoch.
- * - Q1 returns month 1, Q2 returns month 4, Q3 returns month 7, Q4 returns month 10.
- * - `disambiguation` controls DST gap/overlap resolution when the quarter-start 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 the 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.
+ * - Q1 returns month 1, Q2 returns month 4, Q3 returns month 7, Q4 returns month 10, with every field below the day reset — milliseconds included.
+ * - Returns the real start of the local quarter in `timeZone` (see `floorToZone`), so the result is never after `value`.
+ * - 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 start of the quarter, or null on invalid input
  *
- * @example startOfQuarterForUnix(1706659200000) // 1704067200000
- * @example startOfQuarterForUnix(-86400000) // -25598400001 (Q1 1969 starts Jan 1)
+ * @example startOfQuarterForUnix(1706659200000, { timeZone: "UTC" }) // 1704067200000
+ * @example startOfQuarterForUnix(1715776496789, { timeZone: "UTC" }) // 1711929600000 (2024-05-15T12:34:56.789Z; the milliseconds are reset too)
+ * @example startOfQuarterForUnix(-86400000, { timeZone: "UTC" }) // -7948800000 (1969-12-31 is in Q4, which starts Oct 1)
+ * @example startOfQuarterForUnix(276046200000, { timeZone: "Africa/Tunis" }) // 276040800000 (the first pass of Q4 1978's repeated first hour)
+ * @example startOfQuarterForUnix(NaN) // null
  */
 export function startOfQuarterForUnix(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 quarterStartMonth = Math.floor((month - 1) / 3) * 3 + 1;
-        const result = zdt.with({ month: quarterStartMonth, day: 1, hour: 0, minute: 0, second: 0 }, { 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 ?? {}, false);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/unix/calculate/startOfUnix.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 start of the specified unit for a Unix timestamp.
  *
- * - Converts to ZonedDateTime, sets to start 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 start 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 real start of the local `unit` containing `value` in `timeZone` — the same bucket `floorToZone` uses — so the result is never after `value`: the second pass of a repeated fall-back hour starts at its own 1am, and `Pacific/Chatham`'s 15-minute spring-forward hour starts at 03:45.
+ * - 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 start
- * @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 start of the unit, or null on invalid input
  *
- * @example startOfUnix(1706659200000, "year") // 1704067200000
- * @example startOfUnix(1706659200000, "month") // 1705353600000
- * @example startOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706640000
- * @example startOfUnix(-86400000, "year") // -31536000001 (start of 1969)
- * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; start-of-hour is ambiguous)
- * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730613600000 (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 startOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1704067200000
+ * @example startOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1704067200000
+ * @example startOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706659200
+ * @example startOfUnix(-86400000, "year", { timeZone: "UTC" }) // -31536000000 (start of 1969)
+ * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730613600000 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour starts at the second 1am)
+ * @example startOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706745600 (plural unit, singular epochUnit, UTC by default)
+ * @example startOfUnix(1706659200000, "quarter") // null (use startOfQuarterForUnix)
+ * @example startOfUnix(NaN, "day") // null
  */
-export declare function startOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function startOfUnix(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/startOfUnix.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 start of the specified unit for a Unix timestamp.
  *
- * - Converts to ZonedDateTime, sets to start 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 start 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 real start of the local `unit` containing `value` in `timeZone` — the same bucket `floorToZone` uses — so the result is never after `value`: the second pass of a repeated fall-back hour starts at its own 1am, and `Pacific/Chatham`'s 15-minute spring-forward hour starts at 03:45.
+ * - 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 start
- * @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 start of the unit, or null on invalid input
  *
- * @example startOfUnix(1706659200000, "year") // 1704067200000
- * @example startOfUnix(1706659200000, "month") // 1705353600000
- * @example startOfUnix(1706659200, "day", { epochUnit: "seconds" }) // 1706640000
- * @example startOfUnix(-86400000, "year") // -31536000001 (start of 1969)
- * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject" }) // null (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back overlap; start-of-hour is ambiguous)
- * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York", disambiguation: "reject", offset: "prefer" }) // 1730613600000 (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 startOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1704067200000
+ * @example startOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1704067200000
+ * @example startOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706659200
+ * @example startOfUnix(-86400000, "year", { timeZone: "UTC" }) // -31536000000 (start of 1969)
+ * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730613600000 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour starts at the second 1am)
+ * @example startOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706745600 (plural unit, singular epochUnit, UTC by default)
+ * @example startOfUnix(1706659200000, "quarter") // null (use startOfQuarterForUnix)
+ * @example startOfUnix(NaN, "day") // null
  */
 export function startOfUnix(value, unit, options) {
-    return startOrEndOfUnix(value, unit, options ?? {}, false);
+    try {
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const resolvedUnit = typeof unit === "string" ? resolveDateTimeUnit(unit) : unit;
+        if (!isValidDateTimeUnit(resolvedUnit))
+            return null;
+        return startOrEndOfUnix(value, resolvedUnit, options ?? {}, false);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
 }