@ultimat3/money 15.0.0 → 17.0.0

package/CLAUDE.md

@@ -99,10 +99,19 @@ the wide shape and answer with the row type.
 - **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
+  `Intl.NumberFormat`. Both halves, always — `assertLocale` 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.
+- **A malformed locale tag is `X_LOCALE_INVALID`, never a bare `RangeError`, `As of 2026-08-26`.**
+  `formatMoney`, `formatMoneyParts`, `formatMoneyDecimal` and `currencySymbol` all screen through
+  `assertLocale` (`@ultimat3/core`), which validates and canonicalizes in ONE step — so the key the
+  cache is bounded on is the tag the screen accepted. The pass-through it replaced was argued as
+  "this seam decides a cache key, never whether a locale is acceptable", which is true of the cache
+  and was never an argument for handing the tag to `Intl.NumberFormat`: `en_US` off an
+  `Accept-Language` header took the request down with an uncoded throw several frames away.
+  `@ultimat3/time` had closed the identical hole one release earlier, and money was the last
+  tier-1 package still doing what time deleted.
 - **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": "15.0.0",
+  "version": "17.0.0",
   "description": "Integer minor units with an attached currency: arithmetic, allocation, rounding, Intl formatting",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "15.0.0",
-    "@ultimat3/schema": "15.0.0"
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/schema": "17.0.0"
   }
 }

package/src/format.ts

@@ -3,7 +3,7 @@
  * JPY renders without decimals and KWD with three, without a per-locale special case.
  */
 
-import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { exponentOf } from './currency';
 import { type Money, toDecimalNumber } from './money';
 import { moneyScale } from './scale';
@@ -74,7 +74,7 @@ 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);
-  const tag = canonicalTag(locale);
+  const tag = assertLocale(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(
@@ -90,12 +90,6 @@ export function formatMoneyDecimal(amount: Money, locale: string): string {
   ).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>();
 
@@ -103,11 +97,17 @@ 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.
+ * **Screened, 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. `assertLocale` 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.
+ *
+ * It also REFUSES a tag `Intl` cannot parse (`X_LOCALE_INVALID`) instead of handing it on. Passing
+ * it through was argued as "this seam decides a cache key, never whether a locale is acceptable",
+ * which is true of the cache and was never an argument for the throw that followed: the
+ * `Intl.NumberFormat` constructor then raised a bare, uncoded `RangeError` at a caller holding a
+ * request header.
  */
 function formatterFor(
   currency: string,
@@ -118,7 +118,7 @@ function formatterFor(
   const digits =
     options.fractionDigits ?? (options.trimZeroFraction === true ? undefined : exponent);
   const sign = options.accounting === true ? 'accounting' : 'standard';
-  const tag = canonicalTag(locale);
+  const tag = assertLocale(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