@northguild/gmt 1.14.2 → 1.16.0

package/dist/internal/intervalNanoseconds.js

@@ -0,0 +1,86 @@
+import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+/**
+ * Parse a candidate `Interval` to epoch nanoseconds, or `null` when it is not one.
+ *
+ * - Any non-null object with ISO 8601 instant strings `start` ≤ `end` (by instant) is accepted;
+ *   extra keys are ignored (GMT rule: the type is structural).
+ * - Each endpoint is read exactly once, so the validated text is the text callers echo.
+ *
+ * @param value candidate `{ start, end }` record
+ * @returns the parsed record, or null when `value` is not a valid `Interval`
+ *
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:00Z", end: "1970-01-01T00:00:00.000000001Z" }) // { start: 0n, end: 1n, startText: "1970-01-01T00:00:00Z", endText: "1970-01-01T00:00:00.000000001Z" }
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:01Z", end: "1970-01-01T00:00:00Z" }) // null — inverted
+ */
+export function parseIntervalNanoseconds(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const { start: startText, end: endText } = value;
+    const start = parseInstantNanoseconds(startText);
+    const end = parseInstantNanoseconds(endText);
+    if (start === null || end === null || start > end) {
+        return null;
+    }
+    return {
+        start,
+        end,
+        startText: startText,
+        endText: endText,
+    };
+}
+/**
+ * Parse a list of candidate `Interval`s, all-or-nothing.
+ *
+ * @param values candidate array of `{ start, end }` records
+ * @returns the parsed records in input order, or null when `values` is not an array or any element is invalid
+ *
+ * @example parseIntervalNanosecondsList([]) // []
+ * @example parseIntervalNanosecondsList([null]) // null
+ */
+export function parseIntervalNanosecondsList(values) {
+    if (!Array.isArray(values)) {
+        return null;
+    }
+    const records = [];
+    for (let index = 0; index < values.length; index++) {
+        const record = parseIntervalNanoseconds(values[index]);
+        if (record === null) {
+            return null;
+        }
+        records.push(record);
+    }
+    return records;
+}
+/**
+ * Sweep parsed intervals into sorted, disjoint, non-touching, non-empty runs.
+ *
+ * - Touching records coalesce (`start <= run.end`); a 1 ns gap does not.
+ * - Equal starts keep input order (stable sort), so a run keeps its first start text; the first
+ *   record to reach the run's latest end keeps its end text (GMT rule: first wins ties).
+ * - Empty records that touch or fall inside a run are absorbed; a stranded one is dropped.
+ * - Runs are copies; the input records are never mutated.
+ *
+ * @param records parsed intervals, in any order
+ * @returns coalesced runs sorted by start
+ *
+ * @example coalesceIntervalNanoseconds([{ start: 3n, end: 5n, startText: "c", endText: "e" }, { start: 1n, end: 3n, startText: "a", endText: "c" }]) // [{ start: 1n, end: 5n, startText: "a", endText: "e" }]
+ * @example coalesceIntervalNanoseconds([{ start: 4n, end: 4n, startText: "d", endText: "d" }]) // []
+ */
+export function coalesceIntervalNanoseconds(records) {
+    const sorted = [...records].sort((x, y) => x.start < y.start ? -1 : x.start > y.start ? 1 : 0);
+    const runs = [];
+    for (const record of sorted) {
+        const last = runs[runs.length - 1];
+        if (last !== undefined && record.start <= last.end) {
+            if (record.end > last.end) {
+                last.end = record.end;
+                last.endText = record.endText;
+            }
+        }
+        else {
+            runs.push({ ...record });
+        }
+    }
+    return runs.filter((run) => run.start < run.end);
+}

package/dist/internal/isObject.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type guard for a non-null object (arrays included), the shape an options bag or a props
+ * object must have before it is destructured. A default parameter covers only `undefined`, so a
+ * `null` or primitive argument reaches the destructure and throws `TypeError` without this check.
+ *
+ * @param value candidate
+ * @example isObject({ smallestUnit: "day" }) // true
+ * @example isObject(null) // false
+ * @example isObject("day") // false
+ * @returns whether `value` is a non-null object
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Whether an `options` argument is acceptable under Temporal GetOptionsObject: omitted
+ * (`undefined`, the defaults) or an object. `null`, a string, a number or a boolean is a TypeError
+ * there, so a function that takes an options bag returns its sentinel for it rather than silently
+ * reading the defaults (e.g. a legacy positional unit string such as `"seconds"`).
+ *
+ * @param options the caller's options argument
+ * @example isOptionsArgument(undefined) // true
+ * @example isOptionsArgument({ overflow: "reject" }) // true
+ * @example isOptionsArgument(null) // false
+ * @example isOptionsArgument("seconds") // false
+ * @returns whether `options` is `undefined` or a non-null object
+ */
+export declare function isOptionsArgument(options: unknown): boolean;

package/dist/internal/isObject.js

@@ -0,0 +1,30 @@
+/**
+ * Type guard for a non-null object (arrays included), the shape an options bag or a props
+ * object must have before it is destructured. A default parameter covers only `undefined`, so a
+ * `null` or primitive argument reaches the destructure and throws `TypeError` without this check.
+ *
+ * @param value candidate
+ * @example isObject({ smallestUnit: "day" }) // true
+ * @example isObject(null) // false
+ * @example isObject("day") // false
+ * @returns whether `value` is a non-null object
+ */
+export function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Whether an `options` argument is acceptable under Temporal GetOptionsObject: omitted
+ * (`undefined`, the defaults) or an object. `null`, a string, a number or a boolean is a TypeError
+ * there, so a function that takes an options bag returns its sentinel for it rather than silently
+ * reading the defaults (e.g. a legacy positional unit string such as `"seconds"`).
+ *
+ * @param options the caller's options argument
+ * @example isOptionsArgument(undefined) // true
+ * @example isOptionsArgument({ overflow: "reject" }) // true
+ * @example isOptionsArgument(null) // false
+ * @example isOptionsArgument("seconds") // false
+ * @returns whether `options` is `undefined` or a non-null object
+ */
+export function isOptionsArgument(options) {
+    return options === undefined || isObject(options);
+}

package/dist/internal/isoStringBody.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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;
+/**
+ * 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,85 @@
+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]`). Hours
+ * 00–23. Basic (`-0400`) and hour-only (`-04`) offsets, which Temporal also reads, do not match.
+ */
+const EXTENDED_UTC_OFFSET = "[+-](?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:[.,]\\d{1,9})?)?";
+/** `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;