@northguild/gmt 1.17.0 → 1.18.0

package/dist/duration/calculate/durationAs.js

@@ -11,16 +11,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   durationAs("P1DT2H30M", "hours") is 26.5, not the 2 that `getDurationUnit` reads.
  * - The result is fractional, not rounded: durationAs("P1DT2H30M", "days") is
  *   1.1041666666666667. Round it yourself, or reach for `normalizeDuration` instead.
- * - `relativeTo` is required whenever a calendar unit (year/month/week) is involved, in
- *   *either* direction — as the requested `unit`, or because the input duration already has
- *   a nonzero year/month/week component. Without it, returns null. This is the same
- *   documented gap `normalizeDuration` (A3) carries; `addDuration`/`subtractDuration` (A2)
- *   have it worse still, since Temporal gives them no `relativeTo` option at all.
+ * - The calendar-unit rule of `relativeTo` is the same one `normalizeDuration` (A3) carries;
+ *   `addDuration`/`subtractDuration` (A2) have it worse still, since Temporal gives them no
+ *   `relativeTo` option at all.
  * - The requested-unit half of that rule bites even on day/time-only input: "P1DT2H30M" has
  *   no calendar component, yet durationAs("P1DT2H30M", "weeks") is still null — a week is a
  *   calendar quantity to Temporal regardless of what it is being measured from.
- * - `relativeTo` changes the answer for non-calendar units too when it names a zoned instant:
- *   a day spanning a DST spring-forward transition totals 23 hours, not 24.
  * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
  *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
  *   nonexistent one the later instant, and an offset that does not match the zone returns null.
@@ -43,7 +39,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value ISO 8601 duration string
  * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
- * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
+ * @param options The anchor calendar units are measured from
  * @returns the fractional total in `unit`, or null on invalid input
  *
  * @example durationAs("P1DT2H30M", "hours") // 26.5

package/dist/duration/compare/compareDurations.d.ts

@@ -5,16 +5,13 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * - Uses Temporal.Duration.compare: -1 when `a` is shorter, 0 when equal, 1 when `a` is longer.
  * - Equality is by length, not by spelling — "PT60M" and "PT1H" compare 0, as do "P1D" and
  *   "PT24H" absent a `relativeTo`.
- * - `relativeTo` is required whenever a calendar unit (year/month/week) appears on either
- *   side and the two durations differ; without it, returns null. Field-identical durations
- *   compare 0 without it ("P1Y" vs "P1Y"), since Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
+ * - Field-identical durations compare 0 without a `relativeTo` ("P1Y" vs "P1Y"), since
+ *   Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
  *   (A2): Temporal.Duration.compare *does* accept `relativeTo`, while .add/.subtract do not,
  *   so calendar-unit durations are comparable here even though they cannot be combined there.
  *   `durationAs` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
  * - The anchor genuinely decides the answer rather than merely unblocking it: "P1M" is longer
  *   than "P30D" relative to January (31 days) and shorter relative to February 2024 (29).
- * - It matters for non-calendar units too when it names a zoned instant — across a DST
- *   spring-forward, "P1D" is 23 real hours and so compares shorter than "PT24H".
  * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
  *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
  *   nonexistent one the later instant, and an offset that does not match the zone returns null.
@@ -37,7 +34,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *
  * @param a ISO 8601 duration string
  * @param b ISO 8601 duration string
- * @param options optional: { relativeTo } — anchor date/instant, required when either side has a calendar unit
+ * @param options The anchor calendar units are measured from
  * @returns -1, 0, or 1, or null on invalid input
  *
  * @example compareDurations("PT1H", "PT30M") // 1
@@ -56,5 +53,14 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 0 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export declare function compareDurations(a: string, b: string, options?: {
+    /**
+     * The date or zoned date-time both durations are measured from. It is required when either
+     * side has a year, month or week and the two differ. With a zoned value, days follow that
+     * zone's clock changes, so across a spring-forward transition `"P1D"` is 23 hours and
+     * compares shorter than `"PT24H"`.
+     *
+     * @defaultValue None. Days are 24 hours, and two different durations of which one has a
+     * year, month or week return `null`.
+     */
     relativeTo?: DurationRelativeTo;
 }): number | null;

package/dist/duration/compare/compareDurations.js

@@ -7,16 +7,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Uses Temporal.Duration.compare: -1 when `a` is shorter, 0 when equal, 1 when `a` is longer.
  * - Equality is by length, not by spelling — "PT60M" and "PT1H" compare 0, as do "P1D" and
  *   "PT24H" absent a `relativeTo`.
- * - `relativeTo` is required whenever a calendar unit (year/month/week) appears on either
- *   side and the two durations differ; without it, returns null. Field-identical durations
- *   compare 0 without it ("P1Y" vs "P1Y"), since Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
+ * - Field-identical durations compare 0 without a `relativeTo` ("P1Y" vs "P1Y"), since
+ *   Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
  *   (A2): Temporal.Duration.compare *does* accept `relativeTo`, while .add/.subtract do not,
  *   so calendar-unit durations are comparable here even though they cannot be combined there.
  *   `durationAs` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
  * - The anchor genuinely decides the answer rather than merely unblocking it: "P1M" is longer
  *   than "P30D" relative to January (31 days) and shorter relative to February 2024 (29).
- * - It matters for non-calendar units too when it names a zoned instant — across a DST
- *   spring-forward, "P1D" is 23 real hours and so compares shorter than "PT24H".
  * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
  *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
  *   nonexistent one the later instant, and an offset that does not match the zone returns null.
@@ -39,7 +36,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param a ISO 8601 duration string
  * @param b ISO 8601 duration string
- * @param options optional: { relativeTo } — anchor date/instant, required when either side has a calendar unit
+ * @param options The anchor calendar units are measured from
  * @returns -1, 0, or 1, or null on invalid input
  *
  * @example compareDurations("PT1H", "PT30M") // 1

package/dist/duration/format/formatDuration.d.ts

@@ -1,5 +1,19 @@
+/** How `formatDuration` writes unit names, and whether it writes zero components. */
 export interface FormatDurationOptions {
+    /**
+     * The length of each unit name, as the `unitDisplay` of `Intl.NumberFormat`: `"long"` ("90
+     * minutes"), `"short"` ("90 min") or `"narrow"` ("90m"). The components are joined as a long list
+     * ("1 day, 2 hours, and 30 minutes") for `"long"` and as a short list otherwise.
+     *
+     * @defaultValue `"long"`
+     */
     style?: "long" | "short" | "narrow";
+    /**
+     * Whether components that are zero are written. `false` leaves them out, so `"P1DT0H30M"`
+     * reads "1 day and 30 minutes"; `true` writes every unit from years to seconds.
+     *
+     * @defaultValue `false`
+     */
     zero?: boolean;
 }
 /**
@@ -16,10 +30,8 @@ export interface FormatDurationOptions {
  * - To render fewer fraction digits, round the string first with parseDuration, e.g.
  *   { smallestUnit: "millisecond", roundingMode: "halfExpand" } for the 3-digit output this
  *   function produced before (parseDuration's default roundingMode "trunc" drops the digits).
- * - By default, zero-valued components are omitted (e.g. "P1DT0H30M" -> "1 day and 30
- *   minutes"). Pass { zero: true } to include them.
  * - A zero-length duration (e.g. "PT0S") always renders its seconds component
- *   ("0 seconds") even with the default zero-omitting behavior, since omitting
+ *   ("0 seconds") even when zero components are left out, since omitting
  *   every component would otherwise produce "".
  * - Negative durations render each component with a leading "-" (Temporal stores
  *   every field of a negative duration as a negative number).
@@ -27,7 +39,7 @@ export interface FormatDurationOptions {
  *
  * @param value ISO 8601 duration string
  * @param locale BCP 47 locale tag, passed to Intl.NumberFormat/Intl.ListFormat; system default if omitted, or a preference list of tags (ECMA-402)
- * @param options optional: { style: "long" | "short" | "narrow" (default "long"), zero: boolean (default false) }
+ * @param options How unit names are written, and whether zero components are shown
  * @returns human-readable rendering of the duration, or "" on invalid input
  *
  * @example formatDuration("P1DT2H30M", "en-US") // "1 day, 2 hours, and 30 minutes"

package/dist/duration/format/formatDuration.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 const UNIT_TO_INTL = {
     years: "year",
     months: "month",
@@ -58,10 +59,8 @@ function exactSeconds(duration) {
  * - To render fewer fraction digits, round the string first with parseDuration, e.g.
  *   { smallestUnit: "millisecond", roundingMode: "halfExpand" } for the 3-digit output this
  *   function produced before (parseDuration's default roundingMode "trunc" drops the digits).
- * - By default, zero-valued components are omitted (e.g. "P1DT0H30M" -> "1 day and 30
- *   minutes"). Pass { zero: true } to include them.
  * - A zero-length duration (e.g. "PT0S") always renders its seconds component
- *   ("0 seconds") even with the default zero-omitting behavior, since omitting
+ *   ("0 seconds") even when zero components are left out, since omitting
  *   every component would otherwise produce "".
  * - Negative durations render each component with a leading "-" (Temporal stores
  *   every field of a negative duration as a negative number).
@@ -69,7 +68,7 @@ function exactSeconds(duration) {
  *
  * @param value ISO 8601 duration string
  * @param locale BCP 47 locale tag, passed to Intl.NumberFormat/Intl.ListFormat; system default if omitted, or a preference list of tags (ECMA-402)
- * @param options optional: { style: "long" | "short" | "narrow" (default "long"), zero: boolean (default false) }
+ * @param options How unit names are written, and whether zero components are shown
  * @returns human-readable rendering of the duration, or "" on invalid input
  *
  * @example formatDuration("P1DT2H30M", "en-US") // "1 day, 2 hours, and 30 minutes"
@@ -94,7 +93,7 @@ export function formatDuration(value, locale, options = {}) {
     }
     try {
         const duration = Temporal.Duration.from(value);
-        const style = options.style === undefined ? "long" : options.style;
+        const style = optionOrDefault(options.style, "long");
         const includeZero = options.zero ?? false;
         const amounts = {
             years: duration.years,

package/dist/duration/normalize/normalizeDuration.d.ts

@@ -4,19 +4,9 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * Roll an ISO 8601 duration string's small units into larger ones.
  *
  * - Uses Temporal.Duration.from and .round to rebalance, then .toString() to re-emit.
- * - Defaults to { largestUnit: "auto" }, which resolves to the larger of smallestUnit and the
- *   duration's own largest non-zero unit, then balances up to it. Units are promoted only up to
- *   a unit already present: "PT90M" stays "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M"
- *   becomes "PT2H30M". Pass an explicit largestUnit to promote further.
- * - relativeTo is required whenever a calendar unit (year/month/week) is involved,
- *   either as the requested largestUnit or because the input duration already has a
- *   nonzero year/month/week component (this applies even under the "auto" default).
- *   Without relativeTo in either case, returns "".
- * - roundingIncrement must evenly divide, and be less than, 24 for hour, 60 for minute/second
- *   and 1000 for millisecond/microsecond/nanosecond (so 60 and 24 themselves are rejected).
- *   For year/month/week/day it has no maximum, but an increment above 1 is rejected unless
- *   largestUnit is that same unit ("auto" resolves to the largest unit present). An invalid
- *   increment returns "".
+ * - With no options, units are promoted only up to a unit already present: "PT90M" stays
+ *   "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M" becomes "PT2H30M". Pass an explicit
+ *   largestUnit to promote further.
  * - A zoned relativeTo string resolves its wall time with disambiguation "compatible" and offset
  *   "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a nonexistent
  *   one the later instant, and an offset that does not match the zone returns "". Pass an
@@ -38,7 +28,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *   invalid relativeTo.
  *
  * @param value ISO 8601 duration string
- * @param options optional: { largestUnit, smallestUnit, roundingIncrement, roundingMode, relativeTo } per Temporal's Duration.round options
+ * @param options The units to balance between, the rounding, and the anchor for calendar units, as Temporal's Duration.round takes them
  * @returns rebalanced ISO 8601 duration string, or "" on invalid input
  *
  * @example normalizeDuration("PT90M", { largestUnit: "hour" }) // "PT1H30M"
@@ -55,9 +45,44 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // "P1M15D" (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export declare function normalizeDuration(value: string, options?: {
+    /**
+     * The largest unit the result may carry; smaller units are rolled up into it. `"auto"` is
+     * the larger of `smallestUnit` and the duration's own largest nonzero unit, so nothing is
+     * promoted past a unit already present.
+     *
+     * @defaultValue `"auto"`
+     */
     largestUnit?: Temporal.LargestUnit<Temporal.DateTimeUnit>;
+    /**
+     * The smallest unit the result may carry; anything smaller is rounded into it.
+     *
+     * @defaultValue `"nanosecond"`, Temporal's default.
+     */
     smallestUnit?: Temporal.SmallestUnit<Temporal.DateTimeUnit>;
+    /**
+     * The step `smallestUnit` is rounded to. It must evenly divide, and be less than, 24 for
+     * hour, 60 for minute and second, and 1000 for the sub-second units. For year, month, week
+     * and day it has no maximum, but an increment above 1 is rejected unless `largestUnit` is
+     * that same unit; an invalid increment returns `""`.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a value between two steps goes when `smallestUnit` or `roundingIncrement` rounds
+     * the duration. `"halfExpand"` rounds to the nearest step, a half going away from zero, and
+     * `"trunc"` rounds toward zero.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
+    /**
+     * The date or zoned date-time the duration is measured from. It is required whenever a year,
+     * month or week is involved, as `largestUnit` or `smallestUnit` or as a nonzero field of the
+     * duration, even under the `"auto"` default.
+     *
+     * @defaultValue None. Days are 24 hours, and a duration or unit that involves a year, month
+     * or week returns `""`.
+     */
     relativeTo?: DurationRelativeTo;
 }): string;

package/dist/duration/normalize/normalizeDuration.js

@@ -1,23 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { durationRound, resolveDurationRelativeTo } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Roll an ISO 8601 duration string's small units into larger ones.
  *
  * - Uses Temporal.Duration.from and .round to rebalance, then .toString() to re-emit.
- * - Defaults to { largestUnit: "auto" }, which resolves to the larger of smallestUnit and the
- *   duration's own largest non-zero unit, then balances up to it. Units are promoted only up to
- *   a unit already present: "PT90M" stays "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M"
- *   becomes "PT2H30M". Pass an explicit largestUnit to promote further.
- * - relativeTo is required whenever a calendar unit (year/month/week) is involved,
- *   either as the requested largestUnit or because the input duration already has a
- *   nonzero year/month/week component (this applies even under the "auto" default).
- *   Without relativeTo in either case, returns "".
- * - roundingIncrement must evenly divide, and be less than, 24 for hour, 60 for minute/second
- *   and 1000 for millisecond/microsecond/nanosecond (so 60 and 24 themselves are rejected).
- *   For year/month/week/day it has no maximum, but an increment above 1 is rejected unless
- *   largestUnit is that same unit ("auto" resolves to the largest unit present). An invalid
- *   increment returns "".
+ * - With no options, units are promoted only up to a unit already present: "PT90M" stays
+ *   "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M" becomes "PT2H30M". Pass an explicit
+ *   largestUnit to promote further.
  * - A zoned relativeTo string resolves its wall time with disambiguation "compatible" and offset
  *   "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a nonexistent
  *   one the later instant, and an offset that does not match the zone returns "". Pass an
@@ -39,7 +30,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   invalid relativeTo.
  *
  * @param value ISO 8601 duration string
- * @param options optional: { largestUnit, smallestUnit, roundingIncrement, roundingMode, relativeTo } per Temporal's Duration.round options
+ * @param options The units to balance between, the rounding, and the anchor for calendar units, as Temporal's Duration.round takes them
  * @returns rebalanced ISO 8601 duration string, or "" on invalid input
  *
  * @example normalizeDuration("PT90M", { largestUnit: "hour" }) // "PT1H30M"
@@ -65,7 +56,7 @@ export function normalizeDuration(value, options) {
     try {
         const duration = Temporal.Duration.from(value);
         return durationRound(duration, {
-            largestUnit: options?.largestUnit === undefined ? "auto" : options.largestUnit,
+            largestUnit: optionOrDefault(options?.largestUnit, "auto"),
             smallestUnit: options?.smallestUnit,
             roundingIncrement: options?.roundingIncrement,
             roundingMode: options?.roundingMode,

package/dist/duration/parse/parseDuration.d.ts

@@ -3,12 +3,10 @@ import { Temporal } from "@js-temporal/polyfill";
  * Parse and re-normalize an ISO 8601 duration string.
  *
  * - Uses Temporal.Duration.from to parse, then .toString() to re-emit.
- * - `smallestUnit`, `fractionalSecondDigits`, and `roundingMode` control the precision/rounding
- *   of the re-emitted string, per Temporal's ToStringPrecisionOptions.
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 duration string
- * @param options optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond" — "minute"/"hour" are rejected by Temporal, resulting in ""), fractionalSecondDigits ("auto" | 0-9, ignored when smallestUnit is also set), roundingMode
+ * @param options The precision of the string written back, as Temporal's ToStringPrecisionOptions
  * @returns re-normalized ISO 8601 duration string, or "" on invalid input
  *
  * @example parseDuration("P1DT2H30M") // "P1DT2H30M"
@@ -18,7 +16,27 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example parseDuration("invalid") // ""
  */
 export declare function parseDuration(value: string, options?: {
+    /**
+     * The smallest unit written in the string: `"second"`, `"millisecond"`, `"microsecond"` or
+     * `"nanosecond"`. It sets how many fractional-second digits appear and takes precedence over
+     * `fractionalSecondDigits`. `"minute"` returns `""`, as `Temporal.Duration` refuses it.
+     *
+     * @defaultValue None. The precision comes from `fractionalSecondDigits`.
+     */
     smallestUnit?: Temporal.ToStringPrecisionOptions["smallestUnit"];
+    /**
+     * The number of fractional-second digits written: `0` to `9` writes exactly that many, and
+     * `"auto"` writes as many as the duration needs, with no trailing zeros. It has no effect when
+     * `smallestUnit` is given.
+     *
+     * @defaultValue `"auto"`, Temporal's default.
+     */
     fractionalSecondDigits?: Temporal.ToStringPrecisionOptions["fractionalSecondDigits"];
+    /**
+     * How the duration is rounded when the precision asked for drops digits. `"trunc"` cuts them
+     * off; `"halfExpand"` rounds to the nearest value, a half going away from zero.
+     *
+     * @defaultValue `"trunc"`, Temporal's default.
+     */
     roundingMode?: Temporal.ToStringPrecisionOptions["roundingMode"];
 }): string;

package/dist/duration/parse/parseDuration.js

@@ -4,12 +4,10 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Parse and re-normalize an ISO 8601 duration string.
  *
  * - Uses Temporal.Duration.from to parse, then .toString() to re-emit.
- * - `smallestUnit`, `fractionalSecondDigits`, and `roundingMode` control the precision/rounding
- *   of the re-emitted string, per Temporal's ToStringPrecisionOptions.
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 duration string
- * @param options optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond" — "minute"/"hour" are rejected by Temporal, resulting in ""), fractionalSecondDigits ("auto" | 0-9, ignored when smallestUnit is also set), roundingMode
+ * @param options The precision of the string written back, as Temporal's ToStringPrecisionOptions
  * @returns re-normalized ISO 8601 duration string, or "" on invalid input
  *
  * @example parseDuration("P1DT2H30M") // "P1DT2H30M"

package/dist/instant/convert/classifyLocal.d.ts

@@ -34,7 +34,7 @@ export type LocalTimeClassification = "unique" | "ambiguous" | "nonexistent";
  * - Returns null on invalid input — never `"unique"`, which would read as a verdict.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
+ * @param timeZone IANA name or UTC offset the wall time is read in
  * @returns "unique" | "ambiguous" | "nonexistent", or null on invalid input
  *
  * @example classifyLocal("2024-07-15T12:00:00", "America/New_York") // "unique"

package/dist/instant/convert/classifyLocal.js

@@ -22,7 +22,7 @@ import { plainToZoned } from "../../internal/index.js";
  * - Returns null on invalid input — never `"unique"`, which would read as a verdict.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
+ * @param timeZone IANA name or UTC offset the wall time is read in
  * @returns "unique" | "ambiguous" | "nonexistent", or null on invalid input
  *
  * @example classifyLocal("2024-07-15T12:00:00", "America/New_York") // "unique"

package/dist/instant/convert/fromOffsetInstant.d.ts

@@ -24,7 +24,9 @@ import type { OffsetInstant } from "./toOffsetInstant.js";
  * - With a `timeZone`, a sub-minute offset is *written* rounded to the minute, because RFC
  *   9557 has no field for the seconds — `Africa/Monrovia`'s `-00:44:30` renders as `-00:45`.
  *   The bracketed zone is what resolves it, so the instant stays exact and the round trip
- *   returns `-00:44:30`. Without a `timeZone` there is no zone to resolve against, so the
+ *   returns `-00:44:30`. Two exceptions, both Temporal's own: a wall time repeated inside
+ *   a sub-minute offset change reads back as its first pass (see `isValidInstant`), and a
+ *   string whose local date is −271821-04-19 is refused by `toOffsetInstant`. Without a `timeZone` there is no zone to resolve against, so the
  *   full `±HH:MM:SS` is written instead; that is ISO 8601, not RFC 9557.
  * - Returns `""` on invalid input.
  *

package/dist/instant/convert/fromOffsetInstant.js

@@ -26,7 +26,9 @@ import { utcOffset } from "../../regex/index.js";
  * - With a `timeZone`, a sub-minute offset is *written* rounded to the minute, because RFC
  *   9557 has no field for the seconds — `Africa/Monrovia`'s `-00:44:30` renders as `-00:45`.
  *   The bracketed zone is what resolves it, so the instant stays exact and the round trip
- *   returns `-00:44:30`. Without a `timeZone` there is no zone to resolve against, so the
+ *   returns `-00:44:30`. Two exceptions, both Temporal's own: a wall time repeated inside
+ *   a sub-minute offset change reads back as its first pass (see `isValidInstant`), and a
+ *   string whose local date is −271821-04-19 is refused by `toOffsetInstant`. Without a `timeZone` there is no zone to resolve against, so the
  *   full `±HH:MM:SS` is written instead; that is ISO 8601, not RFC 9557.
  * - Returns `""` on invalid input.
  *

package/dist/instant/convert/resolveLocal.d.ts

@@ -6,11 +6,8 @@ import type { Disambiguation } from "../../types/index.js";
  * into an instant takes a zone the sender did not send plus a policy for the two days a year
  * the mapping is not one-to-one. This states both.
  *
- * - `disambiguation` decides what happens when the wall time is ambiguous (a fall-back hour
- *   that happens twice) or nonexistent (a spring-forward hour that never happens):
- *   `"compatible"` (the default, matching Temporal), `"earlier"`, `"later"`, or `"reject"`,
- *   which returns `""` rather than resolving. Call `classifyLocal` first to find out which
- *   case you are in before a policy is applied.
+ * - Call `classifyLocal` first to find out whether the wall time is ambiguous or nonexistent
+ *   before a `disambiguation` policy is applied.
  * - Returns a UTC instant, exactly — no rounding, so a nanosecond wall time survives. Pass it
  *   to `toOffsetInstant` for the offset pair, or reach for `convertPlainDateTimeToZoned` when
  *   what you want is the bracketed zoned string (it defaults to millisecond precision).
@@ -21,8 +18,8 @@ import type { Disambiguation } from "../../types/index.js";
  * - Returns `""` on invalid input.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @param timeZone IANA name or UTC offset the wall time is read in
+ * @param optionsArg How an ambiguous or nonexistent wall time is resolved
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
  * @example resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"
@@ -36,5 +33,13 @@ import type { Disambiguation } from "../../types/index.js";
  * @example resolveLocal("2024-07-15T12:00:00", "Invalid/Zone") // ""
  */
 export declare function resolveLocal(localDateTime: string, timeZone: string, optionsArg?: {
+    /**
+     * What happens when the wall time is ambiguous (a fall-back hour that happens twice) or
+     * nonexistent (a spring-forward hour that never happens). `"compatible"` takes the earlier
+     * instant of an ambiguous time and the later one of a nonexistent time, `"earlier"` and
+     * `"later"` take that side in both cases, and `"reject"` returns `""` rather than resolving.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
     disambiguation?: Disambiguation;
 }): string;

package/dist/instant/convert/resolveLocal.js

@@ -2,6 +2,7 @@ import { isValidDateTime } from "../../plain/validate/index.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
 import { isoStringBody, zonedDateTimeFrom } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 const DISAMBIGUATIONS = [
     "compatible",
     "earlier",
@@ -15,11 +16,8 @@ const DISAMBIGUATIONS = [
  * into an instant takes a zone the sender did not send plus a policy for the two days a year
  * the mapping is not one-to-one. This states both.
  *
- * - `disambiguation` decides what happens when the wall time is ambiguous (a fall-back hour
- *   that happens twice) or nonexistent (a spring-forward hour that never happens):
- *   `"compatible"` (the default, matching Temporal), `"earlier"`, `"later"`, or `"reject"`,
- *   which returns `""` rather than resolving. Call `classifyLocal` first to find out which
- *   case you are in before a policy is applied.
+ * - Call `classifyLocal` first to find out whether the wall time is ambiguous or nonexistent
+ *   before a `disambiguation` policy is applied.
  * - Returns a UTC instant, exactly — no rounding, so a nanosecond wall time survives. Pass it
  *   to `toOffsetInstant` for the offset pair, or reach for `convertPlainDateTimeToZoned` when
  *   what you want is the bracketed zoned string (it defaults to millisecond precision).
@@ -30,8 +28,8 @@ const DISAMBIGUATIONS = [
  * - Returns `""` on invalid input.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @param timeZone IANA name or UTC offset the wall time is read in
+ * @param optionsArg How an ambiguous or nonexistent wall time is resolved
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
  * @example resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"
@@ -49,9 +47,7 @@ export function resolveLocal(localDateTime, timeZone, optionsArg) {
         if (!isOptionsArgument(optionsArg)) {
             return "";
         }
-        const disambiguation = optionsArg?.disambiguation === undefined
-            ? "compatible"
-            : optionsArg.disambiguation;
+        const disambiguation = optionOrDefault(optionsArg?.disambiguation, "compatible");
         if (!isValidDateTime(localDateTime) ||
             !isValidTimeZone(timeZone) ||
             !DISAMBIGUATIONS.includes(disambiguation)) {

package/dist/instant/convert/toOffsetInstant.d.ts

@@ -1,14 +1,6 @@
 /**
  * An absolute instant paired with the local UTC offset in force where the event happened.
  *
- * @remarks Members:
- *
- * | Member | Type | Description |
- * | --- | --- | --- |
- * | `instant` | `string` | UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally. |
- * | `offset` | `string` | UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972 zone that did not run on a whole minute). Renders the event as the human on the ground saw it. |
- * | `timeZone` | `string \| undefined` | IANA zone identifier, when one is known. Absent from most feeds, so absent from most pairs. |
- *
  * Neither `instant` nor `offset` derives from the other, which is why both are stored. It is
  * the shape GS1 EPCIS 2.0 (`eventTime` + a required `eventTimeZoneOffset`), UN/EDIFACT DTM
  * (qualifier `303`/`304`) and DICOM (`DT` + `&ZZXX`) all exchange.
@@ -22,8 +14,22 @@
  * };
  */
 export interface OffsetInstant {
+    /**
+     * The UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally.
+     */
     instant: string;
+    /**
+     * The UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972
+     * zone that did not run on a whole minute). Renders the event as the human on the ground saw it.
+     */
     offset: string;
+    /**
+     * The IANA name of the zone, when one is known. Most feeds send none, so `toOffsetInstant` leaves
+     * it out unless the string or its `timeZone` argument names a zone.
+     *
+     * @defaultValue None. The pair names no zone, and `offset` alone places the instant on a local
+     * clock.
+     */
     timeZone?: string;
 }
 /**
@@ -68,10 +74,15 @@ export interface OffsetInstant {
  *   rounding it would put the pair 30 seconds from the event it describes. Such a zone's
  *   *string* still carries the rounded `-00:45`, because RFC 9557 caps a written offset at
  *   minutes; the bracketed zone is what resolves it, so the instant stays exact.
+ * - A bracketed zone is checked as `Temporal.ZonedDateTime.from` checks it, which also rejects
+ *   a local date of −271821-04-19. A zone west of Greenwich shows that date for the first hours
+ *   of the instant range, so a zoned string written there
+ *   (`-271821-04-19T23:59:00-00:01[Europe/London]`) returns null, although `isValidInstant`
+ *   accepts it. Pass the instant in `Z` form with `timeZone` instead.
  * - Returns null on invalid input, not a zero-offset pair — `+00:00` is a real offset.
  *
  * @param value ISO 8601 instant string, with an offset designator and optionally a bracketed zone
- * @param timeZone optional IANA zone identifier to read the offset in
+ * @param timeZone optional IANA name or UTC offset to read the offset in
  * @returns `{ instant, offset, timeZone? }`, or null on invalid input
  *
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
@@ -83,6 +94,8 @@ export interface OffsetInstant {
  * @example toOffsetInstant("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" } — the zone, not the rounded offset, fixes the instant
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[-04:00]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — a bracketed offset is not a zone, so no timeZone field
  * @example toOffsetInstant("2024-07-15T12:00:00-05:00[America/New_York]") // null (offset contradicts the bracketed zone)
+ * @example toOffsetInstant("-271821-04-19T23:59:00-00:01[Europe/London]") // null (a bracketed zone on a local date before Temporal's date range)
+ * @example toOffsetInstant("-271821-04-20T00:00:15Z", "Europe/London") // { instant: "-271821-04-20T00:00:15Z", offset: "-00:01:15", timeZone: "Europe/London" }
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an elective annotation is ignored
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[!foo=bar]") // null (an unknown critical annotation)
  * @example toOffsetInstant("2024-07-15T12:00:00") // null (no offset designator)

package/dist/instant/convert/toOffsetInstant.js

@@ -46,10 +46,15 @@ const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
  *   rounding it would put the pair 30 seconds from the event it describes. Such a zone's
  *   *string* still carries the rounded `-00:45`, because RFC 9557 caps a written offset at
  *   minutes; the bracketed zone is what resolves it, so the instant stays exact.
+ * - A bracketed zone is checked as `Temporal.ZonedDateTime.from` checks it, which also rejects
+ *   a local date of −271821-04-19. A zone west of Greenwich shows that date for the first hours
+ *   of the instant range, so a zoned string written there
+ *   (`-271821-04-19T23:59:00-00:01[Europe/London]`) returns null, although `isValidInstant`
+ *   accepts it. Pass the instant in `Z` form with `timeZone` instead.
  * - Returns null on invalid input, not a zero-offset pair — `+00:00` is a real offset.
  *
  * @param value ISO 8601 instant string, with an offset designator and optionally a bracketed zone
- * @param timeZone optional IANA zone identifier to read the offset in
+ * @param timeZone optional IANA name or UTC offset to read the offset in
  * @returns `{ instant, offset, timeZone? }`, or null on invalid input
  *
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
@@ -61,6 +66,8 @@ const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
  * @example toOffsetInstant("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" } — the zone, not the rounded offset, fixes the instant
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[-04:00]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — a bracketed offset is not a zone, so no timeZone field
  * @example toOffsetInstant("2024-07-15T12:00:00-05:00[America/New_York]") // null (offset contradicts the bracketed zone)
+ * @example toOffsetInstant("-271821-04-19T23:59:00-00:01[Europe/London]") // null (a bracketed zone on a local date before Temporal's date range)
+ * @example toOffsetInstant("-271821-04-20T00:00:15Z", "Europe/London") // { instant: "-271821-04-20T00:00:15Z", offset: "-00:01:15", timeZone: "Europe/London" }
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an elective annotation is ignored
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[!foo=bar]") // null (an unknown critical annotation)
  * @example toOffsetInstant("2024-07-15T12:00:00") // null (no offset designator)
@@ -80,8 +87,8 @@ export function toOffsetInstant(value, timeZone) {
         return null;
     }
     try {
-        // `parseInstantNanoseconds` reads the offset and ignores the bracket, so a self-
-        // contradictory string parses fine as an instant. `ZonedDateTime.from` is what checks
+        // `parseInstantNanoseconds` does not validate the bracket, so a self-contradictory string
+        // parses fine as an instant. `ZonedDateTime.from` is what checks
         // the two agree, and it runs even when `timeZone` overrides the bracketed zone.
         // Only a time zone annotation makes the string zoned: it is the first annotation, and the
         // only kind with no `=` (RFC 9557 §4.1). A calendar or elective annotation alone leaves an