@northguild/gmt 1.19.0 → 1.20.0

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();
+}

package/dist/internal/freeTimeLedger.d.ts

@@ -1,12 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { type ResolvedBusinessCalendar } from "./businessCalendar.js";
-/**
- * Local days a free-time walk may visit before giving up: the same cap as `bucketRange`. A
- * valid business calendar leaves at least one working day a week, so a working-day count needs
- * at most about seven local days per free or chargeable day. A walk that runs out answers with
- * the sentinel, never a partial ledger.
- */
-export declare const MAX_WALKED_DAYS = 10000;
 /**
  * The tariff terms reduced to what the walk reads. `calendar` is the working-day calendar free
  * days are counted against, `null` on the calendar basis; `chargeCalendar` is the one charged days
@@ -16,7 +9,7 @@ export type FreeTimeTerms = {
     /**
      * The counting zone as the caller wrote it: a time zone identifier or a stored UTC offset
      * (`±HH:MM[:SS]`), so always readable by `zoneFrame`. The walk's zoned values are placed with
-     * `frameZoned` and turned back with `frameInstant`.
+     * `frameZoned` and turned back with `frameEpochNanoseconds` and `Temporal.Instant.fromEpochNanoseconds`.
      */
     timeZone: string;
     firstDay: "eventDay" | "nextDay";
@@ -52,47 +45,42 @@ export declare function bandsByTier(tiers: number[], chargeable: number): {
     to: number | null;
     days: number;
 }[];
-/** One local date of the terminal: its first instant, and its ISO label. */
-export interface LedgerDay {
-    start: Temporal.ZonedDateTime;
-    date: string;
+/**
+ * What a free-time walk returns, on epoch days (days from 1970-01-01, `epochDay.ts`) and epoch
+ * nanoseconds, so the dwell's length costs no Temporal work: callers format the few values they
+ * output.
+ */
+export interface FreeTimeLedger {
+    /** The first free day; `null` with no free days. */
+    firstFree: number | null;
+    /** The last free day; `null` with no free days. */
+    lastFree: number | null;
     /**
-     * True when the date began before the first instant Temporal represents, so `start` is the
-     * clock start standing in for it. Such a start is never output: it can only anchor the walk.
+     * The first instant of the local day after the last free day (with no free days, of day one), in
+     * epoch nanoseconds. It includes the frame's shift, so it is the real instant.
      */
-    clamped?: boolean;
-}
-/** What `walkFreeTime` returns: the free days, the expiry, and what the dwell used and owes. */
-export interface FreeTimeLedger {
-    /** The free days in order, exactly `freeDays` of them. */
-    free: LedgerDay[];
-    /** The first instant of the local day after the last free day; with no free days, of day one. */
-    expiresAt: Temporal.ZonedDateTime;
+    expiresAtNs: bigint;
     /** Free days the half-open dwell `[clockStart, clockEnd)` touched; `0` with no `clockEnd`. */
     used: number;
-    /** Counted days from `expiresAt` that the dwell touched, in order; empty with no `clockEnd`. */
-    charged: LedgerDay[];
+    /** Counted days from `expiresAt` that the dwell touched, ascending; empty with no `clockEnd`. */
+    charged: number[];
 }
 /**
- * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ * Lay out free time and charges from the clock start, in epoch days (see `FreeTimeLedger`).
  *
- * Each day is a bucket `zonedUnitStart` / `nextZonedBucketStart` returns for `"day"`, the same
- * boundaries `floorToZone` and `bucketRange` use, so a 23- or 25-hour day is one day, a date the
- * zone deleted is never visited, and a date the clock falls back into is one day. Free days and
- * charged days are counted against their own terms: on a working basis a weekend day or holiday is
- * visited but not counted; on a calendar basis every day counts. The day of the event is neither
- * free nor charged under `"nextDay"`.
+ * The local days of the terminal are the dates from the event day on, each once, without a date
+ * the zone deleted. Free days are the first `freeDays` counted ones (every date on a calendar
+ * basis, a working day of `calendar` otherwise); `expiresAt` is the first instant of the visited
+ * date after the last of them, or with `freeDays` of `0` of the first counted one. With a
+ * `clockEnd` the half-open dwell `[clockStart, clockEnd)` touches a date when it starts before
+ * `clockEnd`, and a zero-length dwell touches the date it sits on, as `dwellTime` counts. `used` is
+ * the free days touched, `charged` the dates from `expiresAt` touched that `chargeCalendar` charges.
+ * The event day is neither free nor charged under `"nextDay"`.
  *
- * - Free days are the first `freeDays` days counted on `calendar`. `expiresAt` is the start of the
- *   day after the last of them, whether or not that day counts; with `freeDays` of `0` it is the
- *   start of the first counted day.
- * - With a `clockEnd`, the dwell `[clockStart, clockEnd)` is half-open: a day is touched when it
- *   starts before `clockEnd`, and a zero-length dwell touches the day it sits on, as `dwellTime`
- *   counts. `used` is the free days touched; `charged` the days from `expiresAt` touched that count
- *   on `chargeCalendar`.
- * - An event day that began before the first representable instant is still walked from the
- *   clock start; only an expiry that would be that unrepresentable start is refused.
- * - Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` local days, when a day
- *   boundary cannot be found, or when the expiry lies outside the representable range.
+ * Counts come from closed forms over the zone's offset changes, so the dwell's length costs no
+ * work per date. Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` dates, when
+ * a day boundary cannot be found, or when the expiry lies outside the representable range. A clock
+ * within `MAX_WALKED_DAYS` dates of Temporal's limits, or in a pass that re-enters its date, is
+ * laid out day by day (`walkFreeTimeByDay`).
  */
 export declare function walkFreeTime(clockStart: Temporal.ZonedDateTime, freeDays: number, terms: FreeTimeTerms, clockEnd?: Temporal.ZonedDateTime): FreeTimeLedger | null;