@northguild/gmt 1.17.0 → 1.19.0

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/parse/parseYearFromDate.d.ts

@@ -1,13 +1,16 @@
 /**
  * Return the year for a given ISO 8601 date string.
  *
- * - Returns the year as a string (e.g., "2024").
+ * - Returns the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - Returns "" for invalid input.
  *
  * @param value ISO date string
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromDate("2024-03-15") // "2024"
+ * @example parseYearFromDate("0005-06-01") // "0005"
+ * @example parseYearFromDate("+010000-01-01") // "+010000"
  * @example parseYearFromDate("invalid") // ""
  */
 export declare function parseYearFromDate(value: string): string;

package/dist/plain/parse/parseYearFromDate.js

@@ -1,15 +1,19 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDate } from "../validate/index.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the year for a given ISO 8601 date string.
  *
- * - Returns the year as a string (e.g., "2024").
+ * - Returns the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - Returns "" for invalid input.
  *
  * @param value ISO date string
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromDate("2024-03-15") // "2024"
+ * @example parseYearFromDate("0005-06-01") // "0005"
+ * @example parseYearFromDate("+010000-01-01") // "+010000"
  * @example parseYearFromDate("invalid") // ""
  */
 export function parseYearFromDate(value) {
@@ -17,7 +21,7 @@ export function parseYearFromDate(value) {
         return "";
     try {
         const date = Temporal.PlainDate.from(value);
-        return date.year.toString();
+        return isoYearString(date.year);
     }
     catch {
         return "";

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

@@ -1,13 +1,15 @@
 /**
  * Return the year for a given ISO 8601 datetime string.
  *
- * - Returns the year as a string (e.g., "2024").
+ * - Returns the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - Returns "" for invalid input.
  *
  * @param value ISO datetime string
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromDateTime("2024-03-15T12:30:00") // "2024"
+ * @example parseYearFromDateTime("0005-06-01T12:30:00") // "0005"
  * @example parseYearFromDateTime("invalid") // ""
  */
 export declare function parseYearFromDateTime(value: string): string;

package/dist/plain/parse/parseYearFromDateTime.js

@@ -1,15 +1,18 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTime } from "../validate/index.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the year for a given ISO 8601 datetime string.
  *
- * - Returns the year as a string (e.g., "2024").
+ * - Returns the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - Returns "" for invalid input.
  *
  * @param value ISO datetime string
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromDateTime("2024-03-15T12:30:00") // "2024"
+ * @example parseYearFromDateTime("0005-06-01T12:30:00") // "0005"
  * @example parseYearFromDateTime("invalid") // ""
  */
 export function parseYearFromDateTime(value) {
@@ -17,7 +20,7 @@ export function parseYearFromDateTime(value) {
         return "";
     try {
         const dateTime = Temporal.PlainDateTime.from(value);
-        return dateTime.year.toString();
+        return isoYearString(dateTime.year);
     }
     catch {
         return "";

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

@@ -12,6 +12,7 @@ export * from "./isValidDateTimeRange.js";
 export * from "./isValidDateTimeUnit.js";
 export * from "./isValidDateUnit.js";
 export * from "./isValidIsoDateLike.js";
+export * from "./isValidSqlDateTime.js";
 export * from "./isValidTime.js";
 export * from "./isValidTimeCycleField.js";
 export * from "./isValidTimeDurationUnit.js";

package/dist/plain/validate/index.js

@@ -12,6 +12,7 @@ export * from "./isValidDateTimeRange.js";
 export * from "./isValidDateTimeUnit.js";
 export * from "./isValidDateUnit.js";
 export * from "./isValidIsoDateLike.js";
+export * from "./isValidSqlDateTime.js";
 export * from "./isValidTime.js";
 export * from "./isValidTimeCycleField.js";
 export * from "./isValidTimeDurationUnit.js";

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/isValidSqlDateTime.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Return true when `value` is a real SQL timestamp literal without a time zone: the
+ * `YYYY-MM-DD HH:MM:SS[.fff]` value of a standard SQL `TIMESTAMP` or a MySQL/SQLite `DATETIME`
+ * column. It checks one date-and-time value, not a SQL statement.
+ *
+ * - True exactly when `parseSqlDateTime` returns a plain string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, as `sqlDateTime`
+ *   matches: a single space separator, a four-digit year `0001`–`9999`, two-digit month, day,
+ *   hour, minute and second (seconds are required), and an optional `.` followed by up to 9
+ *   fraction digits.
+ * - Checks the calendar as well as the shape. The `sqlDateTime` pattern proves the shape alone, so
+ *   it matches a day that does not exist: 30 February, 29 February in a common year and 31 June
+ *   are false here.
+ * - False for a second of 60: GMT rejects leap seconds.
+ * - **Plain only.** A `T` separator, a `Z` and an offset are false: SQL's offset-carrying
+ *   `TIMESTAMP WITH TIME ZONE` literal is out of scope.
+ * - False for a non-string. Read the value with `parseSqlDateTime`; write one with
+ *   `formatSqlDateTime`.
+ *
+ * @param value candidate SQL timestamp literal
+ * @returns boolean indicating validity
+ *
+ * @example isValidSqlDateTime("2024-03-15 14:30:00") // true
+ * @example isValidSqlDateTime("2024-03-15 14:30:00.123456789") // true
+ * @example isValidSqlDateTime("2024-02-30 14:30:00") // false (February has no 30th; the sqlDateTime pattern matches it)
+ * @example isValidSqlDateTime("2023-02-29 14:30:00") // false (2023 has no 29 February; the sqlDateTime pattern matches it)
+ * @example isValidSqlDateTime("2024-06-31 00:00:00") // false (June has 30 days; the sqlDateTime pattern matches it)
+ * @example isValidSqlDateTime("2024-03-15 14:30") // false (seconds are required)
+ * @example isValidSqlDateTime("2024-03-15T14:30:00") // false (T separator)
+ * @example isValidSqlDateTime("not a date") // false
+ */
+export declare function isValidSqlDateTime(value: string): boolean;

package/dist/plain/validate/isValidSqlDateTime.js

@@ -0,0 +1,36 @@
+import { parseSqlDateTime } from "../parse/parseSqlDateTime.js";
+/**
+ * Return true when `value` is a real SQL timestamp literal without a time zone: the
+ * `YYYY-MM-DD HH:MM:SS[.fff]` value of a standard SQL `TIMESTAMP` or a MySQL/SQLite `DATETIME`
+ * column. It checks one date-and-time value, not a SQL statement.
+ *
+ * - True exactly when `parseSqlDateTime` returns a plain string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, as `sqlDateTime`
+ *   matches: a single space separator, a four-digit year `0001`–`9999`, two-digit month, day,
+ *   hour, minute and second (seconds are required), and an optional `.` followed by up to 9
+ *   fraction digits.
+ * - Checks the calendar as well as the shape. The `sqlDateTime` pattern proves the shape alone, so
+ *   it matches a day that does not exist: 30 February, 29 February in a common year and 31 June
+ *   are false here.
+ * - False for a second of 60: GMT rejects leap seconds.
+ * - **Plain only.** A `T` separator, a `Z` and an offset are false: SQL's offset-carrying
+ *   `TIMESTAMP WITH TIME ZONE` literal is out of scope.
+ * - False for a non-string. Read the value with `parseSqlDateTime`; write one with
+ *   `formatSqlDateTime`.
+ *
+ * @param value candidate SQL timestamp literal
+ * @returns boolean indicating validity
+ *
+ * @example isValidSqlDateTime("2024-03-15 14:30:00") // true
+ * @example isValidSqlDateTime("2024-03-15 14:30:00.123456789") // true
+ * @example isValidSqlDateTime("2024-02-30 14:30:00") // false (February has no 30th; the sqlDateTime pattern matches it)
+ * @example isValidSqlDateTime("2023-02-29 14:30:00") // false (2023 has no 29 February; the sqlDateTime pattern matches it)
+ * @example isValidSqlDateTime("2024-06-31 00:00:00") // false (June has 30 days; the sqlDateTime pattern matches it)
+ * @example isValidSqlDateTime("2024-03-15 14:30") // false (seconds are required)
+ * @example isValidSqlDateTime("2024-03-15T14:30:00") // false (T separator)
+ * @example isValidSqlDateTime("not a date") // false
+ */
+export function isValidSqlDateTime(value) {
+    return parseSqlDateTime(value) !== "";
+}

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

@@ -5,17 +5,23 @@
  *   (`"...[America/New_York]"`) when one is.
  * - No disambiguation policy applies: an instant maps to exactly one wall time in a zone,
  *   so DST gaps and overlaps cannot arise on this direction of the conversion.
- * - A time zone, when given, must be a valid IANA identifier. `undefined` is the same as omitting
- *   it (UTC), as TC39 treats an undefined argument as absent.
+ * - A time zone, when given, must be a time zone identifier: an IANA name or a UTC offset to the
+ *   minute. `undefined` is the same as omitting it (UTC), as TC39 treats an undefined argument as
+ *   absent.
  * - Rejects values outside the range `Temporal.Instant` can represent
  *   (±8_640_000_000_000_000_000_000n, i.e. ±10^8 days from the epoch).
  * - **Storage round-trip:** most engines cannot hold nanoseconds — PostgreSQL `timestamptz`
  *   stores microseconds — so writing this value and reading it back breaks equality unless
  *   the caller applies `truncateNanoseconds` to the target precision first.
  * - Returns "" on invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @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 a UTC offset to the minute (what `isValidTimeZone`
+ *   accepts); 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

@@ -8,17 +8,23 @@ import { isValidTimeZone } from "../../zoned/validate/index.js";
  *   (`"...[America/New_York]"`) when one is.
  * - No disambiguation policy applies: an instant maps to exactly one wall time in a zone,
  *   so DST gaps and overlaps cannot arise on this direction of the conversion.
- * - A time zone, when given, must be a valid IANA identifier. `undefined` is the same as omitting
- *   it (UTC), as TC39 treats an undefined argument as absent.
+ * - A time zone, when given, must be a time zone identifier: an IANA name or a UTC offset to the
+ *   minute. `undefined` is the same as omitting it (UTC), as TC39 treats an undefined argument as
+ *   absent.
  * - Rejects values outside the range `Temporal.Instant` can represent
  *   (±8_640_000_000_000_000_000_000n, i.e. ±10^8 days from the epoch).
  * - **Storage round-trip:** most engines cannot hold nanoseconds — PostgreSQL `timestamptz`
  *   stores microseconds — so writing this value and reading it back breaks equality unless
  *   the caller applies `truncateNanoseconds` to the target precision first.
  * - Returns "" on invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @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 a UTC offset to the minute (what `isValidTimeZone`
+ *   accepts); 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;