@northguild/gmt 1.15.0 → 1.17.0

package/dist/unix/calculate/addUnix.js

@@ -1,51 +1,64 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { addToZoned, isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Add a temporal amount to a Unix epoch value and return the resulting epoch.
  *
  * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
  * - Validates duration units and values.
+ * - `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.
  * - Returns null for invalid input.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
  * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @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")
  * @returns Unix epoch number after addition, or null on invalid input
  *
  * @example addUnix(1706659200000, { days: 1 }) // 1706745600000
  * @example addUnix(1706659200, { days: 1 }, { epochUnit: "seconds" }) // 1706745600
  * @example addUnix(-86400000, { days: 1 }) // 0 (Dec 31 1969 + 1 day = Jan 1 1970)
+ * @example addUnix(1.5, { days: 1 }) // null (not an integer epoch)
+ * @example addUnix("1706659200000", { days: 1 }) // 1706745600000 (digit string)
+ * @example addUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
  */
 export function addUnix(value, units, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    const overflow = resolveOverflow(options?.overflow);
-    if (!timeZone || !isValidTimeZone(timeZone))
-        return null;
-    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validUnits || !validAmounts) {
-        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 result = zdt.add(units, { overflow });
-        const epoch = epochUnit === "seconds"
-            ? Math.floor(result.epochMilliseconds / 1000)
-            : result.epochMilliseconds;
-        return epoch;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        const overflow = resolveOverflow(options?.overflow);
+        if (!timeZone || epochUnit === null)
+            return null;
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateTimeDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validUnits || !validAmounts) {
+            return null;
+        }
+        const instant = unixEpochToInstant(value, epochUnit);
+        if (instant === null) {
+            return null;
+        }
+        try {
+            const zdt = instant.toZonedDateTimeISO(timeZone);
+            return toUnixEpoch(addToZoned(zdt, units, { overflow }), 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/diffUnix.d.ts

@@ -1,9 +1,13 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return the difference between two Unix timestamps measured in the given unit.
  *
- * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Converts both epochs to a `Temporal.ZonedDateTime` in `timeZone` and uses its `until()`, so
+ *   calendar units (days, weeks, months, years) are measured on that zone's wall clock — a
+ *   23-hour DST day is 1 day — while time units (hours and smaller) 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,20 +15,43 @@ 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 }`.
+ *   Days carried into a time unit follow the wall clock of `timeZone` (a 23-hour DST day is
+ *   23 hours).
+ * - Nanosecond precision: the result is a JavaScript `number`, so past about 104 days a
+ *   nanosecond count exceeds `Number.MAX_SAFE_INTEGER`. Every value this function can return is
+ *   still exact — its inputs are whole milliseconds or seconds — but it is no longer a safe
+ *   integer, so arithmetic on it silently loses nanoseconds:
+ *   `diffUnix(0, 9072000000, "nanoseconds")` returns `9072000000000000`, and adding `1` to that
+ *   gives the same number back. For an exact count use the `bigint` APIs: `spanNs` in `span/`,
+ *   or `toNanoseconds` in `precision/`.
+ * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
+ *   invalid.
+ * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal; a record result
+ *   keeps the plural keys.
  *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
+ * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
+ * @param value2 second Unix epoch, in the same form and unit
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), 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 diffUnix(1706745600000, 1706659200000, "day") // 1
- * @example diffUnix(1706745600, 1706659200, "day", { epochUnit: "seconds" }) // 1
- * @example diffUnix(0, -86400000, "day") // 1 (Jan 1 1970 - Dec 31 1969 = 1 day)
+ * @example diffUnix(1706745600000, 1706659200000, "days", { timeZone: "UTC" }) // -1 (measured from the first value to the second)
+ * @example diffUnix(1706745600, 1706659200, "days", { epochUnit: "seconds", timeZone: "UTC" }) // -1
+ * @example diffUnix(0, -86400000, "days", { timeZone: "UTC" }) // -1 (1970-01-01 until 1969-12-31 is minus one day)
+ * @example diffUnix(NaN, 0, "days") // null
+ * @example diffUnix("0", "90000000", ["day", "hour"]) // { days: 1, hours: 1 } (digit strings, singular names with plural keys, UTC by default)
+ * @example diffUnix(1704067200000, 1740787200000, ["years", "days"], { timeZone: "UTC" }) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
-export declare function diffUnix(value1: number, value2: number, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function diffUnix(value1: number | string, value2: number | string, units: DateTimeDurationUnit | Temporal.DateTimeUnit | Array<DateTimeDurationUnit | Temporal.DateTimeUnit>, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
 } & RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/unix/calculate/diffUnix.js

@@ -1,11 +1,17 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUnixEpochPair, resolveUnixTimeZone, } from "../../internal/resolveUnixTimeZone.js";
+import { addToZoned, resolveDurationUnit, zonedUntil } from "../../internal/index.js";
+import { differenceRecord } from "../../internal/differenceRecord.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { getLargestDateTimeDurationUnit } from "../../plain/calculate/getLargestDateTimeDurationUnit.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two Unix timestamps measured in the given unit.
  *
- * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Converts both epochs to a `Temporal.ZonedDateTime` in `timeZone` and uses its `until()`, so
+ *   calendar units (days, weeks, months, years) are measured on that zone's wall clock — a
+ *   23-hour DST day is 1 day — while time units (hours and smaller) 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.
  *
@@ -13,54 +19,92 @@ import { isValidDateTimeDurationUnit } from "../../plain/validate/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 }`.
+ *   Days carried into a time unit follow the wall clock of `timeZone` (a 23-hour DST day is
+ *   23 hours).
+ * - Nanosecond precision: the result is a JavaScript `number`, so past about 104 days a
+ *   nanosecond count exceeds `Number.MAX_SAFE_INTEGER`. Every value this function can return is
+ *   still exact — its inputs are whole milliseconds or seconds — but it is no longer a safe
+ *   integer, so arithmetic on it silently loses nanoseconds:
+ *   `diffUnix(0, 9072000000, "nanoseconds")` returns `9072000000000000`, and adding `1` to that
+ *   gives the same number back. For an exact count use the `bigint` APIs: `spanNs` in `span/`,
+ *   or `toNanoseconds` in `precision/`.
+ * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
+ *   invalid.
+ * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal; a record result
+ *   keeps the plural keys.
  *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
+ * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
+ * @param value2 second Unix epoch, in the same form and unit
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), 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 diffUnix(1706745600000, 1706659200000, "day") // 1
- * @example diffUnix(1706745600, 1706659200, "day", { epochUnit: "seconds" }) // 1
- * @example diffUnix(0, -86400000, "day") // 1 (Jan 1 1970 - Dec 31 1969 = 1 day)
+ * @example diffUnix(1706745600000, 1706659200000, "days", { timeZone: "UTC" }) // -1 (measured from the first value to the second)
+ * @example diffUnix(1706745600, 1706659200, "days", { epochUnit: "seconds", timeZone: "UTC" }) // -1
+ * @example diffUnix(0, -86400000, "days", { timeZone: "UTC" }) // -1 (1970-01-01 until 1969-12-31 is minus one day)
+ * @example diffUnix(NaN, 0, "days") // null
+ * @example diffUnix("0", "90000000", ["day", "hour"]) // { days: 1, hours: 1 } (digit strings, singular names with plural keys, UTC by default)
+ * @example diffUnix(1704067200000, 1740787200000, ["years", "days"], { timeZone: "UTC" }) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
 export function diffUnix(value1, value2, units, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = resolveUnixTimeZone(options?.timeZone);
-    if (!timeZone)
-        return null;
-    const isSingleUnit = !Array.isArray(units);
-    const validUnits = isSingleUnit
-        ? isValidDateTimeDurationUnit(units)
-        : units.every(isValidDateTimeDurationUnit);
-    if (!validUnits) {
-        return null;
-    }
-    if (!isValidUnixEpochPair(value1, value2)) {
-        return null;
-    }
     try {
-        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
-        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
-        const zdt1 = instant1.toZonedDateTimeISO(timeZone);
-        const zdt2 = instant2.toZonedDateTimeISO(timeZone);
-        const duration = zdt1.until(zdt2, {
-            largestUnit: isSingleUnit ? units : getLargestDateTimeDurationUnit(units),
-            smallestUnit: options?.smallestUnit,
-            roundingIncrement: options?.roundingIncrement,
-            roundingMode: options?.roundingMode,
-        });
-        if (isSingleUnit) {
-            return duration[units] ?? 0;
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (!timeZone || epochUnit === null)
+            return null;
+        const requested = Array.isArray(units) ? units : [units];
+        const plurals = requested.map((unit) => typeof unit === "string" ? resolveDurationUnit(unit) : "");
+        if (!plurals.every(isValidDateTimeDurationUnit)) {
+            return null;
+        }
+        const instant1 = unixEpochToInstant(value1, epochUnit);
+        const instant2 = unixEpochToInstant(value2, epochUnit);
+        if (instant1 === null || instant2 === null) {
+            return null;
+        }
+        const largestUnit = getLargestDateTimeDurationUnit(plurals);
+        if (largestUnit === "")
+            return null;
+        try {
+            const duration = zonedUntil(instant1.toZonedDateTimeISO(timeZone), instant2.toZonedDateTimeISO(timeZone), {
+                largestUnit,
+                smallestUnit: options?.smallestUnit,
+                roundingIncrement: options?.roundingIncrement,
+                roundingMode: options?.roundingMode,
+            });
+            if (!Array.isArray(units)) {
+                return duration[plurals[0]] ?? 0;
+            }
+            // An unlisted unit between two listed units is carried into the next smaller listed unit.
+            const start = instant1.toZonedDateTimeISO(timeZone);
+            // Record keys are the plural names, as in every other diff family.
+            return differenceRecord(start, duration, plurals, {
+                add: (from, amount) => addToZoned(from, amount),
+                until: (from, to, largest) => zonedUntil(from, to, {
+                    largestUnit: largest,
+                }),
+            });
+        }
+        catch {
+            return null;
         }
-        return units.reduce((result, unit) => {
-            result[unit] = duration[unit] ?? 0;
-            return result;
-        }, {});
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,10 +1,15 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return the difference between two Unix timestamps as an ISO 8601 duration string,
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
  *
- * - Uses Temporal.Instant.until() with `largestUnit` set to `unit`, then `.toString()`.
+ * - Converts both epochs to a `Temporal.ZonedDateTime` in `timeZone` and uses its `until()` with
+ *   `largestUnit` set to `unit`, then `.toString()`. Calendar units (days, weeks, months, years)
+ *   are therefore measured on that zone's wall clock — a 23-hour DST day is `P1D` — while time
+ *   units are exact elapsed time. `Temporal.Instant.until()` is not used: it rejects every
+ *   calendar `largestUnit`.
  * - Unlike `diffUnix`, `unit` is a single unit (not an array) — an ISO duration string
  *   already expresses a full multi-unit breakdown via `largestUnit` alone, so there's no
  *   array-of-units overload here.
@@ -17,19 +22,24 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
+ * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
+ *   invalid.
+ * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal.
  *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
+ * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
+ * @param value2 second Unix epoch, in the same form and unit
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"
  * @example diffUnixAsDuration(1706745600000, 1706659200000, "days") // "-P1D"
  * @example diffUnixAsDuration(1706659200, 1706745600, "days", { epochUnit: "seconds" }) // "P1D"
+ * @example diffUnixAsDuration("0", "90000000", "day") // "P1DT1H" (digit strings, singular unit, UTC by default)
  * @example diffUnixAsDuration(NaN, 1706745600000, "days") // ""
  */
-export declare function diffUnixAsDuration(value1: number, value2: number, unit: DateTimeDurationUnit, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function diffUnixAsDuration(value1: number | string, value2: number | string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
 } & RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/unix/calculate/diffUnixAsDuration.js

@@ -1,12 +1,17 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { durationUntilString } from "../../internal/index.js";
-import { isValidUnixEpochPair, resolveUnixTimeZone, } from "../../internal/resolveUnixTimeZone.js";
+import { durationUntilString, resolveDurationUnit } from "../../internal/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two Unix timestamps as an ISO 8601 duration string,
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
  *
- * - Uses Temporal.Instant.until() with `largestUnit` set to `unit`, then `.toString()`.
+ * - Converts both epochs to a `Temporal.ZonedDateTime` in `timeZone` and uses its `until()` with
+ *   `largestUnit` set to `unit`, then `.toString()`. Calendar units (days, weeks, months, years)
+ *   are therefore measured on that zone's wall clock — a 23-hour DST day is `P1D` — while time
+ *   units are exact elapsed time. `Temporal.Instant.until()` is not used: it rejects every
+ *   calendar `largestUnit`.
  * - Unlike `diffUnix`, `unit` is a single unit (not an array) — an ISO duration string
  *   already expresses a full multi-unit breakdown via `largestUnit` alone, so there's no
  *   array-of-units overload here.
@@ -19,38 +24,52 @@ import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
  * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
+ * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
+ *   invalid.
+ * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal.
  *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
+ * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
+ * @param value2 second Unix epoch, in the same form and unit
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"
  * @example diffUnixAsDuration(1706745600000, 1706659200000, "days") // "-P1D"
  * @example diffUnixAsDuration(1706659200, 1706745600, "days", { epochUnit: "seconds" }) // "P1D"
+ * @example diffUnixAsDuration("0", "90000000", "day") // "P1DT1H" (digit strings, singular unit, UTC by default)
  * @example diffUnixAsDuration(NaN, 1706745600000, "days") // ""
  */
 export function diffUnixAsDuration(value1, value2, unit, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = resolveUnixTimeZone(options?.timeZone);
-    if (!timeZone)
-        return "";
-    const validUnit = isValidDateTimeDurationUnit(unit);
-    if (!validUnit) {
-        return "";
-    }
-    if (!isValidUnixEpochPair(value1, value2)) {
-        return "";
-    }
     try {
-        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
-        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
-        const zdt1 = instant1.toZonedDateTimeISO(timeZone);
-        const zdt2 = instant2.toZonedDateTimeISO(timeZone);
-        return durationUntilString(zdt1, zdt2, unit, options);
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (!timeZone || epochUnit === null)
+            return "";
+        const largestUnit = typeof unit === "string" ? resolveDurationUnit(unit) : unit;
+        if (!isValidDateTimeDurationUnit(largestUnit)) {
+            return "";
+        }
+        const instant1 = unixEpochToInstant(value1, epochUnit);
+        const instant2 = unixEpochToInstant(value2, epochUnit);
+        if (instant1 === null || instant2 === null) {
+            return "";
+        }
+        try {
+            return durationUntilString(instant1.toZonedDateTimeISO(timeZone), instant2.toZonedDateTimeISO(timeZone), largestUnit, options);
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,23 +1,27 @@
-import type { Disambiguation, Offset } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.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 declare function endOfQuarterForUnix(value: number, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function endOfQuarterForUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): number | null;

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