@northguild/gmt 1.16.0 → 1.18.0

package/dist/unix/interval/splitIntervalByUnitUnix.js

@@ -3,7 +3,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { 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,36 @@ 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.
  *
  * @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 +54,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 {
@@ -67,8 +70,10 @@ export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
             return [];
         }
         const { startVal, endVal, epochUnit } = pair;
-        // Temporal's plural duration field name, as the tiling steps add `{ [unit]: amount }`.
-        const resolvedUnit = resolveDurationUnit(pair.resolvedUnit);
+        // 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 [
                 {
@@ -79,11 +84,11 @@ export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
         }
         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),

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,18 @@ 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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseDateFromUnix.js

@@ -4,11 +4,10 @@ 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"

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,18 @@ 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, 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,18 @@ 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, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/unix/parse/parseDayOfWeekFromUnix.js

@@ -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

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,18 @@ 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, 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,18 @@ 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, 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,18 @@ 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, 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,18 @@ 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, 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"

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

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the month (1-12) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "month".
- * - `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 Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUnix(1700000000000, { timeZone: "UTC" }) // "11"
@@ -16,6 +16,18 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseMonthFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseMonthFromUnix(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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseMonthFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the month (1-12) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "month".
- * - `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 Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUnix(1700000000000, { timeZone: "UTC" }) // "11"

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

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the nanosecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
- * - `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 Nanosecond field (0-999), zero-padded to 3 digits ("000") as Temporal's `nanosecond` field, or "" on invalid input
  *
  * @example parseNanosecondFromUnix(1700000000000) // "000"
@@ -16,6 +16,18 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseNanosecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseNanosecondFromUnix(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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseNanosecondFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the nanosecond (0-999) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "nanosecond".
- * - `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 Nanosecond field (0-999), zero-padded to 3 digits ("000") as Temporal's `nanosecond` field, or "" on invalid input
  *
  * @example parseNanosecondFromUnix(1700000000000) // "000"

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

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the second (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "second".
- * - `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 Second (00-59) or "" on invalid input
  *
  * @example parseSecondFromUnix(1700000000000, { timeZone: "UTC" }) // "20"
@@ -15,6 +15,18 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseSecondFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseSecondFromUnix(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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseSecondFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the second (0-59) from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "second".
- * - `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 Second (00-59) or "" on invalid input
  *
  * @example parseSecondFromUnix(1700000000000, { timeZone: "UTC" }) // "20"

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

@@ -3,11 +3,10 @@ import type { UnixUnit } from "../validate/index.js";
  * Extract the time portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainTime.
- * - 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 time string (e.g., "14:30:45") or "" on invalid input
  *
  * @example parseTimeFromUnix(1700000000000, { timeZone: "UTC" }) // "22:13:20"
@@ -17,6 +16,18 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
  */
 export declare function parseTimeFromUnix(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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseTimeFromUnix.js

@@ -4,11 +4,10 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Extract the time portion from a unix epoch value.
  *
  * - Converts to ZonedDateTime then extracts the PlainTime.
- * - 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 time string (e.g., "14:30:45") or "" on invalid input
  *
  * @example parseTimeFromUnix(1700000000000, { timeZone: "UTC" }) // "22:13:20"