@ultimat3/money 1.2.0 → 3.0.0

package/src/money.ts

@@ -3,20 +3,45 @@
  * There is no float anywhere in this package, and no amount without a currency.
  */
 
-import { assertCurrency, type CurrencyCode, exponentOf, scaleOf } from './currency';
+import { isMoneyScale, type MoneyValue } from '@ultimat3/schema';
+import { assertCurrency, type CurrencyCode, exponentOf } from './currency';
 import { decimalNotNumeric, decimalTooPrecise, moneyNotInteger } from './errors';
-import { type RoundingMode, roundToInteger } from './rounding';
+import { type RoundingMode, roundRatio } from './rounding';
+import { assertScale, commonScale, minorAt, moneyScale } from './scale';
 
-/** `{ minor: 129900, currency: 'EUR' }` is €1,299.00. Treat instances as immutable. */
-export type Money = { minor: number; currency: string };
+/**
+ * `{ minor: 129900, currency: 'EUR' }` is €1,299.00. Instances are immutable, and now enforced
+ * rather than asked for: both fields are `readonly`.
+ *
+ * An **alias**, never a restatement. `@ultimat3/schema`'s `MoneyValue` is the framework's one
+ * declaration (tier 0, so every package may reach it) and `@ultimat3/entity`'s `MoneyValue` is
+ * the same alias — a second structural copy is what let `minor` drift to `bigint` in the entity
+ * layer, so a row it decoded satisfied neither `t.money` nor `JSON.stringify`.
+ */
+export type Money = MoneyValue;
 
 const DECIMAL = /^([+-])?(\d+)(?:\.(\d+))?$/;
 
-/** The only constructor. Validates the currency and rejects fractional minor units. */
-export function money(minor: number, currency: string): Money {
+/**
+ * The only constructor. Validates the currency and rejects fractional minor units.
+ *
+ * `scale` names how many decimal places `minor` counts when the currency's own are not enough:
+ * `money(2, 'USD', 6)` is $0.000002. Omitted — and canonically omitted again when it says nothing
+ * the currency does not already say — so a value at the natural scale serializes byte-for-byte as
+ * it always has, and there is exactly one encoding of it.
+ */
+export function money(minor: number, currency: string, scale?: number): Money {
   const code = assertCurrency(currency);
   if (!Number.isSafeInteger(minor)) throw moneyNotInteger(minor, code);
-  return { minor, currency: code };
+  // `-0` is one amount with two identities: `JSON.stringify` writes `0` while `Object.is` and any
+  // keyed `Map` see something else, so a ledger reconciles against a value its own wire format
+  // cannot reproduce. Normalised here because this is the one place canonical form is decided.
+  const value = minor === 0 ? 0 : minor;
+  if (scale === undefined) return { minor: value, currency: code };
+  assertScale(scale);
+  return scale === exponentOf(code)
+    ? { minor: value, currency: code }
+    : { minor: value, currency: code, scale };
 }
 
 export function zero(currency: string): Money {
@@ -24,8 +49,13 @@ export function zero(currency: string): Money {
 }
 
 export interface FromDecimalOptions {
-  /** Required to accept a value with more precision than the currency has. */
+  /** Required to accept a value with more precision than the target scale has. */
   rounding?: RoundingMode;
+  /**
+   * Decimal places to keep, when the currency's own are not enough:
+   * `fromDecimal('0.000002', 'USD', { scale: 6 })`. Omitted, the currency decides, as before.
+   */
+  scale?: number;
 }
 
 /**
@@ -45,7 +75,7 @@ export function fromDecimal(
     throw decimalNotNumeric(value, code);
   }
 
-  const exponent = exponentOf(code);
+  const exponent = options.scale === undefined ? exponentOf(code) : assertScale(options.scale);
   const negative = match[1] === '-';
   const fractionPart = match[3] ?? '';
 
@@ -56,18 +86,23 @@ export function fromDecimal(
   } else {
     const mode = options.rounding;
     if (mode === undefined) throw decimalTooPrecise(value, code, exponent);
-    const kept = Number(`${integerPart}${fractionPart.slice(0, exponent)}`);
-    const remainder = Number(`0.${fractionPart.slice(exponent)}`);
-    minor = roundToInteger(kept + remainder, mode);
+    // The exact fraction the digits spell, never a float: `Number('0.4999999999999999999')` is
+    // exactly 0.5, so the float path showed `half-up` a tie the written decimal does not have and
+    // billed 101 for an amount that owes 100. Same `roundRatio` multiply/divide/convert use.
+    const dropped = fractionPart.slice(exponent);
+    minor = roundRatio(
+      BigInt(`${integerPart}${fractionPart}`),
+      10n ** BigInt(dropped.length),
+      mode,
+    );
   }
 
-  if (!Number.isSafeInteger(minor)) throw moneyNotInteger(minor, code);
-  return { minor: negative ? -minor : minor, currency: code };
+  return money(negative ? -minor : minor, code, options.scale);
 }
 
-/** `1299 EUR` → `'12.99'`; `1200 JPY` → `'1200'`; `1234 KWD` → `'1.234'`. */
+/** `1299 EUR` → `'12.99'`; `1200 JPY` → `'1200'`; `2 USD @ scale 6` → `'0.000002'`. */
 export function toDecimalString(amount: Money): string {
-  const exponent = exponentOf(amount.currency);
+  const exponent = moneyScale(amount);
   const sign = amount.minor < 0 ? '-' : '';
   const digits = Math.abs(amount.minor)
     .toString()
@@ -81,23 +116,37 @@ export function toDecimalString(amount: Money): string {
  * currency scale is legitimate, because `Intl.NumberFormat` takes a number.
  */
 export function toDecimalNumber(amount: Money): number {
-  return amount.minor / scaleOf(amount.currency);
+  return amount.minor / 10 ** moneyScale(amount);
 }
 
 export function isMoney(value: unknown): value is Money {
   if (value === null || typeof value !== 'object') return false;
-  const candidate = value as { minor?: unknown; currency?: unknown };
-  return Number.isSafeInteger(candidate.minor) && typeof candidate.currency === 'string';
+  const candidate = value as { minor?: unknown; currency?: unknown; scale?: unknown };
+  if (!Number.isSafeInteger(candidate.minor) || typeof candidate.currency !== 'string')
+    return false;
+  return candidate.scale === undefined || isMoneyScale(candidate.scale);
 }
 
-/** Same currency, same minor units. */
+/**
+ * Same currency, same value. Same *value*, not the same encoding: 1299 EUR and 12,990,000 EUR at
+ * scale 6 are one amount written two ways, and a ledger that called them different would
+ * reconcile against itself.
+ */
 export function equals(left: Money, right: Money): boolean {
-  return left.currency === right.currency && left.minor === right.minor;
+  if (left.currency !== right.currency) return false;
+  const scale = commonScale(left, right);
+  return minorAt(left, scale) === minorAt(right, scale);
 }
 
-/** Stable serialization for logs, JSON columns and the manifest: `EUR 1299`. */
+/**
+ * Stable serialization for logs, JSON columns and the manifest: `EUR 1299`, and `USD 2e-6` for a
+ * value whose scale is not the currency's — unchanged for every value that carries none.
+ */
 export function formatMoneyDebug(amount: Money): string {
-  return `${amount.currency} ${amount.minor}`;
+  const scale = amount.scale;
+  return scale === undefined
+    ? `${amount.currency} ${amount.minor}`
+    : `${amount.currency} ${amount.minor}e-${scale}`;
 }
 
 export function currencyOf(amount: Money): CurrencyCode {

package/src/rescale.ts

@@ -0,0 +1,31 @@
+/**
+ * Moving a money value between decimal scales.
+ * Widening is exact and free. Narrowing throws away digits, so it happens only when the caller
+ * names the rounding mode — the same bar `fromDecimal` sets for excess precision.
+ */
+
+import { rescaleNotExact } from './errors';
+import { type Money, money } from './money';
+import { type RoundingMode, roundRatio } from './rounding';
+import { assertScale, minorAt, moneyScale, toMinor } from './scale';
+
+/**
+ * `rescale(money(80, 'USD'), 8)` → 80,000,000 hundred-millionths, the granularity a per-token
+ * price needs. `rescale(m, 2, 'half-up')` brings it back to cents, having named who pays for the
+ * digits that go.
+ */
+export function rescale(amount: Money, scale: number, mode?: RoundingMode): Money {
+  assertScale(scale);
+  const from = moneyScale(amount);
+  if (scale >= from) {
+    return money(toMinor(minorAt(amount, scale), scale, amount.currency), amount.currency, scale);
+  }
+
+  const divisor = 10n ** BigInt(from - scale);
+  const numerator = BigInt(amount.minor);
+  // An exact narrowing needs no mode: nothing is being decided, so nothing has to be declared.
+  if (mode === undefined && numerator % divisor !== 0n) {
+    throw rescaleNotExact(amount, from, scale);
+  }
+  return money(roundRatio(numerator, divisor, mode), amount.currency, scale);
+}

package/src/rounding.ts

@@ -3,6 +3,7 @@
  * whichever one `Math.round` happens to implement is not an answer.
  */
 
+import { invariant } from '@ultimat3/core';
 import { notRoundable } from './errors';
 
 export type RoundingMode =
@@ -29,19 +30,76 @@ export function roundToInteger(value: number, mode: RoundingMode = DEFAULT_ROUND
 
   switch (mode) {
     case 'down':
-      return sign * floor;
+      return signed(sign, floor);
     case 'up':
-      return sign * (fraction > 0 ? floor + 1 : floor);
+      return signed(sign, fraction > 0 ? floor + 1 : floor);
     case 'half-up':
-      return sign * (fraction >= 0.5 ? floor + 1 : floor);
+      return signed(sign, fraction >= 0.5 ? floor + 1 : floor);
     case 'half-even': {
-      if (fraction > 0.5) return sign * (floor + 1);
-      if (fraction < 0.5) return sign * floor;
-      return sign * (floor % 2 === 0 ? floor : floor + 1);
+      if (fraction > 0.5) return signed(sign, floor + 1);
+      if (fraction < 0.5) return signed(sign, floor);
+      return signed(sign, floor % 2 === 0 ? floor : floor + 1);
     }
   }
 }
 
+/**
+ * `sign * magnitude`, except that a magnitude of zero stays `0`. `-1 * 0` is `-0`, which
+ * `JSON.stringify` writes as `0` while `Object.is` and any keyed `Map` see a different value —
+ * so a refund rounding to nothing produced an amount its own wire format cannot reproduce.
+ */
+function signed(sign: number, magnitude: number): number {
+  return magnitude === 0 ? 0 : sign * magnitude;
+}
+
+/**
+ * Round the exact rational `numerator / denominator` with the same four modes.
+ *
+ * The float path above can only judge a value IEEE-754 has already moved: `100 * 1.005` is
+ * 100.49999999999999, so `half-up` answers 100 where the exact 100.5 owes 101 — a 0.5% fee on
+ * €1.00 charged as nothing. A scale therefore reaches a mode as a fraction, never as a product.
+ */
+export function roundRatio(
+  numerator: bigint,
+  denominator: bigint,
+  mode: RoundingMode = DEFAULT_ROUNDING,
+): number {
+  invariant(
+    denominator !== 0n,
+    'X_INVARIANT',
+    'cannot round a ratio whose denominator is zero',
+    'roundRatio(numerator, 1n, mode)   # a zero denominator names no value; divide(amount, 0) is refused before it reaches here, so this is a caller building the fraction itself',
+  );
+  // One sign, carried out front, so each mode sees a magnitude exactly as `roundToInteger` does.
+  const negative = numerator < 0n !== denominator < 0n;
+  const top = numerator < 0n ? -numerator : numerator;
+  const bottom = denominator < 0n ? -denominator : denominator;
+  const whole = top / bottom;
+  const remainder = top % bottom;
+  // `remainder / bottom` vs `1/2` without leaving the integers: compare `2 * remainder` to `bottom`.
+  const twice = remainder * 2n;
+
+  let rounded: bigint;
+  switch (mode) {
+    case 'down':
+      rounded = whole;
+      break;
+    case 'up':
+      rounded = remainder > 0n ? whole + 1n : whole;
+      break;
+    case 'half-up':
+      rounded = twice >= bottom ? whole + 1n : whole;
+      break;
+    case 'half-even':
+      if (twice > bottom) rounded = whole + 1n;
+      else if (twice < bottom) rounded = whole;
+      else rounded = whole % 2n === 0n ? whole : whole + 1n;
+      break;
+  }
+  // Past 2^53 the `Number` is already approximate, which `money()` refuses as X_MONEY_NOT_INTEGER.
+  return Number(negative ? -rounded : rounded);
+}
+
 /**
  * Round to `digits` decimal places, used when converting a decimal string whose
  * precision exceeds the currency's minor unit.

package/src/scale.ts

@@ -0,0 +1,73 @@
+/**
+ * What decimal place a money value's `minor` counts, and which scales are legal.
+ * A value naming none counts the currency's own minor unit — the shape every amount already had,
+ * which is why nothing that predates this file has to change to keep meaning what it meant.
+ */
+
+import { isMoneyScale, MAX_MONEY_SCALE } from '@ultimat3/schema';
+import { exponentOf } from './currency';
+import { scaleInvalid, scaleNotWidening, scaleOverflow } from './errors';
+import type { Money } from './money';
+
+export { MAX_MONEY_SCALE };
+
+/**
+ * The decimal exponent this value's `minor` counts in — its own, or the currency's.
+ *
+ * Not to be confused with `scaleOf(currency)`, which is the multiplier `10 ** exponentOf(currency)`.
+ * This one is a count of digits, like `exponentOf`.
+ */
+export function moneyScale(amount: Money): number {
+  return amount.scale ?? exponentOf(amount.currency);
+}
+
+/** A scale that names no decimal place is a data bug, not a formatting preference. */
+export function assertScale(scale: number): number {
+  if (!isMoneyScale(scale)) throw scaleInvalid(scale);
+  return scale;
+}
+
+/**
+ * `amount.minor` restated at `scale`, exactly, as a bigint.
+ *
+ * A bigint because widening is what a comparison does first, and a comparison must not throw:
+ * `MAX_SAFE_INTEGER` cents restated in micros is past 2^53, which `money()` rightly refuses to
+ * *store* and which says nothing about whether it is larger than the value beside it.
+ *
+ * Widening only. Narrowing drops digits, and which digits go is a decision with a mode attached —
+ * `rescale()` owns that, out loud.
+ */
+export function minorAt(amount: Money, scale: number): bigint {
+  assertScale(scale);
+  const from = moneyScale(amount);
+  if (scale < from) throw scaleNotWidening(from, scale);
+  return BigInt(amount.minor) * 10n ** BigInt(scale - from);
+}
+
+/** The finer of two scales: where two values have to meet before they can be one number. */
+export function commonScale(left: Money, right: Money): number {
+  return Math.max(moneyScale(left), moneyScale(right));
+}
+
+/**
+ * A widened bigint back to a storable `minor`, or a scale error naming the finest scale that
+ * would fit. The one place that conversion happens, because `Number(widened)` alone reached
+ * `money()` as a plain out-of-range amount — reported as a fractional minor nobody wrote, with a
+ * `fromDecimal` fix line that throws the same error again.
+ */
+export function toMinor(widened: bigint, scale: number, currency: string): number {
+  const minor = Number(widened);
+  if (Number.isSafeInteger(minor)) return minor;
+  throw scaleOverflow(scale, currency, finestFitting(widened, scale));
+}
+
+/** How coarse the scale has to get before the magnitude fits; `undefined` if it never does. */
+function finestFitting(widened: bigint, scale: number): number | undefined {
+  const limit = BigInt(Number.MAX_SAFE_INTEGER);
+  let magnitude = widened < 0n ? -widened : widened;
+  for (let fitted = scale; fitted >= 0; fitted -= 1) {
+    if (magnitude <= limit) return fitted;
+    magnitude /= 10n;
+  }
+  return undefined;
+}