@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/isoStringBody.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The part of a Temporal ISO 8601 string before its first RFC 9557 annotation: everything before
+ * the first `[`, or the whole string when it has none.
+ *
+ * GMT's validators check this part against GMT's strict ISO 8601 extended shape (`plainDate`,
+ * `plainDateTime`, `plainTime`, `utcDateTime`, and `zonedDateTimeBody` / `instantBody` below) and hand the whole string to `Temporal.X.from`, which applies Temporal's
+ * annotation grammar (proposal-temporal `ParseISODateTime`; RFC 9557 §3.3): elective unknown
+ * annotations and a time zone annotation on a plain value are read and ignored, the first `u-ca`
+ * annotation names the calendar, and an unknown critical annotation is rejected. The same split
+ * as `internal/calendarDateString.ts`.
+ *
+ * @param value candidate ISO 8601 string
+ * @returns the string up to its first annotation, or `""` for a non-string
+ *
+ * @example isoStringBody("2024-03-10[u-ca=iso8601]") // "2024-03-10"
+ * @example isoStringBody("2024-03-10T12:30Z[foo=bar]") // "2024-03-10T12:30Z"
+ * @example isoStringBody("12:30") // "12:30"
+ */
+export declare function isoStringBody(value: string): string;
+/**
+ * An ISO 8601 extended UTC offset, as RFC 3339 §5.6 `time-numoffset` writes it (`±HH:MM`), with
+ * the seconds and fraction Temporal's `UTCOffset` grammar adds (`±HH:MM:SS[.fraction]`, the
+ * fraction after either decimal sign, `.` or `,`, as `TemporalDecimalSeparator` allows). Hours
+ * 00–23. Basic (`-0400`) and hour-only (`-04`) offsets, which Temporal also reads, do not match.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed it:
+ * GMT's one statement of the offset grammar its instant and zoned validators accept.
+ *
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("+05:30:00,5") // true
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("-0400") // false (basic format)
+ */
+export declare const EXTENDED_UTC_OFFSET = "[+-](?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:[.,]\\d{1,9})?)?";
+/**
+ * An RFC 9557 time-zone annotation: a bracket whose content has no `=` (§4.1 `time-zone`,
+ * against `suffix-tag`'s `key=value`), with an optional leading `!` marking it critical (§3.3).
+ * `[Europe/London]`, `[!+01:00]`; never `[u-ca=hebrew]` or `[!foo=bar]`. Every `key=value`
+ * bracket is a tagged annotation, which Temporal reads (or rejects) on its own.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed or
+ * anchor it: GMT's one statement of "this bracket names a time zone".
+ *
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[!Europe/London]") // true
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[u-ca=gregory]") // false
+ */
+export declare const TIME_ZONE_ANNOTATION = "\\[!?[^\\]=]+\\]";
+/**
+ * True when `value` is a string whose part before the first annotation is `zonedDateTimeBody`.
+ * The shape gate every GMT zoned string input passes before `Temporal.ZonedDateTime.from`.
+ *
+ * @param value candidate zoned datetime string
+ * @returns whether the unannotated part has GMT's strict extended zoned shape
+ *
+ * @example hasZonedDateTimeShape("2024-10-03T14:30:00-04:00[America/New_York]") // true
+ * @example hasZonedDateTimeShape("2024-10-03 14:30:00-04:00[America/New_York]") // false
+ */
+export declare function hasZonedDateTimeShape(value: string): boolean;
+/**
+ * True when `value` is a string whose part before the first annotation is `instantBody`.
+ *
+ * @param value candidate instant string
+ * @returns whether the unannotated part has GMT's strict extended instant shape
+ *
+ * @example hasInstantShape("2024-10-03T18:30:00Z[foo=bar]") // true
+ * @example hasInstantShape("20241003T183000Z") // false
+ */
+export declare function hasInstantShape(value: string): boolean;

package/dist/internal/isoStringBody.js

@@ -0,0 +1,105 @@
+import { plainDateTime } from "../regex/date-time.js";
+/**
+ * The part of a Temporal ISO 8601 string before its first RFC 9557 annotation: everything before
+ * the first `[`, or the whole string when it has none.
+ *
+ * GMT's validators check this part against GMT's strict ISO 8601 extended shape (`plainDate`,
+ * `plainDateTime`, `plainTime`, `utcDateTime`, and `zonedDateTimeBody` / `instantBody` below) and hand the whole string to `Temporal.X.from`, which applies Temporal's
+ * annotation grammar (proposal-temporal `ParseISODateTime`; RFC 9557 §3.3): elective unknown
+ * annotations and a time zone annotation on a plain value are read and ignored, the first `u-ca`
+ * annotation names the calendar, and an unknown critical annotation is rejected. The same split
+ * as `internal/calendarDateString.ts`.
+ *
+ * @param value candidate ISO 8601 string
+ * @returns the string up to its first annotation, or `""` for a non-string
+ *
+ * @example isoStringBody("2024-03-10[u-ca=iso8601]") // "2024-03-10"
+ * @example isoStringBody("2024-03-10T12:30Z[foo=bar]") // "2024-03-10T12:30Z"
+ * @example isoStringBody("12:30") // "12:30"
+ */
+export function isoStringBody(value) {
+    if (typeof value !== "string") {
+        return "";
+    }
+    const annotationStart = value.indexOf("[");
+    return annotationStart === -1 ? value : value.slice(0, annotationStart);
+}
+/**
+ * An ISO 8601 extended UTC offset, as RFC 3339 §5.6 `time-numoffset` writes it (`±HH:MM`), with
+ * the seconds and fraction Temporal's `UTCOffset` grammar adds (`±HH:MM:SS[.fraction]`, the
+ * fraction after either decimal sign, `.` or `,`, as `TemporalDecimalSeparator` allows). Hours
+ * 00–23. Basic (`-0400`) and hour-only (`-04`) offsets, which Temporal also reads, do not match.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed it:
+ * GMT's one statement of the offset grammar its instant and zoned validators accept.
+ *
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("+05:30:00,5") // true
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("-0400") // false (basic format)
+ */
+export const EXTENDED_UTC_OFFSET = "[+-](?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:[.,]\\d{1,9})?)?";
+/**
+ * An RFC 9557 time-zone annotation: a bracket whose content has no `=` (§4.1 `time-zone`,
+ * against `suffix-tag`'s `key=value`), with an optional leading `!` marking it critical (§3.3).
+ * `[Europe/London]`, `[!+01:00]`; never `[u-ca=hebrew]` or `[!foo=bar]`. Every `key=value`
+ * bracket is a tagged annotation, which Temporal reads (or rejects) on its own.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed or
+ * anchor it: GMT's one statement of "this bracket names a time zone".
+ *
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[!Europe/London]") // true
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[u-ca=gregory]") // false
+ */
+export const TIME_ZONE_ANNOTATION = "\\[!?[^\\]=]+\\]";
+/** `plainDateTime` without its anchors: `<date>T<time>` with an optional fraction. */
+const EXTENDED_DATE_TIME = plainDateTime.source.slice(1, -1);
+/**
+ * The part of a zoned datetime string before its first annotation (`isoStringBody`), in GMT's
+ * strict ISO 8601 extended shape: `<date>T<time>` exactly as `plainDateTime` matches it, then
+ * nothing, an upper-case `Z`, or an extended offset (`±HH:MM[:SS[.fraction]]`). GMT's strict-shape rule
+ * applied to zoned strings. `Temporal.ZonedDateTime.from` reads more — basic format, a space or
+ * lower-case `t` separator, a lower-case `z`, an hour-only time or offset, a date with no time —
+ * and GMT rejects all of it before Temporal reads the annotations.
+ *
+ * @example zonedDateTimeBody.test("2024-10-03T14:30:00-04:00") // true
+ * @example zonedDateTimeBody.test("2024-10-03T14:30:00") // true (the zone annotation resolves the offset)
+ * @example zonedDateTimeBody.test("20241003T143000-0400") // false (basic format)
+ * @example zonedDateTimeBody.test("2024-10-03") // false (no time)
+ */
+const zonedDateTimeBody = new RegExp(`^${EXTENDED_DATE_TIME}(?:Z|${EXTENDED_UTC_OFFSET})?$`);
+/**
+ * An instant string before its first annotation, in GMT's strict ISO 8601 extended shape: the
+ * `zonedDateTimeBody` shape with the `Z` or offset required (an instant has no zone to resolve a
+ * wall clock). `Temporal.Instant.from` also reads basic format, `t`/space separators, `z` and
+ * hour-only offsets; GMT rejects them.
+ *
+ * @example instantBody.test("2024-10-03T18:30:00Z") // true
+ * @example instantBody.test("2024-10-03T14:30:00-04:00") // true
+ * @example instantBody.test("2024-10-03T18:30:00z") // false (lower-case z)
+ * @example instantBody.test("2024-10-03T14:30:00") // false (no designator)
+ */
+const instantBody = new RegExp(`^${EXTENDED_DATE_TIME}(?:Z|${EXTENDED_UTC_OFFSET})$`);
+/**
+ * True when `value` is a string whose part before the first annotation is `zonedDateTimeBody`.
+ * The shape gate every GMT zoned string input passes before `Temporal.ZonedDateTime.from`.
+ *
+ * @param value candidate zoned datetime string
+ * @returns whether the unannotated part has GMT's strict extended zoned shape
+ *
+ * @example hasZonedDateTimeShape("2024-10-03T14:30:00-04:00[America/New_York]") // true
+ * @example hasZonedDateTimeShape("2024-10-03 14:30:00-04:00[America/New_York]") // false
+ */
+export function hasZonedDateTimeShape(value) {
+    return (typeof value === "string" && zonedDateTimeBody.test(isoStringBody(value)));
+}
+/**
+ * True when `value` is a string whose part before the first annotation is `instantBody`.
+ *
+ * @param value candidate instant string
+ * @returns whether the unannotated part has GMT's strict extended instant shape
+ *
+ * @example hasInstantShape("2024-10-03T18:30:00Z[foo=bar]") // true
+ * @example hasInstantShape("20241003T183000Z") // false
+ */
+export function hasInstantShape(value) {
+    return typeof value === "string" && instantBody.test(isoStringBody(value));
+}

package/dist/internal/joinDateTimeConnector.d.ts

@@ -34,4 +34,4 @@
  * @param timeStyle Intl.DateTimeFormatOptions `timeStyle` for the time half
  * @returns `dayLabel` joined to the localized time with the locale's own connector
  */
-export declare function joinDateTimeConnector(epochMilliseconds: number, timeZone: string, locale: string | undefined, dayLabel: string, timeStyle: "short" | "medium" | "full"): string;
+export declare function joinDateTimeConnector(epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, dayLabel: string, timeStyle: "short" | "medium" | "full"): string;

package/dist/internal/localeWeekInfo.d.ts

@@ -0,0 +1,34 @@
+import { type LocalesArgument } from "./resolveLocale.js";
+interface LocaleWeekInfo {
+    firstDay: number;
+    weekend: number[];
+    minimalDays: number;
+}
+declare global {
+    namespace Intl {
+        interface Locale {
+            /** The proposal's current API. V8 12.x and later (Node 24, Node 26). */
+            getWeekInfo?(): Partial<LocaleWeekInfo>;
+            /** The proposal's earlier accessor. Removed in V8 14 (Node 26); present on Node 22/24. */
+            readonly weekInfo?: Partial<LocaleWeekInfo>;
+        }
+    }
+}
+/**
+ * A locale's CLDR week data, from whichever form of the Intl Locale Info proposal the runtime
+ * implements.
+ *
+ * - Prefers `Intl.Locale.prototype.getWeekInfo()`, the proposal's current method, and falls back
+ *   to the earlier `weekInfo` accessor on engines that only have that (Node 22). Node 26 removed
+ *   the accessor, so reading it alone silently returned `undefined` there and every locale lost
+ *   its week data.
+ * - Returns `undefined` when neither form is available. Fields may be missing: Node 24/26 omit
+ *   `minimalDays`. Callers apply their own ISO defaults.
+ * - Throws `RangeError` (from `Intl.Locale`) if `locale` is not a well-formed BCP 47 tag; callers turn
+ *   that into their sentinel.
+ *
+ * @example localeWeekInfo("en-US")?.firstDay // 7
+ * @example localeWeekInfo("ar-SA")?.weekend // [5, 6]
+ */
+export declare function localeWeekInfo(locale: LocalesArgument): Partial<LocaleWeekInfo> | undefined;
+export {};

package/dist/internal/localeWeekInfo.js

@@ -0,0 +1,27 @@
+import { resolveRequiredLocale } from "./resolveLocale.js";
+/**
+ * A locale's CLDR week data, from whichever form of the Intl Locale Info proposal the runtime
+ * implements.
+ *
+ * - Prefers `Intl.Locale.prototype.getWeekInfo()`, the proposal's current method, and falls back
+ *   to the earlier `weekInfo` accessor on engines that only have that (Node 22). Node 26 removed
+ *   the accessor, so reading it alone silently returned `undefined` there and every locale lost
+ *   its week data.
+ * - Returns `undefined` when neither form is available. Fields may be missing: Node 24/26 omit
+ *   `minimalDays`. Callers apply their own ISO defaults.
+ * - Throws `RangeError` (from `Intl.Locale`) if `locale` is not a well-formed BCP 47 tag; callers turn
+ *   that into their sentinel.
+ *
+ * @example localeWeekInfo("en-US")?.firstDay // 7
+ * @example localeWeekInfo("ar-SA")?.weekend // [5, 6]
+ */
+export function localeWeekInfo(locale) {
+    const resolved = resolveRequiredLocale(locale);
+    if (resolved === null)
+        throw new RangeError("Invalid locale");
+    const intlLocale = new Intl.Locale(resolved);
+    if (typeof intlLocale.getWeekInfo === "function") {
+        return intlLocale.getWeekInfo();
+    }
+    return intlLocale.weekInfo;
+}

package/dist/internal/maxPieces.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Default `maxPieces` for functions that return one array element per generated piece
+ * (`splitIntervalByUnit*`, `intervalDivideEqually*`, `mapDatesInRange`, `mapZonedDatesInRange`).
+ *
+ * Owner decision A2 (CORE-8): an output that would be larger returns the sentinel `[]` rather
+ * than exhausting the heap, which aborts the process where no caller can catch it.
+ */
+export declare const DEFAULT_MAX_PIECES = 1000000;
+/** ECMA-262 §10.4.2 (Array exotic objects): an array length is at most 2^32 - 1. */
+export declare const MAX_ARRAY_LENGTH: number;
+/**
+ * Read the `maxPieces` option.
+ *
+ * - Omitted options, or an omitted/`undefined` `maxPieces`, give `DEFAULT_MAX_PIECES`
+ *   (Temporal GetOption reads `undefined` as absent).
+ * - A non-object options argument returns `null` (Temporal GetOptionsObject throws `TypeError`).
+ * - `maxPieces` must be a positive safe integer, otherwise `null`.
+ *
+ * @param options the caller's options argument
+ * @returns the piece limit, or `null` when the option is invalid
+ *
+ * @example resolveMaxPieces(undefined) // 1000000
+ * @example resolveMaxPieces({ maxPieces: 10 }) // 10
+ * @example resolveMaxPieces({ maxPieces: 0 }) // null
+ */
+export declare function resolveMaxPieces(options: {
+    maxPieces?: number;
+} | undefined): number | null;
+/**
+ * Whether an output of `count` pieces is over the limit.
+ *
+ * - Over `maxPieces`, or over the longest array a JavaScript engine can hold.
+ *
+ * @param count number of pieces the output would hold
+ * @param maxPieces resolved limit from `resolveMaxPieces`
+ * @returns `true` when the function must return its sentinel instead
+ *
+ * @example exceedsPieceLimit(11, 10) // true
+ * @example exceedsPieceLimit(2 ** 32, 2 ** 40) // true
+ */
+export declare function exceedsPieceLimit(count: number, maxPieces: number): boolean;

package/dist/internal/maxPieces.js

@@ -0,0 +1,53 @@
+/**
+ * Default `maxPieces` for functions that return one array element per generated piece
+ * (`splitIntervalByUnit*`, `intervalDivideEqually*`, `mapDatesInRange`, `mapZonedDatesInRange`).
+ *
+ * Owner decision A2 (CORE-8): an output that would be larger returns the sentinel `[]` rather
+ * than exhausting the heap, which aborts the process where no caller can catch it.
+ */
+export const DEFAULT_MAX_PIECES = 1_000_000;
+/** ECMA-262 §10.4.2 (Array exotic objects): an array length is at most 2^32 - 1. */
+export const MAX_ARRAY_LENGTH = 2 ** 32 - 1;
+/**
+ * Read the `maxPieces` option.
+ *
+ * - Omitted options, or an omitted/`undefined` `maxPieces`, give `DEFAULT_MAX_PIECES`
+ *   (Temporal GetOption reads `undefined` as absent).
+ * - A non-object options argument returns `null` (Temporal GetOptionsObject throws `TypeError`).
+ * - `maxPieces` must be a positive safe integer, otherwise `null`.
+ *
+ * @param options the caller's options argument
+ * @returns the piece limit, or `null` when the option is invalid
+ *
+ * @example resolveMaxPieces(undefined) // 1000000
+ * @example resolveMaxPieces({ maxPieces: 10 }) // 10
+ * @example resolveMaxPieces({ maxPieces: 0 }) // null
+ */
+export function resolveMaxPieces(options) {
+    if (options === undefined) {
+        return DEFAULT_MAX_PIECES;
+    }
+    if (typeof options !== "object" || options === null) {
+        return null;
+    }
+    const { maxPieces } = options;
+    if (maxPieces === undefined) {
+        return DEFAULT_MAX_PIECES;
+    }
+    return Number.isSafeInteger(maxPieces) && maxPieces > 0 ? maxPieces : null;
+}
+/**
+ * Whether an output of `count` pieces is over the limit.
+ *
+ * - Over `maxPieces`, or over the longest array a JavaScript engine can hold.
+ *
+ * @param count number of pieces the output would hold
+ * @param maxPieces resolved limit from `resolveMaxPieces`
+ * @returns `true` when the function must return its sentinel instead
+ *
+ * @example exceedsPieceLimit(11, 10) // true
+ * @example exceedsPieceLimit(2 ** 32, 2 ** 40) // true
+ */
+export function exceedsPieceLimit(count, maxPieces) {
+    return count > maxPieces || count > MAX_ARRAY_LENGTH;
+}

package/dist/internal/measureNearRangeEnd.d.ts

@@ -0,0 +1,26 @@
+interface ShiftableByDays<T> {
+    readonly calendarId: string;
+    withCalendar(calendar: "iso8601"): {
+        readonly year: number;
+    };
+    subtract(duration: {
+        days: number;
+    }): T;
+}
+/**
+ * Run `measure` on `source`, and when it throws because a boundary it builds lies after the last
+ * representable date, run it again on `source` shifted back by whole 400-year Gregorian cycles.
+ *
+ * - Use only for a quantity the cycle leaves unchanged: a length in days (or time) between
+ *   boundaries of years, months or weeks. Never for a returned date.
+ * - Applies to Gregorian-structured calendars only; any other calendar rethrows the error.
+ * - A source already below `PROXY_FLOOR_YEAR` rethrows: its failure is not a max-edge one.
+ *
+ * @param source date or date-time whose surroundings are measured
+ * @param measure computes the quantity from a date in the same position of its cycle
+ * @returns the quantity, identical for `source` and its shifted proxy
+ *
+ * @example measureNearRangeEnd(Temporal.PlainDate.from("+275760-09-13"), (d) => d.until(d.with({ month: 10, day: 1 })).days) // 18
+ */
+export declare function measureNearRangeEnd<T extends ShiftableByDays<T>, R>(source: T, measure: (from: T) => R): R;
+export {};

package/dist/internal/measureNearRangeEnd.js

@@ -0,0 +1,47 @@
+/**
+ * Days in one 400-year proleptic Gregorian cycle (97 leap years: 400 × 365 + 97). The cycle is a
+ * whole number of weeks (146,097 = 7 × 20,871), so shifting a date by it keeps its month lengths,
+ * leap years and weekday (ISO 8601-1:2019 §4.3.4 and §4.3.2.1).
+ */
+const GREGORIAN_CYCLE_DAYS = 146_097;
+/** ISO year the proxy is shifted down to or just above: clear of every era start (reiwa, 2019). */
+const PROXY_FLOOR_YEAR = 2400;
+/**
+ * Calendars whose months, leap years and year starts follow the proleptic Gregorian calendar
+ * (CLDR calendar data: gregory, buddhist and roc only offset the year number; japanese does too
+ * outside its era-start years, and the proxy never lands on one).
+ */
+const GREGORIAN_STRUCTURED_CALENDARS = new Set([
+    "iso8601",
+    "gregory",
+    "buddhist",
+    "roc",
+    "japanese",
+]);
+/**
+ * Run `measure` on `source`, and when it throws because a boundary it builds lies after the last
+ * representable date, run it again on `source` shifted back by whole 400-year Gregorian cycles.
+ *
+ * - Use only for a quantity the cycle leaves unchanged: a length in days (or time) between
+ *   boundaries of years, months or weeks. Never for a returned date.
+ * - Applies to Gregorian-structured calendars only; any other calendar rethrows the error.
+ * - A source already below `PROXY_FLOOR_YEAR` rethrows: its failure is not a max-edge one.
+ *
+ * @param source date or date-time whose surroundings are measured
+ * @param measure computes the quantity from a date in the same position of its cycle
+ * @returns the quantity, identical for `source` and its shifted proxy
+ *
+ * @example measureNearRangeEnd(Temporal.PlainDate.from("+275760-09-13"), (d) => d.until(d.with({ month: 10, day: 1 })).days) // 18
+ */
+export function measureNearRangeEnd(source, measure) {
+    try {
+        return measure(source);
+    }
+    catch (error) {
+        const cycles = Math.floor((source.withCalendar("iso8601").year - PROXY_FLOOR_YEAR) / 400);
+        if (cycles <= 0 || !GREGORIAN_STRUCTURED_CALENDARS.has(source.calendarId)) {
+            throw error;
+        }
+        return measure(source.subtract({ days: cycles * GREGORIAN_CYCLE_DAYS }));
+    }
+}

package/dist/internal/monthGridWeekRow.d.ts

@@ -8,5 +8,8 @@ import type { Temporal } from "@js-temporal/polyfill";
  * `getWeeksInMonth` (row for the month's last day, i.e. the row count).
  * Week 1 is the row containing the 1st of the month, even when that row
  * is a partial week (date-fns's `getWeekOfMonth` convention).
+ *
+ * Only the weekday of the 1st is read, so callers may pass `{ dayOfWeek }` without building a
+ * date that could lie before the representable range (April 1 of -271821).
  */
-export declare function monthGridWeekRow(firstOfMonth: Temporal.PlainDate, firstDay: number, dayInMonth: number): number;
+export declare function monthGridWeekRow(firstOfMonth: Pick<Temporal.PlainDate, "dayOfWeek">, firstDay: number, dayInMonth: number): number;

package/dist/internal/monthGridWeekRow.js

@@ -7,6 +7,9 @@
  * `getWeeksInMonth` (row for the month's last day, i.e. the row count).
  * Week 1 is the row containing the 1st of the month, even when that row
  * is a partial week (date-fns's `getWeekOfMonth` convention).
+ *
+ * Only the weekday of the 1st is read, so callers may pass `{ dayOfWeek }` without building a
+ * date that could lie before the representable range (April 1 of -271821).
  */
 export function monthGridWeekRow(firstOfMonth, firstDay, dayInMonth) {
     const leadingOffset = (firstOfMonth.dayOfWeek - firstDay + 7) % 7;

package/dist/internal/normalizeTimeZone.d.ts

@@ -1,14 +1,21 @@
 /**
- * Resolve a timezone string for the Unix/UTC formatters.
+ * Resolve the `timeZone` option of every `unix/` function and the `utc/` formatters.
  *
- * - `"local"` → the system timezone via `getSystemTimeZone()`.
- * - A valid IANA timezone identifier → returned as-is.
- * - Anything else (undefined, empty, invalid name, typo) → `"UTC"`.
+ * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
+ *   zone is read unless asked for.
+ * - `"local"` → the system time zone (`getSystemTimeZone()`), or `""` when the host reports none
+ *   that is valid.
+ * - A valid IANA identifier → returned as-is.
+ * - Anything else (`null`, `""`, a typo, a non-string) → `""`, the caller's cue to return its
+ *   sentinel. ECMA-402 `Intl.DateTimeFormat` and Temporal `ToTemporalTimeZoneIdentifier` throw
+ *   `RangeError` for an unknown zone, so a typo never silently renders UTC.
  *
- * The UTC fallback is intentional: `formatUnix` / `formatUtc` / the relative
- * formatters expose `timeZone` as an *optional* convenience, so we degrade
- * gracefully when callers pass nothing or pass a typo. Callers that need
- * strict timezone validation should use `isValidTimeZone()` themselves
- * before calling these formatters.
+ * @param timeZone the caller's `timeZone` option
+ * @returns the zone to use, or `""` when invalid
+ *
+ * @example normalizeTimeZone(undefined) // "UTC"
+ * @example normalizeTimeZone("local") // system zone, e.g. "America/New_York"
+ * @example normalizeTimeZone("Europe/Helsinki") // "Europe/Helsinki"
+ * @example normalizeTimeZone("America/New_Yrok") // ""
  */
-export declare function normalizeTimeZone(tz?: string): string;
+export declare function normalizeTimeZone(timeZone?: unknown): string;

package/dist/internal/normalizeTimeZone.js

@@ -1,22 +1,32 @@
 import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
 import { isValidTimeZone } from "../zoned/validate/index.js";
 /**
- * Resolve a timezone string for the Unix/UTC formatters.
+ * Resolve the `timeZone` option of every `unix/` function and the `utc/` formatters.
  *
- * - `"local"` → the system timezone via `getSystemTimeZone()`.
- * - A valid IANA timezone identifier → returned as-is.
- * - Anything else (undefined, empty, invalid name, typo) → `"UTC"`.
+ * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
+ *   zone is read unless asked for.
+ * - `"local"` → the system time zone (`getSystemTimeZone()`), or `""` when the host reports none
+ *   that is valid.
+ * - A valid IANA identifier → returned as-is.
+ * - Anything else (`null`, `""`, a typo, a non-string) → `""`, the caller's cue to return its
+ *   sentinel. ECMA-402 `Intl.DateTimeFormat` and Temporal `ToTemporalTimeZoneIdentifier` throw
+ *   `RangeError` for an unknown zone, so a typo never silently renders UTC.
  *
- * The UTC fallback is intentional: `formatUnix` / `formatUtc` / the relative
- * formatters expose `timeZone` as an *optional* convenience, so we degrade
- * gracefully when callers pass nothing or pass a typo. Callers that need
- * strict timezone validation should use `isValidTimeZone()` themselves
- * before calling these formatters.
+ * @param timeZone the caller's `timeZone` option
+ * @returns the zone to use, or `""` when invalid
+ *
+ * @example normalizeTimeZone(undefined) // "UTC"
+ * @example normalizeTimeZone("local") // system zone, e.g. "America/New_York"
+ * @example normalizeTimeZone("Europe/Helsinki") // "Europe/Helsinki"
+ * @example normalizeTimeZone("America/New_Yrok") // ""
  */
-export function normalizeTimeZone(tz) {
-    if (tz === "local")
-        return getSystemTimeZone();
-    if (typeof tz === "string" && tz.length > 0 && isValidTimeZone(tz))
-        return tz;
-    return "UTC";
+export function normalizeTimeZone(timeZone) {
+    if (timeZone === undefined)
+        return "UTC";
+    const resolved = timeZone === "local" ? getSystemTimeZone() : timeZone;
+    return typeof resolved === "string" &&
+        resolved.length > 0 &&
+        isValidTimeZone(resolved)
+        ? resolved
+        : "";
 }

package/dist/internal/patternToken.d.ts

@@ -1,3 +1,4 @@
+import { type LocalesArgument } from "./resolveLocale.js";
 /**
  * Shared token-pattern engine for J11's `parse*WithPattern` family.
  *
@@ -42,4 +43,4 @@ export interface ParsedPatternFields {
  * never distinguishes malformed-pattern from no-match from invalid-input,
  * matching the shared never-throw / sentinel-return contract.
  */
-export declare function parseValueWithPattern(value: string, pattern: string, locale: string | undefined, allowedFields: ReadonlySet<PatternField>): ParsedPatternFields | null;
+export declare function parseValueWithPattern(value: string, pattern: string, locale: LocalesArgument | undefined, allowedFields: ReadonlySet<PatternField>): ParsedPatternFields | null;

package/dist/internal/patternToken.js

@@ -1,3 +1,4 @@
+import { resolveLocale } from "./resolveLocale.js";
 import { getLocaleEraNames } from "../plain/locale/getLocaleEraNames.js";
 import { getLocaleMeridiems } from "../plain/locale/getLocaleMeridiems.js";
 import { getLocaleMonthNames } from "../plain/locale/getLocaleMonthNames.js";
@@ -367,14 +368,19 @@ export function parseValueWithPattern(value, pattern, locale, allowedFields) {
         return null;
     if (typeof pattern !== "string" || pattern.length === 0)
         return null;
-    if (locale !== undefined && typeof locale !== "string")
-        return null;
     // No `locale` is required to parse a pattern containing only numeric
     // tokens, but a name-based token (MMM/MMMM/EEE/EEEE/a/GG/GGGG) needs
     // *some* locale to resolve against — default to "en-US" rather than
     // silently returning "" for every caller who didn't have another
-    // locale in mind.
-    const resolvedLocale = typeof locale === "string" ? locale : "en-US";
+    // locale in mind. An empty preference list names no locale either, so
+    // it takes that same default: ECMA-402 ResolveLocale would answer `[]`
+    // with the *host* locale, which would make a decoder of a fixed
+    // producer format read differently on a French machine (house rule,
+    // ./resolveLocale.ts).
+    const omitted = locale === undefined || (Array.isArray(locale) && locale.length === 0);
+    const resolvedLocale = omitted ? "en-US" : resolveLocale(locale);
+    if (resolvedLocale === null)
+        return null;
     const compiled = compilePattern(pattern, allowedFields, resolvedLocale);
     if (compiled === null)
         return null;

package/dist/internal/plainDateAdd.d.ts

@@ -0,0 +1,20 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * `date.add(duration, { overflow })` for a PlainDate in any calendar.
+ *
+ * - `iso8601` is the polyfill's own `add`, untouched.
+ * - Other calendars go through the Temporal compat layer's `calendarDateAdd` (CORE-6: the polyfill's
+ *   calendar add throws near the range limits and is wrong in the corrected calendar ranges). Time
+ *   fields become whole days exactly as TC39 `ToDateDurationRecordWithoutTime` does: the time
+ *   duration in nanoseconds, truncated toward zero to 24-hour days, added to `days`.
+ * - The duration is validated by `Temporal.Duration.from`, as `add` itself does.
+ *
+ * @param date PlainDate to add to
+ * @param duration a DurationLike (negate it to subtract)
+ * @param overflow "constrain" (default, as in Temporal) | "reject"
+ * @returns the resulting PlainDate in `date`'s calendar; throws on invalid input or out of range
+ *
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "constrain").toString() // "2024-02-29"
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "reject") // throws RangeError
+ */
+export declare function plainDateAdd(date: Temporal.PlainDate, duration: Temporal.Duration | Temporal.DurationLike, overflow?: "constrain" | "reject"): Temporal.PlainDate;

package/dist/internal/plainDateAdd.js

@@ -0,0 +1,42 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarDateAdd } from "./temporalCompat/index.js";
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+const NANOSECONDS_PER_SECOND = 1000000000n;
+const NANOSECONDS_PER_DAY = 86400000000000n;
+/**
+ * `date.add(duration, { overflow })` for a PlainDate in any calendar.
+ *
+ * - `iso8601` is the polyfill's own `add`, untouched.
+ * - Other calendars go through the Temporal compat layer's `calendarDateAdd` (CORE-6: the polyfill's
+ *   calendar add throws near the range limits and is wrong in the corrected calendar ranges). Time
+ *   fields become whole days exactly as TC39 `ToDateDurationRecordWithoutTime` does: the time
+ *   duration in nanoseconds, truncated toward zero to 24-hour days, added to `days`.
+ * - The duration is validated by `Temporal.Duration.from`, as `add` itself does.
+ *
+ * @param date PlainDate to add to
+ * @param duration a DurationLike (negate it to subtract)
+ * @param overflow "constrain" (default, as in Temporal) | "reject"
+ * @returns the resulting PlainDate in `date`'s calendar; throws on invalid input or out of range
+ *
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "constrain").toString() // "2024-02-29"
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "reject") // throws RangeError
+ */
+export function plainDateAdd(date, duration, overflow = "constrain") {
+    if (date.calendarId === "iso8601") {
+        return date.add(duration, { overflow });
+    }
+    const { years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds, } = Temporal.Duration.from(duration);
+    const timeNanoseconds = BigInt(hours) * NANOSECONDS_PER_HOUR +
+        BigInt(minutes) * NANOSECONDS_PER_MINUTE +
+        BigInt(seconds) * NANOSECONDS_PER_SECOND +
+        BigInt(milliseconds) * 1000000n +
+        BigInt(microseconds) * 1000n +
+        BigInt(nanoseconds);
+    return calendarDateAdd(date, {
+        years,
+        months,
+        weeks,
+        days: days + Number(timeNanoseconds / NANOSECONDS_PER_DAY),
+    }, overflow);
+}