@northguild/gmt 1.17.0 → 1.19.0

package/dist/unix/interval/splitIntervalByUnitUnix.d.ts

@@ -7,34 +7,42 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   no value and together cover `[start, end)` exactly once.
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER` (boundaries are then floored to milliseconds).
  * - A calendar step that resolves to the same instant as the previous boundary (a deleted local
  *   day, such as 30 December 2011 in `Pacific/Apia`) is skipped, so no empty slice is produced.
  *   A step that goes backwards returns `[]`.
+ * - A step finer than `epochUnit` (500 milliseconds when the epochs are seconds, any microsecond
+ *   or nanosecond step shorter than a millisecond) cannot be written in that unit: its boundaries
+ *   floor to every whole unit from `start` to `end`, so the pieces are one `epochUnit` long and
+ *   none is empty. `maxPieces` counts those pieces.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (`start`/`end` that is not a safe integer or numeric string of
  *   one — fractions, empty strings and values beyond ±(2^53 − 1) are invalid — unsupported unit,
  *   non-positive amount, an invalid `epochUnit` or an unknown `timeZone`).
  *
- * - Reads `start` and `end`, and returns every boundary, in `options.epochUnit` (`"milliseconds"`
- *   by default, `"seconds"`; singular accepted). Each input is a safe integer or a string of
- *   optionally negative ASCII digits.
- * - Calendar-unit arithmetic runs in `options.timeZone`: omitted is `"UTC"`, `"local"` is the
- *   system zone, and an unknown zone returns `[]`.
+ * - `start` and `end` are each a safe integer or a string of optionally negative ASCII digits.
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
+ * - A split into more than `options.maxPieces` slices returns `[]`, decided from the span before
+ *   stepping where it can be, and otherwise as soon as slice `maxPieces + 1` is due.
+ * - **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 `[]`. An offset to the minute has no
+ *   such limit.
  *
  * @param start Unix epoch in `epochUnit` — interval start
  * @param end Unix epoch in `epochUnit` — interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`, singular or plural
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`), `epochUnit` ("seconds" | "milliseconds", singular accepted; default "milliseconds"), `timeZone` (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: the limit on the number of slices, how the epochs are read and the zone calendar steps run in
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
@@ -46,12 +54,43 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6, { maxPieces: 4 }) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
  * @example splitIntervalByUnitUnix(1710046800000, 1710216000000, "day", 1, { timeZone: "America/New_York" }) // [{ start: 1710046800000, end: 1710129600000 }, { start: 1710129600000, end: 1710216000000 }] (the first local day is 23 hours)
  * @example splitIntervalByUnitUnix("0", "86400", "hours", 12, { epochUnit: "second" }) // [{ start: 0, end: 43200 }, { start: 43200, end: 86400 }]
+ * @example splitIntervalByUnitUnix(0, 2, "millisecond", 500, { epochUnit: "seconds" }) // [{ start: 0, end: 1 }, { start: 1, end: 2 }] (a step finer than the epoch unit gives one-second pieces)
  */
 export declare function splitIntervalByUnitUnix(start: number | string, end: number | string, unit: string, amount: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `[]`. 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
+     * `[]`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): Array<{
+    /**
+     * The instant the interval begins at, as a Unix epoch number counted in `epochUnit`. A boundary
+     * that falls between two whole units is rounded down to the earlier one.
+     */
     start: number;
+    /**
+     * The first instant after the interval, counted in `epochUnit` and rounded as `start` is. It is
+     * exclusive: the interval holds everything from `start` up to but not including this value. It
+     * can equal `start`, which makes the interval empty.
+     */
     end: number;
 }>;

package/dist/unix/interval/splitIntervalByUnitUnix.js

@@ -1,9 +1,9 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveDurationUnit, tileByUnit } from "../../internal/index.js";
+import { frameInstant, resolveDurationUnit, tileByUnit } from "../../internal/index.js";
 import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
 import { resolveUnixIntervalPair } from "../../internal/resolveUnixIntervalPair.js";
-import { minSlicesForSpan } from "../../internal/splitStep.js";
+import { minSlicesForSpan, stepNoFinerThan } from "../../internal/splitStep.js";
 import { toUnixEpoch } from "../../internal/unixEpochValue.js";
 /**
  * Split a Unix epoch interval into sub-intervals of `amount × unit`.
@@ -13,34 +13,42 @@ import { toUnixEpoch } from "../../internal/unixEpochValue.js";
  *   no value and together cover `[start, end)` exactly once.
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER` (boundaries are then floored to milliseconds).
  * - A calendar step that resolves to the same instant as the previous boundary (a deleted local
  *   day, such as 30 December 2011 in `Pacific/Apia`) is skipped, so no empty slice is produced.
  *   A step that goes backwards returns `[]`.
+ * - A step finer than `epochUnit` (500 milliseconds when the epochs are seconds, any microsecond
+ *   or nanosecond step shorter than a millisecond) cannot be written in that unit: its boundaries
+ *   floor to every whole unit from `start` to `end`, so the pieces are one `epochUnit` long and
+ *   none is empty. `maxPieces` counts those pieces.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (`start`/`end` that is not a safe integer or numeric string of
  *   one — fractions, empty strings and values beyond ±(2^53 − 1) are invalid — unsupported unit,
  *   non-positive amount, an invalid `epochUnit` or an unknown `timeZone`).
  *
- * - Reads `start` and `end`, and returns every boundary, in `options.epochUnit` (`"milliseconds"`
- *   by default, `"seconds"`; singular accepted). Each input is a safe integer or a string of
- *   optionally negative ASCII digits.
- * - Calendar-unit arithmetic runs in `options.timeZone`: omitted is `"UTC"`, `"local"` is the
- *   system zone, and an unknown zone returns `[]`.
+ * - `start` and `end` are each a safe integer or a string of optionally negative ASCII digits.
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
+ * - A split into more than `options.maxPieces` slices returns `[]`, decided from the span before
+ *   stepping where it can be, and otherwise as soon as slice `maxPieces + 1` is due.
+ * - **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 `[]`. An offset to the minute has no
+ *   such limit.
  *
  * @param start Unix epoch in `epochUnit` — interval start
  * @param end Unix epoch in `epochUnit` — interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`, singular or plural
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`), `epochUnit` ("seconds" | "milliseconds", singular accepted; default "milliseconds"), `timeZone` (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: the limit on the number of slices, how the epochs are read and the zone calendar steps run in
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
@@ -52,6 +60,7 @@ import { toUnixEpoch } from "../../internal/unixEpochValue.js";
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6, { maxPieces: 4 }) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
  * @example splitIntervalByUnitUnix(1710046800000, 1710216000000, "day", 1, { timeZone: "America/New_York" }) // [{ start: 1710046800000, end: 1710129600000 }, { start: 1710129600000, end: 1710216000000 }] (the first local day is 23 hours)
  * @example splitIntervalByUnitUnix("0", "86400", "hours", 12, { epochUnit: "second" }) // [{ start: 0, end: 43200 }, { start: 43200, end: 86400 }]
+ * @example splitIntervalByUnitUnix(0, 2, "millisecond", 500, { epochUnit: "seconds" }) // [{ start: 0, end: 1 }, { start: 1, end: 2 }] (a step finer than the epoch unit gives one-second pieces)
  */
 export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
     try {
@@ -66,27 +75,29 @@ export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
         if (maxPieces === null) {
             return [];
         }
-        const { startVal, endVal, epochUnit } = pair;
-        // Temporal's plural duration field name, as the tiling steps add `{ [unit]: amount }`.
-        const resolvedUnit = resolveDurationUnit(pair.resolvedUnit);
+        const { startVal, endVal, epochUnit, frame } = pair;
+        // Temporal's plural duration field name, as the tiling steps add `{ [unit]: amount }`. A step
+        // finer than the epoch unit would floor neighbouring boundaries to one value (an empty slice),
+        // so it steps by one epoch unit instead.
+        const [resolvedUnit, stepAmount] = stepNoFinerThan(resolveDurationUnit(pair.resolvedUnit), amount, epochUnit);
         if (startVal.epochNanoseconds === endVal.epochNanoseconds) {
             return [
                 {
-                    start: toUnixEpoch(startVal, epochUnit),
-                    end: toUnixEpoch(endVal, epochUnit),
+                    start: toUnixEpoch(frameInstant(startVal, frame), epochUnit),
+                    end: toUnixEpoch(frameInstant(endVal, frame), epochUnit),
                 },
             ];
         }
         try {
             const spanNs = Number(endVal.epochNanoseconds - startVal.epochNanoseconds);
-            if (exceedsPieceLimit(minSlicesForSpan(spanNs, resolvedUnit, amount, true), maxPieces)) {
+            if (exceedsPieceLimit(minSlicesForSpan(spanNs, resolvedUnit, stepAmount, true), maxPieces)) {
                 return [];
             }
             // Boundaries stay ZonedDateTime (nanosecond) values; only the output is floored to epochUnit.
-            const slices = tileByUnit(startVal, endVal, Temporal.ZonedDateTime.compare, resolvedUnit, amount, maxPieces);
+            const slices = tileByUnit(startVal, endVal, Temporal.ZonedDateTime.compare, resolvedUnit, stepAmount, maxPieces);
             return (slices ?? []).map(([sliceStart, sliceEnd]) => ({
-                start: toUnixEpoch(sliceStart, epochUnit),
-                end: toUnixEpoch(sliceEnd, epochUnit),
+                start: toUnixEpoch(frameInstant(sliceStart, frame), epochUnit),
+                end: toUnixEpoch(frameInstant(sliceEnd, frame), epochUnit),
             }));
         }
         catch {

package/dist/unix/parse/parseDateFromUnix.d.ts

@@ -3,11 +3,10 @@ import type { UnixUnit } from "../validate/index.js";
  * Extract the date portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainDate.
- * - Uses UTC if `timeZone` is not specified; `"local"` is the system time zone.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUnix(1700000000000, { timeZone: "UTC" }) // "2023-11-14"
@@ -17,6 +16,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseDateFromUnix(1.5) // "" (not an integer epoch)
  */
 export declare function parseDateFromUnix(value: 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/parse/parseDateFromUnix.js

@@ -1,14 +1,13 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the date portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainDate.
- * - Uses UTC if `timeZone` is not specified; `"local"` is the system time zone.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUnix(1700000000000, { timeZone: "UTC" }) // "2023-11-14"
@@ -22,8 +21,8 @@ export function parseDateFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
-        return zdt === null ? "" : zdt.toPlainDate().toString();
+        const wallClock = unixWallClock(value, options);
+        return wallClock === null ? "" : wallClock.toPlainDate().toString();
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/unix/parse/parseDayFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the day of month (1-31) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "day".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUnix(1700000000000, { timeZone: "UTC" }) // "14"
@@ -15,6 +15,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseDayFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseDayFromUnix(value: 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/parse/parseDayFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the day of month (1-31) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "day".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUnix(1700000000000, { timeZone: "UTC" }) // "14"

package/dist/unix/parse/parseDayOfWeekFromUnix.d.ts

@@ -6,7 +6,7 @@ import type { UnixUnit } from "../validate/index.js";
  * - Returns null for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
@@ -16,6 +16,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseDayOfWeekFromUnix("") // null (a blank string is not epoch 0)
  */
 export declare function parseDayOfWeekFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`.
+     *
+     * @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
+     * `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/unix/parse/parseDayOfWeekFromUnix.js

@@ -1,4 +1,4 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of week (1-7) from a unix epoch value.
@@ -7,7 +7,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Returns null for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
@@ -21,7 +21,7 @@ export function parseDayOfWeekFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        return unixZonedDateTime(value, options)?.dayOfWeek ?? null;
+        return unixWallClock(value, options)?.dayOfWeek ?? null;
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/unix/parse/parseHourFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the hour (0-23) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "hour".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUnix(1700000000000, { timeZone: "UTC" }) // "22"
@@ -15,6 +15,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseHourFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseHourFromUnix(value: 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/parse/parseHourFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the hour (0-23) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "hour".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUnix(1700000000000, { timeZone: "UTC" }) // "22"

package/dist/unix/parse/parseMicrosecondFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the microsecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "microsecond".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Microsecond (000-999) or "" on invalid input
  *
  * @example parseMicrosecondFromUnix(1700000000000) // "000"
@@ -15,6 +15,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseMicrosecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMicrosecondFromUnix(value: 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/parse/parseMicrosecondFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the microsecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "microsecond".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Microsecond (000-999) or "" on invalid input
  *
  * @example parseMicrosecondFromUnix(1700000000000) // "000"

package/dist/unix/parse/parseMillisecondFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the millisecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "millisecond".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Millisecond (000-999) or "" on invalid input
  *
  * @example parseMillisecondFromUnix(1700000000000) // "000"
@@ -15,6 +15,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseMillisecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMillisecondFromUnix(value: 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/parse/parseMillisecondFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the millisecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "millisecond".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Millisecond (000-999) or "" on invalid input
  *
  * @example parseMillisecondFromUnix(1700000000000) // "000"

package/dist/unix/parse/parseMinuteFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the minute (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "minute".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Minute (00-59) or "" on invalid input
  *
  * @example parseMinuteFromUnix(1700000000000, { timeZone: "UTC" }) // "13"
@@ -15,6 +15,20 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseMinuteFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMinuteFromUnix(value: 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/parse/parseMinuteFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the minute (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "minute".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: 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"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Minute (00-59) or "" on invalid input
  *
  * @example parseMinuteFromUnix(1700000000000, { timeZone: "UTC" }) // "13"