@northguild/gmt 1.17.0 → 1.18.0

package/dist/plain/parse/parseUnitFromDateTime.d.ts

@@ -8,13 +8,13 @@ import { Temporal } from "@js-temporal/polyfill";
  * - Returns zero-padded string for most units.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDateTime string
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"
@@ -26,5 +26,13 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example parseUnitFromDateTime("2024-01-01T00:00:00", "week", { weekStartsOn: "sunday" }) // "1"
  */
 export declare function parseUnitFromDateTime(value: string, unit: Temporal.SmallestUnit<"year" | "month" | "day" | "week" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"> | "dayOfWeek", optionsArg?: {
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/parse/parseUnitFromDateTime.js

@@ -14,13 +14,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Returns zero-padded string for most units.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDateTime string
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"

package/dist/plain/parse/parseWeekFromDate.d.ts

@@ -1,15 +1,11 @@
 /**
  * Return the week number for a given ISO 8601 date string.
  *
- * - By default uses ISO weeks (Monday-based).
- * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
- *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
- *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is the week of the week-year, 1–53, under either numbering — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value ISO date string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg How weeks are numbered
  * @returns Week number (1-53) or null on invalid input
  *
  * @example parseWeekFromDate("2024-01-01") // 1
@@ -20,5 +16,13 @@
  * @example parseWeekFromDate("2024-12-31", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromDate(value: string, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the week is numbered. `"monday"` gives the ISO 8601
+     * week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS #35 week
+     * number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other
+     * value returns `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/plain/parse/parseWeekFromDate.js

@@ -5,15 +5,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number for a given ISO 8601 date string.
  *
- * - By default uses ISO weeks (Monday-based).
- * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
- *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
- *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is the week of the week-year, 1–53, under either numbering — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value ISO date string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg How weeks are numbered
  * @returns Week number (1-53) or null on invalid input
  *
  * @example parseWeekFromDate("2024-01-01") // 1

package/dist/plain/parse/parseWeekFromDateTime.d.ts

@@ -1,15 +1,11 @@
 /**
  * Return the week number for a given ISO 8601 datetime string.
  *
- * - By default uses ISO weeks (Monday-based).
- * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
- *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
- *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is the week of the week-year, 1–53, under either numbering — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value ISO 8601 datetime string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg How weeks are numbered
  * @returns Week number (1-53) or null on invalid input
  *
  * @example parseWeekFromDateTime("2024-01-01T12:00:00") // 1
@@ -19,5 +15,13 @@
  * @example parseWeekFromDateTime("2024-12-31T12:00:00", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromDateTime(value: string, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the week is numbered. `"monday"` gives the ISO 8601
+     * week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS #35 week
+     * number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other
+     * value returns `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/plain/parse/parseWeekFromDateTime.js

@@ -6,15 +6,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number for a given ISO 8601 datetime string.
  *
- * - By default uses ISO weeks (Monday-based).
- * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
- *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
- *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is the week of the week-year, 1–53, under either numbering — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value ISO 8601 datetime string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg How weeks are numbered
  * @returns Week number (1-53) or null on invalid input
  *
  * @example parseWeekFromDateTime("2024-01-01T12:00:00") // 1

package/dist/plain/validate/isValidDateRange.d.ts

@@ -6,9 +6,27 @@
  * const range: IsValidDateRangeProps = { value1: "2024-02-28", value2: "2024-02-29" };
  */
 export interface IsValidDateRangeProps {
+    /**
+     * The start of the range, an ISO PlainDate string.
+     */
     value1: string;
+    /**
+     * The end of the range, an ISO PlainDate string.
+     */
     value2: string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Equal values are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` equal to `value2` is a valid range. `false` requires `value1` to be
+         * before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }
@@ -18,11 +36,8 @@ export interface IsValidDateRangeProps {
  * - Validates both dates with `isValidDate`, so each endpoint's RFC 9557 annotations are read as
  *   `Temporal.PlainDate.from` reads them (an elective `[foo=bar]` or `[u-ca=iso8601]` is ignored).
  * - Rejects leap seconds in either date.
- * - When `options.allowEqual` is true, equality is considered valid as well.
  *
- * @param value1 first ISO PlainDate string
- * @param value2 second ISO PlainDate string
- * @param options optional allowEqual flag
+ * @param props The two values to compare and how equal values are treated
  * @returns boolean indicating whether the date range is valid
  *
  * @example isValidDateRange({ value1: "2024-02-28", value2: "2024-02-29" }) // true

package/dist/plain/validate/isValidDateRange.js

@@ -7,11 +7,8 @@ import { isObject, isOptionsArgument } from "../../internal/isObject.js";
  * - Validates both dates with `isValidDate`, so each endpoint's RFC 9557 annotations are read as
  *   `Temporal.PlainDate.from` reads them (an elective `[foo=bar]` or `[u-ca=iso8601]` is ignored).
  * - Rejects leap seconds in either date.
- * - When `options.allowEqual` is true, equality is considered valid as well.
  *
- * @param value1 first ISO PlainDate string
- * @param value2 second ISO PlainDate string
- * @param options optional allowEqual flag
+ * @param props The two values to compare and how equal values are treated
  * @returns boolean indicating whether the date range is valid
  *
  * @example isValidDateRange({ value1: "2024-02-28", value2: "2024-02-29" }) // true

package/dist/plain/validate/isValidDateTimeRange.d.ts

@@ -1,15 +1,12 @@
 /**
  * Return true if `value1` and `value2` form a valid datetime range — both parseable as
- * ISO PlainDateTime strings and `value1 <= value2`.
+ * ISO PlainDateTime strings and `value1` before `value2`.
  *
  * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`), as
  *   `isValidDateTime` accepts, annotations included.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
- * @param value1 first ISO PlainDateTime string
- * @param value2 second ISO PlainDateTime string
- * @param options optional allowEqual flag
+ * @param props The two values to compare and how equal values are treated
  * @returns boolean indicating whether the datetime range is valid
  *
  * @example isValidDateTimeRange({ value1: "2024-01-01T10:00:00", value2: "2024-12-31T23:59:59" }) // true
@@ -17,9 +14,27 @@
  * @example isValidDateTimeRange({ value1: "2024-01-01T10:00:00", value2: "2024-01-01T10:00:00", options: { allowEqual: true } }) // true
  */
 export declare function isValidDateTimeRange(props: {
+    /**
+     * The start of the range, an ISO PlainDateTime string.
+     */
     value1: string;
+    /**
+     * The end of the range, an ISO PlainDateTime string.
+     */
     value2: string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Equal values are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` equal to `value2` is a valid range. `false` requires `value1` to be
+         * before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }): boolean;

package/dist/plain/validate/isValidDateTimeRange.js

@@ -4,16 +4,13 @@ import { isValidDateTime } from "./isValidDateTime.js";
 import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true if `value1` and `value2` form a valid datetime range — both parseable as
- * ISO PlainDateTime strings and `value1 <= value2`.
+ * ISO PlainDateTime strings and `value1` before `value2`.
  *
  * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`), as
  *   `isValidDateTime` accepts, annotations included.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
- * @param value1 first ISO PlainDateTime string
- * @param value2 second ISO PlainDateTime string
- * @param options optional allowEqual flag
+ * @param props The two values to compare and how equal values are treated
  * @returns boolean indicating whether the datetime range is valid
  *
  * @example isValidDateTimeRange({ value1: "2024-01-01T10:00:00", value2: "2024-12-31T23:59:59" }) // true

package/dist/plain/validate/isValidTimeRange.d.ts

@@ -1,16 +1,13 @@
 /**
  * Return true if `value1` and `value2` form a valid time range — both parseable as
- * ISO PlainTime strings and `value1 <= value2`.
+ * ISO PlainTime strings and `value1` before `value2`.
  *
  * - Both inputs must be ISO 8601 time strings (e.g. `"14:30:00"`), as `isValidTime` accepts,
  *   annotations included.
  * - Ordered by `Temporal.PlainTime.compare`, to the nanosecond.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
- * @param value1 first ISO PlainTime string
- * @param value2 second ISO PlainTime string
- * @param options optional allowEqual flag
+ * @param props The two values to compare and how equal values are treated
  * @returns boolean indicating whether the time range is valid
  *
  * @example isValidTimeRange({ value1: "09:00:00", value2: "17:00:00" }) // true
@@ -18,9 +15,27 @@
  * @example isValidTimeRange({ value1: "12:00:00", value2: "12:00:00", options: { allowEqual: true } }) // true
  */
 export declare function isValidTimeRange(props: {
+    /**
+     * The start of the range, an ISO PlainTime string.
+     */
     value1: string;
+    /**
+     * The end of the range, an ISO PlainTime string.
+     */
     value2: string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Equal values are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` equal to `value2` is a valid range. `false` requires `value1` to be
+         * before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }): boolean;

package/dist/plain/validate/isValidTimeRange.js

@@ -4,17 +4,14 @@ import { isValidTime } from "./isValidTime.js";
 import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true if `value1` and `value2` form a valid time range — both parseable as
- * ISO PlainTime strings and `value1 <= value2`.
+ * ISO PlainTime strings and `value1` before `value2`.
  *
  * - Both inputs must be ISO 8601 time strings (e.g. `"14:30:00"`), as `isValidTime` accepts,
  *   annotations included.
  * - Ordered by `Temporal.PlainTime.compare`, to the nanosecond.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
- * @param value1 first ISO PlainTime string
- * @param value2 second ISO PlainTime string
- * @param options optional allowEqual flag
+ * @param props The two values to compare and how equal values are treated
  * @returns boolean indicating whether the time range is valid
  *
  * @example isValidTimeRange({ value1: "09:00:00", value2: "17:00:00" }) // true

package/dist/precision/convert/fromExcelSerial.d.ts

@@ -7,9 +7,7 @@ import type { ExcelDateSystem } from "./toExcelSerial.js";
  *   that never existed. Lotus 1-2-3 treated 1900 as a leap year and Excel keeps the bug for
  *   compatibility, so the whole serial day `[60, 61)` is a hole: 59 is 1900-02-28 and 61 is
  *   1900-03-01. Mapping 60 to either neighbour would put every earlier date one day out.
- * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01 and
- *   which has no phantom day — serial 60 there is a real 1904-03-01. A 1904 serial resolves
- *   to the same instant as the 1900 serial exactly 1462 higher.
+ * - In the 1904 system serial 60 is a real 1904-03-01.
  * - Accepted range is Excel's own: serial 1 (1900-01-01) to just under 2958466 (the end of
  *   9999-12-31) in the 1900 system, serial 0 to just under 2957004 in the 1904 system.
  *   Serial 0 in the 1900 system is Excel's "January 0, 1900" placeholder, not a date.
@@ -19,7 +17,7 @@ import type { ExcelDateSystem } from "./toExcelSerial.js";
  * - Returns "" on invalid input.
  *
  * @param value Excel day serial (number, may carry a fractional time of day)
- * @param options optional: system ("1900" (default) | "1904")
+ * @param options Which Excel date system the serial is in
  * @returns ISO 8601 instant string (UTC), or "" on invalid input
  *
  * @example fromExcelSerial(1) // "1900-01-01T00:00:00Z" — Excel's first serial
@@ -34,5 +32,13 @@ import type { ExcelDateSystem } from "./toExcelSerial.js";
  * @example fromExcelSerial(-1) // ""
  */
 export declare function fromExcelSerial(value: number, options?: {
+    /**
+     * Which Excel date system the serial is counted in. `"1900"` counts serial 1 as 1900-01-01
+     * and has the phantom serial 60; `"1904"` is the legacy Mac system, whose serial 0 is
+     * 1904-01-01 and which has no phantom day. The same instant is exactly 1462 lower in the 1904
+     * system.
+     *
+     * @defaultValue `"1900"`
+     */
     system?: ExcelDateSystem;
 }): string;

package/dist/precision/convert/fromExcelSerial.js

@@ -1,6 +1,7 @@
 import { EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MILLISECONDS_PER_DAY, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, NANOSECONDS_PER_MILLISECOND, } from "../../internal/index.js";
 import { fromNanoseconds } from "./fromNanoseconds.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Convert an Excel day serial back to an ISO 8601 instant string.
  *
@@ -9,9 +10,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   that never existed. Lotus 1-2-3 treated 1900 as a leap year and Excel keeps the bug for
  *   compatibility, so the whole serial day `[60, 61)` is a hole: 59 is 1900-02-28 and 61 is
  *   1900-03-01. Mapping 60 to either neighbour would put every earlier date one day out.
- * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01 and
- *   which has no phantom day — serial 60 there is a real 1904-03-01. A 1904 serial resolves
- *   to the same instant as the 1900 serial exactly 1462 higher.
+ * - In the 1904 system serial 60 is a real 1904-03-01.
  * - Accepted range is Excel's own: serial 1 (1900-01-01) to just under 2958466 (the end of
  *   9999-12-31) in the 1900 system, serial 0 to just under 2957004 in the 1904 system.
  *   Serial 0 in the 1900 system is Excel's "January 0, 1900" placeholder, not a date.
@@ -21,7 +20,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Returns "" on invalid input.
  *
  * @param value Excel day serial (number, may carry a fractional time of day)
- * @param options optional: system ("1900" (default) | "1904")
+ * @param options Which Excel date system the serial is in
  * @returns ISO 8601 instant string (UTC), or "" on invalid input
  *
  * @example fromExcelSerial(1) // "1900-01-01T00:00:00Z" — Excel's first serial
@@ -40,7 +39,7 @@ export function fromExcelSerial(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const system = options?.system === undefined ? "1900" : options.system;
+        const system = optionOrDefault(options?.system, "1900");
         if (system !== "1900" && system !== "1904") {
             return "";
         }

package/dist/precision/convert/fromNanoseconds.d.ts

@@ -15,7 +15,7 @@
  * - Returns "" on invalid input.
  *
  * @param nanoseconds nanoseconds since the Unix epoch (bigint)
- * @param timeZone optional IANA timeZone identifier; omitted or `undefined` is UTC
+ * @param timeZone optional IANA name or UTC offset; omitted or `undefined` is UTC
  * @returns ISO 8601 instant string (UTC), zoned ISO 8601 string when a timeZone is given, or "" on invalid input
  *
  * @example fromNanoseconds(0n) // "1970-01-01T00:00:00Z"

package/dist/precision/convert/fromNanoseconds.js

@@ -18,7 +18,7 @@ import { isValidTimeZone } from "../../zoned/validate/index.js";
  * - Returns "" on invalid input.
  *
  * @param nanoseconds nanoseconds since the Unix epoch (bigint)
- * @param timeZone optional IANA timeZone identifier; omitted or `undefined` is UTC
+ * @param timeZone optional IANA name or UTC offset; omitted or `undefined` is UTC
  * @returns ISO 8601 instant string (UTC), zoned ISO 8601 string when a timeZone is given, or "" on invalid input
  *
  * @example fromNanoseconds(0n) // "1970-01-01T00:00:00Z"

package/dist/precision/convert/toExcelSerial.d.ts

@@ -20,8 +20,6 @@ export type ExcelDateSystem = "1900" | "1904";
  *   compatibility. No instant maps to serial 60: 1900-02-28 is 59 and 1900-03-01 is 61.
  *   Silently "fixing" this would put GMT one day out from Excel for every date before March
  *   1900.
- * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01. The
- *   same instant is exactly 1462 lower there than in the 1900 system.
  * - **Instants outside Excel's own serial range are invalid input**, not an out-of-range
  *   number: the 1900 system runs from serial 1 (1900-01-01) to 2958465 (9999-12-31), the
  *   1904 system from serial 0 (1904-01-01) to 2957003. Serial 0 in the 1900 system is
@@ -38,7 +36,7 @@ export type ExcelDateSystem = "1900" | "1904";
  *   that Excel rejects on the way in.
  *
  * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
- * @param options optional: system ("1900" (default) | "1904")
+ * @param options Which Excel date system the serial is in
  * @returns Excel day serial as a number, or null on invalid input
  *
  * @example toExcelSerial("1900-01-01T00:00:00Z") // 1 — Excel's first serial
@@ -52,5 +50,13 @@ export type ExcelDateSystem = "1900" | "1904";
  * @example toExcelSerial("invalid") // null
  */
 export declare function toExcelSerial(isoString: string, options?: {
+    /**
+     * Which Excel date system the serial is counted in. `"1900"` counts serial 1 as 1900-01-01
+     * and has the phantom serial 60; `"1904"` is the legacy Mac system, whose serial 0 is
+     * 1904-01-01 and which has no phantom day. The same instant is exactly 1462 lower in the 1904
+     * system.
+     *
+     * @defaultValue `"1900"`
+     */
     system?: ExcelDateSystem;
 }): number | null;

package/dist/precision/convert/toExcelSerial.js

@@ -1,5 +1,6 @@
 import { EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, floorDivide, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, parseInstantNanoseconds, } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Convert an ISO 8601 instant string to an Excel day serial.
  *
@@ -11,8 +12,6 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   compatibility. No instant maps to serial 60: 1900-02-28 is 59 and 1900-03-01 is 61.
  *   Silently "fixing" this would put GMT one day out from Excel for every date before March
  *   1900.
- * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01. The
- *   same instant is exactly 1462 lower there than in the 1900 system.
  * - **Instants outside Excel's own serial range are invalid input**, not an out-of-range
  *   number: the 1900 system runs from serial 1 (1900-01-01) to 2958465 (9999-12-31), the
  *   1904 system from serial 0 (1904-01-01) to 2957003. Serial 0 in the 1900 system is
@@ -29,7 +28,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   that Excel rejects on the way in.
  *
  * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
- * @param options optional: system ("1900" (default) | "1904")
+ * @param options Which Excel date system the serial is in
  * @returns Excel day serial as a number, or null on invalid input
  *
  * @example toExcelSerial("1900-01-01T00:00:00Z") // 1 — Excel's first serial
@@ -47,7 +46,7 @@ export function toExcelSerial(isoString, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        const system = options?.system === undefined ? "1900" : options.system;
+        const system = optionOrDefault(options?.system, "1900");
         if (system !== "1900" && system !== "1904") {
             return null;
         }

package/dist/precision/convert/toNanoseconds.d.ts

@@ -3,11 +3,15 @@
  *
  * - Requires an offset designator (`Z`, `±HH:MM`), as `Temporal.Instant` does — date-only
  *   and offset-less strings are rejected.
- * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation, both
- *   ignored as `Temporal.Instant.from` ignores them (an instant has no calendar).
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation. The
+ *   calendar is ignored, as `Temporal.Instant.from` ignores it (an instant has no calendar).
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `0n`, although
@@ -29,7 +33,8 @@
  * @example toNanoseconds("2024-03-10T12:00:00.123456789Z") // 1710072000123456789n
  * @example toNanoseconds("1969-12-31T23:59:59Z") // -1000000000n
  * @example toNanoseconds("2024-03-10T12:00:00-05:00[America/New_York]") // 1710090000000000000n
- * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is ignored
+ * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is not checked
+ * @example toNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // -315615330000000000n — the zone's −00:44:30, which `-00:45` rounds
  * @example toNanoseconds("2024-03-10T12:00:00") // 0n — no offset designator
  * @example toNanoseconds("20240310T120000Z") // 0n — basic format
  * @example toNanoseconds("invalid") // 0n

package/dist/precision/convert/toNanoseconds.js

@@ -4,11 +4,15 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  *
  * - Requires an offset designator (`Z`, `±HH:MM`), as `Temporal.Instant` does — date-only
  *   and offset-less strings are rejected.
- * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation, both
- *   ignored as `Temporal.Instant.from` ignores them (an instant has no calendar).
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation. The
+ *   calendar is ignored, as `Temporal.Instant.from` ignores it (an instant has no calendar).
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `0n`, although
@@ -30,7 +34,8 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  * @example toNanoseconds("2024-03-10T12:00:00.123456789Z") // 1710072000123456789n
  * @example toNanoseconds("1969-12-31T23:59:59Z") // -1000000000n
  * @example toNanoseconds("2024-03-10T12:00:00-05:00[America/New_York]") // 1710090000000000000n
- * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is ignored
+ * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is not checked
+ * @example toNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // -315615330000000000n — the zone's −00:44:30, which `-00:45` rounds
  * @example toNanoseconds("2024-03-10T12:00:00") // 0n — no offset designator
  * @example toNanoseconds("20240310T120000Z") // 0n — basic format
  * @example toNanoseconds("invalid") // 0n

package/dist/precision/validate/isValidInstant.d.ts

@@ -9,9 +9,18 @@
  *
  * - Requires an offset designator (`Z`, `±HH:MM`); a bracketed IANA zone may follow, but a
  *   bracket alone is not enough.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, at the first and last instants of the range too, where the
+ *   written offset's own reading can fall just outside it
+ *   (`-271821-04-19T23:58:45-00:01[Europe/London]` is the first instant). One exception, which
+ *   is Temporal's own: a wall time repeated inside a sub-minute offset change, written with a
+ *   minute-rounded offset, reads as its first pass (for example `1952-10-15T23:59:59-11:20[Pacific/Niue]`,
+ *   where the zone moved from −11:19:40 to −11:20:00, is the pass at −11:19:40). Otherwise the bracket is not checked: a
+ *   zone that does not exist, or that disagrees with the offset, changes nothing. Validity never depends
+ *   on the bracket.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `false`, although

package/dist/precision/validate/isValidInstant.js

@@ -10,9 +10,18 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  *
  * - Requires an offset designator (`Z`, `±HH:MM`); a bracketed IANA zone may follow, but a
  *   bracket alone is not enough.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, at the first and last instants of the range too, where the
+ *   written offset's own reading can fall just outside it
+ *   (`-271821-04-19T23:58:45-00:01[Europe/London]` is the first instant). One exception, which
+ *   is Temporal's own: a wall time repeated inside a sub-minute offset change, written with a
+ *   minute-rounded offset, reads as its first pass (for example `1952-10-15T23:59:59-11:20[Pacific/Niue]`,
+ *   where the zone moved from −11:19:40 to −11:20:00, is the pass at −11:19:40). Otherwise the bracket is not checked: a
+ *   zone that does not exist, or that disagrees with the offset, changes nothing. Validity never depends
+ *   on the bracket.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `false`, although