@ultimat3/money 3.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/money",
-  "version": "3.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": "3.0.0",
-    "@ultimat3/schema": "3.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/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);
 }