@northguild/gmt 1.17.0 → 1.18.0

package/dist/plain/compare/areDatesEqualBy.d.ts

@@ -4,19 +4,21 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Equality means both values share the same start-of-`unit` boundary, so
  *   `"month"` requires the same month AND year — March 2023 and March 2024 are
- *   NOT equal by month, matching date-fns's `isSameMonth` and Luxon's
- *   `dt.hasSame(other, "month")`. This is a common point of confusion for
- *   callers expecting a bare "same month-of-year" comparison.
+ *   NOT equal by month. A calendar month is a year and a month together, as in
+ *   Temporal's `PlainYearMonth`, not a bare month-of-year number. This is a
+ *   common point of confusion for callers expecting a bare "same month-of-year"
+ *   comparison.
+ * - Comparison: date-fns's `isSameMonth` and Luxon's `dt.hasSame(other, "month")`
+ *   give the same answer.
  * - `"day"` matches `areDatesEqual` for PlainDate inputs only: `areDatesEqual` also accepts
  *   PlainDateTime strings (`areDatesEqual("2024-01-01", "2024-01-01T10:00")` is `true`), while this
  *   function accepts PlainDate strings only (`areDatesEqualBy` with those inputs and `"day"` is
  *   `false`).
  * - `"year"`, `"month"`, `"week"` are computed via `startOfDate`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areDatesEqualBy(a, b, "day")`
  * - `isSameWeek(a, b, options)` → `areDatesEqualBy(a, b, "week", { weekStartsOn })`
  * - `isSameMonth(a, b)` → `areDatesEqualBy(a, b, "month")`
@@ -25,7 +27,7 @@ import { Temporal } from "@js-temporal/polyfill";
  * @param value1 first ISO date string
  * @param value2 second ISO date string
  * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns true if both dates share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areDatesEqualBy("2024-03-15", "2024-03-20", "month") // true
@@ -37,5 +39,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example areDatesEqualBy("invalid", "2024-03-15", "month") // false
  */
 export declare function areDatesEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * false, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): boolean;

package/dist/plain/compare/areDatesEqualBy.js

@@ -11,19 +11,21 @@ const supported = ["year", "month", "week", "day"];
  *
  * - Equality means both values share the same start-of-`unit` boundary, so
  *   `"month"` requires the same month AND year — March 2023 and March 2024 are
- *   NOT equal by month, matching date-fns's `isSameMonth` and Luxon's
- *   `dt.hasSame(other, "month")`. This is a common point of confusion for
- *   callers expecting a bare "same month-of-year" comparison.
+ *   NOT equal by month. A calendar month is a year and a month together, as in
+ *   Temporal's `PlainYearMonth`, not a bare month-of-year number. This is a
+ *   common point of confusion for callers expecting a bare "same month-of-year"
+ *   comparison.
+ * - Comparison: date-fns's `isSameMonth` and Luxon's `dt.hasSame(other, "month")`
+ *   give the same answer.
  * - `"day"` matches `areDatesEqual` for PlainDate inputs only: `areDatesEqual` also accepts
  *   PlainDateTime strings (`areDatesEqual("2024-01-01", "2024-01-01T10:00")` is `true`), while this
  *   function accepts PlainDate strings only (`areDatesEqualBy` with those inputs and `"day"` is
  *   `false`).
  * - `"year"`, `"month"`, `"week"` are computed via `startOfDate`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areDatesEqualBy(a, b, "day")`
  * - `isSameWeek(a, b, options)` → `areDatesEqualBy(a, b, "week", { weekStartsOn })`
  * - `isSameMonth(a, b)` → `areDatesEqualBy(a, b, "month")`
@@ -32,7 +34,7 @@ const supported = ["year", "month", "week", "day"];
  * @param value1 first ISO date string
  * @param value2 second ISO date string
  * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns true if both dates share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areDatesEqualBy("2024-03-15", "2024-03-20", "month") // true

package/dist/plain/compare/isBetweenDate.d.ts

@@ -4,12 +4,11 @@
  * - Uses Temporal.PlainDate.compare to compare dates.
  * - Returns false if start > end (invalid range).
  * - Returns false if any input is invalid.
- * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
  *
  * @param date ISO PlainDate string to check
  * @param start ISO PlainDate string for the start of the range
  * @param end ISO PlainDate string for the end of the range
- * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @param options Whether each end of the range counts as inside it
  * @returns boolean indicating whether date is between start and end
  *
  * @example isBetweenDate("2024-02-29", "2024-02-01", "2024-02-28") // false
@@ -21,6 +20,18 @@
  * @example isBetweenDate("2024-02-29", "2024-02-01", "invalid") // false
  */
 export declare function isBetweenDate(date: string, start: string, end: string, options?: {
+    /**
+     * Whether `date` equal to `start` counts as inside the range. `false` requires it to
+     * be after `start`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveStart?: boolean;
+    /**
+     * Whether `date` equal to `end` counts as inside the range. `false` requires it to be
+     * before `end`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveEnd?: boolean;
 }): boolean;

package/dist/plain/compare/isBetweenDate.js

@@ -2,18 +2,18 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDate } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return true when `date` is between `start` and `end` (inclusive by default).
  *
  * - Uses Temporal.PlainDate.compare to compare dates.
  * - Returns false if start > end (invalid range).
  * - Returns false if any input is invalid.
- * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
  *
  * @param date ISO PlainDate string to check
  * @param start ISO PlainDate string for the start of the range
  * @param end ISO PlainDate string for the end of the range
- * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @param options Whether each end of the range counts as inside it
  * @returns boolean indicating whether date is between start and end
  *
  * @example isBetweenDate("2024-02-29", "2024-02-01", "2024-02-28") // false
@@ -33,8 +33,8 @@ export function isBetweenDate(date, start, end, options) {
         // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
         // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
         // behaves here exactly as `0` and `""` already do.
-        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
-        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
+        const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
         if (!isValidDate(date) || !isValidDate(start) || !isValidDate(end)) {
             return false;
         }

package/dist/plain/compare/isBetweenDateTime.d.ts

@@ -4,12 +4,11 @@
  * - Uses Temporal.PlainDateTime.compare to compare date-times.
  * - Returns false if start > end (invalid range).
  * - Returns false if any input is invalid.
- * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
  *
  * @param dateTime ISO PlainDateTime string to check
  * @param start ISO PlainDateTime string for the start of the range
  * @param end ISO PlainDateTime string for the end of the range
- * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @param options Whether each end of the range counts as inside it
  * @returns boolean indicating whether dateTime is between start and end
  *
  * @example isBetweenDateTime("2024-02-29T12:00:00", "2024-02-01T00:00:00", "2024-02-28T23:59:59") // false
@@ -21,6 +20,18 @@
  * @example isBetweenDateTime("2024-02-29T12:00:00", "2024-02-01T00:00:00", "invalid") // false
  */
 export declare function isBetweenDateTime(dateTime: string, start: string, end: string, options?: {
+    /**
+     * Whether `dateTime` equal to `start` counts as inside the range. `false` requires it to
+     * be after `start`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveStart?: boolean;
+    /**
+     * Whether `dateTime` equal to `end` counts as inside the range. `false` requires it to be
+     * before `end`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveEnd?: boolean;
 }): boolean;

package/dist/plain/compare/isBetweenDateTime.js

@@ -2,18 +2,18 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return true when `dateTime` is between `start` and `end` (inclusive by default).
  *
  * - Uses Temporal.PlainDateTime.compare to compare date-times.
  * - Returns false if start > end (invalid range).
  * - Returns false if any input is invalid.
- * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
  *
  * @param dateTime ISO PlainDateTime string to check
  * @param start ISO PlainDateTime string for the start of the range
  * @param end ISO PlainDateTime string for the end of the range
- * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @param options Whether each end of the range counts as inside it
  * @returns boolean indicating whether dateTime is between start and end
  *
  * @example isBetweenDateTime("2024-02-29T12:00:00", "2024-02-01T00:00:00", "2024-02-28T23:59:59") // false
@@ -33,8 +33,8 @@ export function isBetweenDateTime(dateTime, start, end, options) {
         // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
         // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
         // behaves here exactly as `0` and `""` already do.
-        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
-        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
+        const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
         if (!isValidDateTime(dateTime) ||
             !isValidDateTime(start) ||
             !isValidDateTime(end)) {

package/dist/plain/compare/isBetweenTime.d.ts

@@ -4,13 +4,12 @@
  * - Uses Temporal.PlainTime.compare to compare times.
  * - Returns false if start > end (invalid range).
  * - Returns false if any input is invalid.
- * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
  * - Note: PlainTime comparison does not account for day overflow.
  *
  * @param time ISO PlainTime string to check
  * @param start ISO PlainTime string for the start of the range
  * @param end ISO PlainTime string for the end of the range
- * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @param options Whether each end of the range counts as inside it
  * @returns boolean indicating whether time is between start and end
  *
  * @example isBetweenTime("12:34:56", "12:00:00", "13:00:00") // true
@@ -23,6 +22,18 @@
  * @example isBetweenTime("12:34:56", "12:00:00", "invalid") // false
  */
 export declare function isBetweenTime(time: string, start: string, end: string, options?: {
+    /**
+     * Whether `time` equal to `start` counts as inside the range. `false` requires it to
+     * be after `start`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveStart?: boolean;
+    /**
+     * Whether `time` equal to `end` counts as inside the range. `false` requires it to be
+     * before `end`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveEnd?: boolean;
 }): boolean;

package/dist/plain/compare/isBetweenTime.js

@@ -2,19 +2,19 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return true when `time` is between `start` and `end` (inclusive by default).
  *
  * - Uses Temporal.PlainTime.compare to compare times.
  * - Returns false if start > end (invalid range).
  * - Returns false if any input is invalid.
- * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
  * - Note: PlainTime comparison does not account for day overflow.
  *
  * @param time ISO PlainTime string to check
  * @param start ISO PlainTime string for the start of the range
  * @param end ISO PlainTime string for the end of the range
- * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @param options Whether each end of the range counts as inside it
  * @returns boolean indicating whether time is between start and end
  *
  * @example isBetweenTime("12:34:56", "12:00:00", "13:00:00") // true
@@ -35,8 +35,8 @@ export function isBetweenTime(time, start, end, options) {
         // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
         // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
         // behaves here exactly as `0` and `""` already do.
-        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
-        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
+        const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
         if (!isValidTime(time) || !isValidTime(start) || !isValidTime(end)) {
             return false;
         }

package/dist/plain/compare/isRelativeDay.d.ts

@@ -14,7 +14,7 @@
  * - `offsetDays` must be an integer; non-integer or non-finite values return false.
  * - Returns false if `value` is invalid or the system timeZone is unavailable.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isToday(value)` → `isRelativeDay(value, 0)`
  * - `isYesterday(value)` → `isRelativeDay(value, -1)`
  * - `isTomorrow(value)` → `isRelativeDay(value, 1)`

package/dist/plain/compare/isRelativeDay.js

@@ -18,7 +18,7 @@ import { areDatesEqual } from "./areDatesEqual.js";
  * - `offsetDays` must be an integer; non-integer or non-finite values return false.
  * - Returns false if `value` is invalid or the system timeZone is unavailable.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isToday(value)` → `isRelativeDay(value, 0)`
  * - `isYesterday(value)` → `isRelativeDay(value, -1)`
  * - `isTomorrow(value)` → `isRelativeDay(value, 1)`

package/dist/plain/compare/isThisUnit.d.ts

@@ -21,7 +21,7 @@ import type { Temporal } from "@js-temporal/polyfill";
  *   unit, so an invalid locale returns false for `"day"`, `"month"` and `"year"` too.
  * - **Compatibility:** before 1.16.0 an invalid locale was ignored for every unit but `"week"`.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isThisWeek(value, options)` → `isThisUnit(value, "week", locale)`
  * - `isThisMonth(value)` → `isThisUnit(value, "month")`
  * - `isThisYear(value)` → `isThisUnit(value, "year")`

package/dist/plain/compare/isThisUnit.js

@@ -26,7 +26,7 @@ import { areDatesEqualBy } from "./areDatesEqualBy.js";
  *   unit, so an invalid locale returns false for `"day"`, `"month"` and `"year"` too.
  * - **Compatibility:** before 1.16.0 an invalid locale was ignored for every unit but `"week"`.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isThisWeek(value, options)` → `isThisUnit(value, "week", locale)`
  * - `isThisMonth(value)` → `isThisUnit(value, "month")`
  * - `isThisYear(value)` → `isThisUnit(value, "year")`

package/dist/plain/format/formatCalendar.d.ts

@@ -1,19 +1,24 @@
 import type { CalendarOptions } from "../../types/index.js";
+/**
+ * Options for `formatCalendar`: the date-time the value is compared with, and the style of the
+ * time-of-day half.
+ */
 export interface FormatCalendarOptions extends CalendarOptions {
     /**
-     * `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half.
-     * "long" and "full" are not offered: they differ from "medium" only by a
-     * `timeZoneName`, and a plain value has no zone. Passed anyway (from
-     * untyped code), they format as "medium" — Temporal's PlainDateTime format
-     * drops `timeZoneName` (AdjustDateTimeStyleFormat).
+     * The length of the time-of-day part, as the `timeStyle` of `Intl.DateTimeFormat`. "long" and
+     * "full" are not offered: they differ from "medium" only by a `timeZoneName`, and a plain value
+     * has no zone. Passed anyway (from untyped code), they format as "medium" — Temporal's
+     * PlainDateTime format drops `timeZoneName` (AdjustDateTimeStyleFormat).
+     *
+     * @defaultValue `"short"`
      */
     timeStyle?: "short" | "medium";
 }
 /**
  * Format a plain date-time as a relative day label plus time-of-day, e.g.
- * "Tomorrow at 2:30 PM" — Moment's `.calendar()`, which the existing
- * `formatRelativeDateTime` family does not cover (that family renders
- * "in 1 day", an elapsed-time phrase, not a day label + clock time).
+ * "Tomorrow at 2:30 PM". The `formatRelativeDateTime` family does not
+ * cover this: it renders "in 1 day", an elapsed-time phrase, not a day
+ * label + clock time.
  *
  * - Within `±6` days of `reference` (default: now), renders `<day label>`
  *   joined to the localized time using the locale's own connector — never a
@@ -21,15 +26,17 @@ export interface FormatCalendarOptions extends CalendarOptions {
  *   (`numeric: "auto"`), so it reads "Today"/"Tomorrow"/"Yesterday" near
  *   the boundary and "in N days"/"N days ago" further out, all locale-native.
  * - Beyond `±6` days, falls back to an absolute `dateStyle: "long"` +
- *   `timeStyle` string with no relative wording, matching Moment's
- *   `sameElse` behavior.
+ *   `timeStyle` string with no relative wording. The one-week limit is
+ *   GMT's own rule, not a standard's: from 7 days out a date is easier to
+ *   place than a day count.
+ * - Comparison: Moment's `.calendar()` switches to a date at the same
+ *   distance (its `sameElse` case); its wording inside the week differs.
  * - The connector between the day label and the time is read from CLDR's
  *   own combined date+time pattern for the locale (see
  *   `internal/joinDateTimeConnector.ts`), not hardcoded — this is what lets
  *   `formatCalendar` avoid the i18n objection that excludes a token
- *   formatter (Decision 1 in `context/roadmap/issues/J.md`).
- * - The time never carries a zone name: a plain value has none. A `timeStyle` of `"long"` or
- *   `"full"` (outside the type) formats as `"medium"`.
+ *   formatter.
+ * - The time never carries a zone name: a plain value has none.
  * - Use `formatCalendar` for user-facing schedules ("Tomorrow at 2:30 PM");
  *   use `formatRelativeDateTime` for elapsed-time displays ("in 1 day").
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
@@ -37,7 +44,7 @@ export interface FormatCalendarOptions extends CalendarOptions {
  *
  * @param value ISO PlainDateTime string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { reference, timeStyle }
+ * @param options What the value is compared with and how the time is written
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendar("2026-03-16T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "tomorrow at 2:30 PM"

package/dist/plain/format/formatCalendar.js

@@ -3,15 +3,16 @@ import { Temporal } from "@js-temporal/polyfill";
 import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.js";
 import { plainTimeStyle } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
-// Beyond a week either direction, Moment's `.calendar()` falls back to an
-// absolute date rather than "6 days ago" / "in 6 days" wording. GMT follows
-// the same threshold (documented, not a byte-for-byte Moment port — see J15).
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
+// GMT's own rule, not a standard's: the relative day label is kept for distances
+// under one week (up to 6 calendar days either way). From 7 days out the phrase
+// is an absolute date, which is easier to place than a day count.
 const ABS_DAY_THRESHOLD = 6;
 /**
  * Format a plain date-time as a relative day label plus time-of-day, e.g.
- * "Tomorrow at 2:30 PM" — Moment's `.calendar()`, which the existing
- * `formatRelativeDateTime` family does not cover (that family renders
- * "in 1 day", an elapsed-time phrase, not a day label + clock time).
+ * "Tomorrow at 2:30 PM". The `formatRelativeDateTime` family does not
+ * cover this: it renders "in 1 day", an elapsed-time phrase, not a day
+ * label + clock time.
  *
  * - Within `±6` days of `reference` (default: now), renders `<day label>`
  *   joined to the localized time using the locale's own connector — never a
@@ -19,15 +20,17 @@ const ABS_DAY_THRESHOLD = 6;
  *   (`numeric: "auto"`), so it reads "Today"/"Tomorrow"/"Yesterday" near
  *   the boundary and "in N days"/"N days ago" further out, all locale-native.
  * - Beyond `±6` days, falls back to an absolute `dateStyle: "long"` +
- *   `timeStyle` string with no relative wording, matching Moment's
- *   `sameElse` behavior.
+ *   `timeStyle` string with no relative wording. The one-week limit is
+ *   GMT's own rule, not a standard's: from 7 days out a date is easier to
+ *   place than a day count.
+ * - Comparison: Moment's `.calendar()` switches to a date at the same
+ *   distance (its `sameElse` case); its wording inside the week differs.
  * - The connector between the day label and the time is read from CLDR's
  *   own combined date+time pattern for the locale (see
  *   `internal/joinDateTimeConnector.ts`), not hardcoded — this is what lets
  *   `formatCalendar` avoid the i18n objection that excludes a token
- *   formatter (Decision 1 in `context/roadmap/issues/J.md`).
- * - The time never carries a zone name: a plain value has none. A `timeStyle` of `"long"` or
- *   `"full"` (outside the type) formats as `"medium"`.
+ *   formatter.
+ * - The time never carries a zone name: a plain value has none.
  * - Use `formatCalendar` for user-facing schedules ("Tomorrow at 2:30 PM");
  *   use `formatRelativeDateTime` for elapsed-time displays ("in 1 day").
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
@@ -35,7 +38,7 @@ const ABS_DAY_THRESHOLD = 6;
  *
  * @param value ISO PlainDateTime string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { reference, timeStyle }
+ * @param options What the value is compared with and how the time is written
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendar("2026-03-16T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "tomorrow at 2:30 PM"
@@ -52,18 +55,20 @@ export function formatCalendar(value, locale, options = {}) {
             return "";
         if (!isValidDateTime(value))
             return "";
-        if (options.reference !== undefined && !isValidDateTime(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidDateTime(referenceOption))
             return "";
         try {
             const target = Temporal.PlainDateTime.from(value);
-            const reference = options.reference
-                ? Temporal.PlainDateTime.from(options.reference)
+            const reference = referenceOption
+                ? Temporal.PlainDateTime.from(referenceOption)
                 : Temporal.Now.plainDateTimeISO();
             const diffDays = target.toPlainDate().since(reference.toPlainDate()).days;
             // "long"/"full" are outside the type but reachable from JS; their zone
             // name would describe the UTC anchor, not the value. Temporal's
             // PlainDateTime format drops timeZoneName (AdjustDateTimeStyleFormat).
-            const timeStyle = plainTimeStyle(options.timeStyle === undefined ? "short" : options.timeStyle);
+            const timeStyle = plainTimeStyle(optionOrDefault(options.timeStyle, "short"));
             // Plain values carry no timezone. UTC is an arbitrary but stable anchor
             // for reusing Intl's part-level formatting — any fixed zone reproduces
             // the same wall-clock fields since there's no real zone to get wrong.

package/dist/plain/format/formatDate.js

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
 import { plainDateFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDate } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return a localized string for a PlainDate ISO input using Intl options.
  *
@@ -45,12 +46,13 @@ export function formatDate(value, locale, options) {
         // (CreateDateTimeFormat ~date~, ~date~), so the requested fields and
         // widths are kept. Constructing with the caller's options first surfaces
         // the TypeError or RangeError Intl.DateTimeFormat raises for invalid ones.
-        new Intl.DateTimeFormat(locale, options);
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
         // CreateDateTimeFormat: required ~date~ with a timeStyle is a TypeError.
-        if (options?.timeStyle !== undefined) {
+        if (read.timeStyle !== undefined) {
             return "";
         }
-        const resolved = plainDateFormatOptions(options ?? {});
+        const resolved = plainDateFormatOptions(read);
         if (resolved === null) {
             return "";
         }

package/dist/plain/format/formatDateRange.js

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
 import { plainDateFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDate } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Format a plain date range using the Temporal Intl.DateTimeFormat formatRange API.
  *
@@ -43,8 +44,9 @@ export function formatDateRange(start, end, locale, options) {
         // (GetDateTimeFormat ~date~, ~date~, ~relevant~). Constructing with the
         // caller's options first surfaces the TypeError or RangeError
         // Intl.DateTimeFormat raises for invalid ones.
-        new Intl.DateTimeFormat(locale, options);
-        const resolved = plainDateFormatOptions(options ?? {});
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
+        const resolved = plainDateFormatOptions(read);
         if (resolved === null) {
             return "";
         }

package/dist/plain/format/formatDateTime.js

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
 import { plainDateTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return a localized string for a PlainDateTime ISO input using Intl options.
  *
@@ -47,9 +48,10 @@ export function formatDateTime(value, locale, options) {
         // and style widths are kept. Constructing with the caller's options first
         // surfaces the TypeError or RangeError Intl.DateTimeFormat raises for
         // invalid ones.
-        new Intl.DateTimeFormat(locale, options);
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
         const epochMilliseconds = Temporal.PlainDateTime.from(value).toZonedDateTime("UTC").epochMilliseconds;
-        return normalizeDateTime(new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options ?? {})).format(epochMilliseconds));
+        return normalizeDateTime(new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(read)).format(epochMilliseconds));
     }
     catch {
         return "";

package/dist/plain/format/formatDateTimeRange.js

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
 import { plainDateTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Format a plain datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
@@ -46,8 +47,9 @@ export function formatDateTimeRange(start, end, locale, options) {
         // (GetDateTimeFormat ~any~, ~all~, ~relevant~). Constructing with the
         // caller's options first surfaces the TypeError or RangeError
         // Intl.DateTimeFormat raises for invalid ones.
-        new Intl.DateTimeFormat(locale, options);
-        const out = new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options ?? {})).formatRange(Temporal.PlainDateTime.from(start).toZonedDateTime("UTC")
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
+        const out = new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(read)).formatRange(Temporal.PlainDateTime.from(start).toZonedDateTime("UTC")
             .epochMilliseconds, Temporal.PlainDateTime.from(end).toZonedDateTime("UTC").epochMilliseconds);
         return normalizeDateTime(out);
     }

package/dist/plain/format/formatDateTimeToParts.d.ts

@@ -5,8 +5,7 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`, `"literal"`.
@@ -24,8 +23,11 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   zone field): a `timeZoneName` option is ignored, and a `"long"`/`"full"` `timeStyle` keeps its
  *   hour, minute and second and drops the zone, formatting as the locale's `"medium"` time. As in
  *   `Intl.DateTimeFormat`, `timeZoneName` together with `dateStyle`/`timeStyle` yields `[]`.
- * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
- *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
+ * - The literal before the day period depends on the runtime. CLDR 42 (ICU 72) put U+202F NARROW
+ *   NO-BREAK SPACE there for `en-US`; Node 22 and 24 return it in the parts, and Node 26 returns
+ *   an ordinary space (U+0020) instead. Both were checked on those runtimes. The examples show the
+ *   Node 22 and 24 form, written as `"\u202f"` so the difference is visible. Treat the two
+ *   characters as equal when you compare parts.
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts.
  *   Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
@@ -50,6 +52,15 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * @example formatDateTimeToParts("2024-02-03T14:30:45", ["fr-FR", "en-US"], { dateStyle: "medium", timeStyle: "short" }) // parts of "3 févr. 2024, 14:30"
  */
 export declare function formatDateTimeToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
+    /**
+     * The kind of part, named as ECMA-402 `Intl.DateTimeFormat.prototype.formatToParts` names it: a
+     * field such as `"year"`, `"month"` or `"day"`, or `"literal"` for the separator text between
+     * fields.
+     */
     type: string;
+    /**
+     * The text of the part in the requested locale, exactly as the formatter wrote it. Joining every
+     * `value` in array order gives the whole formatted text.
+     */
     value: string;
 }>;