@northguild/gmt 1.16.0 → 1.18.0

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

@@ -4,15 +4,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *
  * - 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 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)
+ * @param options optional: how the epochs are read and whether each end of the range is included
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000) // true
@@ -22,8 +19,33 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000, { timeZone: "Mars/Olympus" }) // false (unknown zone)
  */
 export declare function isBetweenUnix(value: number | string, start: number | string, end: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `false`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * A time zone that is validated only: the comparison is on exact instants, so the zone never
+     * changes the result. It is an IANA name, a UTC offset, or `"local"` for the system time zone.
+     * An unknown zone returns `false`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * Whether `value` equal to `start` counts as inside the range. `false` requires it to be after
+     * `start`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveStart?: boolean;
+    /**
+     * Whether `value` equal to `end` counts as inside the range. `false` requires it to be before
+     * `end`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveEnd?: boolean;
 }): boolean;

package/dist/unix/calculate/isBetweenUnix.js

@@ -3,20 +3,18 @@ import { Temporal } from "@js-temporal/polyfill";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.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 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)
+ * @param options optional: how the epochs are read and whether each end of the range is included
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUnix(1705000000000, 1704000000000, 1706000000000) // true
@@ -36,8 +34,8 @@ export function isBetweenUnix(value, start, end, options) {
         // 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;
+        const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
+        const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
         if (!timeZone || epochUnit === null)
             return false;
         const instant = unixEpochToInstant(value, epochUnit);

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

@@ -14,12 +14,10 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   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 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")
+ * @param options rounding settings: the unit to round to, how to round, and how `value` is read
  * @returns Rounded Unix epoch number, or null on invalid input
  *
  * @example roundUnix(1706661000000, { smallestUnit: "hour", timeZone: "UTC" }) // 1706662800000 (00:30 is a tie; halfExpand rounds up)
@@ -33,9 +31,39 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example roundUnix(NaN, { smallestUnit: "hour" }) // null
  */
 export declare function roundUnix(value: number | string, options: {
+    /**
+     * The unit to round to, from `"day"` down to `"nanosecond"`, singular or plural. A larger unit
+     * returns `null`, as `Temporal.ZonedDateTime.prototype.round` accepts none above `"day"`.
+     */
     smallestUnit: Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+    /**
+     * The number of `smallestUnit` steps to round to, such as `15` with `"minute"` for quarter
+     * hours. It must divide the next larger unit evenly and be smaller than it, and must be `1` for
+     * `"day"`; any other value returns `null`. A non-integer is truncated first, as Temporal does.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * The step a value between two steps is rounded to. `"halfExpand"` picks the nearer step and
+     * sends a tie to the later one; `"floor"` and `"trunc"` pick the earlier step, `"ceil"` and
+     * `"expand"` the later, and the other `"half…"` modes differ only in how a tie breaks.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall clock is rounded in: an IANA name, a UTC offset, or `"local"` for the
+     * system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/unix/calculate/roundUnix.js

@@ -28,12 +28,10 @@ function isZonedRoundingUnit(unit) {
  *   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 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")
+ * @param options rounding settings: the unit to round to, how to round, and how `value` is read
  * @returns Rounded Unix epoch number, or null on invalid input
  *
  * @example roundUnix(1706661000000, { smallestUnit: "hour", timeZone: "UTC" }) // 1706662800000 (00:30 is a tie; halfExpand rounds up)
@@ -53,9 +51,8 @@ export function roundUnix(value, options) {
         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;
+        // One read (GetOption): resolveDateTimeUnit returns a value that is not a string unchanged.
+        const smallestUnit = resolveDateTimeUnit(options.smallestUnit);
         if (!timeZone || epochUnit === null || !isValidDateTimeUnit(smallestUnit)) {
             return null;
         }

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

@@ -12,20 +12,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
  *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
  *   their current value. An empty object is a no-op.
- * - `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 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", 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")
+ * @param options optional: how `value` is read, and how an out-of-range field or a skipped or repeated wall-clock time is resolved
  * @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)
@@ -36,9 +28,43 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example setUnix(NaN, { hour: 9 }) // null
  */
 export declare function setUnix(value: number | string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the fields are set in: an IANA name, a UTC offset, or `"local"` for the system
+     * time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * How an out-of-range field is handled, such as `month: 2` on a value whose day is 31.
+     * `"constrain"` clamps to the nearest valid value, and `"reject"` returns `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
+    /**
+     * How a wall-clock time that a zone transition skips or repeats is resolved, once `offset` does
+     * not settle it. `"compatible"` takes the later time in a gap and the earlier of a repeat,
+     * `"earlier"` and `"later"` take that side, and `"reject"` returns `null`.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
     disambiguation?: Disambiguation;
+    /**
+     * How the source's UTC offset is weighed against the new wall-clock time, as in
+     * `Temporal.ZonedDateTime.prototype.with`. `"prefer"` keeps it while it is still valid, so a
+     * repeated hour stays on the same side of a fall-back, and `"use"` keeps it always. `"ignore"`
+     * re-resolves the wall clock with `disambiguation`, and `"reject"` returns `null` when the
+     * offset is no longer valid.
+     *
+     * @defaultValue `"prefer"`, Temporal's default.
+     */
     offset?: Offset;
 }): number | null;

package/dist/unix/calculate/setUnix.js

@@ -2,6 +2,7 @@ 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";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return a Unix epoch value with the given `fields` set on `value`, interpreted in `timeZone`.
  *
@@ -13,20 +14,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
  *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
  *   their current value. An empty object is a no-op.
- * - `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 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", 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")
+ * @param options optional: how `value` is read, and how an out-of-range field or a skipped or repeated wall-clock time is resolved
  * @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)
@@ -49,11 +42,9 @@ export function setUnix(value, fields, options) {
         if (instant === null)
             return null;
         const overflow = resolveOverflow(options?.overflow);
-        const disambiguation = options?.disambiguation === undefined
-            ? "compatible"
-            : options.disambiguation;
+        const disambiguation = optionOrDefault(options?.disambiguation, "compatible");
         // Temporal ZonedDateTime.prototype.with: GetTemporalOffsetOption(options, "prefer").
-        const offset = options?.offset === undefined ? "prefer" : options.offset;
+        const offset = optionOrDefault(options?.offset, "prefer");
         try {
             const zoned = instant.toZonedDateTimeISO(timeZone);
             // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported

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

@@ -9,11 +9,9 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   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 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")
+ * @param options optional: how `value` is read and the zone the quarter is found in
  * @returns Unix epoch number representing the start of the quarter, or null on invalid input
  *
  * @example startOfQuarterForUnix(1706659200000, { timeZone: "UTC" }) // 1704067200000
@@ -23,6 +21,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example startOfQuarterForUnix(NaN) // null
  */
 export declare function startOfQuarterForUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/unix/calculate/startOfQuarterForUnix.js

@@ -10,11 +10,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   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 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")
+ * @param options optional: how `value` is read and the zone the quarter is found in
  * @returns Unix epoch number representing the start of the quarter, or null on invalid input
  *
  * @example startOfQuarterForUnix(1706659200000, { timeZone: "UTC" }) // 1704067200000

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

@@ -8,15 +8,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - 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 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", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
+ * @param options optional: how `value` is read, the zone the unit is found in and the first day of the week
  * @returns Unix epoch number representing the start of the unit, or null on invalid input
  *
  * @example startOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1704067200000
@@ -29,7 +26,26 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example startOfUnix(NaN, "day") // null
  */
 export declare function startOfUnix(value: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * null, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/unix/calculate/startOfUnix.js

@@ -10,15 +10,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - 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 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", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
+ * @param options optional: how `value` is read, the zone the unit is found in and the first day of the week
  * @returns Unix epoch number representing the start of the unit, or null on invalid input
  *
  * @example startOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1704067200000

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

@@ -6,15 +6,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Converts to ZonedDateTime, subtracts 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. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
- *
  * @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 subtract
- * @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")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns Unix epoch number after subtraction, or null on invalid input
  *
  * @example subtractUnix(1706745600000, { days: 1 }) // 1706659200000
@@ -25,7 +21,25 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example subtractUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
  */
 export declare function subtractUnix(value: number | string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the calendar arithmetic runs in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * How a result day that does not exist in its month is handled, such as March 31 minus one
+     * month. `"constrain"` clamps to the last valid day, and `"reject"` returns `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): number | null;

package/dist/unix/calculate/subtractUnix.js

@@ -9,15 +9,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Converts to ZonedDateTime, subtracts 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. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
- *
  * @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 subtract
- * @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")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns Unix epoch number after subtraction, or null on invalid input
  *
  * @example subtractUnix(1706745600000, { days: 1 }) // 1706659200000

package/dist/unix/compare/areUnixEqual.d.ts

@@ -9,7 +9,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *
  * @param value1 first unix epoch: a safe integer or a digit string
  * @param value2 second unix epoch, in the same unit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how both epochs are read
  * @returns `true` if `value1` and `value2` are equal, otherwise `false`
  *
  * @example areUnixEqual(1706659200, 1706659200) // true
@@ -21,5 +21,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example areUnixEqual("1706659200.0", 1706659200) // false (not a digit string)
  */
 export declare function areUnixEqual(value1: number | string, value2: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `false`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): boolean;

package/dist/unix/compare/areUnixEqual.js

@@ -10,7 +10,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value1 first unix epoch: a safe integer or a digit string
  * @param value2 second unix epoch, in the same unit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how both epochs are read
  * @returns `true` if `value1` and `value2` are equal, otherwise `false`
  *
  * @example areUnixEqual(1706659200, 1706659200) // true

package/dist/unix/compare/areUnixEqualBy.d.ts

@@ -3,19 +3,17 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Compare two Unix epoch values for equality at a given unit.
  *
- * - Both values are resolved to the start of `unit` in `options.timeZone`
- *   (default: `"UTC"`) before comparison, so `"day"` compares
- *   calendar days in that zone, not raw epoch buckets.
+ * - Both values are resolved to the start of `unit` in `options.timeZone` before comparison,
+ *   so `"day"` compares calendar days in that zone, not raw epoch buckets.
  * - The start of `unit` is the real local bucket (see `startOfUnix`), so two epochs are equal
  *   only when they fall in the same bucket — including one a zone transition shortened, like
  *   `Pacific/Chatham`'s 15-minute 03:00 hour on its 2024 spring-forward.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
  * - Each value is a safe integer or a string of optionally negative ASCII digits; `unit` may be
- *   singular or plural. An omitted `timeZone` is UTC; `"local"` is the system zone.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
+ *   singular or plural.
  * - Returns false for an unsupported unit (including `"quarter"`) or invalid input.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
@@ -23,7 +21,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @param value1 first Unix epoch: a safe integer or a digit string
  * @param value2 second Unix epoch, in the same unit
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
+ * @param options optional: how both epochs are read, the zone the unit is found in and the first day of the week
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUnixEqualBy(1710498000000, 1710503000000, "day", { timeZone: "UTC" }) // true (both fall on 2024-03-15 in UTC)
@@ -32,7 +30,26 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
  */
 export declare function areUnixEqualBy(value1: number | string, value2: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `false`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `false`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * false, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): boolean;

package/dist/unix/compare/areUnixEqualBy.js

@@ -3,19 +3,17 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Compare two Unix epoch values for equality at a given unit.
  *
- * - Both values are resolved to the start of `unit` in `options.timeZone`
- *   (default: `"UTC"`) before comparison, so `"day"` compares
- *   calendar days in that zone, not raw epoch buckets.
+ * - Both values are resolved to the start of `unit` in `options.timeZone` before comparison,
+ *   so `"day"` compares calendar days in that zone, not raw epoch buckets.
  * - The start of `unit` is the real local bucket (see `startOfUnix`), so two epochs are equal
  *   only when they fall in the same bucket — including one a zone transition shortened, like
  *   `Pacific/Chatham`'s 15-minute 03:00 hour on its 2024 spring-forward.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
  * - Each value is a safe integer or a string of optionally negative ASCII digits; `unit` may be
- *   singular or plural. An omitted `timeZone` is UTC; `"local"` is the system zone.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
+ *   singular or plural.
  * - Returns false for an unsupported unit (including `"quarter"`) or invalid input.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
@@ -23,7 +21,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 first Unix epoch: a safe integer or a digit string
  * @param value2 second Unix epoch, in the same unit
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
+ * @param options optional: how both epochs are read, the zone the unit is found in and the first day of the week
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUnixEqualBy(1710498000000, 1710503000000, "day", { timeZone: "UTC" }) // true (both fall on 2024-03-15 in UTC)
@@ -36,8 +34,14 @@ export function areUnixEqualBy(value1, value2, unit, options) {
         return false;
     }
     try {
-        const start1 = startOfUnix(value1, unit, options);
-        const start2 = startOfUnix(value2, unit, options);
+        // Each option is read once (GetOption); both values are then measured with the same ones.
+        const read = {
+            epochUnit: options?.epochUnit,
+            timeZone: options?.timeZone,
+            weekStartsOn: options?.weekStartsOn,
+        };
+        const start1 = startOfUnix(value1, unit, read);
+        const start2 = startOfUnix(value2, unit, read);
         return start1 !== null && start1 === start2;
     }
     catch {

package/dist/unix/compare/isAfterUnix.d.ts

@@ -9,7 +9,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *
  * @param value1 first unix epoch: a safe integer or a digit string
  * @param value2 second unix epoch, in the same unit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how both epochs are read
  * @returns `true` if `value1` is after `value2`, otherwise `false`
  *
  * @example isAfterUnix(1706659200, 1704067200) // true
@@ -19,5 +19,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example isAfterUnix(" 1706659200", 1704067200) // false (a padded string is not an epoch)
  */
 export declare function isAfterUnix(value1: number | string, value2: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `false`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): boolean;