@ultimat3/money 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -79,6 +79,13 @@ shape is still additive and this is still a minor version.
   `USD/EUR: 0.92` names 23/25, so EUR→USD is exactly 25/23, where `1 / 0.92` is a double whose own
   decimal spelling rounds a large amount one minor unit low. `rate` stays the readable number the
   audit trail records; `convert` scales by `ratio` whenever the provider supplied one.
+- **Never cache an `Intl` formatter on a raw caller string.** `locale` arrives from
+  `Accept-Language`, so an unbounded `Map` keyed on it is memory the client chooses: 20,000 valid
+  `en-US-x-*` tags through `formatMoney` retained +55.1 MB of RSS, at ~2.7 KB per
+  `Intl.NumberFormat`. Both halves, always — `canonicalLocale` for the key, `cachedFormatter` for
+  the bound, both `@ultimat3/core`'s and shared with `@ultimat3/time` (tier 1 may not import
+  sideways, so the mechanism lives a tier down rather than twice). Every formatter in `format.ts`
+  goes through that pair; a `new Intl.NumberFormat` outside one is the bug written again.
 - **One place decides a sign.** `formatMoney` is `formatMoneyParts` joined, and `accounting`
   reaches `Intl` as `currencySign` — so the locale places the minus and picks the parenthesised
   form, and a UI styling the parts cannot render a different format from the label beside it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/money",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Integer minor units with an attached currency: arithmetic, allocation, rounding, Intl formatting",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/schema": "2.0.0"
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/schema": "3.0.0"
   }
 }

package/src/format.ts

@@ -3,6 +3,7 @@
  * JPY renders without decimals and KWD with three, without a per-locale special case.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { exponentOf } from './currency';
 import { type Money, toDecimalNumber } from './money';
 import { moneyScale } from './scale';
@@ -73,19 +74,40 @@ export function currencySymbol(currency: string, locale: string): string {
 /** Digits only, no symbol — for editable inputs and CSV exports. */
 export function formatMoneyDecimal(amount: Money, locale: string): string {
   const digits = moneyScale(amount);
-  return new Intl.NumberFormat(locale, {
-    style: 'decimal',
-    minimumFractionDigits: digits,
-    maximumFractionDigits: digits,
-    useGrouping: false,
-  }).format(toDecimalNumber(amount));
+  const tag = canonicalTag(locale);
+  // Through the same cache as `formatterFor`, for the same reason: this took the caller's raw
+  // locale too, and a second way to build a formatter in one file is a second place to forget.
+  return cachedFormatter(
+    decimalCache,
+    `${tag}|${digits}`,
+    () =>
+      new Intl.NumberFormat(tag, {
+        style: 'decimal',
+        minimumFractionDigits: digits,
+        maximumFractionDigits: digits,
+        useGrouping: false,
+      }),
+  ).format(toDecimalNumber(amount));
 }
 
+/**
+ * A tag `Intl` cannot parse falls through unchanged, so the `Intl.NumberFormat` constructor still
+ * raises it — this seam decides a cache key, never whether a locale is acceptable.
+ */
+const canonicalTag = (locale: string): string => canonicalLocale(locale) ?? locale;
+
 const cache = new Map<string, Intl.NumberFormat>();
+const decimalCache = new Map<string, Intl.NumberFormat>();
 
 /**
  * `scale` is the amount's own, not the currency's: rendering $0.000002 with two digits shows
  * `$0.00`, which is the sub-cent bug back again, in the one place a human would read it.
+ *
+ * **Canonically keyed and hard-capped, because `locale` arrives from `Accept-Language`.** Keyed
+ * raw into an unbounded `Map`, 20,000 valid-but-distinct tags (`en-US-x-a0` …) retained 55 MB —
+ * memory the client chooses. `canonicalLocale` collapses `EN-us` and `en-US` onto one key and
+ * `cachedFormatter` caps the rest; neither half is sufficient alone, which is why both come from
+ * the one place `@ultimat3/time` reads them from too.
  */
 function formatterFor(
   currency: string,
@@ -96,13 +118,14 @@ function formatterFor(
   const digits =
     options.fractionDigits ?? (options.trimZeroFraction === true ? undefined : exponent);
   const sign = options.accounting === true ? 'accounting' : 'standard';
+  const tag = canonicalTag(locale);
   // `exponent` is in the key because it stopped being derivable from `currency` the moment it
   // started coming from the amount's own scale. On the `trimZeroFraction` path `digits` is
   // `undefined`, so without it every scale of one currency shared a formatter: format 12.99 EUR
   // first and 12.990001 EUR then rendered as `12,99 €` — the sub-cent bug back, silently, in the
   // one place a human reads the number.
   const key = [
-    locale,
+    tag,
     currency,
     options.display ?? 'symbol',
     digits ?? 'auto',
@@ -110,19 +133,19 @@ function formatterFor(
     options.grouping ?? 'auto',
     sign,
   ].join('|');
-  const cached = cache.get(key);
-  if (cached !== undefined) return cached;
-
-  const formatter = new Intl.NumberFormat(locale, {
-    style: 'currency',
-    currency,
-    currencyDisplay: options.display ?? 'symbol',
-    currencySign: sign,
-    ...(digits === undefined
-      ? { minimumFractionDigits: 0, maximumFractionDigits: exponent }
-      : { minimumFractionDigits: digits, maximumFractionDigits: digits }),
-    ...(options.grouping === 'never' ? { useGrouping: false } : {}),
-  });
-  cache.set(key, formatter);
-  return formatter;
+  return cachedFormatter(
+    cache,
+    key,
+    () =>
+      new Intl.NumberFormat(tag, {
+        style: 'currency',
+        currency,
+        currencyDisplay: options.display ?? 'symbol',
+        currencySign: sign,
+        ...(digits === undefined
+          ? { minimumFractionDigits: 0, maximumFractionDigits: exponent }
+          : { minimumFractionDigits: digits, maximumFractionDigits: digits }),
+        ...(options.grouping === 'never' ? { useGrouping: false } : {}),
+      }),
+  );
 }