@northguild/gmt 1.16.0 → 1.18.0

package/dist/unix/get/getUnixNow.d.ts

@@ -3,12 +3,10 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * Return the current Unix timestamp in either seconds or milliseconds.
  *
  * - Uses Temporal.Now.instant() to get current time.
- * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
- *   `"milliseconds"`. Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
  * - An explicit `undefined` is the same as omitted. An unknown `epochUnit`, or a non-object
  *   `options` (such as a bare `"seconds"` string), returns null.
  *
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: the unit of the result
  * @returns the current unix timestamp, or null on invalid options
  *
  * @example getUnixNow() // 1700000000000
@@ -17,5 +15,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example getUnixNow("seconds" as never) // null (options must be an object)
  */
 export declare function getUnixNow(options?: {
+    /**
+     * The unit of the returned epoch: `"seconds"` or `"milliseconds"`, singular or plural. Seconds
+     * floor toward −∞, as POSIX `time_t` counts whole elapsed seconds. Any other value returns
+     * `null`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): number | null;

package/dist/unix/get/getUnixNow.js

@@ -4,12 +4,10 @@ import { resolveUnixEpochUnitOptions, toUnixEpoch, } from "../../internal/unixEp
  * Return the current Unix timestamp in either seconds or milliseconds.
  *
  * - Uses Temporal.Now.instant() to get current time.
- * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
- *   `"milliseconds"`. Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
  * - An explicit `undefined` is the same as omitted. An unknown `epochUnit`, or a non-object
  *   `options` (such as a bare `"seconds"` string), returns null.
  *
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: the unit of the result
  * @returns the current unix timestamp, or null on invalid options
  *
  * @example getUnixNow() // 1700000000000

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

@@ -7,10 +7,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
  * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
  *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
- * - Reads `start` and `end` in `options.epochUnit` (`"milliseconds"` by default, `"seconds"`; singular
- *   accepted). Each is a safe integer or a string of optionally negative ASCII digits.
- * - Uses `options.timeZone` for calendar-unit boundaries: omitted is `"UTC"`, `"local"` is the
- *   system zone, and an unknown zone returns `null`.
+ * - `start` and `end` are each a safe integer or a string of optionally negative ASCII digits.
  * - Counts the real local buckets `floorToZone`/`bucketRange` walk in that zone: a bucket
  *   shorter than its unit still counts once (a 15-minute `Pacific/Chatham` hour on its
  *   spring-forward), and a local day the zone deleted counts not at all
@@ -28,7 +25,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @param start Unix epoch in `epochUnit` — interval start
  * @param end Unix epoch in `epochUnit` — interval end
  * @param unit unit string — any `DateTimeUnit`, singular or plural
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how the epochs are read and the zone the boundaries are found in
  * @returns number of unit boundaries touched, or null on invalid input
  *
  * @example intervalCountUnix(0, 86400000, "hour") // 24
@@ -40,6 +37,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example intervalCountUnix(NaN, 86400000, "hour") // null
  */
 export declare function intervalCountUnix(start: number | string, end: number | string, unit: 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 unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/unix/interval/intervalCountUnix.js

@@ -10,10 +10,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
  * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
  *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
- * - Reads `start` and `end` in `options.epochUnit` (`"milliseconds"` by default, `"seconds"`; singular
- *   accepted). Each is a safe integer or a string of optionally negative ASCII digits.
- * - Uses `options.timeZone` for calendar-unit boundaries: omitted is `"UTC"`, `"local"` is the
- *   system zone, and an unknown zone returns `null`.
+ * - `start` and `end` are each a safe integer or a string of optionally negative ASCII digits.
  * - Counts the real local buckets `floorToZone`/`bucketRange` walk in that zone: a bucket
  *   shorter than its unit still counts once (a 15-minute `Pacific/Chatham` hour on its
  *   spring-forward), and a local day the zone deleted counts not at all
@@ -31,7 +28,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param start Unix epoch in `epochUnit` — interval start
  * @param end Unix epoch in `epochUnit` — interval end
  * @param unit unit string — any `DateTimeUnit`, singular or plural
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how the epochs are read and the zone the boundaries are found in
  * @returns number of unit boundaries touched, or null on invalid input
  *
  * @example intervalCountUnix(0, 86400000, "hour") // 24

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

@@ -28,6 +28,12 @@
  * @example intervalDifferenceUnix(5, 10, 0, 5) // [{ start: 5, end: 10 }] (B ends where A starts)
  */
 export declare function intervalDifferenceUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): Array<{
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: number;
 }>;

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

@@ -9,20 +9,21 @@
  *   milliseconds), taken in `bigint` so no product past 2^53 loses a unit: the split is exact
  *   whenever the total divides evenly by `n`, and within half a unit of the exact cut otherwise (an
  *   exact half rounds up). No time zone is involved.
+ * - When `n` is larger than the number of whole epoch units in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
  *   an empty `[start, start)` that holds no instant.
  * - Returns `[]` when `n` is not a positive integer, or 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 — or `start > end`).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - Returns `[]` before building any piece when `n` exceeds `options.maxPieces` or the longest
+ *   possible array (2^32 - 1).
  *
  * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
  * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional: the limit on the number of pieces
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyUnix(0, 90000000, 3) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
@@ -34,8 +35,21 @@
  * @example intervalDivideEquallyUnix(0, 90000000, 3, { maxPieces: 3 }) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
  */
 export declare function intervalDivideEquallyUnix(start: number | string, end: number | string, n: 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;
 }): Array<{
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. 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/intervalDivideEquallyUnix.js

@@ -13,20 +13,21 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *   milliseconds), taken in `bigint` so no product past 2^53 loses a unit: the split is exact
  *   whenever the total divides evenly by `n`, and within half a unit of the exact cut otherwise (an
  *   exact half rounds up). No time zone is involved.
+ * - When `n` is larger than the number of whole epoch units in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
  *   an empty `[start, start)` that holds no instant.
  * - Returns `[]` when `n` is not a positive integer, or 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 — or `start > end`).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - Returns `[]` before building any piece when `n` exceeds `options.maxPieces` or the longest
+ *   possible array (2^32 - 1).
  *
  * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
  * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional: the limit on the number of pieces
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyUnix(0, 90000000, 3) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]

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

@@ -5,15 +5,16 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *
  * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
  * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
- * - Converts to `ZonedDateTime` in `timeZone` (`"UTC"` by default, consistent with `addUnix`; `"local"`
- *   is the system zone), adds/subtracts
+ * - Converts to `ZonedDateTime` in `timeZone`, adds/subtracts
  *   the duration there, then converts back to epoch — this is what lets calendar units (years/months/
  *   weeks/days) resolve without a `relativeTo`: unlike a bare `Temporal.Instant`, the `ZonedDateTime`
  *   supplies its own implicit reference point.
+ * - The computed boundary is floored to a whole `epochUnit`, so a duration shorter than one unit does
+ *   not survive: with `anchor: "start"` the interval is empty (`"PT0.5S"` in seconds gives the
+ *   same `{ start, end }` as `"PT0S"`), and with `anchor: "end"` the start falls back to the
+ *   previous whole unit, making the interval one unit long.
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionUnix`'s `start > end` rejection.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
  * - Returns null on invalid input (a `value` that is not a safe integer or numeric string of one —
  *   fractions, empty strings and values beyond ±(2^53 − 1) are invalid — invalid `duration`, an
  *   `anchor` other than `"start"`/`"end"`, or an invalid/unavailable timeZone).
@@ -21,7 +22,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @param value Unix epoch value (seconds or milliseconds): a safe integer or a digit string
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), overflow ("constrain" | "reject")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns `{ start, end }` with the constructed span (epoch numbers), or null on invalid input
  *
  * @example intervalFromDurationUnix(1704067200000, "P1D", "start", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }
@@ -32,10 +33,37 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example intervalFromDurationUnix(NaN, "P1D", "start") // null
  */
 export declare function intervalFromDurationUnix(value: number | string, duration: string, anchor: "start" | "end", options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the calendar arithmetic runs in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * How a result day that does not exist in its month is handled, such as January 31 plus one
+     * month. `"constrain"` clamps to the last valid day, and `"reject"` returns `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): {
+    /**
+     * 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;
 } | null;

package/dist/unix/interval/intervalFromDurationUnix.js

@@ -10,15 +10,16 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
  * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
- * - Converts to `ZonedDateTime` in `timeZone` (`"UTC"` by default, consistent with `addUnix`; `"local"`
- *   is the system zone), adds/subtracts
+ * - Converts to `ZonedDateTime` in `timeZone`, adds/subtracts
  *   the duration there, then converts back to epoch — this is what lets calendar units (years/months/
  *   weeks/days) resolve without a `relativeTo`: unlike a bare `Temporal.Instant`, the `ZonedDateTime`
  *   supplies its own implicit reference point.
+ * - The computed boundary is floored to a whole `epochUnit`, so a duration shorter than one unit does
+ *   not survive: with `anchor: "start"` the interval is empty (`"PT0.5S"` in seconds gives the
+ *   same `{ start, end }` as `"PT0S"`), and with `anchor: "end"` the start falls back to the
+ *   previous whole unit, making the interval one unit long.
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionUnix`'s `start > end` rejection.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
  * - Returns null on invalid input (a `value` that is not a safe integer or numeric string of one —
  *   fractions, empty strings and values beyond ±(2^53 − 1) are invalid — invalid `duration`, an
  *   `anchor` other than `"start"`/`"end"`, or an invalid/unavailable timeZone).
@@ -26,7 +27,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value Unix epoch value (seconds or milliseconds): a safe integer or a digit string
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), overflow ("constrain" | "reject")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns `{ start, end }` with the constructed span (epoch numbers), or null on invalid input
  *
  * @example intervalFromDurationUnix(1704067200000, "P1D", "start", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }

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

@@ -26,6 +26,12 @@
  * @example intervalIntersectionUnix("0", "1700000000", "1000000", "2000000") // { start: 1000000, end: 2000000 }
  */
 export declare function intervalIntersectionUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): {
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. 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;
 } | null;

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

@@ -4,11 +4,9 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *
  * - Distinct from `intervalCountUnix`, which counts local calendar `unit` boundaries *crossed*
  *   rather than measuring exact duration.
- * - Reads `start` and `end` in `options.epochUnit` (`"milliseconds"` by default, `"seconds"`; singular
- *   accepted). Each is a safe integer or a string of optionally negative ASCII digits.
- * - Resolves calendar units in `options.timeZone`: omitted is `"UTC"`, `"local"` is the system
- *   zone, and an unknown zone returns `null`. Fixed-length units (hour, minute, second, …) are
- *   zone-independent; a day is a local day, so New York's 23-hour 2024-03-10 is 1 day long there.
+ * - `start` and `end` are each a safe integer or a string of optionally negative ASCII digits.
+ * - Fixed-length units (hour, minute, second, …) are zone-independent; a day is a local day in
+ *   `options.timeZone`, so New York's 23-hour 2024-03-10 is 1 day long there.
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
  * - Returns `0` for a zero-length interval (`start === end`).
  * - Returns `null` on invalid input (`start`/`end` that is not a safe integer or numeric string of
@@ -18,7 +16,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @param start Unix epoch in `epochUnit` — interval start
  * @param end Unix epoch in `epochUnit` — interval end
  * @param unit unit string — any `DateTimeUnit`, singular or plural
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how the epochs are read and the zone calendar units are measured in
  * @returns exact length of the interval expressed in `unit`, or null on invalid input
  *
  * @example intervalLengthUnix(0, 86400000, "hour") // 24
@@ -31,6 +29,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example intervalLengthUnix(NaN, 86400000, "hour") // null
  */
 export declare function intervalLengthUnix(start: number | string, end: number | string, unit: 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 calendar units are measured 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/interval/intervalLengthUnix.js

@@ -7,11 +7,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - Distinct from `intervalCountUnix`, which counts local calendar `unit` boundaries *crossed*
  *   rather than measuring exact duration.
- * - Reads `start` and `end` in `options.epochUnit` (`"milliseconds"` by default, `"seconds"`; singular
- *   accepted). Each is a safe integer or a string of optionally negative ASCII digits.
- * - Resolves calendar units in `options.timeZone`: omitted is `"UTC"`, `"local"` is the system
- *   zone, and an unknown zone returns `null`. Fixed-length units (hour, minute, second, …) are
- *   zone-independent; a day is a local day, so New York's 23-hour 2024-03-10 is 1 day long there.
+ * - `start` and `end` are each a safe integer or a string of optionally negative ASCII digits.
+ * - Fixed-length units (hour, minute, second, …) are zone-independent; a day is a local day in
+ *   `options.timeZone`, so New York's 23-hour 2024-03-10 is 1 day long there.
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
  * - Returns `0` for a zero-length interval (`start === end`).
  * - Returns `null` on invalid input (`start`/`end` that is not a safe integer or numeric string of
@@ -21,7 +19,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param start Unix epoch in `epochUnit` — interval start
  * @param end Unix epoch in `epochUnit` — interval end
  * @param unit unit string — any `DateTimeUnit`, singular or plural
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how the epochs are read and the zone calendar units are measured in
  * @returns exact length of the interval expressed in `unit`, or null on invalid input
  *
  * @example intervalLengthUnix(0, 86400000, "hour") // 24

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

@@ -6,8 +6,6 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Counts the local dates that hold at least one instant of the half-open intersection
  *   `[max(aStart, bStart), min(aEnd, bEnd))`. The end is excluded, so an intersection ending at
  *   local midnight does not touch the date that midnight starts.
- * - Uses `"UTC"` by default (consistent with `addUnix` and `intervalCountUnix`); `"local"` is the
- *   system zone and an unknown zone returns `null`.
  * - Each instant in the intersection contributes its own local date in `timeZone`, and each date
  *   counts once. A date the zone deleted is not counted (`Pacific/Apia` skipped 2011-12-30), and a
  *   fall-back into the previous date does not lose that date (`America/Goose_Bay`, 2010-11-07).
@@ -31,7 +29,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
  * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
  * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how the epochs are read and the zone the dates are counted in
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
  * @example intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // 1 (the intersection [86400000, 172800000) is 1970-01-02)
@@ -43,6 +41,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example intervalOverlappingDaysUnix(NaN, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // null
  */
 export declare function intervalOverlappingDaysUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: 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 calendar dates are counted 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/interval/intervalOverlappingDaysUnix.js

@@ -9,8 +9,6 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Counts the local dates that hold at least one instant of the half-open intersection
  *   `[max(aStart, bStart), min(aEnd, bEnd))`. The end is excluded, so an intersection ending at
  *   local midnight does not touch the date that midnight starts.
- * - Uses `"UTC"` by default (consistent with `addUnix` and `intervalCountUnix`); `"local"` is the
- *   system zone and an unknown zone returns `null`.
  * - Each instant in the intersection contributes its own local date in `timeZone`, and each date
  *   counts once. A date the zone deleted is not counted (`Pacific/Apia` skipped 2011-12-30), and a
  *   fall-back into the previous date does not lose that date (`America/Goose_Bay`, 2010-11-07).
@@ -34,7 +32,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
  * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
  * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how the epochs are read and the zone the dates are counted in
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
  * @example intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // 1 (the intersection [86400000, 172800000) is 1970-01-02)

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

@@ -11,6 +11,8 @@
  *   each record's `end` is the next record's `start` and belongs only to that next record, so the
  *   pieces share no value and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
+ * - A piece's `end` equals its `start` only when the interval itself is zero-length (`start`
+ *   equal to `end`): the result is then that one empty piece, whatever the points.
  * - Returns `[]` when `points` is not an array, or when `start`, `end` or any point is not a safe
  *   integer (or numeric string of one) — fractions, empty strings and values beyond ±(2^53 − 1)
  *   are invalid even when they would fall outside the interval — or when `start > end`.
@@ -26,6 +28,12 @@
  * @example intervalSplitAtUnix(0, 100000, [50000.5]) // [] (fractional point)
  */
 export declare function intervalSplitAtUnix(start: number | string, end: number | string, points: Array<number | string>): Array<{
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. 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/intervalSplitAtUnix.js

@@ -12,6 +12,8 @@ import { parseUnixEpochInterval, parseUnixEpochValue } from "../../internal/inde
  *   each record's `end` is the next record's `start` and belongs only to that next record, so the
  *   pieces share no value and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
+ * - A piece's `end` equals its `start` only when the interval itself is zero-length (`start`
+ *   equal to `end`): the result is then that one empty piece, whatever the points.
  * - Returns `[]` when `points` is not an array, or when `start`, `end` or any point is not a safe
  *   integer (or numeric string of one) — fractions, empty strings and values beyond ±(2^53 − 1)
  *   are invalid even when they would fall outside the interval — or when `start > end`.

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

@@ -26,6 +26,12 @@
  * @example intervalUnionUnix("0", "1700000000", "1000000", "2000000") // { start: 0, end: 1700000000 }
  */
 export declare function intervalUnionUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): {
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: number;
 } | null;

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

@@ -25,6 +25,12 @@ export declare function intervalXorAllUnix(intervals: Array<{
     start: number | string;
     end: number | string;
 }>): Array<{
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: number;
 }>;

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

@@ -31,6 +31,12 @@
  * @example intervalXorUnix(0, 1, 0.5, 2) // [] (fractional epoch)
  */
 export declare function intervalXorUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): Array<{
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: number;
 }>;

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

@@ -26,6 +26,12 @@ export declare function mergeIntervalsUnix(intervals: Array<{
     start: number | string;
     end: number | string;
 }>): Array<{
+    /** The instant the interval begins at, as a Unix epoch number in the unit the arguments share. */
     start: number;
+    /**
+     * The first instant after the interval, in the same unit as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: number;
 }>;

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

@@ -7,34 +7,36 @@ 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.
  *
  * @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 +48,41 @@ 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, 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;
 }>;