@northguild/gmt 1.17.0 → 1.19.0

package/dist/unix/calculate/startOfQuarterForUnix.js

@@ -10,11 +10,15 @@ 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.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @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,18 @@ 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.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @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
@@ -27,9 +30,31 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @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
+ * @example startOfUnix(45870000, "day", { timeZone: "-00:44:30" }) // 2670000 (local midnight at a stored offset with seconds)
  */
 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 (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), 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,18 @@ 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.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @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,6 +32,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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
+ * @example startOfUnix(45870000, "day", { timeZone: "-00:44:30" }) // 2670000 (local midnight at a stored offset with seconds)
  */
 export function startOfUnix(value, unit, options) {
     try {

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

@@ -6,15 +6,17 @@ 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).
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @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 +27,27 @@ 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 (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), 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

@@ -1,5 +1,4 @@
-import { subtractFromZoned, isValidAmount, resolveOverflow, } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameInstant, frameZoned, normalizeZoneFrame, readDurationUnits, resolveOverflow, subtractFromZoned, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -9,15 +8,17 @@ 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).
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @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
@@ -33,15 +34,12 @@ export function subtractUnix(value, units, options) {
             return null;
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
+        const frame = normalizeZoneFrame(options?.timeZone);
         const overflow = resolveOverflow(options?.overflow);
-        if (!timeZone || epochUnit === null)
+        if (frame === null || 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) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (amounts === null) {
             return null;
         }
         const instant = unixEpochToInstant(value, epochUnit);
@@ -49,8 +47,8 @@ export function subtractUnix(value, units, options) {
             return null;
         }
         try {
-            const zdt = instant.toZonedDateTimeISO(timeZone);
-            return toUnixEpoch(subtractFromZoned(zdt, units, { overflow }), epochUnit);
+            const zdt = frameZoned(instant, frame);
+            return toUnixEpoch(frameInstant(subtractFromZoned(zdt, amounts, { overflow }), frame), epochUnit);
         }
         catch {
             return null;

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,36 +3,62 @@ 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")`
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `false`. There `false` is the sentinel,
+ *   not a comparison. An offset to the minute has no such limit.
  *
  * @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)
  * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
  * @example areUnixEqualBy("1710498000000", 1710503000000, "days") // true (digit string, plural unit, UTC by default)
  * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
+ * @example areUnixEqualBy(2669999, 2670000, "day", { timeZone: "-00:44:30" }) // false (the local day turns at 00:44:30Z)
  */
 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 (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), 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,41 +3,52 @@ 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")`
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `false`. There `false` is the sentinel,
+ *   not a comparison. An offset to the minute has no such limit.
  *
  * @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)
  * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
  * @example areUnixEqualBy("1710498000000", 1710503000000, "days") // true (digit string, plural unit, UTC by default)
  * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
+ * @example areUnixEqualBy(2669999, 2670000, "day", { timeZone: "-00:44:30" }) // false (the local day turns at 00:44:30Z)
  */
 export function areUnixEqualBy(value1, value2, unit, options) {
     if (!isOptionsArgument(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;

package/dist/unix/compare/isAfterUnix.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` is after `value2`, otherwise `false`
  *
  * @example isAfterUnix(1706659200, 1704067200) // true

package/dist/unix/compare/isBeforeUnix.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 before `value2`, otherwise `false`
  *
  * @example isBeforeUnix(1704067200, 1706659200) // true
@@ -20,5 +20,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example isBeforeUnix("-1", "0") // true (digit strings)
  */
 export declare function isBeforeUnix(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/isBeforeUnix.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` is before `value2`, otherwise `false`
  *
  * @example isBeforeUnix(1704067200, 1706659200) // true

package/dist/unix/convert/convertUnixToPlainDate.d.ts

@@ -2,15 +2,13 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to PlainDate in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainDate in `timeZone`.
  * - `unix` is a safe integer or a string of optionally negative ASCII digits; anything else returns
  *   "".
- * - Validates epoch unit ("seconds" | "milliseconds", singular accepted).
  * - Returns "" for invalid input.
  *
  * @param unix Unix epoch: a safe integer or a digit string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how `unix` is read and the zone its wall clock is read in
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "UTC" }) // "2024-02-29"
@@ -20,8 +18,23 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example convertUnixToPlainDate(NaN) // ""
+ * @example convertUnixToPlainDate(1800000, { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainDate(unix: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/convert/convertUnixToPlainDate.js

@@ -1,19 +1,17 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to PlainDate in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainDate in `timeZone`.
  * - `unix` is a safe integer or a string of optionally negative ASCII digits; anything else returns
  *   "".
- * - Validates epoch unit ("seconds" | "milliseconds", singular accepted).
  * - Returns "" for invalid input.
  *
  * @param unix Unix epoch: a safe integer or a digit string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how `unix` is read and the zone its wall clock is read in
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "UTC" }) // "2024-02-29"
@@ -23,6 +21,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example convertUnixToPlainDate(NaN) // ""
+ * @example convertUnixToPlainDate(1800000, { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export function convertUnixToPlainDate(unix, options) {
     try {
@@ -30,14 +29,14 @@ export function convertUnixToPlainDate(unix, options) {
             return "";
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (epochUnit === null || !timeZone)
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (epochUnit === null || frame === null)
             return "";
         const instant = unixEpochToInstant(unix, epochUnit);
         if (instant === null)
             return "";
         try {
-            return instant.toZonedDateTimeISO(timeZone).toPlainDate().toString();
+            return frameWallClock(instant, frame).toPlainDate().toString();
         }
         catch {
             return "";

package/dist/unix/convert/convertUnixToPlainDateTime.d.ts

@@ -2,15 +2,13 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a Unix timestamp to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
- * - Converts to PlainDateTime in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainDateTime in `timeZone`.
  * - `unix` is a safe integer or a string of optionally negative ASCII digits; anything else returns
  *   "".
- * - Validates epoch unit ("seconds" | "milliseconds", singular accepted).
  * - Returns "" for invalid input.
  *
  * @param unix Unix epoch: a safe integer or a digit string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how `unix` is read and the zone its wall clock is read in
  * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
  *
  * @example convertUnixToPlainDateTime(1709164800000, { timeZone: "UTC" }) // "2024-02-29T00:00:00"
@@ -18,8 +16,23 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainDateTime(-1, { timeZone: "UTC" }) // "1969-12-31T23:59:59.999"
  * @example convertUnixToPlainDateTime("1709164800000", { timeZone: "Asia/Tokyo" }) // "2024-02-29T09:00:00"
  * @example convertUnixToPlainDateTime(NaN) // ""
+ * @example convertUnixToPlainDateTime(45870000, { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainDateTime(unix: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;