@northguild/gmt 1.17.0 → 1.19.0

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,23 +5,30 @@ 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).
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch 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 +39,39 @@ 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 (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * How a result day that does not exist in its month is handled, such as 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

@@ -1,8 +1,7 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDuration } from "../../duration/validate/index.js";
-import { addToZoned, resolveOverflow, subtractFromZoned } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { addToZoned, frameInstant, frameZoned, normalizeZoneFrame, resolveOverflow, subtractFromZoned, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -10,23 +9,30 @@ 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).
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch 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 }
@@ -48,8 +54,8 @@ export function intervalFromDurationUnix(value, duration, anchor, options) {
             return null;
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (!timeZone || epochUnit === null) {
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null || epochUnit === null) {
             return null;
         }
         const instant = unixEpochToInstant(value, epochUnit);
@@ -57,7 +63,7 @@ export function intervalFromDurationUnix(value, duration, anchor, options) {
             return null;
         }
         try {
-            const point = instant.toZonedDateTimeISO(timeZone);
+            const point = frameZoned(instant, frame);
             const dur = Temporal.Duration.from(duration);
             const overflow = resolveOverflow(options?.overflow);
             const other = anchor === "start"
@@ -69,8 +75,8 @@ export function intervalFromDurationUnix(value, duration, anchor, options) {
                 return null;
             }
             return {
-                start: toUnixEpoch(start, epochUnit),
-                end: toUnixEpoch(end, epochUnit),
+                start: toUnixEpoch(frameInstant(start, frame), epochUnit),
+                end: toUnixEpoch(frameInstant(end, frame), epochUnit),
             };
         }
         catch {

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,21 +4,25 @@ 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
  *   one, or lies outside the Temporal instant range, `start > end`, an unsupported unit, an invalid
  *   `epochUnit` or an unknown `timeZone`).
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param 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 +35,20 @@ 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 (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/interval/intervalLengthUnix.js

@@ -7,21 +7,25 @@ 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
  *   one, or lies outside the Temporal instant range, `start > end`, an unsupported unit, an invalid
  *   `epochUnit` or an unknown `timeZone`).
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param 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).
@@ -26,12 +24,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   24-hour periods instead of counting calendar dates. To reproduce date-fns's number,
  *   compose `intervalIntersectionUnix` with `intervalCountUnix`:
  *   `const span = intervalIntersectionUnix(aStart, aEnd, bStart, bEnd); span ? intervalCountUnix(span.start, span.end, "day") : 0;`
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
  * @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 +47,20 @@ 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 (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/interval/intervalOverlappingDaysUnix.js

@@ -1,5 +1,4 @@
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { countZonedLocalDates, halfOpenIntersection, parseUnixEpochInterval, } from "../../internal/index.js";
+import { countZonedLocalDates, frameZoned, halfOpenIntersection, normalizeZoneFrame, parseUnixEpochInterval, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -9,8 +8,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).
@@ -29,12 +26,18 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   24-hour periods instead of counting calendar dates. To reproduce date-fns's number,
  *   compose `intervalIntersectionUnix` with `intervalCountUnix`:
  *   `const span = intervalIntersectionUnix(aStart, aEnd, bStart, bEnd); span ? intervalCountUnix(span.start, span.end, "day") : 0;`
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
  * @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)
@@ -58,8 +61,8 @@ export function intervalOverlappingDaysUnix(aStart, aEnd, bStart, bEnd, options)
         const { start: a1, end: a2 } = a;
         const { start: b1, end: b2 } = b;
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (!timeZone || epochUnit === null) {
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null || epochUnit === null) {
             return null;
         }
         const overlap = halfOpenIntersection({ start: a1, end: a2 }, { start: b1, end: b2 }, (left, right) => left - right);
@@ -79,7 +82,7 @@ export function intervalOverlappingDaysUnix(aStart, aEnd, bStart, bEnd, options)
         try {
             // The last instant the half-open intersection holds is one nanosecond before its end, so the
             // closed local-date count runs to there.
-            return countZonedLocalDates(first.toZonedDateTimeISO(timeZone), afterLast.toZonedDateTimeISO(timeZone).subtract({ nanoseconds: 1 }));
+            return countZonedLocalDates(frameZoned(first, frame), frameZoned(afterLast, frame).subtract({ nanoseconds: 1 }));
         }
         catch {
             return null;

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;
 }>;