@ultimat3/money 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -30,7 +30,7 @@ shape is still additive and this is still a minor version.
 | `arithmetic.ts` | add/subtract/multiply/compare, refuses mixed currencies |
 | `allocate.ts` | largest-remainder splits that preserve the total |
 | `factor.ts` | the exact fraction a scaling factor's decimal spelling names. `factorFraction` is internal — never exported; the `Fraction` **type** is public, because `ExchangeRate.ratio` is one |
-| `rounding.ts` | explicit modes, no implicit default, over a float (`roundToInteger`) or a ratio (`roundRatio`) |
+| `rounding.ts` | explicit modes, no implicit default, over a float (`roundToInteger`) or a ratio (`roundRatio`, and `roundToDigits` through it) |
 | `format.ts` | `Intl.NumberFormat` only, digits from the exponent |
 | `convert.ts` | explicit rate + `RateProvider`, records provenance |
 
@@ -40,6 +40,12 @@ shape is still additive and this is still a minor version.
 - Never `/ 100`, and never `exponentOf(amount.currency)` for a value's own precision — that is
   `moneyScale(amount)`, which falls back to the currency and is right for both. `exponentOf` and
   `scaleOf` still answer for a *currency*, which is a different question.
+- **A stated currency is an ASSERTION, never a fallback.** `sum(amounts, currency)` used its
+  second argument only when the list was empty and ignored it entirely once a first addend existed:
+  `sum([money(1, 'EUR')], 'USD')` answered `{ minor: 1, currency: 'EUR' }`, so a caller who wrote
+  down USD received EUR with nothing refused — in the one entry point of a file whose header is
+  "Integer arithmetic that refuses to mix currencies". A stated currency the first addend
+  contradicts is `X_CURRENCY_MISMATCH`.
 - **Two scales meet at the finer one, never the coarser.** `add`, `subtract` and `compare`
   widen through `minorAt` (bigint, exact) before they do anything else, so a sub-cent fee added to
   a cent survives and a comparison answers where storing the widened value would rightly be
@@ -63,7 +69,11 @@ shape is still additive and this is still a minor version.
   100.49999999999999 `100 * 1.005` produces. A new scaling entry point goes through the same pair
   — `roundToInteger(a * b, mode)` is the bug, written again. `fromDecimal` was the last float
   path and it is the one every user-typed price goes through: `Number('0.4999999999999999999')`
-  is exactly 0.5, so `half-up` saw a tie the written decimal does not have.
+  is exactly 0.5, so `half-up` saw a tie the written decimal does not have. **`roundToDigits` was
+  that rule broken in this very file** — its body was literally `roundToInteger(value * factor,
+  mode) / factor`, so `roundToDigits(1.005, 2, 'half-up')` answered 1.00 where 1.01 is owed. It
+  goes through `factorFraction` + `roundRatio` as of 2026-08, and a digit count that is not a whole
+  number of decimal places is `X_MONEY_SCALE_INVALID`, never a bare `RangeError` out of `BigInt`.
 - **`convert` preserves the amount's own `scale`.** `exponentOf(target)` decides the natural scale
   of a value that names none; a value that names one keeps it, because narrowing $0.000002 to
   EUR's two decimals is the 10,000x reinterpretation `scale` was added to prevent. Same rule as
@@ -79,6 +89,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": "4.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": "4.0.0",
+    "@ultimat3/schema": "4.0.0"
   }
 }

package/src/arithmetic.ts

@@ -39,9 +39,21 @@ export function subtract(left: Money, right: Money): Money {
   );
 }
 
-/** Every addend must share one currency; an empty list needs an explicit currency. */
+/**
+ * Every addend must share one currency; an empty list needs an explicit currency.
+ *
+ * A stated currency the first addend contradicts is `X_CURRENCY_MISMATCH`, not a silent win for
+ * the list: `sum([money(1, 'EUR')], 'USD')` used to answer `{ minor: 1, currency: 'EUR' }`, so a
+ * caller who wrote down USD received EUR and nothing refused — the exact failure this file's
+ * header exists to rule out, in the one entry point that treated its currency as a fallback rather
+ * than as an assertion.
+ */
 export function sum(amounts: readonly Money[], currency?: string): Money {
-  const base = amounts[0]?.currency ?? currency;
+  const first = amounts[0]?.currency;
+  if (first !== undefined && currency !== undefined && first !== currency) {
+    throw currencyMismatch(currency, first);
+  }
+  const base = first ?? currency;
   if (base === undefined) throw currencyRequired('sum([])');
   return amounts.reduce((total, amount) => add(total, amount), money(0, base));
 }

package/src/errors.ts

@@ -116,6 +116,19 @@ function countFractionDigits(value: string): number {
   return value.trim().split('.')[1]?.length ?? 0;
 }
 
+/**
+ * A `roundToDigits` digit count that names no decimal place. Reported as `X_MONEY_SCALE_INVALID`
+ * because a digit count IS a scale — `10 ** 1.5` is not a power of ten, and `BigInt(1.5)` is a
+ * bare `RangeError` out of a function whose every other refusal is coded.
+ */
+export function digitsInvalid(digits: number): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_SCALE_INVALID',
+    cause: `a digit count must be a whole number between -${MAX_MONEY_SCALE} and ${MAX_MONEY_SCALE}, got ${String(digits)}`,
+    fix: "pass an integer digit count — roundToDigits(value, 2, 'half-up') for two decimal places",
+  });
+}
+
 /** A scale outside 0…MAX_MONEY_SCALE names no decimal place a `minor` could count in. */
 export function scaleInvalid(scale: number): MoneyError {
   return new MoneyError({

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 } : {}),
+      }),
+  );
 }

package/src/rounding.ts

@@ -4,7 +4,9 @@
  */
 
 import { invariant } from '@ultimat3/core';
-import { notRoundable } from './errors';
+import { MAX_MONEY_SCALE } from '@ultimat3/schema';
+import { digitsInvalid, notRoundable } from './errors';
+import { factorFraction } from './factor';
 
 export type RoundingMode =
   /** 0.5 away from zero — the commercial default most invoicing rules specify. */
@@ -103,12 +105,25 @@ export function roundRatio(
 /**
  * Round to `digits` decimal places, used when converting a decimal string whose
  * precision exceeds the currency's minor unit.
+ *
+ * Over `roundRatio`, never `roundToInteger(value * factor, mode)` — that product is the bug this
+ * package documents as forbidden: `1.005 * 100` is 100.49999999999999, so half-up answered 1.00
+ * where 1.01 is owed. The value reaches the mode as the exact fraction its shortest round-trip
+ * decimal names, which is the same path `multiply` and `convert` already take.
  */
 export function roundToDigits(
   value: number,
   digits: number,
   mode: RoundingMode = DEFAULT_ROUNDING,
 ): number {
-  const factor = 10 ** digits;
-  return roundToInteger(value * factor, mode) / factor;
+  if (!Number.isInteger(digits) || Math.abs(digits) > MAX_MONEY_SCALE) throw digitsInvalid(digits);
+  const { numerator, denominator } = factorFraction(value);
+  const scale = 10n ** BigInt(Math.abs(digits));
+  // A negative digit count rounds to tens or hundreds, so the power moves to the other side of the
+  // fraction rather than becoming a fractional bigint, which has no spelling.
+  const rounded =
+    digits >= 0
+      ? roundRatio(numerator * scale, denominator, mode)
+      : roundRatio(numerator, denominator * scale, mode);
+  return digits >= 0 ? rounded / Number(scale) : rounded * Number(scale);
 }