@ultimat3/money 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -120,6 +120,20 @@ shape is still additive and this is still a minor version.
   or an empty name is `X_CURRENCY_INVALID`; a second declaration of one code is
   `X_CURRENCY_REDEFINED`, and an **identical** one is a no-op so a twice-imported module is not a
   crash. A shipped ISO row cannot be redefined at all.
+- **A shipped row is frozen, and `CurrencyInfo`'s three fields are `readonly`.** `currencyInfo()`
+  hands the row itself out by reference, and `exponent` decides what every stored `minor` in that
+  currency counts — one `currencyInfo('USD').exponent = 3` silently rescales every USD amount in
+  the process by a power of ten, through the one door `registerCurrency` already refuses
+  (`X_CURRENCY_REDEFINED`). The compiler is the first guard, `Object.freeze` on the array AND on
+  every row the second, for the caller that has no types. Both halves: a frozen array of writable
+  rows guards the list and leaves every value in it open.
+- **A `fix:` naming `fromDecimal` must name a call that RUNS.** `moneyNotInteger` emitted
+  `fromDecimal('<minor>', '<ccy>')` for every arrival: it threw this same code straight back for
+  anything past the currency's own digits, read `fromDecimal('1e+21', …)` for a magnitude
+  `DECIMAL` refuses, and read `fromDecimal('0', …)` for `NaN`, which runs and invents an amount.
+  Three arrivals, three instructions — a rounding call for a fractional minor, `{ scale: d }` or
+  `{ rounding: 'half-up' }` when the value is really a major-unit amount, and NO call at all where
+  none could work. `errors.test.ts` executes every call a `X_MONEY_NOT_INTEGER` fix line names.
 - **Two enumerations, two questions.** `CURRENCIES` is the constant this package ships;
   `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/money",
-  "version": "7.0.0",
+  "version": "9.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": "7.0.0",
-    "@ultimat3/schema": "7.0.0"
+    "@ultimat3/core": "9.0.0",
+    "@ultimat3/schema": "9.0.0"
   }
 }

package/src/currency.ts

@@ -11,68 +11,80 @@ import { currencyDeclarationInvalid, currencyRedefined, currencyUnknown } from '
 /** Uppercase ISO-4217 alphabetic code. */
 export type CurrencyCode = string;
 
+/**
+ * `readonly` on all three, because `currencyInfo()` hands the SHIPPED row out by reference and
+ * `exponent` decides what every stored `minor` in that currency counts: one
+ * `currencyInfo('USD').exponent = 3` silently rescales every USD amount in the process by a power
+ * of ten. The compiler is the first of the two guards; `Object.freeze` on every row below is the
+ * second, for the caller that has no types.
+ */
 export interface CurrencyInfo {
-  code: CurrencyCode;
+  readonly code: CurrencyCode;
   /** Number of decimal digits in the minor unit: USD 2, JPY 0, KWD 3. */
-  exponent: number;
-  name: string;
+  readonly exponent: number;
+  readonly name: string;
 }
 
-const TABLE: readonly CurrencyInfo[] = [
-  { code: 'AED', exponent: 2, name: 'UAE Dirham' },
-  { code: 'ARS', exponent: 2, name: 'Argentine Peso' },
-  { code: 'AUD', exponent: 2, name: 'Australian Dollar' },
-  { code: 'BGN', exponent: 2, name: 'Bulgarian Lev' },
-  { code: 'BHD', exponent: 3, name: 'Bahraini Dinar' },
-  { code: 'BRL', exponent: 2, name: 'Brazilian Real' },
-  { code: 'CAD', exponent: 2, name: 'Canadian Dollar' },
-  { code: 'CHF', exponent: 2, name: 'Swiss Franc' },
-  { code: 'CLP', exponent: 0, name: 'Chilean Peso' },
-  { code: 'CNY', exponent: 2, name: 'Yuan Renminbi' },
-  { code: 'COP', exponent: 2, name: 'Colombian Peso' },
-  { code: 'CZK', exponent: 2, name: 'Czech Koruna' },
-  { code: 'DKK', exponent: 2, name: 'Danish Krone' },
-  { code: 'EGP', exponent: 2, name: 'Egyptian Pound' },
-  { code: 'EUR', exponent: 2, name: 'Euro' },
-  { code: 'GBP', exponent: 2, name: 'Pound Sterling' },
-  { code: 'HKD', exponent: 2, name: 'Hong Kong Dollar' },
-  { code: 'HUF', exponent: 2, name: 'Forint' },
-  { code: 'IDR', exponent: 2, name: 'Rupiah' },
-  { code: 'ILS', exponent: 2, name: 'New Israeli Sheqel' },
-  { code: 'INR', exponent: 2, name: 'Indian Rupee' },
-  { code: 'ISK', exponent: 0, name: 'Iceland Krona' },
-  { code: 'JOD', exponent: 3, name: 'Jordanian Dinar' },
-  { code: 'JPY', exponent: 0, name: 'Yen' },
-  { code: 'KES', exponent: 2, name: 'Kenyan Shilling' },
-  { code: 'KRW', exponent: 0, name: 'Won' },
-  { code: 'KWD', exponent: 3, name: 'Kuwaiti Dinar' },
-  { code: 'MAD', exponent: 2, name: 'Moroccan Dirham' },
-  { code: 'MXN', exponent: 2, name: 'Mexican Peso' },
-  { code: 'MYR', exponent: 2, name: 'Malaysian Ringgit' },
-  { code: 'NGN', exponent: 2, name: 'Naira' },
-  { code: 'NOK', exponent: 2, name: 'Norwegian Krone' },
-  { code: 'NZD', exponent: 2, name: 'New Zealand Dollar' },
-  { code: 'OMR', exponent: 3, name: 'Rial Omani' },
-  { code: 'PEN', exponent: 2, name: 'Sol' },
-  { code: 'PHP', exponent: 2, name: 'Philippine Peso' },
-  { code: 'PKR', exponent: 2, name: 'Pakistan Rupee' },
-  { code: 'PLN', exponent: 2, name: 'Zloty' },
-  { code: 'RON', exponent: 2, name: 'Romanian Leu' },
-  { code: 'RSD', exponent: 2, name: 'Serbian Dinar' },
-  { code: 'SAR', exponent: 2, name: 'Saudi Riyal' },
-  { code: 'SEK', exponent: 2, name: 'Swedish Krona' },
-  { code: 'SGD', exponent: 2, name: 'Singapore Dollar' },
-  { code: 'THB', exponent: 2, name: 'Baht' },
-  { code: 'TND', exponent: 3, name: 'Tunisian Dinar' },
-  { code: 'TRY', exponent: 2, name: 'Turkish Lira' },
-  { code: 'TWD', exponent: 2, name: 'New Taiwan Dollar' },
-  { code: 'UAH', exponent: 2, name: 'Hryvnia' },
-  { code: 'USD', exponent: 2, name: 'US Dollar' },
-  { code: 'UYU', exponent: 2, name: 'Peso Uruguayo' },
-  { code: 'VND', exponent: 0, name: 'Dong' },
-  { code: 'XOF', exponent: 0, name: 'CFA Franc BCEAO' },
-  { code: 'ZAR', exponent: 2, name: 'Rand' },
-];
+const TABLE: readonly CurrencyInfo[] = Object.freeze(
+  [
+    { code: 'AED', exponent: 2, name: 'UAE Dirham' },
+    { code: 'ARS', exponent: 2, name: 'Argentine Peso' },
+    { code: 'AUD', exponent: 2, name: 'Australian Dollar' },
+    { code: 'BGN', exponent: 2, name: 'Bulgarian Lev' },
+    { code: 'BHD', exponent: 3, name: 'Bahraini Dinar' },
+    { code: 'BRL', exponent: 2, name: 'Brazilian Real' },
+    { code: 'CAD', exponent: 2, name: 'Canadian Dollar' },
+    { code: 'CHF', exponent: 2, name: 'Swiss Franc' },
+    { code: 'CLP', exponent: 0, name: 'Chilean Peso' },
+    { code: 'CNY', exponent: 2, name: 'Yuan Renminbi' },
+    { code: 'COP', exponent: 2, name: 'Colombian Peso' },
+    { code: 'CZK', exponent: 2, name: 'Czech Koruna' },
+    { code: 'DKK', exponent: 2, name: 'Danish Krone' },
+    { code: 'EGP', exponent: 2, name: 'Egyptian Pound' },
+    { code: 'EUR', exponent: 2, name: 'Euro' },
+    { code: 'GBP', exponent: 2, name: 'Pound Sterling' },
+    { code: 'HKD', exponent: 2, name: 'Hong Kong Dollar' },
+    { code: 'HUF', exponent: 2, name: 'Forint' },
+    { code: 'IDR', exponent: 2, name: 'Rupiah' },
+    { code: 'ILS', exponent: 2, name: 'New Israeli Sheqel' },
+    { code: 'INR', exponent: 2, name: 'Indian Rupee' },
+    { code: 'ISK', exponent: 0, name: 'Iceland Krona' },
+    { code: 'JOD', exponent: 3, name: 'Jordanian Dinar' },
+    { code: 'JPY', exponent: 0, name: 'Yen' },
+    { code: 'KES', exponent: 2, name: 'Kenyan Shilling' },
+    { code: 'KRW', exponent: 0, name: 'Won' },
+    { code: 'KWD', exponent: 3, name: 'Kuwaiti Dinar' },
+    { code: 'MAD', exponent: 2, name: 'Moroccan Dirham' },
+    { code: 'MXN', exponent: 2, name: 'Mexican Peso' },
+    { code: 'MYR', exponent: 2, name: 'Malaysian Ringgit' },
+    { code: 'NGN', exponent: 2, name: 'Naira' },
+    { code: 'NOK', exponent: 2, name: 'Norwegian Krone' },
+    { code: 'NZD', exponent: 2, name: 'New Zealand Dollar' },
+    { code: 'OMR', exponent: 3, name: 'Rial Omani' },
+    { code: 'PEN', exponent: 2, name: 'Sol' },
+    { code: 'PHP', exponent: 2, name: 'Philippine Peso' },
+    { code: 'PKR', exponent: 2, name: 'Pakistan Rupee' },
+    { code: 'PLN', exponent: 2, name: 'Zloty' },
+    { code: 'RON', exponent: 2, name: 'Romanian Leu' },
+    { code: 'RSD', exponent: 2, name: 'Serbian Dinar' },
+    { code: 'SAR', exponent: 2, name: 'Saudi Riyal' },
+    { code: 'SEK', exponent: 2, name: 'Swedish Krona' },
+    { code: 'SGD', exponent: 2, name: 'Singapore Dollar' },
+    { code: 'THB', exponent: 2, name: 'Baht' },
+    { code: 'TND', exponent: 3, name: 'Tunisian Dinar' },
+    { code: 'TRY', exponent: 2, name: 'Turkish Lira' },
+    { code: 'TWD', exponent: 2, name: 'New Taiwan Dollar' },
+    { code: 'UAH', exponent: 2, name: 'Hryvnia' },
+    { code: 'USD', exponent: 2, name: 'US Dollar' },
+    { code: 'UYU', exponent: 2, name: 'Peso Uruguayo' },
+    { code: 'VND', exponent: 0, name: 'Dong' },
+    { code: 'XOF', exponent: 0, name: 'CFA Franc BCEAO' },
+    { code: 'ZAR', exponent: 2, name: 'Rand' },
+    // Each ROW frozen too, not just the array: `CURRENCIES[0].exponent = 3` reaches the same
+    // object `currencyInfo` returns, and a frozen array holding writable rows guards the list
+    // while leaving every value in it open. `registerCurrency` already freezes what an app adds.
+  ].map((row) => Object.freeze(row)),
+);
 
 const BY_CODE: ReadonlyMap<string, CurrencyInfo> = new Map(
   TABLE.map((info) => [info.code, info] as const),

package/src/errors.ts

@@ -73,14 +73,51 @@ function codeLiteral(currency: string): string {
   return `'${codeExample(currency)}'`;
 }
 
+/** A number whose `String()` is source a decimal parser accepts — never `1e+21`, `1e-7` or `NaN`. */
+const PLAIN_DECIMAL = /^-?\d+(?:\.\d+)?$/;
+
 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}', ${codeLiteral(currency)}) or round explicitly with multiply(m, factor, 'half-up')`,
+    fix: notIntegerFix(minor, currency),
   });
 }
 
+/**
+ * Three arrivals reach `money()` with an unusable `minor`, and each needs its own instruction.
+ * One line answered all three — `fromDecimal('<minor>', '<ccy>')` — and it raised THIS code back
+ * at the reader for every value past the currency's own digits, which is the anti-pattern
+ * `currencyDeclarationInvalid` below already names; for `1e21` it read `fromDecimal('1e+21', …)`,
+ * a spelling `fromDecimal`'s own `DECIMAL` refuses outright; and for `NaN` it read
+ * `fromDecimal('0', …)`, which runs and invents an amount nobody wrote.
+ */
+function notIntegerFix(minor: number, currency: string): string {
+  if (!Number.isFinite(minor)) {
+    return 'no rounding recovers a non-finite amount — trace it back to the division or float multiply upstream, then build the value from a decimal string';
+  }
+  // `Math.round` is offered only when its RESULT is storable: past a safe integer it answers the
+  // same unusable magnitude, so the instruction would raise the error it is answering.
+  if (!Number.isSafeInteger(Math.round(minor))) {
+    return `${String(minor)} is more minor units than a safe integer holds — split the amount, or carry it as two ${codeExample(currency)} values`;
+  }
+  const code = codeLiteral(currency);
+  // Safe to interpolate un-escaped, and only here: `PLAIN_DECIMAL` has just proved the spelling is
+  // digits, one dot and one leading `-`, so it closes no literal `renderFixLiteral` would escape.
+  const spelling = String(minor);
+  const rounded = `money(Math.round(${spelling}), ${code})`;
+  if (!PLAIN_DECIMAL.test(spelling)) {
+    return `${rounded} — the value counts minor units, and that is the whole one nearest it`;
+  }
+  const digits = countFractionDigits(spelling);
+  // `{ scale: d }` on a value with exactly `d` fraction digits can never be too precise for
+  // itself, whatever the currency's exponent is — so this branch needs no exponent and loses no
+  // digit. Past MAX_MONEY_SCALE no scale holds them all and rounding is the only offer left, the
+  // same withdrawal `decimalTooPrecise` makes.
+  const asAmount = digits <= MAX_MONEY_SCALE ? `{ scale: ${digits} }` : "{ rounding: 'half-up' }";
+  return `${rounded} if ${spelling} counts minor units, or fromDecimal('${spelling}', ${code}, ${asAmount}) if it is a ${codeExample(currency)} amount — a fractional minor is usually an unrounded multiply, whose third argument names the mode`;
+}
+
 /**
  * A non-finite input to rounding is upstream float arithmetic that already lost the amount —
  * rounding it would invent a number, so it throws instead.