@ultimat3/money 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -154,6 +154,14 @@ the wide shape and answer with the row type.
   `currencyCodes()` is what this process accepts, registrations included, and it is the list
   `X_CURRENCY_UNKNOWN`'s fix line names — so it must include them or that fix is the dead end it
   used to be.
+- **`trimZeroFraction` is `trailingZeroDisplay: 'stripIfInteger'`, never `minimumFractionDigits:
+  0`.** Min = max = the amount's scale, always; the min-0 form trimmed EVERY trailing zero and
+  rendered 1250 cents as `$12.5`. `trim` is in the formatter cache key because it no longer changes
+  the digit count.
+- **Every bound a caller names is screened before a built-in sees it.** `fractionDigits` outside
+  0…`MAX_FRACTION_DIGITS` is `X_MONEY_SCALE_INVALID` (`Intl` raised a bare `RangeError`), and
+  `allocate(m, parts)` past `MAX_ALLOCATION_PARTS` is `X_ALLOCATION_INVALID` (`new Array(1e10)`
+  did). Defaults are taken on `=== undefined`, never `??`, so a blanked `null` is refused.
 - Adding a currency to the *shipped* rows: one row in `currency.ts` with its correct exponent, plus
   a format test. An app never needs this — that is what `registerCurrency` is for.
 

package/README.md

@@ -37,6 +37,11 @@ add(price, money(500, 'USD'));               // throws X_CURRENCY_MISMATCH
 `fromDecimal` scales by it (`'1.234'` KWD → 1234), `toDecimalString` reverses it, and
 `formatMoney` sets the fraction digits from it. Hardcoding `/ 100` is a JPY bug and a KWD bug.
 
+`formatMoney(amount, locale, { trimZeroFraction: true })` drops the fraction of a WHOLE amount and
+nothing else — 1200 USD is `$12`, 1250 USD is `$12.50`, never `$12.5` (`trailingZeroDisplay:
+'stripIfInteger'`, with min = max = the amount's scale). `fractionDigits` is a whole number from 0
+to `MAX_FRACTION_DIGITS` (100, `Intl`'s own ceiling); anything else is `X_MONEY_SCALE_INVALID`.
+
 ## A currency the shipped rows do not carry
 
 `As of 2026-08`, 53 ISO-4217 rows ship. They are a *convention* — one useful subset — so an app
@@ -100,6 +105,9 @@ fiction. The alternative was a second money type.
 then hand out the leftover units one at a time, biggest fractional remainder first.
 `round(100 / 3)` either loses a cent or invents one, and an invoice that does that fails
 reconciliation forever. `allocateByRatios` does the same for revenue shares and line splits.
+A part count is a positive integer of at most `MAX_ALLOCATION_PARTS` (1,000,000) — every part is a
+`Money` held at once, so `allocate(m, 1e10)` is `X_ALLOCATION_INVALID`, where it was a bare
+`RangeError` out of `new Array`. More parts than minor units is fine: the surplus parts are zero.
 
 ## Rounding is never implicit
 

package/package.json

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

package/src/allocate.ts

@@ -14,11 +14,24 @@ import { factorFraction } from './factor';
 import { formatMoneyDebug, type Money, money } from './money';
 import { minorAt, moneyScale } from './scale';
 
+/**
+ * The most equal shares one `allocate` call hands back. A bound on memory, not on business: every
+ * part is a `Money` held at once, so `allocate(m, 1e10)` was a bare `RangeError` out of `new
+ * Array` and a count just under that an out-of-memory kill. A split wider than this is paged by
+ * the caller — `allocateByRatios` over each page's share.
+ */
+export const MAX_ALLOCATION_PARTS = 1_000_000;
+
 /** Split into `parts` equal shares. `allocate(money(100,'USD'), 3)` → 34, 33, 33. */
 export function allocate(amount: Money, parts: number): Money[] {
   if (!Number.isSafeInteger(parts) || parts <= 0) {
     throw allocationInvalid(`part count must be a positive integer, got ${String(parts)}`);
   }
+  if (parts > MAX_ALLOCATION_PARTS) {
+    throw allocationInvalid(
+      `part count ${String(parts)} is over the ${MAX_ALLOCATION_PARTS} shares one call holds in memory`,
+    );
+  }
   return allocateByRatios(amount, new Array<number>(parts).fill(1));
 }
 

package/src/errors.ts

@@ -165,6 +165,18 @@ export function digitsInvalid(digits: number): MoneyError {
   });
 }
 
+/**
+ * A `formatMoney` digit count `Intl.NumberFormat` cannot be built with. Never echoes the rejected
+ * value into the `fix:` — an instruction that raises the error it is answering is not one.
+ */
+export function fractionDigitsInvalid(digits: number, max: number): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_SCALE_INVALID',
+    cause: `fractionDigits must be a whole number between 0 and ${max}, got ${String(digits)}`,
+    fix: "formatMoney(amount, locale, { fractionDigits: 2 }) — or omit fractionDigits and take the amount's own scale",
+  });
+}
+
 /** 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

@@ -5,6 +5,7 @@
 
 import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { exponentOf } from './currency';
+import { fractionDigitsInvalid } from './errors';
 import { type Money, toDecimalString } from './money';
 import { moneyScale } from './scale';
 
@@ -16,10 +17,13 @@ export interface FormatMoneyOptions {
    * 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. */
+  /**
+   * Drop `.00` on whole amounts — price lists, never invoices. A fractional amount keeps every
+   * digit: 1250 cents is `$12.50`, never `$12.5`.
+   */
   trimZeroFraction?: boolean;
-  /** Force a digit count; defaults to the value's own scale, which is the currency's unless
-   * the amount names a finer one. */
+  /** Force a digit count, 0…`MAX_FRACTION_DIGITS` (`X_MONEY_SCALE_INVALID` otherwise); 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';
@@ -98,6 +102,20 @@ export function formatMoneyDecimal(amount: Money, locale: string): string {
  */
 const exactDecimal = (amount: Money): `${number}` => toDecimalString(amount) as `${number}`;
 
+/** `Intl.NumberFormat`'s own ceiling on a fraction digit count. */
+export const MAX_FRACTION_DIGITS = 100;
+
+/**
+ * `Intl` refuses a digit count outside 0…100, a fraction and `NaN` with a bare `RangeError`,
+ * several frames from the call that named it. A digit count IS a scale, so it is refused as one.
+ */
+function assertFractionDigits(digits: number): number {
+  if (!Number.isInteger(digits) || digits < 0 || digits > MAX_FRACTION_DIGITS) {
+    throw fractionDigitsInvalid(digits, MAX_FRACTION_DIGITS);
+  }
+  return digits;
+}
+
 const cache = new Map<string, Intl.NumberFormat>();
 const decimalCache = new Map<string, Intl.NumberFormat>();
 
@@ -123,21 +141,22 @@ function formatterFor(
   options: FormatMoneyOptions,
   exponent: number,
 ): Intl.NumberFormat {
+  // `=== undefined`, never `??`: `??` coalesces on `null` too, so an untyped caller's blanked
+  // option took the default instead of the refusal beside it.
   const digits =
-    options.fractionDigits ?? (options.trimZeroFraction === true ? undefined : exponent);
+    options.fractionDigits === undefined ? exponent : assertFractionDigits(options.fractionDigits);
+  const trim = options.trimZeroFraction === true;
   const sign = options.accounting === true ? 'accounting' : 'standard';
   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
-  // 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.
+  // `trim` is in the key because it no longer changes `digits`: a trimmed and an untrimmed
+  // formatter at one digit count are two formatters, and sharing an entry rendered whichever was
+  // built first.
   const key = [
     tag,
     currency,
     options.display ?? 'symbol',
-    digits ?? 'auto',
-    exponent,
+    digits,
+    trim ? 'trim' : 'keep',
     options.grouping ?? 'auto',
     sign,
   ].join('|');
@@ -150,9 +169,12 @@ function formatterFor(
         currency,
         currencyDisplay: options.display ?? 'symbol',
         currencySign: sign,
-        ...(digits === undefined
-          ? { minimumFractionDigits: 0, maximumFractionDigits: exponent }
-          : { minimumFractionDigits: digits, maximumFractionDigits: digits }),
+        // min = max, always: the digit count is the value's scale and never a range. Trimming is
+        // `stripIfInteger` — drop the fraction of a WHOLE amount — because `minimumFractionDigits:
+        // 0` trimmed every trailing zero and rendered 1250 cents as `$12.5`.
+        minimumFractionDigits: digits,
+        maximumFractionDigits: digits,
+        ...(trim ? { trailingZeroDisplay: 'stripIfInteger' as const } : {}),
         ...(options.grouping === 'never' ? { useGrouping: false } : {}),
       }),
   );

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   allocateByPercentages,
   allocateByRatios,
   assertAllocationSums,
+  MAX_ALLOCATION_PARTS,
 } from './allocate';
 export {
   absolute,
@@ -71,6 +72,7 @@ export {
   formatMoney,
   formatMoneyDecimal,
   formatMoneyParts,
+  MAX_FRACTION_DIGITS,
 } from './format';
 export {
   currencyOf,