@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/fiscalCalendar.d.ts

@@ -1,5 +1,18 @@
-import { Temporal } from "@js-temporal/polyfill";
-import type { FiscalPattern } from "../types/index.js";
+import { Temporal } from "./temporal.js";
+import type { FiscalExtraWeek, FiscalPattern, FiscalYearLabel } from "../types/index.js";
+/**
+ * Return the multiple of 400 years that moves `year` into 2000 to 2399, where it keeps its
+ * place in the Gregorian cycle.
+ *
+ * Subtract the result to move a year into that cycle, and add it to move it back. Calendar
+ * arithmetic near Temporal's first or last date (-271821-04-19, +275760-09-13) can step past
+ * the range on the way to an answer that lies inside it; done in the safe cycle it cannot.
+ *
+ * @example gregorianCycleShift(2024) // 0
+ * @example gregorianCycleShift(-271820) // -274000 (-271820 sits where 2180 does)
+ * @example gregorianCycleShift(275760) // 273600 (275760 sits where 2160 does)
+ */
+export declare function gregorianCycleShift(year: number): number;
 /**
  * Return the fiscal year end falling in calendar year `year`, under the rule `anchor` states.
  *
@@ -21,8 +34,13 @@ export declare function fiscalYearEndIn(anchor: Temporal.PlainDate, year: number
  *
  * - The fiscal year is the one whose end is the first at or after `date`.
  * - `weeks` is derived from the gap between consecutive year ends — 52 or 53 — never assumed.
- * - Returns null when that gap is neither 364 nor 371 days, which no "nearest weekday" rule
- *   can produce and so only a corrupted anchor could reach.
+ * - The search reads the year ends in the calendar years either side of `date`, so it throws
+ *   RangeError when one of them lies outside Temporal's range. Near -271821-04-19 or
+ *   +275760-09-13 that happens even when the date is valid. Move `date` into 2000 to 2399 with
+ *   `gregorianCycleShift` first, then add the shift back to any year read off the result:
+ *   whole 400-year cycles keep every month, day, weekday and day count.
+ * - Returns null when the gap between year ends is neither 364 nor 371 days, which no
+ *   "nearest weekday" rule can produce and so only a corrupted anchor could reach.
  */
 export declare function fiscalYearOf(date: Temporal.PlainDate, anchor: Temporal.PlainDate): {
     start: Temporal.PlainDate;
@@ -31,7 +49,23 @@ export declare function fiscalYearOf(date: Temporal.PlainDate, anchor: Temporal.
 /**
  * Return the 1-based period holding `week` of a `weeks`-long fiscal year under `pattern`.
  *
- * The 53rd week, when the year has one, is appended to the final period — the NRF adds it
- * "to the end of the calendar", which turns a 4-5-4 year's last quarter into 4-5-5.
+ * - The 53rd week, when the year has one, lengthens period 1 (`"firstPeriod"`) or period 12
+ *   (`"lastPeriod"`), as `extraWeek` says. A 4-4-5 year then runs 5-4-5 … 4-4-5 or
+ *   4-4-5 … 4-4-6.
+ * - In a 52-week year `extraWeek` has no effect.
+ */
+export declare function fiscalPeriodOfWeek(week: number, weeks: number, pattern: FiscalPattern, extraWeek: FiscalExtraWeek): number;
+/**
+ * Return the calendar year that names the fiscal year running `start` to `end`, both inclusive.
+ *
+ * - `"startYear"` is `start`'s year and `"endYear"` is `end`'s year.
+ * - `"majorityYear"` is the calendar year holding the most of the fiscal year's days. Days are
+ *   the unit because the fiscal year and the calendar year share no other: months differ in
+ *   length, and a week can straddle 1 January.
+ * - Every calendar year in the span is counted, not only the two end years. A 371-day year can
+ *   touch three calendar years (2024-12-29 to 2026-01-03), and then the middle one wins.
+ * - GMT rule: when two years hold exactly half the days each (182 and 182), the later one, the
+ *   year holding the end date, wins, because IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a
+ *   reporting period be identified by the date it ends.
  */
-export declare function fiscalPeriodOfWeek(week: number, weeks: number, pattern: FiscalPattern): number;
+export declare function fiscalYearLabel(start: Temporal.PlainDate, end: Temporal.PlainDate, label: FiscalYearLabel): number;

package/dist/internal/fiscalCalendar.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /** Weeks per period within one quarter, by pattern. */
 const WEEKS_PER_PERIOD = {
     "4-5-4": [4, 5, 4],
@@ -22,6 +22,31 @@ const DAYS_IN_53_WEEK_YEAR = 371;
 const YEAR_END_SEARCH_OFFSETS = [-1, 0, 1, 2];
 /** Half the width of the 7-day window a "nearest weekday" year end can land in. */
 const NEAREST_WEEKDAY_RADIUS = 3;
+/**
+ * Years in one cycle of the Gregorian leap rule. Every 400-year span has 146,097 days, a whole
+ * number of weeks, and the same leap years in the same places, so moving a date by a multiple
+ * of 400 years keeps its month, day and weekday.
+ */
+const GREGORIAN_CYCLE_YEARS = 400;
+/** First year of the cycle that dates are moved into, well inside Temporal's range. */
+const SAFE_CYCLE_START = 2000;
+/**
+ * Return the multiple of 400 years that moves `year` into 2000 to 2399, where it keeps its
+ * place in the Gregorian cycle.
+ *
+ * Subtract the result to move a year into that cycle, and add it to move it back. Calendar
+ * arithmetic near Temporal's first or last date (-271821-04-19, +275760-09-13) can step past
+ * the range on the way to an answer that lies inside it; done in the safe cycle it cannot.
+ *
+ * @example gregorianCycleShift(2024) // 0
+ * @example gregorianCycleShift(-271820) // -274000 (-271820 sits where 2180 does)
+ * @example gregorianCycleShift(275760) // 273600 (275760 sits where 2160 does)
+ */
+export function gregorianCycleShift(year) {
+    const placeInCycle = ((year % GREGORIAN_CYCLE_YEARS) + GREGORIAN_CYCLE_YEARS) %
+        GREGORIAN_CYCLE_YEARS;
+    return year - SAFE_CYCLE_START - placeInCycle;
+}
 /**
  * Return the fiscal year end falling in calendar year `year`, under the rule `anchor` states.
  *
@@ -49,8 +74,13 @@ export function fiscalYearEndIn(anchor, year) {
  *
  * - The fiscal year is the one whose end is the first at or after `date`.
  * - `weeks` is derived from the gap between consecutive year ends — 52 or 53 — never assumed.
- * - Returns null when that gap is neither 364 nor 371 days, which no "nearest weekday" rule
- *   can produce and so only a corrupted anchor could reach.
+ * - The search reads the year ends in the calendar years either side of `date`, so it throws
+ *   RangeError when one of them lies outside Temporal's range. Near -271821-04-19 or
+ *   +275760-09-13 that happens even when the date is valid. Move `date` into 2000 to 2399 with
+ *   `gregorianCycleShift` first, then add the shift back to any year read off the result:
+ *   whole 400-year cycles keep every month, day, weekday and day count.
+ * - Returns null when the gap between year ends is neither 364 nor 371 days, which no
+ *   "nearest weekday" rule can produce and so only a corrupted anchor could reach.
  */
 export function fiscalYearOf(date, anchor) {
     for (const offset of YEAR_END_SEARCH_OFFSETS) {
@@ -70,18 +100,56 @@ export function fiscalYearOf(date, anchor) {
 /**
  * Return the 1-based period holding `week` of a `weeks`-long fiscal year under `pattern`.
  *
- * The 53rd week, when the year has one, is appended to the final period — the NRF adds it
- * "to the end of the calendar", which turns a 4-5-4 year's last quarter into 4-5-5.
+ * - The 53rd week, when the year has one, lengthens period 1 (`"firstPeriod"`) or period 12
+ *   (`"lastPeriod"`), as `extraWeek` says. A 4-4-5 year then runs 5-4-5 … 4-4-5 or
+ *   4-4-5 … 4-4-6.
+ * - In a 52-week year `extraWeek` has no effect.
  */
-export function fiscalPeriodOfWeek(week, weeks, pattern) {
+export function fiscalPeriodOfWeek(week, weeks, pattern, extraWeek) {
     const quarterShape = WEEKS_PER_PERIOD[pattern];
+    const longPeriod = extraWeek === "firstPeriod" ? 1 : PERIODS_PER_YEAR;
     let consumed = 0;
     for (let period = 1; period <= PERIODS_PER_YEAR; period++) {
-        const isFinalPeriod = period === PERIODS_PER_YEAR;
-        const extraWeek = isFinalPeriod && weeks === 53 ? 1 : 0;
-        consumed += quarterShape[(period - 1) % quarterShape.length] + extraWeek;
+        const added = weeks === 53 && period === longPeriod ? 1 : 0;
+        consumed += quarterShape[(period - 1) % quarterShape.length] + added;
         if (week <= consumed)
             return period;
     }
     return PERIODS_PER_YEAR;
 }
+/**
+ * Return the calendar year that names the fiscal year running `start` to `end`, both inclusive.
+ *
+ * - `"startYear"` is `start`'s year and `"endYear"` is `end`'s year.
+ * - `"majorityYear"` is the calendar year holding the most of the fiscal year's days. Days are
+ *   the unit because the fiscal year and the calendar year share no other: months differ in
+ *   length, and a week can straddle 1 January.
+ * - Every calendar year in the span is counted, not only the two end years. A 371-day year can
+ *   touch three calendar years (2024-12-29 to 2026-01-03), and then the middle one wins.
+ * - GMT rule: when two years hold exactly half the days each (182 and 182), the later one, the
+ *   year holding the end date, wins, because IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a
+ *   reporting period be identified by the date it ends.
+ */
+export function fiscalYearLabel(start, end, label) {
+    if (label === "startYear")
+        return start.year;
+    if (label === "endYear")
+        return end.year;
+    let best = end.year;
+    let bestDays = -1;
+    for (let year = start.year; year <= end.year; year++) {
+        const from = year === start.year
+            ? start
+            : Temporal.PlainDate.from({ year, month: 1, day: 1 });
+        const to = year === end.year
+            ? end
+            : Temporal.PlainDate.from({ year, month: 12, day: 31 });
+        const days = from.until(to, { largestUnit: "day" }).days + 1;
+        // ">=": a tie goes to the later year, which holds the end date.
+        if (days >= bestDays) {
+            best = year;
+            bestDays = days;
+        }
+    }
+    return best;
+}

package/dist/internal/foreignEpochs.d.ts

@@ -29,6 +29,11 @@ export declare const NANOSECONDS_PER_MICROSECOND = 1000n;
 export declare const NANOSECONDS_PER_TICK = 100n;
 /** Nanoseconds in one 24-hour day. */
 export declare const NANOSECONDS_PER_DAY = 86400000000000n;
+/**
+ * Nanoseconds in one week: 604 800 s, the week every satellite week counter counts (IS-GPS-200N
+ * §3.3.4: "The largest unit used in stating GPS time is one week defined as 604,800 seconds").
+ */
+export declare const NANOSECONDS_PER_WEEK = 604800000000000n;
 /** The same value as a `number` — an Excel serial is days in a `double`. */
 export declare const NANOSECONDS_PER_DAY_NUMBER = 86400000000000;
 /** Milliseconds in one 24-hour day. Excel serials round to this grid; see `fromExcelSerial`. */

package/dist/internal/foreignEpochs.js

@@ -29,6 +29,11 @@ export const NANOSECONDS_PER_MICROSECOND = 1000n;
 export const NANOSECONDS_PER_TICK = 100n;
 /** Nanoseconds in one 24-hour day. */
 export const NANOSECONDS_PER_DAY = 86400000000000n;
+/**
+ * Nanoseconds in one week: 604 800 s, the week every satellite week counter counts (IS-GPS-200N
+ * §3.3.4: "The largest unit used in stating GPS time is one week defined as 604,800 seconds").
+ */
+export const NANOSECONDS_PER_WEEK = 604800000000000n;
 /** The same value as a `number` — an Excel serial is days in a `double`. */
 export const NANOSECONDS_PER_DAY_NUMBER = 86_400_000_000_000;
 /** Milliseconds in one 24-hour day. Excel serials round to this grid; see `fromExcelSerial`. */

package/dist/internal/formatCalendarDays.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * Render a calendar phrase for a moment `diffDays` calendar days from the reference: "tomorrow at
  * 2:30 PM" within six days, else the long date and time. Shared by the zoned, utc and unix
@@ -10,8 +10,8 @@ import type { Temporal } from "@js-temporal/polyfill";
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where `Intl` throws, for the caller's sentinel
- * @example formatCalendarDays(1, 1710685800000, "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
- * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-US", "short") // "March 17, 2024 at 2:30 PM"
+ * @example formatCalendarDays(1, 1710685800000, "UTC", "en-GB", "short") // "tomorrow at 14:30"
+ * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-GB", "short") // "17 March 2024 at 14:30"
  */
 export declare function formatCalendarDays(diffDays: number, epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;
 /**
@@ -23,6 +23,6 @@ export declare function formatCalendarDays(diffDays: number, epochMilliseconds:
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where Temporal or `Intl` throws
- * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
+ * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-GB", "short") // "tomorrow at 14:30"
  */
 export declare function formatCalendarInstants(target: Temporal.Instant, reference: Temporal.Instant, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;

package/dist/internal/formatCalendarDays.js

@@ -1,3 +1,4 @@
+import { cachedFormatter } from "./formatterCache.js";
 import { joinDateTimeConnector } from "./joinDateTimeConnector.js";
 import { normalizeDateTime } from "./normalizeDateTime.js";
 // Beyond a week either direction the phrase falls back to an absolute date, as plain
@@ -14,18 +15,18 @@ const ABS_DAY_THRESHOLD = 6;
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where `Intl` throws, for the caller's sentinel
- * @example formatCalendarDays(1, 1710685800000, "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
- * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-US", "short") // "March 17, 2024 at 2:30 PM"
+ * @example formatCalendarDays(1, 1710685800000, "UTC", "en-GB", "short") // "tomorrow at 14:30"
+ * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-GB", "short") // "17 March 2024 at 14:30"
  */
 export function formatCalendarDays(diffDays, epochMilliseconds, timeZone, locale, timeStyle) {
     if (Math.abs(diffDays) > ABS_DAY_THRESHOLD) {
-        return normalizeDateTime(new Intl.DateTimeFormat(locale, {
+        return normalizeDateTime(cachedFormatter("DateTimeFormat", locale, {
             dateStyle: "long",
             timeStyle,
             timeZone,
         }).format(epochMilliseconds));
     }
-    const dayLabel = new Intl.RelativeTimeFormat(locale, {
+    const dayLabel = cachedFormatter("RelativeTimeFormat", locale, {
         numeric: "auto",
     }).format(diffDays, "day");
     return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle));
@@ -39,7 +40,7 @@ export function formatCalendarDays(diffDays, epochMilliseconds, timeZone, locale
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where Temporal or `Intl` throws
- * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
+ * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-GB", "short") // "tomorrow at 14:30"
  */
 export function formatCalendarInstants(target, reference, timeZone, locale, timeStyle) {
     const targetDate = target.toZonedDateTimeISO(timeZone).toPlainDate();

package/dist/internal/formatDateInCalendar.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 import type { CalendarSystem } from "../types/index.js";
 /**
  * Write a Temporal.PlainDate as a GMT PlainDate string in `calendar`: exactly

package/dist/internal/formatRelativeDuration.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 import type { RelativeRoundingMethod, RelativeTimeFormatOptions, RelativeUnit } from "../types/index.js";
 /** A relative unit, singular or plural (`Intl.RelativeTimeFormat` and Temporal accept both). */
 type RelativeUnitName = RelativeUnit | `${RelativeUnit}s`;
@@ -19,9 +19,9 @@ export interface RelativeDurationFormatOptions {
  * @param calendarTotal the total in `unit` against the caller's anchor; called only when the unit
  *   is calendrical (month, year) and `diff.total(unit)` throws without a `relativeTo`
  * @returns the formatted phrase; throws where `Intl` or Temporal throws, for the caller's sentinel
- * @example formatRelativeDuration(Temporal.Duration.from({ minutes: -30 }), "en-US", {}, () => 0) // "30 minutes ago"
- * @example formatRelativeDuration(Temporal.Duration.from({ hours: 36 }), "en-US", { largestUnit: "hour" }, () => 0) // "in 36 hours"
- * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-US", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
+ * @example formatRelativeDuration(Temporal.Duration.from({ minutes: -30 }), "en-GB", {}, () => 0) // "30 minutes ago"
+ * @example formatRelativeDuration(Temporal.Duration.from({ hours: 36 }), "de-DE", { largestUnit: "hour" }, () => 0) // "in 36 Stunden"
+ * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-GB", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
  */
 export declare function formatRelativeDuration(diff: Temporal.Duration, locale: string | string[] | undefined, options: RelativeDurationFormatOptions, calendarTotal: (unit: RelativeUnit) => number): string;
 /**
@@ -39,9 +39,9 @@ export declare function formatRelativeDuration(diff: Temporal.Duration, locale:
  * @param roundingMethod the caller's `roundingMethod`, `undefined` for the default `"round"`
  * @returns the formatted phrase; throws where `Intl` throws or the rounding method is invalid, for
  *   the caller's sentinel
- * @example formatRelativeAmount(-1.5, "hour", "en-US", {}, "floor") // "2 hours ago"
- * @example formatRelativeAmount(1, "day", "en-US", { numeric: "always" }, undefined) // "in 1 day"
- * @example formatRelativeAmount(1, "day", "en-US", { style: "wide" as never }, undefined) // throws RangeError
+ * @example formatRelativeAmount(-1.5, "hour", "en-GB", {}, "floor") // "2 hours ago"
+ * @example formatRelativeAmount(1, "day", "ja-JP", { numeric: "always" }, undefined) // "1 日後"
+ * @example formatRelativeAmount(1, "day", "fr-FR", { style: "wide" as never }, undefined) // throws RangeError
  */
 export declare function formatRelativeAmount(total: number, unit: RelativeUnit, locale: string | string[] | undefined, options: Pick<RelativeDurationFormatOptions, "numeric" | "style">, roundingMethod: RelativeRoundingMethod | undefined): string;
 export {};

package/dist/internal/formatRelativeDuration.js

@@ -1,3 +1,4 @@
+import { cachedFormatter } from "./formatterCache.js";
 import { normalizeDateTime } from "./normalizeDateTime.js";
 import { resolveRelativeRounding } from "./resolveRelativeRounding.js";
 import { optionOrDefault } from "./optionOrDefault.js";
@@ -34,9 +35,9 @@ const AUTO_UNITS = [
  * @param calendarTotal the total in `unit` against the caller's anchor; called only when the unit
  *   is calendrical (month, year) and `diff.total(unit)` throws without a `relativeTo`
  * @returns the formatted phrase; throws where `Intl` or Temporal throws, for the caller's sentinel
- * @example formatRelativeDuration(Temporal.Duration.from({ minutes: -30 }), "en-US", {}, () => 0) // "30 minutes ago"
- * @example formatRelativeDuration(Temporal.Duration.from({ hours: 36 }), "en-US", { largestUnit: "hour" }, () => 0) // "in 36 hours"
- * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-US", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
+ * @example formatRelativeDuration(Temporal.Duration.from({ minutes: -30 }), "en-GB", {}, () => 0) // "30 minutes ago"
+ * @example formatRelativeDuration(Temporal.Duration.from({ hours: 36 }), "de-DE", { largestUnit: "hour" }, () => 0) // "in 36 Stunden"
+ * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-GB", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
  */
 export function formatRelativeDuration(diff, locale, options, calendarTotal) {
     // Each option is read once (GetOption), and largestUnit is validated before anything is measured.
@@ -72,13 +73,13 @@ export function formatRelativeDuration(diff, locale, options, calendarTotal) {
  * @param roundingMethod the caller's `roundingMethod`, `undefined` for the default `"round"`
  * @returns the formatted phrase; throws where `Intl` throws or the rounding method is invalid, for
  *   the caller's sentinel
- * @example formatRelativeAmount(-1.5, "hour", "en-US", {}, "floor") // "2 hours ago"
- * @example formatRelativeAmount(1, "day", "en-US", { numeric: "always" }, undefined) // "in 1 day"
- * @example formatRelativeAmount(1, "day", "en-US", { style: "wide" as never }, undefined) // throws RangeError
+ * @example formatRelativeAmount(-1.5, "hour", "en-GB", {}, "floor") // "2 hours ago"
+ * @example formatRelativeAmount(1, "day", "ja-JP", { numeric: "always" }, undefined) // "1 日後"
+ * @example formatRelativeAmount(1, "day", "fr-FR", { style: "wide" as never }, undefined) // throws RangeError
  */
 export function formatRelativeAmount(total, unit, locale, options, roundingMethod) {
     const amount = resolveRelativeRounding(total, roundingMethod);
-    return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
+    return normalizeDateTime(cachedFormatter("RelativeTimeFormat", locale, {
         numeric: optionOrDefault(options.numeric, "auto"),
         style: optionOrDefault(options.style, "long"),
     }).format(amount, unit));

package/dist/internal/formatterCache.d.ts

@@ -0,0 +1,40 @@
+/** The `Intl` formatter classes this module builds. */
+type FormatterKind = "DateTimeFormat" | "NumberFormat" | "ListFormat" | "RelativeTimeFormat";
+type FormatterLocale = string | string[] | undefined;
+/**
+ * A shared, read-only formatter for these arguments; built on the first call with them.
+ *
+ * A formatter's output is fixed by its constructor arguments and the host's locale data. A
+ * `DateTimeFormat` also reads the default locale and default time zone, so it is cached only
+ * with a `locale` string (or array of strings) and a `timeZone` string; any other argument
+ * set is constructed fresh, exactly as `new Intl[kind](locale, options)` would. A construction
+ * failure throws and is never cached. A formatter is kept only while `Intl[kind]` is the
+ * constructor that built it.
+ *
+ * @param kind which `Intl` formatter class to build
+ * @param locale BCP 47 locale or locales, or `undefined` for the runtime default
+ * @param options the formatter's options, built by GMT code
+ * @returns the formatter
+ *
+ * @example cachedFormatter("DateTimeFormat", "en-GB", { timeZone: "UTC" }).format(0) // "01/01/1970"
+ * @example cachedFormatter("ListFormat", "en", { type: "conjunction" }).format(["a", "b"]) // "a and b"
+ * @example cachedFormatter("DateTimeFormat", "not a locale", { timeZone: "UTC" }) // throws RangeError
+ */
+export declare function cachedFormatter<K extends FormatterKind>(kind: K, locale: FormatterLocale, options: object): InstanceType<(typeof Intl)[K]>;
+/**
+ * Construct once to raise the error `Intl` raises for these arguments; a repeat is a no-op.
+ *
+ * Whether construction throws does not depend on the default zone, so the arguments need no
+ * `timeZone`. Only a success is remembered; an invalid call throws every time.
+ *
+ * @param kind which `Intl` formatter class to build
+ * @param locale BCP 47 locale or locales, or `undefined` for the runtime default
+ * @param options the formatter's options, built by GMT code
+ *
+ * @example checkFormatterArguments("DateTimeFormat", "en-GB", { dateStyle: "long" }) // returns
+ * @example checkFormatterArguments("DateTimeFormat", "en-GB", { dateStyle: "huge" }) // throws RangeError
+ */
+export declare function checkFormatterArguments(kind: FormatterKind, locale: FormatterLocale, options: object): void;
+/** Test seam: forget every cached formatter and every checked argument set. */
+export declare function clearFormatterCache(): void;
+export {};

package/dist/internal/formatterCache.js

@@ -0,0 +1,181 @@
+/** At most this many formatters (or checked argument sets) per kind; past it the kind's map clears. */
+const MAX_ENTRIES_PER_KIND = 256;
+const formatters = new Map();
+const checked = new Map();
+/** The `Intl[kind]` constructor each kind's entries were built with. */
+const builtWith = new Map();
+/**
+ * Forget a kind's formatters and checked argument sets when `Intl[kind]` is no longer the
+ * constructor they were built with (a polyfill loaded later, a test stub), so every answer comes
+ * from the constructor installed now.
+ */
+function forgetIfReplaced(kind) {
+    const current = Intl[kind];
+    if (builtWith.get(kind) !== current) {
+        formatters.delete(kind);
+        checked.delete(kind);
+        builtWith.set(kind, current);
+    }
+}
+function construct(kind, locale, options) {
+    switch (kind) {
+        case "DateTimeFormat":
+            return new Intl.DateTimeFormat(locale, options);
+        case "NumberFormat":
+            return new Intl.NumberFormat(locale, options);
+        case "ListFormat":
+            return new Intl.ListFormat(locale, options);
+        case "RelativeTimeFormat":
+            return new Intl.RelativeTimeFormat(locale, options);
+    }
+}
+/**
+ * Whether a canonical locale list can be part of a cache key: a string, or a non-empty array.
+ * `undefined` and `[]` answer from the process default locale, which can change.
+ */
+function isCacheableLocale(locale) {
+    return (typeof locale === "string" || (Array.isArray(locale) && locale.length > 0));
+}
+/** Whether `Intl` can read this option value without running caller code. */
+function isPlainOptionValue(value) {
+    return (typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
+/**
+ * The own enumerable options as `[name, value]` pairs, read through property descriptors so a
+ * getter is never run, or `null` when one is an accessor or holds a value `Intl` would coerce
+ * by running caller code (anything but a string, a finite number or a boolean). An `undefined`
+ * value is skipped, as `Intl` reads it as absent.
+ */
+function plainOptionEntries(options) {
+    const entries = [];
+    for (const name of Object.keys(options)) {
+        const descriptor = Object.getOwnPropertyDescriptor(options, name);
+        if (descriptor === undefined || !("value" in descriptor)) {
+            return null;
+        }
+        const value = descriptor.value;
+        if (value === undefined) {
+            continue;
+        }
+        if (!isPlainOptionValue(value)) {
+            return null;
+        }
+        entries.push([name, value]);
+    }
+    return entries;
+}
+/** Whether these entries carry a `timeZone` string. */
+function hasZoneString(entries) {
+    return entries.some(([name, value]) => name === "timeZone" && typeof value === "string");
+}
+/**
+ * The cache key for these arguments, or `null` when they must be constructed fresh. The
+ * locale is already canonical (see `canonicalLocale`).
+ *
+ * @param zoneRequired whether the options must carry a `timeZone` string: a `DateTimeFormat`
+ * without one answers from the process default zone, which can change.
+ */
+function cacheKey(kind, locale, options, zoneRequired) {
+    if (!isCacheableLocale(locale)) {
+        return null;
+    }
+    const entries = plainOptionEntries(options);
+    if (entries === null || (zoneRequired && !hasZoneString(entries))) {
+        return null;
+    }
+    return kind + JSON.stringify([locale, entries]);
+}
+/**
+ * The locale list as `Intl` canonicalizes it (ECMA-402 CanonicalizeLocaleList): an array is read
+ * once, here, through `Intl.getCanonicalLocales`, so the key and the constructor see the same
+ * strings even when the array is a Proxy that answers each read differently, and a bad list
+ * throws before the options are read, as in the constructors.
+ */
+function canonicalLocale(locale) {
+    return Array.isArray(locale) ? Intl.getCanonicalLocales(locale) : locale;
+}
+/**
+ * A shared, read-only formatter for these arguments; built on the first call with them.
+ *
+ * A formatter's output is fixed by its constructor arguments and the host's locale data. A
+ * `DateTimeFormat` also reads the default locale and default time zone, so it is cached only
+ * with a `locale` string (or array of strings) and a `timeZone` string; any other argument
+ * set is constructed fresh, exactly as `new Intl[kind](locale, options)` would. A construction
+ * failure throws and is never cached. A formatter is kept only while `Intl[kind]` is the
+ * constructor that built it.
+ *
+ * @param kind which `Intl` formatter class to build
+ * @param locale BCP 47 locale or locales, or `undefined` for the runtime default
+ * @param options the formatter's options, built by GMT code
+ * @returns the formatter
+ *
+ * @example cachedFormatter("DateTimeFormat", "en-GB", { timeZone: "UTC" }).format(0) // "01/01/1970"
+ * @example cachedFormatter("ListFormat", "en", { type: "conjunction" }).format(["a", "b"]) // "a and b"
+ * @example cachedFormatter("DateTimeFormat", "not a locale", { timeZone: "UTC" }) // throws RangeError
+ */
+export function cachedFormatter(kind, locale, options) {
+    locale = canonicalLocale(locale);
+    const key = cacheKey(kind, locale, options, kind === "DateTimeFormat");
+    if (key === null) {
+        return construct(kind, locale, options);
+    }
+    forgetIfReplaced(kind);
+    let byKey = formatters.get(kind);
+    const hit = byKey?.get(key);
+    if (hit !== undefined) {
+        return hit;
+    }
+    const built = construct(kind, locale, options);
+    if (byKey === undefined) {
+        byKey = new Map();
+        formatters.set(kind, byKey);
+    }
+    else if (byKey.size >= MAX_ENTRIES_PER_KIND) {
+        byKey.clear();
+    }
+    byKey.set(key, built);
+    return built;
+}
+/**
+ * Construct once to raise the error `Intl` raises for these arguments; a repeat is a no-op.
+ *
+ * Whether construction throws does not depend on the default zone, so the arguments need no
+ * `timeZone`. Only a success is remembered; an invalid call throws every time.
+ *
+ * @param kind which `Intl` formatter class to build
+ * @param locale BCP 47 locale or locales, or `undefined` for the runtime default
+ * @param options the formatter's options, built by GMT code
+ *
+ * @example checkFormatterArguments("DateTimeFormat", "en-GB", { dateStyle: "long" }) // returns
+ * @example checkFormatterArguments("DateTimeFormat", "en-GB", { dateStyle: "huge" }) // throws RangeError
+ */
+export function checkFormatterArguments(kind, locale, options) {
+    locale = canonicalLocale(locale);
+    const key = cacheKey(kind, locale, options, false);
+    if (key === null) {
+        construct(kind, locale, options);
+        return;
+    }
+    forgetIfReplaced(kind);
+    let seen = checked.get(kind);
+    if (seen?.has(key)) {
+        return;
+    }
+    construct(kind, locale, options);
+    if (seen === undefined) {
+        seen = new Set();
+        checked.set(kind, seen);
+    }
+    else if (seen.size >= MAX_ENTRIES_PER_KIND) {
+        seen.clear();
+    }
+    seen.add(key);
+}
+/** Test seam: forget every cached formatter and every checked argument set. */
+export function clearFormatterCache() {
+    formatters.clear();
+    checked.clear();
+    builtWith.clear();
+}