@northguild/gmt 1.17.0 → 1.19.0

package/dist/unix/format/formatUnix.js

@@ -3,16 +3,14 @@ import { formatWallClockOrZoned } from "../../internal/instantFormatOptions.js";
 import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Format a unix epoch value (string or number) as a localized date/time string.
  *
  * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
- * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
  * - `value` is a safe integer or a string of optionally negative ASCII digits (no whitespace, `+`,
- *   decimal point or exponent); `epochUnit` also accepts `"second"` / `"millisecond"`.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`, `"local"` is the
- *   system zone, and an unknown zone returns `""` (ECMA-402 throws RangeError for it).
- * - `includeTimeZoneName` appends the localized timezone name when true.
+ *   decimal point or exponent).
  * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
  *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
  *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
@@ -22,10 +20,14 @@ import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEp
  *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
  *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
  * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
+ * - An offset with seconds (`-00:44:30`) returns `""`. `Intl.DateTimeFormat` takes a time zone
+ *   identifier only: constructing one with an offset that has seconds throws (ECMA-402, the
+ *   `DateTimeFormat` construction step "If parseResult contains more than one MinuteSecond Parse
+ *   Node, throw a RangeError exception"). Pass the IANA name.
  *
  * @param value unix epoch value to format (string or number, per `epochUnit`)
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { epochUnit, timeZone, includeTimeZoneName }
+ * @param options optional: `Intl.DateTimeFormatOptions` fields, plus how `value` is read, the zone and whether its name is shown
  * @returns the formatted date/time string, or "" on invalid input
  *
  * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
@@ -48,7 +50,10 @@ export function formatUnix(value, locale, options) {
         // ECMA-402 CoerceOptionsToObject: undefined is defaults; null is a TypeError.
         if (options === null)
             return "";
-        const { epochUnit, timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        // Each option is read once (GetOption), inherited ones included.
+        const epochUnit = options?.epochUnit;
+        const includeTimeZoneName = optionOrDefault(options?.includeTimeZoneName, false);
+        const { timeZone, ...intlOptions } = readDateTimeFormatOptions(options);
         const resolvedUnit = resolveUnixEpochUnit(epochUnit);
         if (resolvedUnit === null)
             return "";

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current day string (zero-padded to 2 digits) or "" on failure
+ * @returns current day string (zero-padded to 2 digits)
  *
  * @example getUnixDay() // "29"
- * @example getUnixDay() // "" (on failure)
  */
 export declare function getUnixDay(): string;

package/dist/unix/get/getUnixDay.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current day string (zero-padded to 2 digits) or "" on failure
+ * @returns current day string (zero-padded to 2 digits)
  *
  * @example getUnixDay() // "29"
- * @example getUnixDay() // "" (on failure)
  */
 export function getUnixDay() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .day.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .day.toString()
+        .padStart(2, "0");
 }

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current hour string (zero-padded to 2 digits) or "" on failure
+ * @returns current hour string (zero-padded to 2 digits)
  *
  * @example getUnixHour() // "00"
- * @example getUnixHour() // "" (on failure)
  */
 export declare function getUnixHour(): string;

package/dist/unix/get/getUnixHour.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current hour string (zero-padded to 2 digits) or "" on failure
+ * @returns current hour string (zero-padded to 2 digits)
  *
  * @example getUnixHour() // "00"
- * @example getUnixHour() // "" (on failure)
  */
 export function getUnixHour() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .hour.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .hour.toString()
+        .padStart(2, "0");
 }

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current microsecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current microsecond string (zero-padded to 3 digits)
  *
  * @example getUnixMicrosecond() // "456"
- * @example getUnixMicrosecond() // "" (on failure)
  */
 export declare function getUnixMicrosecond(): string;

package/dist/unix/get/getUnixMicrosecond.js

@@ -4,20 +4,13 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current microsecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current microsecond string (zero-padded to 3 digits)
  *
  * @example getUnixMicrosecond() // "456"
- * @example getUnixMicrosecond() // "" (on failure)
  */
 export function getUnixMicrosecond() {
-    try {
-        return (Temporal.Now.instant().toZonedDateTimeISO("UTC").microsecond ?? 0)
-            .toString()
-            .padStart(3, "0");
-    }
-    catch {
-        return "";
-    }
+    return (Temporal.Now.instant().toZonedDateTimeISO("UTC").microsecond ?? 0)
+        .toString()
+        .padStart(3, "0");
 }

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current millisecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current millisecond string (zero-padded to 3 digits)
  *
  * @example getUnixMillisecond() // "123"
- * @example getUnixMillisecond() // "" (on failure)
  */
 export declare function getUnixMillisecond(): string;

package/dist/unix/get/getUnixMillisecond.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current millisecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current millisecond string (zero-padded to 3 digits)
  *
  * @example getUnixMillisecond() // "123"
- * @example getUnixMillisecond() // "" (on failure)
  */
 export function getUnixMillisecond() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .millisecond.toString()
-            .padStart(3, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .millisecond.toString()
+        .padStart(3, "0");
 }

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current minute string (zero-padded to 2 digits) or "" on failure
+ * @returns current minute string (zero-padded to 2 digits)
  *
  * @example getUnixMinute() // "30"
- * @example getUnixMinute() // "" (on failure)
  */
 export declare function getUnixMinute(): string;

package/dist/unix/get/getUnixMinute.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current minute string (zero-padded to 2 digits) or "" on failure
+ * @returns current minute string (zero-padded to 2 digits)
  *
  * @example getUnixMinute() // "30"
- * @example getUnixMinute() // "" (on failure)
  */
 export function getUnixMinute() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .minute.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .minute.toString()
+        .padStart(2, "0");
 }

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current month string (zero-padded to 2 digits) or "" on failure
+ * @returns current month string (zero-padded to 2 digits)
  *
  * @example getUnixMonth() // "02"
- * @example getUnixMonth() // "" (on failure)
  */
 export declare function getUnixMonth(): string;

package/dist/unix/get/getUnixMonth.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current month string (zero-padded to 2 digits) or "" on failure
+ * @returns current month string (zero-padded to 2 digits)
  *
  * @example getUnixMonth() // "02"
- * @example getUnixMonth() // "" (on failure)
  */
 export function getUnixMonth() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .month.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .month.toString()
+        .padStart(2, "0");
 }

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current nanosecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current nanosecond string (zero-padded to 3 digits)
  *
  * @example getUnixNanosecond() // "789"
- * @example getUnixNanosecond() // "" (on failure)
  */
 export declare function getUnixNanosecond(): string;

package/dist/unix/get/getUnixNanosecond.js

@@ -4,20 +4,13 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current nanosecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current nanosecond string (zero-padded to 3 digits)
  *
  * @example getUnixNanosecond() // "789"
- * @example getUnixNanosecond() // "" (on failure)
  */
 export function getUnixNanosecond() {
-    try {
-        return (Temporal.Now.instant().toZonedDateTimeISO("UTC").nanosecond ?? 0)
-            .toString()
-            .padStart(3, "0");
-    }
-    catch {
-        return "";
-    }
+    return (Temporal.Now.instant().toZonedDateTimeISO("UTC").nanosecond ?? 0)
+        .toString()
+        .padStart(3, "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/get/getUnixNowUnit.d.ts

@@ -8,6 +8,8 @@ export type { UnixNowUnit };
  * - `microsecond` and `nanosecond` are Temporal's 0–999 fields, zero-padded to 3 digits.
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns "" on invalid unit or failure.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param unit unit to extract from current unix timestamp
  * @returns string representation of the requested unit or "" on invalid

package/dist/unix/get/getUnixNowUnit.js

@@ -12,6 +12,8 @@ function isValidUnixNowUnit(unit) {
  * - `microsecond` and `nanosecond` are Temporal's 0–999 fields, zero-padded to 3 digits.
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns "" on invalid unit or failure.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param unit unit to extract from current unix timestamp
  * @returns string representation of the requested unit or "" on invalid

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current second string (zero-padded to 2 digits) or "" on failure
+ * @returns current second string (zero-padded to 2 digits)
  *
  * @example getUnixSecond() // "45"
- * @example getUnixSecond() // "" (on failure)
  */
 export declare function getUnixSecond(): string;

package/dist/unix/get/getUnixSecond.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current second string (zero-padded to 2 digits) or "" on failure
+ * @returns current second string (zero-padded to 2 digits)
  *
  * @example getUnixSecond() // "45"
- * @example getUnixSecond() // "" (on failure)
  */
 export function getUnixSecond() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .second.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .second.toString()
+        .padStart(2, "0");
 }

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

@@ -3,11 +3,11 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 4 digits.
- * - Returns "" on failure.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it at the head of a date.
  *
- * @returns current year string (zero-padded to 4 digits) or "" on failure
+ * @returns current year string (zero-padded to 4 digits)
  *
  * @example getUnixYear() // "2024"
- * @example getUnixYear() // "" (on failure)
  */
 export declare function getUnixYear(): string;

package/dist/unix/get/getUnixYear.js

@@ -1,24 +1,17 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the current year from the Unix timestamp in UTC as a zero-padded string.
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 4 digits.
- * - Returns "" on failure.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it at the head of a date.
  *
- * @returns current year string (zero-padded to 4 digits) or "" on failure
+ * @returns current year string (zero-padded to 4 digits)
  *
  * @example getUnixYear() // "2024"
- * @example getUnixYear() // "" (on failure)
  */
 export function getUnixYear() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .year.toString()
-            .padStart(4, "0");
-    }
-    catch {
-        return "";
-    }
+    return isoYearString(Temporal.Now.instant().toZonedDateTimeISO("UTC").year);
 }

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
@@ -24,11 +21,17 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - 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 the boundaries are found in
  * @returns number of unit boundaries touched, or null on invalid input
  *
  * @example intervalCountUnix(0, 86400000, "hour") // 24
@@ -38,8 +41,23 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example intervalCountUnix(1704151800000, 1704155400000, "day", { timeZone: "Asia/Tokyo" }) // 1 (08:30 to 09:30 on one Tokyo day)
  * @example intervalCountUnix("1704151800", "1704155400", "days", { epochUnit: "second" }) // 2
  * @example intervalCountUnix(NaN, 86400000, "hour") // null
+ * @example intervalCountUnix(2669999, 2670001, "day", { timeZone: "-00:44:30" }) // 2 (the local day turns at 00:44:30Z)
  */
 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 (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/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
@@ -27,11 +24,17 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - 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 the boundaries are found in
  * @returns number of unit boundaries touched, or null on invalid input
  *
  * @example intervalCountUnix(0, 86400000, "hour") // 24
@@ -41,6 +44,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example intervalCountUnix(1704151800000, 1704155400000, "day", { timeZone: "Asia/Tokyo" }) // 1 (08:30 to 09:30 on one Tokyo day)
  * @example intervalCountUnix("1704151800", "1704155400", "days", { epochUnit: "second" }) // 2
  * @example intervalCountUnix(NaN, 86400000, "hour") // null
+ * @example intervalCountUnix(2669999, 2670001, "day", { timeZone: "-00:44:30" }) // 2 (the local day turns at 00:44:30Z)
  */
 export function intervalCountUnix(start, end, unit, options) {
     try {

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