@ultimat3/money 21.0.0 → 22.0.0

package/README.md

@@ -137,6 +137,15 @@ the epoch: `ExchangeRate.at` is the audit trail.
 | `X_ALLOCATION_INVALID` | bad part count, empty/negative/all-zero ratios, percentages ≠ 100 |
 | `X_RATE_MISSING` | no rate for the pair — never assumes parity |
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `MoneyError` | any `MoneyErrorCode` — `MONEY_ERROR_CODES` | `src/errors.ts` |
+
 ## Why it exists
 
 Every money bug in production is one of three things: a float, a missing currency, or a

package/package.json

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

package/src/format.ts

@@ -5,7 +5,7 @@
 
 import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { exponentOf } from './currency';
-import { type Money, toDecimalNumber } from './money';
+import { type Money, toDecimalString } from './money';
 import { moneyScale } from './scale';
 
 export interface FormatMoneyOptions {
@@ -56,7 +56,7 @@ export function formatMoneyParts(
   options: FormatMoneyOptions = {},
 ): Intl.NumberFormatPart[] {
   return formatterFor(amount.currency, locale, options, moneyScale(amount)).formatToParts(
-    toDecimalNumber(amount),
+    exactDecimal(amount),
   );
 }
 
@@ -87,9 +87,17 @@ export function formatMoneyDecimal(amount: Money, locale: string): string {
         maximumFractionDigits: digits,
         useGrouping: false,
       }),
-  ).format(toDecimalNumber(amount));
+  ).format(exactDecimal(amount));
 }
 
+/**
+ * The amount as the decimal STRING `Intl` accepts (Intl.NumberFormat v3), never a float: dividing
+ * `9007199254740991` minor units by `10 ** 6` in floating point lands on `…740992` before any
+ * formatter sees it, so the largest amount a `Money` can hold rendered a digit it does not have.
+ * The cast is the one `toDecimalString` earns: it only ever writes `-?\d+(\.\d+)?`.
+ */
+const exactDecimal = (amount: Money): `${number}` => toDecimalString(amount) as `${number}`;
+
 const cache = new Map<string, Intl.NumberFormat>();
 const decimalCache = new Map<string, Intl.NumberFormat>();
 

package/src/money.ts

@@ -112,8 +112,10 @@ export function toDecimalString(amount: Money): string {
 }
 
 /**
- * Major units as a float. **Format-time only** — the one place a division by the
- * currency scale is legitimate, because `Intl.NumberFormat` takes a number.
+ * Major units as a float — lossy past 2^53 / 10^scale, so never for arithmetic and no longer for
+ * formatting either: `format.ts` hands `Intl` the exact `toDecimalString`, since a float rendered
+ * `money(9007199254740991, 'USD', 6)` as `…740992`. Kept as public API for a chart axis or a sort
+ * key, where an approximation is the point.
  */
 export function toDecimalNumber(amount: Money): number {
   return amount.minor / 10 ** moneyScale(amount);