@ultimat3/money 1.2.0 → 3.0.0

package/src/currency.ts

@@ -1,10 +1,12 @@
 /**
- * The ISO-4217 minor-unit exponent table. Every scale in the package derives from here —
- * a hardcoded `/ 100` is a bug in JPY (0 digits) and in KWD (3 digits).
- * As of 2026-07.
+ * The minor-unit exponent table: the ISO-4217 rows Ultimate ships, plus the rows an app registers.
+ * Every scale in the package derives from here — a hardcoded `/ 100` is a bug in JPY (0 digits)
+ * and in KWD (3 digits). As of 2026-08.
  */
 
-import { currencyUnknown } from './errors';
+import { renderCauseValue } from '@ultimat3/core';
+import { isCurrencyCode, isMoneyScale, MAX_MONEY_SCALE } from '@ultimat3/schema';
+import { currencyDeclarationInvalid, currencyRedefined, currencyUnknown } from './errors';
 
 /** Uppercase ISO-4217 alphabetic code. */
 export type CurrencyCode = string;
@@ -76,15 +78,82 @@ const BY_CODE: ReadonlyMap<string, CurrencyInfo> = new Map(
   TABLE.map((info) => [info.code, info] as const),
 );
 
+/**
+ * What the app added. Separate from `BY_CODE` so a shipped ISO row can never be overwritten and
+ * `CURRENCIES` keeps meaning exactly what it meant: the constant this package ships.
+ */
+const REGISTERED = new Map<string, CurrencyInfo>();
+
+/**
+ * The ISO-4217 rows Ultimate ships — a constant, the same in every process.
+ *
+ * Not the same question as `currencyCodes()`, which answers for *this* process and includes
+ * whatever the app registered. That is why one is a value and the other is a call.
+ */
 export const CURRENCIES: readonly CurrencyInfo[] = TABLE;
 
+/**
+ * Declare a currency the shipped ISO rows do not carry — a local currency, a scrip, a loyalty
+ * point, a token. Call it once, at boot, before any amount in that currency is built.
+ *
+ * The 53 shipped rows are a *convention* — one useful subset of ISO-4217 — and axiom 8 says an app
+ * encodes its own by calling a function, never by forking the package. The rest of the framework
+ * already agreed: `@ultimat3/schema`'s `moneySchema`, the published OpenAPI contract and
+ * `@ultimat3/entity`'s `char(3)` CHECK all accept any `^[A-Z]{3}$`, so an app could take an
+ * unregistered code over HTTP and store it, and only arithmetic would refuse it afterwards.
+ *
+ * Returns the row now in force, so the identical second call is a no-op rather than a crash — a
+ * module imported twice must not take the process down.
+ */
+export function registerCurrency(info: CurrencyInfo): CurrencyInfo {
+  const { code, exponent, name } = info;
+  // `isCurrencyCode`, imported for the same reason `isMoneyScale` below is: this is the bound
+  // `moneySchema`, the published OpenAPI `pattern` and `@ultimat3/entity`'s CHECK all apply, and a
+  // registration accepting a code any of them refuses would put a row in a table the app cannot
+  // read back. It also carries the `typeof` half, so an untyped caller's symbol is a refusal here
+  // rather than a `TypeError` from `.test()`. Not taste either:
+  // `Intl.NumberFormat({ style: 'currency', currency })` throws a `RangeError` on anything else,
+  // so a registration that skipped the shape would format nothing.
+  if (!isCurrencyCode(code)) {
+    throw currencyDeclarationInvalid(
+      // `renderCauseValue`, not `String(code)`: the signature says `string` but nothing stops an
+      // untyped caller passing a symbol, and `String()` raises on one — the validator would then
+      // throw a TypeError instead of the coded refusal it exists to produce.
+      `a currency code must be three uppercase letters, got ${renderCauseValue(code)}`,
+      'XBT',
+    );
+  }
+  // `isMoneyScale`, imported rather than restated: an exponent past MAX_MONEY_SCALE names a
+  // decimal place `minor` could not count in, and one bound with two declarations is one bound
+  // that drifts. It also rejects a non-integer, so a 2.5 cannot round itself into the table.
+  if (!isMoneyScale(exponent)) {
+    throw currencyDeclarationInvalid(
+      `${code} needs a whole number of decimal places between 0 and ${MAX_MONEY_SCALE} — an exponent decides what a stored minor counts, so there is no safe default`,
+      code,
+    );
+  }
+  if (typeof name !== 'string' || name.trim() === '') {
+    throw currencyDeclarationInvalid(`${code} needs a non-empty name`, code);
+  }
+
+  const existing = BY_CODE.get(code) ?? REGISTERED.get(code);
+  if (existing !== undefined) {
+    if (existing.exponent === exponent && existing.name === name) return existing;
+    throw currencyRedefined(code, existing, { exponent, name });
+  }
+
+  const row: CurrencyInfo = Object.freeze({ code, exponent, name });
+  REGISTERED.set(code, row);
+  return row;
+}
+
 export function isValidCurrency(currency: string): boolean {
-  return BY_CODE.has(currency);
+  return BY_CODE.has(currency) || REGISTERED.has(currency);
 }
 
 /** Loud lookup: an unknown code is a data bug, not a formatting quirk. */
 export function currencyInfo(currency: string): CurrencyInfo {
-  const info = BY_CODE.get(currency);
+  const info = BY_CODE.get(currency) ?? REGISTERED.get(currency);
   if (info === undefined) throw currencyUnknown(currency);
   return info;
 }
@@ -103,6 +172,14 @@ export function scaleOf(currency: string): number {
   return 10 ** exponentOf(currency);
 }
 
+/**
+ * Every code this process accepts — the shipped rows plus whatever the app registered. Sorted, so
+ * two processes with the same registrations print the same list.
+ *
+ * This is the one enumeration `X_CURRENCY_UNKNOWN`'s fix line points at, so it has to include the
+ * registered rows: a fix that named a list the accepted code is missing from would be the same
+ * dead end that error used to hand back.
+ */
 export function currencyCodes(): CurrencyCode[] {
-  return TABLE.map((info) => info.code);
+  return [...TABLE.map((info) => info.code), ...REGISTERED.keys()].sort();
 }

package/src/errors.ts

@@ -3,14 +3,18 @@
  * A money bug that throws is a bug you can fix; one that rounds is a bug you ship.
  */
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import { isCurrencyCode, MAX_MONEY_SCALE } from '@ultimat3/schema';
 
 export const MONEY_ERROR_CODES = [
   'X_MONEY_NOT_INTEGER',
   'X_CURRENCY_UNKNOWN',
   'X_CURRENCY_MISMATCH',
+  'X_CURRENCY_INVALID',
+  'X_CURRENCY_REDEFINED',
   'X_ALLOCATION_INVALID',
   'X_RATE_MISSING',
+  'X_MONEY_SCALE_INVALID',
 ] as const;
 
 export type MoneyErrorCode = (typeof MONEY_ERROR_CODES)[number];
@@ -19,8 +23,11 @@ export const MONEY_ERROR_TITLES: Readonly<Record<MoneyErrorCode, string>> = {
   X_MONEY_NOT_INTEGER: 'a Money.minor value that is not an integer',
   X_CURRENCY_UNKNOWN: 'currency code not in the currency table',
   X_CURRENCY_MISMATCH: 'two Money values in different currencies',
+  X_CURRENCY_INVALID: 'a registerCurrency declaration that cannot become a currency',
+  X_CURRENCY_REDEFINED: 'one currency code registered twice with different meanings',
   X_ALLOCATION_INVALID: 'split ratios or part count are unusable',
   X_RATE_MISSING: 'no FX rate for the pair',
+  X_MONEY_SCALE_INVALID: 'a Money.scale that is not a usable decimal exponent',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -41,11 +48,36 @@ export class MoneyError extends UltimateError {
   }
 }
 
+/**
+ * A currency code fit to stand in a `fix:` — the caller's when it already is one, `XXX` otherwise.
+ * Two rules at once, and every factory below that names a code goes through it.
+ *
+ * A fix is PASTED AND RUN, so a code carrying a quote closes the literal it sits in and the
+ * instruction becomes a syntax error — `assertCurrency('O'Reilly')` — which is worse than no fix,
+ * because it looks runnable. And a malformed code echoed back would name a call that raises the
+ * error it is answering, the rule `currencyDeclarationInvalid` below already states. Every one of
+ * these factories is exported, so the argument is whatever an app passed, not only what this
+ * package throws. `bun run error-render` cannot see the class: these parameters are typed
+ * `string`, not `unknown`.
+ */
+function codeExample(currency: string): string {
+  // Uppercased and cut to three because the lookup is case-sensitive, so 'usd' is the common
+  // arrival and 'USD' answers it. The `typeof` guard is what keeps an untyped caller's symbol from
+  // throwing out of `.toUpperCase()` inside an error factory.
+  const upper = typeof currency === 'string' ? currency.toUpperCase().slice(0, 3) : '';
+  return isCurrencyCode(upper) ? upper : 'XXX';
+}
+
+/** The same code as source. Safe to interpolate: `codeExample` answers `^[A-Z]{3}$`, nothing else. */
+function codeLiteral(currency: string): string {
+  return `'${codeExample(currency)}'`;
+}
+
 export function moneyNotInteger(minor: number, currency: string): MoneyError {
   return new MoneyError({
     code: 'X_MONEY_NOT_INTEGER',
     cause: `minor units must be a safe integer, got ${String(minor)} for ${currency}`,
-    fix: `use fromDecimal('${Number.isFinite(minor) ? minor : 0}', '${currency}') or round explicitly with multiply(m, factor, 'half-up')`,
+    fix: `use fromDecimal('${Number.isFinite(minor) ? minor : 0}', ${codeLiteral(currency)}) or round explicitly with multiply(m, factor, 'half-up')`,
   });
 }
 
@@ -62,10 +94,82 @@ export function notRoundable(value: number): MoneyError {
 }
 
 export function decimalTooPrecise(value: string, currency: string, exponent: number): MoneyError {
+  const digits = countFractionDigits(value);
+  // Past MAX_MONEY_SCALE no scale keeps every digit, so the offer is withdrawn rather than
+  // clamped: `{ scale: 19 }` was a fix line that answered X_MONEY_SCALE_INVALID, and an
+  // instruction that throws is not one.
+  const keepThemAll =
+    digits <= MAX_MONEY_SCALE
+      ? // `renderFixLiteral`, not `'${value}'`: the amount is a caller's string, and `fromDecimal`
+        // trims before it parses — so a value ending in a newline reached the fix line and put a
+        // raw line break inside a single-quoted literal, which no reader can paste.
+        `fromDecimal(${renderFixLiteral(value.trim(), "'12.9999'")}, ${codeLiteral(currency)}, { scale: ${digits} }) to keep every digit, or `
+      : '';
   return new MoneyError({
     code: 'X_MONEY_NOT_INTEGER',
-    cause: `"${value}" has more fraction digits than ${currency} has minor units (${exponent})`,
-    fix: `pass { rounding: 'half-up' } to fromDecimal to accept the loss of precision on purpose`,
+    cause: `"${value}" has more than ${exponent} fraction digit(s), which is all ${currency} is being counted in`,
+    fix: `${keepThemAll}pass { rounding: 'half-up' } to fromDecimal to lose the extra digits on purpose`,
+  });
+}
+
+function countFractionDigits(value: string): number {
+  return value.trim().split('.')[1]?.length ?? 0;
+}
+
+/** 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({
+    code: 'X_MONEY_SCALE_INVALID',
+    cause: `a money scale must be a whole number of decimal places between 0 and ${MAX_MONEY_SCALE}, got ${String(scale)}`,
+    fix: `use a scale in range — money(minor, currency, 6) for micros, or omit it for the currency's own minor unit`,
+  });
+}
+
+/**
+ * A widened value that no longer fits a safe integer. Reported under `X_MONEY_SCALE_INVALID`
+ * rather than `X_MONEY_NOT_INTEGER` because the caller never wrote a fractional minor — the scale
+ * the operation had to meet at is what does not fit, and that code's fix line
+ * (`fromDecimal('90071992547409900000', …)`) throws again. Same code as the other scale faults, so
+ * the reader lands on the page about scales, which is where the answer is.
+ */
+export function scaleOverflow(
+  scale: number,
+  currency: string,
+  fits: number | undefined,
+): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_SCALE_INVALID',
+    cause: `this ${currency} amount needs more digits at scale ${scale} than a safe integer holds`,
+    fix:
+      fits === undefined
+        ? `the amount is too large for any scale — split it, or carry it as two ${codeExample(currency)} values`
+        : `rescale(theFinerOperand, ${fits}, 'half-up') before combining — scale ${fits} is the finest that fits`,
+  });
+}
+
+/** Widening is exact; narrowing is a rounding decision, and `minorAt` does not make those. */
+export function scaleNotWidening(from: number, to: number): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_SCALE_INVALID',
+    cause: `cannot restate a value at scale ${from} as scale ${to} without dropping digits`,
+    fix: `rescale(amount, ${to}, 'half-up') — narrowing needs the mode named at the call`,
+  });
+}
+
+/**
+ * A narrowing that would drop a non-zero digit. Reported as `X_MONEY_NOT_INTEGER` because that is
+ * literally what it would produce — a fractional count of minor units — and the same situation
+ * `fromDecimal` already answers with that code.
+ */
+export function rescaleNotExact(
+  amount: { readonly minor: number; readonly currency: string },
+  from: number,
+  to: number,
+): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_NOT_INTEGER',
+    cause: `${amount.currency} ${amount.minor} at scale ${from} is not a whole number of minor units at scale ${to}`,
+    fix: `rescale(amount, ${to}, 'half-up') — name the mode, or keep the value at scale ${from}`,
   });
 }
 
@@ -73,15 +177,54 @@ export function decimalNotNumeric(value: string, currency: string): MoneyError {
   return new MoneyError({
     code: 'X_MONEY_NOT_INTEGER',
     cause: `"${value}" is not a decimal amount — no grouping separators, no exponent notation`,
-    fix: `pass a plain decimal string: fromDecimal('12.99', '${currency}')`,
+    fix: `pass a plain decimal string: fromDecimal('12.99', ${codeLiteral(currency)})`,
   });
 }
 
 export function currencyUnknown(currency: string): MoneyError {
+  const example = codeLiteral(currency);
+  // Two arrivals, one code, so the fix names both doors. The lookup is exact and case-sensitive,
+  // which is what makes 'usd' the common one; the other is a currency the shipped ISO rows do not
+  // carry, and since 1.2.0 that is a call the app makes rather than a fork of this package.
   return new MoneyError({
     code: 'X_CURRENCY_UNKNOWN',
-    cause: `"${currency}" is not an ISO-4217 code in the currency table`,
-    fix: `x money add-currency ${currency.toUpperCase().slice(0, 3) || 'XXX'} --exponent 2`,
+    cause: `"${currency}" is not a currency this process knows — not in the shipped ISO-4217 rows, and not registered by the app`,
+    fix: `pass a code currencyCodes() lists, uppercased — assertCurrency(${example}) — or declare it once at boot: registerCurrency({ code: ${example}, exponent: 2, name: ${example} })`,
+  });
+}
+
+/**
+ * A `registerCurrency` declaration that could not become a currency. Never echoes the rejected
+ * value back into the `fix:` — `decimalTooPrecise` shipped that shape once, and an instruction
+ * that raises the error it is answering is not an instruction.
+ */
+export function currencyDeclarationInvalid(reason: string, exampleCode: string): MoneyError {
+  return new MoneyError({
+    code: 'X_CURRENCY_INVALID',
+    cause: reason,
+    fix: `registerCurrency({ code: ${codeLiteral(exampleCode)}, exponent: 2, name: ${codeLiteral(exampleCode)} }) — three A–Z letters, a whole exponent from 0 to ${MAX_MONEY_SCALE}, and a non-empty name`,
+  });
+}
+
+/**
+ * One code, one declaration. The exponent is the dangerous half: it decides what a stored `minor`
+ * counts, so accepting a second one silently reinterprets every amount already written in that
+ * currency by a power of ten. The name matters for a smaller reason that is still a bug —
+ * `currencyInfo(code).name` is rendered, and two registrations would make it depend on import
+ * order.
+ */
+export function currencyRedefined(
+  code: string,
+  existing: { readonly exponent: number; readonly name: string },
+  attempted: { readonly exponent: number; readonly name: string },
+): MoneyError {
+  return new MoneyError({
+    code: 'X_CURRENCY_REDEFINED',
+    cause: `${code} is already registered as "${existing.name}" with exponent ${existing.exponent}; refusing to redefine it as "${attempted.name}" with exponent ${attempted.exponent}`,
+    // `renderFixLiteral` on the name and nowhere else: a name is free text by design — `O'Reilly
+    // Points` is a currency an app may legitimately register — and it is the one value here that
+    // cannot be gated into a safe shape, so it is escaped instead.
+    fix: `keep one registerCurrency({ code: ${codeLiteral(code)}, exponent: ${existing.exponent}, name: ${renderFixLiteral(existing.name, "'the name already registered'")} }) call and delete the other — to change a live exponent you must migrate every stored ${codeExample(code)} amount, because each one shifts by a power of ten`,
   });
 }
 
@@ -97,7 +240,7 @@ export function currencyMismatch(left: string, right: string): MoneyError {
   return new MoneyError({
     code: 'X_CURRENCY_MISMATCH',
     cause: `refusing to combine ${left} and ${right} — two currencies are not one number`,
-    fix: `convert(rightOperand, '${left}', rate) first, then combine`,
+    fix: `convert(rightOperand, ${codeLiteral(left)}, rate) first, then combine`,
   });
 }
 

package/src/factor.ts

@@ -0,0 +1,33 @@
+/**
+ * The exact fraction a scaling factor's decimal spelling names.
+ * A rate, a quantity or a percentage arrives as an IEEE-754 double, and `1.005` is held as
+ * 1.00499999999999989…; scaling first and rounding after therefore shows the rounding mode a
+ * value nobody wrote. The shortest round-trip decimal IS what was written, so its expansion is
+ * the exact value every scale in this package is taken against.
+ */
+
+import { notRoundable } from './errors';
+
+/** `numerator / denominator`, exactly. `denominator` is always a positive power of ten. */
+export interface Fraction {
+  readonly numerator: bigint;
+  readonly denominator: bigint;
+}
+
+/** The grammar `Number.prototype.toString` emits for every finite double, exponent included. */
+const SPELLING = /^([+-]?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+
+export function factorFraction(factor: number): Fraction {
+  if (!Number.isFinite(factor)) throw notRoundable(factor);
+  const match = SPELLING.exec(String(factor));
+  if (match === null) throw notRoundable(factor);
+  const [, sign = '', whole = '0', fraction = '', exponent = '0'] = match;
+
+  let numerator = BigInt(`${whole}${fraction}`);
+  let denominator = 10n ** BigInt(fraction.length);
+  const shift = BigInt(exponent);
+  if (shift > 0n) numerator *= 10n ** shift;
+  else if (shift < 0n) denominator *= 10n ** -shift;
+
+  return { numerator: sign === '-' ? -numerator : numerator, denominator };
+}

package/src/format.ts

@@ -3,95 +3,149 @@
  * 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';
 
 export interface FormatMoneyOptions {
   /** How the currency appears: `€1,299.00` / `EUR 1,299.00` / `1,299.00 euros`. */
   display?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
-  /** Accounting negatives: `(€12.99)` instead of `-€12.99`. */
+  /**
+   * Accounting negatives — `(€12.99)` in `en-US`. Passed to `Intl` as `currencySign`, so the
+   * locale decides the notation: `de-DE` has no parenthesised form in CLDR and keeps `-1.299,00 €`.
+   */
   accounting?: boolean;
   /** Drop `.00` on whole amounts — price lists, never invoices. */
   trimZeroFraction?: boolean;
-  /** Force a digit count; defaults to the currency's minor-unit exponent. */
+  /** Force a digit count; defaults to the value's own scale, which is the currency's unless
+   * the amount names a finer one. */
   fractionDigits?: number;
   /** `never` disables grouping separators. */
   grouping?: 'auto' | 'never';
 }
 
-/** `formatMoney(money(129900,'EUR'), 'de-DE')` → `1.299,00 €`. */
+/**
+ * `formatMoney(money(129900,'EUR'), 'de-DE')` → `1.299,00 €`.
+ *
+ * Delegates to `formatMoneyParts` and joins: a UI styling the symbol off the parts and a label
+ * rendering the string must not disagree about where the sign goes. Hand-prefixing `-` here put
+ * it outside the symbol (`-€ 1.299,00`) where `nl-NL` puts it inside (`€ -1.299,00`), and
+ * `accounting` was applied on this path only.
+ */
 export function formatMoney(
   amount: Money,
   locale: string,
   options: FormatMoneyOptions = {},
 ): string {
-  const rendered = formatterFor(amount.currency, locale, options).format(
-    Math.abs(toDecimalNumber(amount)),
-  );
-  if (amount.minor < 0) {
-    return options.accounting === true ? `(${rendered})` : `-${rendered}`;
-  }
-  return rendered;
+  return formatMoneyParts(amount, locale, options)
+    .map((part) => part.value)
+    .join('');
 }
 
 /**
  * Parts, for UI that styles the symbol or the decimals differently (a smaller superscript
  * cent, a muted currency code). Never re-split a formatted string with a regex.
+ *
+ * The signed value goes to `Intl`, so sign placement and the accounting notation are the
+ * locale's — the one place either is decided.
  */
 export function formatMoneyParts(
   amount: Money,
   locale: string,
   options: FormatMoneyOptions = {},
 ): Intl.NumberFormatPart[] {
-  return formatterFor(amount.currency, locale, options).formatToParts(toDecimalNumber(amount));
+  return formatterFor(amount.currency, locale, options, moneyScale(amount)).formatToParts(
+    toDecimalNumber(amount),
+  );
 }
 
 /** The symbol alone, e.g. for an input prefix: `€`, `¥`, `KD`. */
 export function currencySymbol(currency: string, locale: string): string {
-  const parts = formatterFor(currency, locale, { display: 'narrowSymbol' }).formatToParts(0);
+  const parts = formatterFor(
+    currency,
+    locale,
+    { display: 'narrowSymbol' },
+    exponentOf(currency),
+  ).formatToParts(0);
   return parts.find((part) => part.type === 'currency')?.value ?? currency;
 }
 
 /** Digits only, no symbol — for editable inputs and CSV exports. */
 export function formatMoneyDecimal(amount: Money, locale: string): string {
-  const digits = exponentOf(amount.currency);
-  return new Intl.NumberFormat(locale, {
-    style: 'decimal',
-    minimumFractionDigits: digits,
-    maximumFractionDigits: digits,
-    useGrouping: false,
-  }).format(toDecimalNumber(amount));
+  const digits = moneyScale(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,
   locale: string,
   options: FormatMoneyOptions,
+  exponent: number,
 ): Intl.NumberFormat {
-  const exponent = exponentOf(currency);
   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',
+    exponent,
     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',
-    ...(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/index.ts

@@ -41,11 +41,14 @@ export {
   currencyInfo,
   exponentOf,
   isValidCurrency,
+  registerCurrency,
   scaleOf,
 } from './currency';
 export {
   allocationInvalid,
+  currencyDeclarationInvalid,
   currencyMismatch,
+  currencyRedefined,
   currencyRequired,
   currencyUnknown,
   decimalNotNumeric,
@@ -56,7 +59,12 @@ export {
   type MoneyErrorCode,
   moneyNotInteger,
   rateMissing,
+  rescaleNotExact,
+  scaleInvalid,
+  scaleNotWidening,
 } from './errors';
+/** `ExchangeRate.ratio` is one of these; a provider with an exact rate writes the pair itself. */
+export type { Fraction } from './factor';
 export {
   currencySymbol,
   type FormatMoneyOptions,
@@ -77,6 +85,7 @@ export {
   toDecimalString,
   zero,
 } from './money';
+export { rescale } from './rescale';
 export {
   DEFAULT_ROUNDING,
   ROUNDING_MODES,
@@ -84,3 +93,4 @@ export {
   roundToDigits,
   roundToInteger,
 } from './rounding';
+export { assertScale, commonScale, MAX_MONEY_SCALE, minorAt, moneyScale } from './scale';