@ultimat3/money 30.9.0 → 31.0.0

package/CLAUDE.md

@@ -40,10 +40,17 @@ the wide shape and answer with the row type.
 | `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 |
+| `index.ts` | the app API only (v31): no code list, no internal assert, and no error factory except five — `currencyUnknown`, `decimalNotNumeric`, `decimalTooPrecise`, `moneyNotInteger`, `rateUnusable` — the refusals an app's own `RateProvider` or amount parser raises, so it throws money's cause rather than a copy (README, Conversion). Match an error on `MoneyError` + its `code` |
 
 ## Rules
 
 - Never a float in a stored or returned amount. `fromDecimal` takes a **string**.
+  Anything else — a JSON body's `12.99`, `null`, `undefined` — is `X_MONEY_NOT_DECIMAL`, as is a
+  string that is not a plain decimal (`'1,299.00'`, `'1e3'`); `parseAmount` refuses a non-string as
+  `X_MONEY_INPUT_INVALID`. Never a bare `TypeError` from `.trim()`, which a route answered as a 500.
+  The refused input reaches the `cause:` through `renderCauseValue` only: bounded, one line.
+  `X_MONEY_NOT_INTEGER` stays for what it names — a fractional minor, excess precision, an inexact
+  narrowing — and stopped answering parse failures in 31.0.
 - 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.
@@ -168,6 +175,6 @@ the wide shape and answer with the row type.
 ## Commands
 
 ```
-bun test packages/money
+bun test ./packages/money/
 bun run --filter @ultimat3/money typecheck
 ```

package/README.md

@@ -136,6 +136,12 @@ already carries its own precision. `convertWith` on a same-currency pair stamps
 injected `Clock` (`{ clock }`, default `systemClock`) or from an explicit `{ at }`, never from
 the epoch: `ExchangeRate.at` is the audit trail.
 
+| Export | Does |
+|---|---|
+| `convert(amount, to, rate, { rounding? })` | exact conversion with the rate given; a rate for another pair is `X_RATE_MISSING` |
+| `convertWith(provider, amount, to, { at?, clock?, rounding? })` | asks a `RateProvider`, then `convert`s; a pair it does not answer is `X_RATE_MISSING`, never parity |
+| `rateUnusable(from, to, field)` | the `X_RATE_MISSING` a rate earns when its `rate`, `at` or `ratio` cannot be used — the cause names the field |
+
 ## Errors
 
 | Code | When |
@@ -145,7 +151,8 @@ the epoch: `ExchangeRate.at` is the audit trail.
 | `X_CURRENCY_UNKNOWN` | a code neither shipped nor registered by this process — `currencyCodes()` is the list |
 | `X_CURRENCY_MISMATCH` | arithmetic across two currencies |
 | `X_ALLOCATION_INVALID` | bad part count, empty/negative/all-zero ratios, percentages ≠ 100 |
-| `X_RATE_MISSING` | no rate for the pair — never assumes parity |
+| `X_MONEY_NOT_DECIMAL` | `fromDecimal` handed a non-string or a string that is not a plain decimal |
+| `X_RATE_MISSING` | no rate for the pair — never assumes parity — or one whose `rate`, `at` or `ratio` is unusable (`rateUnusable`) |
 
 ### Error classes
 
@@ -154,7 +161,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
-| `MoneyError` | any `MoneyErrorCode` — `MONEY_ERROR_CODES` | `src/errors.ts` |
+| `MoneyError` | any `MoneyErrorCode` — the codes in the table above | `src/errors.ts` |
 
 ## Why it exists
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/money",
-  "version": "30.9.0",
+  "version": "31.0.0",
   "description": "Integer minor units with an attached currency: arithmetic, allocation, rounding, Intl formatting",
   "keywords": [
     "ultimate",
@@ -44,7 +44,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.9.0",
-    "@ultimat3/schema": "30.9.0"
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/schema": "31.0.0"
   }
 }

package/src/allocate.ts

@@ -40,6 +40,10 @@ export function allocate(amount: Money, parts: number): Money[] {
  * `[1, 1, 1]` over 100 → 34, 33, 33. Weights need not sum to anything in particular.
  */
 export function allocateByRatios(amount: Money, ratios: readonly number[]): Money[] {
+  // `Money` is a type, not a check: a hand-built `{ minor: 12.5 }` reached `BigInt()` below and left
+  // as a bare `RangeError`. The constructor is the one place a value is judged.
+  fromMinor(amount.minor, amount.currency, amount.scale);
+  if (!Array.isArray(ratios)) throw allocationInvalid('ratios must be a list of numbers');
   if (ratios.length === 0) throw allocationInvalid('ratios must not be empty');
   const weights = weigh(ratios);
   let total = 0n;
@@ -104,6 +108,7 @@ function weigh(ratios: readonly number[]): bigint[] {
  * where a mis-typed percentage should be an error, not a silent re-normalization.
  */
 export function allocateByPercentages(amount: Money, percentages: readonly number[]): Money[] {
+  if (!Array.isArray(percentages)) throw allocationInvalid('percentages must be a list of numbers');
   const total = percentages.reduce((sum, percentage) => sum + percentage, 0);
   if (Math.abs(total - 100) > 1e-9) {
     throw allocationInvalid(`percentages must sum to 100, got ${String(total)}`);

package/src/convert.ts

@@ -6,7 +6,7 @@
 
 import { type Clock, systemClock } from '@ultimat3/core';
 import { assertCurrency, exponentOf } from './currency';
-import { rateMissing } from './errors';
+import { rateMissing, rateUnusable } from './errors';
 import { type Fraction, factorFraction } from './factor';
 import { fromMinor, type Money } from './money';
 import { DEFAULT_ROUNDING, type RoundingMode, roundRatio } from './rounding';
@@ -58,14 +58,21 @@ export function convert(
   options: ConvertOptions = {},
 ): ConvertedMoney {
   const target = assertCurrency(to);
+  // `Money` is a type, not a check: a hand-built `{ minor: 1.5 }` reached `BigInt()` below and left
+  // as a bare `RangeError`. The constructor is the one place a value is judged.
+  fromMinor(amount.minor, amount.currency, amount.scale);
   if (rate.from !== amount.currency || rate.to !== target) {
     throw rateMissing(amount.currency, target);
   }
   if (!Number.isFinite(rate.rate) || rate.rate <= 0) {
-    throw rateMissing(amount.currency, target);
+    throw rateUnusable(amount.currency, target, 'rate');
   }
-  if (rate.ratio !== undefined && (rate.ratio.numerator <= 0n || rate.ratio.denominator <= 0n)) {
-    throw rateMissing(amount.currency, target);
+  // `at` is the audit trail: an Invalid Date threw a bare `RangeError` out of `toISOString`.
+  if (!(rate.at instanceof Date) || Number.isNaN(rate.at.getTime())) {
+    throw rateUnusable(amount.currency, target, 'at');
+  }
+  if (rate.ratio !== undefined && !isPositiveFraction(rate.ratio)) {
+    throw rateUnusable(amount.currency, target, 'ratio');
   }
 
   // Exact, not a float product: `minor * rate * scale` shows the rounding mode a value IEEE-754
@@ -93,6 +100,17 @@ export function convert(
   };
 }
 
+/** Both terms positive BIGINTS — a provider's `{ numerator: 23 }` mixed a number into bigint maths. */
+function isPositiveFraction(ratio: Fraction): boolean {
+  const { numerator, denominator } = ratio as { numerator: unknown; denominator: unknown };
+  return (
+    typeof numerator === 'bigint' &&
+    typeof denominator === 'bigint' &&
+    numerator > 0n &&
+    denominator > 0n
+  );
+}
+
 /** Rate lookup. Implemented by the app — the framework ships no live provider. */
 export interface RateProvider {
   readonly name: string;

package/src/errors.ts

@@ -3,7 +3,12 @@
  * A money bug that throws is a bug you can fix; one that rounds is a bug you ship.
  */
 
-import { registerErrorCodes, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import {
+  registerErrorCodes,
+  renderCauseValue,
+  renderFixLiteral,
+  UltimateError,
+} from '@ultimat3/core';
 import { isCurrencyCode, MAX_MONEY_SCALE } from '@ultimat3/schema';
 
 export const MONEY_ERROR_CODES = [
@@ -16,6 +21,7 @@ export const MONEY_ERROR_CODES = [
   'X_RATE_MISSING',
   'X_MONEY_SCALE_INVALID',
   'X_MONEY_INPUT_INVALID',
+  'X_MONEY_NOT_DECIMAL',
 ] as const;
 
 export type MoneyErrorCode = (typeof MONEY_ERROR_CODES)[number];
@@ -30,6 +36,7 @@ export const MONEY_ERROR_TITLES: Readonly<Record<MoneyErrorCode, string>> = {
   X_RATE_MISSING: 'no FX rate for the pair',
   X_MONEY_SCALE_INVALID: 'a Money.scale that is not a usable decimal exponent',
   X_MONEY_INPUT_INVALID: 'a typed amount could not be read in this locale',
+  X_MONEY_NOT_DECIMAL: 'a fromDecimal input that is not a plain decimal string',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -242,10 +249,20 @@ export function rescaleNotExact(
   });
 }
 
-export function decimalNotNumeric(value: string, currency: string): MoneyError {
+/**
+ * A `fromDecimal` input that is not a plain decimal string: a parse failure, so its own code — the
+ * value never reached the point where "a fractional minor" could describe it. `unknown` because a
+ * JSON body hands over a number as readily as a string, and the input is rendered bounded and on
+ * one line: it is caller text of any length.
+ */
+export function decimalNotNumeric(value: unknown, currency: string): MoneyError {
+  const shown = renderCauseValue(value);
   return new MoneyError({
-    code: 'X_MONEY_NOT_INTEGER',
-    cause: `"${value}" is not a decimal amount — no grouping separators, no exponent notation`,
+    code: 'X_MONEY_NOT_DECIMAL',
+    cause:
+      typeof value === 'string'
+        ? `${shown} is not a decimal amount — no grouping separators, no exponent notation`
+        : `${shown} is not a string — fromDecimal reads a decimal string, never a ${value === null ? 'null' : typeof value}`,
     fix: `pass a plain decimal string: fromDecimal('12.99', ${codeLiteral(currency)})`,
   });
 }
@@ -321,6 +338,19 @@ export function allocationInvalid(cause: string): MoneyError {
   });
 }
 
+/**
+ * A rate for the pair that cannot be used: a non-positive or non-finite `rate`, an `at` that is not
+ * a valid `Date`, a `ratio` whose terms are not positive bigints. No usable rate is a missing rate —
+ * the same code — but the cause names the field, so the provider's bug is findable.
+ */
+export function rateUnusable(from: string, to: string, field: string): MoneyError {
+  return new MoneyError({
+    code: 'X_RATE_MISSING',
+    cause: `the ${from}→${to} rate cannot be used: its \`${field}\` is not valid`,
+    fix: `convert(amount, ${codeLiteral(to)}, { from: ${codeLiteral(from)}, to: ${codeLiteral(to)}, rate: 0.92, at: new Date('2026-03-14T00:00:00Z') })   # a finite positive rate, a valid Date, and a ratio of positive bigints if any`,
+  });
+}
+
 export function rateMissing(from: string, to: string): MoneyError {
   return new MoneyError({
     code: 'X_RATE_MISSING',

package/src/index.ts

@@ -4,7 +4,6 @@ export {
   allocate,
   allocateByPercentages,
   allocateByRatios,
-  assertAllocationSums,
   MAX_ALLOCATION_PARTS,
 } from './allocate';
 export {
@@ -29,6 +28,7 @@ export {
   type ConvertedMoney,
   type ConvertOptions,
   convert,
+  convertWith,
   type ExchangeRate,
   fixedRateProvider,
   type RateProvider,
@@ -46,28 +46,17 @@ export {
   scaleOf,
 } from './currency';
 export {
-  allocationInvalid,
-  currencyDeclarationInvalid,
-  currencyMismatch,
-  currencyRedefined,
-  currencyRequired,
   currencyUnknown,
   decimalNotNumeric,
   decimalTooPrecise,
-  MONEY_ERROR_CODES,
-  MONEY_ERROR_TITLES,
   MoneyError,
   type MoneyErrorCode,
   moneyNotInteger,
-  rateMissing,
-  rescaleNotExact,
-  scaleInvalid,
-  scaleNotWidening,
+  rateUnusable,
 } 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,
   formatMoney,
   formatMoneyDecimal,
@@ -96,4 +85,4 @@ export {
   roundToDigits,
   roundToInteger,
 } from './rounding';
-export { assertScale, commonScale, minorAt, moneyScale } from './scale';
+export { commonScale, minorAt, moneyScale } from './scale';

package/src/money.ts

@@ -69,6 +69,9 @@ export function fromDecimal(
   options: FromDecimalOptions = {},
 ): Money {
   const code = assertCurrency(currency);
+  // The signature says `string`; a JSON body does not read it. `12.99` arriving as a number was a
+  // bare TypeError from `.trim()` — a 500 for a caller mistake.
+  if (typeof value !== 'string') throw decimalNotNumeric(value, code);
   const match = DECIMAL.exec(value.trim());
   const integerPart = match?.[2];
   if (match === null || integerPart === undefined) {

package/src/parse-input.ts

@@ -59,12 +59,12 @@ function numeralsOf(tag: string): LocaleNumerals {
   };
 }
 
-const refused = (text: string, locale: string, currency: string, reason: string): MoneyError =>
+const refused = (text: unknown, locale: string, currency: string, reason: string): MoneyError =>
   new MoneyError({
     code: 'X_MONEY_INPUT_INVALID',
     cause: `the amount typed could not be read as ${currency} in ${locale}: ${reason}`,
     fix: `parseAmount(text, { currency: '${currency}', locale: '${locale}' })   # re-prompt the person for the amount; nothing was rounded or guessed`,
-    meta: { locale, currency, length: text.length },
+    meta: { locale, currency, length: typeof text === 'string' ? text.length : 0 },
   });
 
 /**
@@ -78,6 +78,9 @@ export function parseAmount(text: string, options: ParseAmountOptions): Money {
   const tag = assertLocale(options.locale);
   const code = assertCurrency(options.currency);
   const fail = (reason: string): MoneyError => refused(text, tag, code, reason);
+  // The signature says `string`; a JSON body does not read it, and `.trim()` on a number was a
+  // bare TypeError — a 500 for an amount the person can simply be asked for again.
+  if (typeof text !== 'string') throw fail(`${renderCauseValue(text)} is not text`);
   const numerals = numeralsOf(tag);
   const symbols = formatterOf(tag, code)
     .formatToParts(1)