Value Objects

1const MINOR_UNITS = { EUR: 2, USD: 2, JPY: 0, KWD: 3 } as const
2type Currency = keyof typeof MINOR_UNITS
3 
4export class Money {
5  private constructor(readonly minor: bigint, readonly currency: Currency) {}
6 
7  static of(minor: bigint, currency: Currency): Money {
8    if (minor < 0n) throw new RangeError('negative amount')
9    return new Money(minor, currency)
10  }
11 
12  add(other: Money): Money {
13    if (other.currency !== this.currency) throw new CurrencyMismatch(this.currency, other.currency)
14    return new Money(this.minor + other.minor, this.currency)
15  }
16 
17  /** split across n lines losing nothing: the remainder goes to the first lines */
18  allocate(n: number): Money[] {
19    const base = this.minor / BigInt(n)
20    let rest = this.minor - base * BigInt(n)
21    return Array.from({ length: n }, () => {
22      const extra = rest > 0n ? 1n : 0n
23      rest -= extra
24      return new Money(base + extra, this.currency)
25    })
26  }
27}

The private constructor is what makes this work: Money.of is the only door, so there is no instance in the system that skipped the check. allocate exists because "split a total across lines" is a domain rule with a legal answer, and leaving it to whoever writes the division is how a cent goes missing per invoice for a year.

function charge(
  amount: number,        // cents? euros? which currency?
  currency: string,      // 'EUR' or 'eur' or 'Eur'?
  taxRate: number,       // 0.19 or 19?
  email: string,         // validated where?
): void

// all of these compile:
charge(45, 'EUR', 19, 'not-an-email')
charge(4500, 'eur', 0.19, ' spaces@example.com ')

function charge(
  amount: Money,
  taxRate: TaxRate,
  to: EmailAddress,
): void

// currency travels inside Money, so it cannot be mismatched
// TaxRate knows whether it is a fraction or a percentage
// EmailAddress cannot be constructed from 'not-an-email'
charge(Money.of(4500n, 'EUR'), TaxRate.percent(19), EmailAddress.parse(input))

The parameter count drops from four to three and, more importantly, the remaining three are mutually unswappable — the compiler rejects an argument order that the first version accepts silently. Validation happens once at parse instead of once per function that felt responsible, which is also why the second version has one place to change when the email rule changes (Parse, Do Not Validate).

caveat The scores say nothing about the thing that actually decides: whether values in your system get combined arithmetically or merely carried. A pipeline that reads a price and writes it unchanged gets almost nothing from Money; a billing engine that adds, splits, discounts and rounds it gets most of its correctness from exactly this type. The same table would score very differently for those two systems, which is why no table replaces looking at what your code does with the values.