@ducatjs/money 0.1.0 → 0.2.0

package/src/sql.ts

@@ -0,0 +1,178 @@
+// Conversions between Money and the values SQL drivers send and receive, shared by the ORM and
+// query-builder integrations (`/drizzle/*`, `/kysely`). Every reader is strict: a driver value that
+// may already have lost digits (an unsafe number, a float for a DECIMAL) is rejected rather than
+// trusted, and every writer refuses a value the column would change.
+import { currencyExponent } from './currency.js';
+import {
+  CurrencyMismatchError,
+  fromJSON,
+  fromMinor,
+  money as parseMoney,
+  toDecimal,
+  toMinor,
+  type Money,
+  type MoneyJSON,
+} from './money.js';
+
+const INTEGER_TEXT = /^-?\d+$/;
+// a BIGINT (SQLite INTEGER) column's range: MySQL outside strict mode clips anything beyond it
+const BIGINT_MIN = -(2n ** 63n);
+const BIGINT_MAX = 2n ** 63n - 1n;
+
+/** The declared size of a NUMERIC/DECIMAL column. */
+export interface DecimalColumnSize {
+  /** Total number of significant digits the column holds. */
+  readonly precision: number;
+  /** Digits after the decimal point. */
+  readonly scale: number;
+}
+
+/** NUMERIC(19,4): 15 integer digits and 4 decimals, enough for every ISO 4217 exponent. */
+export const DEFAULT_DECIMAL_SIZE: DecimalColumnSize = { precision: 19, scale: 4 };
+
+/** Throws unless the money is in the column's currency (when the column has a fixed currency). */
+export function checkCurrency(money: Money, currency: string | undefined): void {
+  if (currency !== undefined && money.currency !== currency) {
+    throw new CurrencyMismatchError(currency, money.currency);
+  }
+}
+
+/**
+ * Throws unless the money is at its currency's exponent. Columns store amounts at the currency's
+ * scale, so a value with sub-minor digits would have to be rounded, and the caller should choose how.
+ */
+export function checkIsoScale(money: Money): void {
+  const exponent = currencyExponent(money.currency);
+  if (money.scale !== exponent) {
+    throw new RangeError(
+      `${money} has scale ${money.scale}; round() it to ${exponent} decimals before storing it`,
+    );
+  }
+}
+
+/**
+ * Minor units for a BIGINT column, as a bigint. Throws beyond the column's range, ±9.2·10^18:
+ * MySQL outside strict mode would store the nearest limit instead.
+ */
+export function minorToDriver(money: Money, currency: string | undefined): bigint {
+  checkCurrency(money, currency);
+  checkIsoScale(money);
+  const minor = toMinor(money);
+
+  if (minor < BIGINT_MIN || minor > BIGINT_MAX) {
+    throw new RangeError(`${money} is ${minor} minor units, beyond the range of a BIGINT column`);
+  }
+  return minor;
+}
+
+/**
+ * Money from a BIGINT driver value. Accepts a bigint, a safe-integer number, or an integer string
+ * (node-postgres returns int8 as a string). A number beyond 2^53 has already lost digits, so it
+ * throws.
+ */
+export function minorFromDriver<C extends string>(value: unknown, currency: C): Money<C> {
+  if (typeof value === 'string') {
+    if (!INTEGER_TEXT.test(value)) {
+      throw new SyntaxError(`Expected an integer from a BIGINT column, got "${value}"`);
+    }
+    return fromMinor(BigInt(value), currency);
+  }
+  if (typeof value === 'number' || typeof value === 'bigint') {
+    return fromMinor(value, currency);
+  }
+  throw new TypeError(`Expected an integer from a BIGINT column, got ${typeof value}`);
+}
+
+/** Throws if a decimal column of this size would round amounts in this currency. */
+export function checkDecimalSize(currency: string, size: DecimalColumnSize): void {
+  const { precision, scale } = size;
+  const isValidSize =
+    Number.isInteger(precision) &&
+    Number.isInteger(scale) &&
+    precision >= 1 &&
+    scale >= 0 &&
+    scale <= precision;
+  if (!isValidSize) {
+    throw new RangeError(`NUMERIC(${precision},${scale}) is not a valid column size`);
+  }
+
+  const exponent = currencyExponent(currency);
+  if (size.scale < exponent) {
+    throw new RangeError(
+      `NUMERIC(${size.precision},${size.scale}) would round ${currency}, which has ${exponent} decimals`,
+    );
+  }
+}
+
+/**
+ * The exact decimal string for a NUMERIC/DECIMAL column. Throws if the column could not hold it
+ * unchanged: MySQL outside strict mode clamps an out-of-range value instead of failing.
+ */
+export function decimalToDriver(
+  money: Money,
+  currency: string | undefined,
+  size: DecimalColumnSize | undefined,
+): string {
+  checkCurrency(money, currency);
+  checkIsoScale(money);
+  const decimal = toDecimal(money);
+
+  if (size !== undefined) {
+    checkIntegerDigits(money, decimal, size);
+  }
+  return decimal;
+}
+
+/**
+ * Throws if the decimal (the money's `toDecimal`) has more integer digits than a column of this
+ * size holds: Postgres rejects it, and MySQL outside strict mode clamps it.
+ */
+export function checkIntegerDigits(money: Money, decimal: string, size: DecimalColumnSize): void {
+  const integerPart = decimal.replace('-', '').split('.')[0]!;
+  // "0.12" has no integer digits: NUMERIC(4,4) holds it
+  const integerDigits = integerPart === '0' ? 0 : integerPart.length;
+  if (integerDigits > size.precision - size.scale) {
+    throw new RangeError(
+      `${money} does not fit NUMERIC(${size.precision},${size.scale}), which holds ` +
+        `${size.precision - size.scale} integer digits`,
+    );
+  }
+}
+
+/**
+ * Money from a NUMERIC/DECIMAL driver value, which must be a string: a number has been through a
+ * float. Trailing zeros (`12.3400` from NUMERIC(19,4)) are fine; more decimals than the currency
+ * has, `NaN` and `Infinity` throw.
+ */
+export function decimalFromDriver<C extends string>(value: unknown, currency: C): Money<C> {
+  if (typeof value !== 'string') {
+    throw new TypeError(
+      `Expected a string from a DECIMAL column, got ${typeof value}; ` +
+        'configure the driver to return decimals as strings',
+    );
+  }
+  return parseMoney(value, currency);
+}
+
+/** `{"amount":"12.34","currency":"EUR"}` for a JSON, JSONB or TEXT column. */
+export function jsonToDriver(money: Money, currency: string | undefined): string {
+  checkCurrency(money, currency);
+  checkIsoScale(money);
+  return JSON.stringify(money);
+}
+
+/**
+ * Money from a JSON column: the parsed object (JSONB in node-postgres, JSON in mysql2) or the
+ * text (SQLite).
+ */
+export function jsonFromDriver<C extends string>(
+  value: unknown,
+  currency: C | undefined,
+): Money<C> {
+  if (typeof value !== 'string' && (typeof value !== 'object' || value === null)) {
+    throw new TypeError(`Expected JSON from a money column, got ${String(value)}`);
+  }
+  const parsed = fromJSON(value as MoneyJSON | string) as Money<C>;
+  checkCurrency(parsed, currency);
+  return parsed;
+}

package/src/tax.ts

@@ -1,6 +1,13 @@
 import { ratio, type Factor, type Ratio } from './decimal.js';
-import { add, multiplyByRatio, subtract, type Money } from './money.js';
-import { DEFAULT_ROUNDING, type RoundingMode } from './rounding.js';
+import {
+  add,
+  multiplyByRatio,
+  roundWithPolicy,
+  subtract,
+  type Money,
+  type RoundingInput,
+} from './money.js';
+import { DEFAULT_ROUNDING } from './rounding.js';
 
 const percentRatio = (percent: Factor): Ratio => {
   const asRatio = ratio(percent);
@@ -14,7 +21,7 @@ const percentRatio = (percent: Factor): Ratio => {
 export function percentage<C extends string>(
   money: Money<C>,
   percent: Factor,
-  rounding: RoundingMode = DEFAULT_ROUNDING,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
 ): Money<C> {
   return multiplyByRatio(money, percentRatio(percent), rounding);
 }
@@ -29,13 +36,25 @@ export interface TaxBreakdown<C extends string> {
 
 /**
  * Tax-exclusive: adds percent% tax to a net amount. addTax(EUR 10, '20', 'halfEven') -> net 10, tax
- * 2, gross 12.
+ * 2, gross 12. A rounding mode rounds the tax; a rounding policy rounds the gross (the amount
+ * charged) to its scale and increment. The other part is always the exact difference.
  */
 export function addTax<C extends string>(
   net: Money<C>,
   percent: Factor,
-  rounding: RoundingMode = DEFAULT_ROUNDING,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
 ): TaxBreakdown<C> {
+  // A rounding mode rounds the tax; a policy rounds the gross, the amount charged, so it lands on
+  // the policy's increment (CHF 0.05 for cash). Either way the other part is the exact difference.
+  if (typeof rounding === 'function') {
+    const percentAsRatio = ratio(percent);
+    const gross = roundWithPolicy(
+      net,
+      ratio(100n * percentAsRatio.den + percentAsRatio.num, 100n * percentAsRatio.den),
+      rounding,
+    );
+    return { net, tax: subtract(gross, net), gross };
+  }
   const tax = multiplyByRatio(net, percentRatio(percent), rounding);
   const gross = add(net, tax);
   return { net, tax, gross };
@@ -44,12 +63,13 @@ export function addTax<C extends string>(
 /**
  * Tax-inclusive: extracts percent% tax contained in a gross amount (VAT extraction).
  * net = gross / (1 + percent/100) rounded; tax = gross - net, so the parts always add up.
- * extractTax(EUR 12, '20', 'halfEven') -> net 10.00, tax 2.00.
+ * extractTax(EUR 12, '20', 'halfEven') -> net 10.00, tax 2.00. A rounding policy rounds the net; the
+ * tax is on the policy's increment too whenever the gross is.
  */
 export function extractTax<C extends string>(
   gross: Money<C>,
   percent: Factor,
-  rounding: RoundingMode = DEFAULT_ROUNDING,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
 ): TaxBreakdown<C> {
   const percentAsRatio = ratio(percent);
   // 1 / (1 + p/100) = 100 den / (100 den + num)
@@ -61,11 +81,22 @@ export function extractTax<C extends string>(
   return { net, tax: subtract(gross, net), gross };
 }
 
-/** Price after a percent% discount; the discount amount is rounded with `rounding`. */
+/**
+ * Price after a percent% discount. A rounding mode rounds the discount amount; a rounding policy
+ * rounds the discounted price itself, so the price lands on the policy's scale and increment.
+ */
 export function discount<C extends string>(
   price: Money<C>,
   percent: Factor,
-  rounding: RoundingMode = DEFAULT_ROUNDING,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
 ): Money<C> {
+  if (typeof rounding === 'function') {
+    const percentAsRatio = ratio(percent);
+    return roundWithPolicy(
+      price,
+      ratio(100n * percentAsRatio.den - percentAsRatio.num, 100n * percentAsRatio.den),
+      rounding,
+    );
+  }
   return subtract(price, multiplyByRatio(price, percentRatio(percent), rounding));
 }

package/src/testing/arbitraries.ts

@@ -0,0 +1,134 @@
+/**
+ * `@ducatjs/money/testing/arbitraries`: fast-check arbitraries for property tests. They cover what
+ * hand-written cases tend to miss: amounts beyond 2^53 (bigint minor units), currencies with
+ * unusual exponents (JPY 0, KWD 3, CLF 4) and scales above the currency's exponent. fast-check is
+ * an optional peer dependency, needed only for this entry.
+ */
+import fc from 'fast-check';
+import { currencyExponent, ISO_EXPONENTS } from '../currency.js';
+import { MAX_DECIMAL_SCALE } from '../decimal.js';
+import { fromMinor, money, type Money } from '../money.js';
+
+/** A mix of exponents: the common two-decimal currencies and every unusual one. */
+const DEFAULT_CURRENCIES = ['EUR', 'USD', 'GBP', 'JPY', 'KRW', 'KWD', 'BHD', 'TND', 'CLF'];
+
+/** Options for `arbCurrency`. */
+export interface ArbCurrencyOptions {
+  /** Only currencies with one of these exponents (default: the representative mix). */
+  readonly exponents?: readonly number[];
+  /** Draw from every ISO 4217 code instead of the representative mix. */
+  readonly all?: boolean;
+  /** More codes to draw from, such as ones registered with `defineCurrency`. */
+  readonly extra?: readonly string[];
+}
+
+/**
+ * Currency codes, by default a representative mix of exponents 0, 2, 3 and 4 (JPY, EUR, KWD,
+ * CLF...). `{ all: true }` draws from every ISO 4217 code, `extra` adds codes (custom ones from
+ * `defineCurrency`), and `exponents` narrows whichever pool that is.
+ */
+export function arbCurrency(options: ArbCurrencyOptions = {}): fc.Arbitrary<string> {
+  const base = options.all === true ? Object.keys(ISO_EXPONENTS) : DEFAULT_CURRENCIES;
+  const pool = [...base, ...(options.extra ?? [])];
+  const exponents = options.exponents;
+  const codes =
+    exponents === undefined
+      ? pool
+      : pool.filter((code) => exponents.includes(currencyExponent(code)));
+  if (codes.length === 0) {
+    throw new RangeError('No currency has the requested exponents');
+  }
+  return fc.constantFrom(...codes);
+}
+
+/** Options for `arbMoney`. */
+export interface ArbMoneyOptions<C extends string = string> {
+  /** The currency, or an arbitrary of currencies (default: `arbCurrency()`). */
+  readonly currency?: C | fc.Arbitrary<C>;
+  /** The smallest amount, in major units (default: none, down to -10^30 minor units). */
+  readonly min?: string | number | bigint;
+  /** The largest amount, in major units (default: none, up to 10^30 minor units). */
+  readonly max?: string | number | bigint;
+  /**
+   * The scale, or an arbitrary of scales. By default mostly the currency's exponent, sometimes up
+   * to three more decimals.
+   */
+  readonly scale?: number | fc.Arbitrary<number>;
+}
+
+const BIG = 10n ** 30n;
+const SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+
+/** Minor units weighted toward the interesting places: small, near 2^53, and far beyond it. */
+function arbMinor(min: bigint, max: bigint): fc.Arbitrary<bigint> {
+  const clamp = (low: bigint, high: bigint) =>
+    fc.bigInt({ min: low > min ? low : min, max: high < max ? high : max });
+  const parts: fc.Arbitrary<bigint>[] = [];
+  if (min <= 10_000n && max >= -10_000n) {
+    parts.push(clamp(-10_000n, 10_000n));
+  }
+  if (min <= SAFE && max >= -SAFE) {
+    parts.push(clamp(-SAFE, SAFE));
+  }
+  // within 1000 of ±2^53, where number and bigint meet
+  for (const edge of [SAFE, -SAFE]) {
+    if (min <= edge + 1000n && max >= edge - 1000n) {
+      parts.push(clamp(edge - 1000n, edge + 1000n));
+    }
+  }
+  parts.push(fc.bigInt({ min, max }));
+  return fc.oneof(...parts);
+}
+
+/**
+ * Money values for property tests: `arbMoney()`, `arbMoney({ currency: 'EUR', min: '0', max:
+ * '100' })`. With bounds, every value is within them; without, minor units reach ±10^30.
+ */
+export function arbMoney<C extends string = string>(
+  options: ArbMoneyOptions<C> = {},
+): fc.Arbitrary<Money<C>> {
+  const given = options.currency;
+  let currencies: fc.Arbitrary<C>;
+  if (given === undefined) {
+    currencies = arbCurrency() as fc.Arbitrary<C>;
+  } else if (typeof given === 'string') {
+    currencies = fc.constant(given);
+  } else {
+    currencies = given;
+  }
+
+  return currencies.chain((currency) => {
+    const exponent = currencyExponent(currency);
+    const scaleOption = options.scale;
+    let scales: fc.Arbitrary<number>;
+    if (typeof scaleOption === 'number') {
+      scales = fc.constant(scaleOption);
+    } else if (scaleOption === undefined) {
+      scales = fc.oneof(
+        { weight: 3, arbitrary: fc.constant(exponent) },
+        { weight: 1, arbitrary: fc.integer({ min: exponent + 1, max: exponent + 3 }) },
+      );
+    } else {
+      scales = scaleOption;
+    }
+
+    return scales.chain((scale) => {
+      if (!(Number.isInteger(scale) && scale >= 0 && scale <= MAX_DECIMAL_SCALE)) {
+        throw new RangeError(`Invalid scale ${scale}`);
+      }
+      // Bounds in minor units at this scale; a bound between two units rounds inward.
+      const min =
+        options.min === undefined
+          ? -BIG
+          : BigInt(money(options.min, currency, { scale, rounding: 'ceil' }).toMinor());
+      const max =
+        options.max === undefined
+          ? BIG
+          : BigInt(money(options.max, currency, { scale, rounding: 'floor' }).toMinor());
+      if (min > max) {
+        throw new RangeError(`No ${currency} amount at scale ${scale} between min and max`);
+      }
+      return arbMinor(min, max).map((minor) => fromMinor(minor, currency, scale));
+    });
+  });
+}

package/src/testing/index.ts

@@ -0,0 +1,247 @@
+/**
+ * `@ducatjs/money/testing`: makes Money pleasant to test with Vitest and Jest. It provides value
+ * equality for `toEqual`, readable snapshots and failure output (`12.34 EUR`), and money matchers.
+ * Call `installMoneyMatchers(expect)` in a setup file, or import `@ducatjs/money/testing/vitest`
+ * or `@ducatjs/money/testing/jest`, which do that for you. Nothing here changes production code.
+ */
+import { currencyExponent } from '../currency.js';
+import { parseDecimal } from '../decimal.js';
+import { compare, equals, isMoney, money, sum, zero, type Money } from '../money.js';
+
+/** An equality tester, as Vitest and Jest's `expect.addEqualityTesters` take them. */
+export type MoneyEqualityTester = (left: unknown, right: unknown) => boolean | undefined;
+
+/**
+ * Money compares by value in `toEqual`, `toStrictEqual` and nested structures: same currency and
+ * the same amount, whatever the scale (`1.0` and `1.00`) and whether the minor units are a number
+ * or a bigint. For anything other than two Money values it returns undefined, so the usual
+ * comparison applies.
+ */
+export const moneyEquality: MoneyEqualityTester = (left, right) => {
+  if (isMoney(left) && isMoney(right)) {
+    return equals(left, right);
+  }
+  // Anything else, including a Money from a second installed copy of the package (which isMoney
+  // does not recognise), is left to the runner's own field-by-field comparison.
+  return undefined;
+};
+
+/** A snapshot serializer that prints Money as `12.34 EUR` (unquoted, so it isn't a string). */
+export const moneySerializer = {
+  test: (value: unknown): boolean => isMoney(value),
+  serialize: (value: unknown): string => String(value as Money),
+};
+
+/** What the matchers receive as `this`, the part of Vitest's and Jest's matcher state used here. */
+export interface MoneyMatcherContext {
+  readonly isNot: boolean;
+}
+
+/** A matcher's result, as Vitest and Jest expect it. */
+export interface MoneyMatcherResult {
+  pass: boolean;
+  message: () => string;
+  actual?: unknown;
+  expected?: unknown;
+}
+
+/** The money matchers, typed for `declare module` augmentation of `Assertion` / `Matchers`. */
+export interface MoneyMatchers<R = unknown> {
+  /** The value is Money equal to `amount` in `currency`, at any scale: `toBeMoney('12.34', 'EUR')`. */
+  toBeMoney(amount: string | number | bigint, currency: string): R;
+  /** The value is Money in `currency`. */
+  toHaveCurrency(currency: string): R;
+  /** The value is Money greater than `other` (same currency). */
+  toBeGreaterThanMoney(other: Money): R;
+  /** The value is Money greater than or equal to `other` (same currency). */
+  toBeGreaterThanOrEqualMoney(other: Money): R;
+  /** The value is Money less than `other` (same currency). */
+  toBeLessThanMoney(other: Money): R;
+  /** The value is Money less than or equal to `other` (same currency). */
+  toBeLessThanOrEqualMoney(other: Money): R;
+  /** The value is a list of Money that sums exactly to `total`, as allocations must. */
+  toSumTo(total: Money): R;
+}
+
+/**
+ * Prints a received value for a failure message. JSON.stringify would throw on a bigint or a
+ * cycle, and a matcher must fail cleanly, not throw while explaining the failure.
+ */
+function show(value: unknown, seen: Set<unknown> = new Set()): string {
+  if (isMoney(value)) {
+    return String(value);
+  }
+  if (typeof value === 'bigint') {
+    return `${value}n`;
+  }
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (typeof value !== 'object' || value === null) {
+    return String(value);
+  }
+  if (seen.has(value)) {
+    return '[Circular]';
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => show(item, seen)).join(', ')}]`;
+  }
+  const fields = Object.entries(value).map(([key, field]) => `${key}: ${show(field, seen)}`);
+  return `{ ${fields.join(', ')} }`;
+}
+
+function result(
+  context: MoneyMatcherContext,
+  pass: boolean,
+  received: unknown,
+  expectation: string,
+  expected?: unknown,
+): MoneyMatcherResult {
+  return {
+    pass,
+    message: () => `expected ${show(received)} ${context.isNot ? 'not ' : ''}${expectation}`,
+    actual: received,
+    expected,
+  };
+}
+
+/**
+ * Comparing amounts in different currencies, or something that isn't Money, is a mistake in the
+ * test, so it throws instead of failing; otherwise `.not` would quietly pass on it.
+ */
+function requireComparable(matcher: string, received: unknown, other: unknown): void {
+  if (!isMoney(received) || !isMoney(other)) {
+    throw new TypeError(
+      `${matcher}: expected two Money values, got ${show(received)} and ${show(other)}`,
+    );
+  }
+  if (received.currency !== other.currency) {
+    throw new TypeError(`${matcher}: cannot compare ${received.currency} with ${other.currency}`);
+  }
+}
+
+/** Decimal places in an amount as `money()` takes it, so `toBeMoney` can keep every digit. */
+function decimalsOf(amount: string | number | bigint): number {
+  // parseDecimal understands exponent notation ('1.5e-7'), as money() does
+  return typeof amount === 'bigint' ? 0 : parseDecimal(String(amount)).scale;
+}
+
+function comparison(
+  name: string,
+  wording: string,
+  accepts: (order: -1 | 0 | 1) => boolean,
+): (this: MoneyMatcherContext, received: unknown, other: Money) => MoneyMatcherResult {
+  return function (this: MoneyMatcherContext, received: unknown, other: Money) {
+    requireComparable(name, received, other);
+    const pass = accepts(compare(received as Money, other));
+    return result(this, pass, received, `${wording} ${show(other)}`);
+  };
+}
+
+/** The matcher implementations, for `expect.extend`. */
+export const moneyMatchers = {
+  toBeMoney(
+    this: MoneyMatcherContext,
+    received: unknown,
+    amount: string | number | bigint,
+    currency: string,
+  ): MoneyMatcherResult {
+    const scale = Math.max(decimalsOf(amount), currencyExponent(currency));
+    const expected = money(amount, currency, { scale });
+    const pass = isMoney(received) && equals(received, expected);
+    return result(this, pass, received, `to be ${expected}`, expected);
+  },
+  toHaveCurrency(
+    this: MoneyMatcherContext,
+    received: unknown,
+    currency: string,
+  ): MoneyMatcherResult {
+    const pass = isMoney(received) && received.currency === currency;
+    return result(this, pass, received, `to have currency ${currency}`);
+  },
+  toBeGreaterThanMoney: comparison(
+    'toBeGreaterThanMoney',
+    'to be greater than',
+    (order) => order > 0,
+  ),
+  toBeGreaterThanOrEqualMoney: comparison(
+    'toBeGreaterThanOrEqualMoney',
+    'to be greater than or equal to',
+    (order) => order >= 0,
+  ),
+  toBeLessThanMoney: comparison('toBeLessThanMoney', 'to be less than', (order) => order < 0),
+  toBeLessThanOrEqualMoney: comparison(
+    'toBeLessThanOrEqualMoney',
+    'to be less than or equal to',
+    (order) => order <= 0,
+  ),
+  toSumTo(this: MoneyMatcherContext, received: unknown, total: Money): MoneyMatcherResult {
+    // Not a list of Money, or parts in another currency, is a mistake in the test: throw.
+    if (!Array.isArray(received) || !isMoney(total)) {
+      throw new TypeError(
+        `toSumTo: expected a list of Money and a Money total, got ${show(received)}`,
+      );
+    }
+    for (const part of received) {
+      requireComparable('toSumTo', part, total);
+    }
+    const partsSum = sum(received as Money[], total.currency);
+    const pass = equals(partsSum, total);
+    return {
+      pass,
+      message: () =>
+        `expected ${show(received)} ${this.isNot ? 'not ' : ''}to sum to ${show(total)}` +
+        (this.isNot ? '' : `; they sum to ${partsSum}`),
+      actual: partsSum,
+      expected: total,
+    };
+  },
+};
+
+/** The parts of Vitest's and Jest's `expect` that `installMoneyMatchers` uses. */
+export interface ExpectWithExtensions {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- each runner types these its own way
+  extend(matchers: any): void;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  addEqualityTesters?(testers: any[]): void;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  addSnapshotSerializer?(serializer: any): void;
+}
+
+const INSPECT = Symbol.for('nodejs.util.inspect.custom');
+
+/**
+ * Installs everything on a test runner's `expect`: the matchers, value equality and the snapshot
+ * serializer. It also gives Money a Node inspect hook, so `console.log(price)` prints
+ * `Money(12.34 EUR)`. Safe to call more than once. A runner that lacks `addEqualityTesters` or
+ * `addSnapshotSerializer` (Bun supports neither) gets the matchers and the inspect hook.
+ */
+export function installMoneyMatchers(expect: ExpectWithExtensions): void {
+  expect.extend(moneyMatchers);
+  // Optional runner features: Bun has no equality testers, and its addSnapshotSerializer throws
+  // "Not implemented". The matchers work without either.
+  try {
+    expect.addEqualityTesters?.([moneyEquality]);
+  } catch {
+    // not supported by this runner
+  }
+  try {
+    expect.addSnapshotSerializer?.(moneySerializer);
+  } catch {
+    // not supported by this runner
+  }
+
+  // The inspect hook is the one change to Money itself; only test setups call this function.
+  const prototype = Object.getPrototypeOf(zero('EUR')) as object;
+  if (!Object.hasOwn(prototype, INSPECT)) {
+    Object.defineProperty(prototype, INSPECT, {
+      value(this: Money) {
+        return `Money(${String(this)})`;
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+}

package/src/testing/jest.ts

@@ -0,0 +1,18 @@
+/**
+ * `@ducatjs/money/testing/jest`: one import in a Jest setup file (`setupFilesAfterEnv`) installs
+ * the money matchers, value equality and the snapshot serializer on Jest's global `expect`. It
+ * needs no Jest package of its own. For the types, add `MoneyMatchers` to Jest's `Matchers` in a
+ * declaration file (see the README): augmenting Jest's global namespace from here would clash
+ * with Vitest's types in projects that have both.
+ */
+import { installMoneyMatchers, type ExpectWithExtensions } from './index.js';
+
+export * from './index.js';
+
+const globalExpect = (globalThis as { expect?: ExpectWithExtensions }).expect;
+if (globalExpect === undefined) {
+  throw new Error(
+    '@ducatjs/money/testing/jest needs Jest’s global expect; import it from a setup file, or call installMoneyMatchers(expect)',
+  );
+}
+installMoneyMatchers(globalExpect);

package/src/testing/vitest.ts

@@ -0,0 +1,18 @@
+/**
+ * `@ducatjs/money/testing/vitest`: one import in a Vitest setup file installs the money matchers,
+ * value equality and the snapshot serializer, and types the matchers on `expect`:
+ *
+ *     // vitest.config.ts: test: { setupFiles: ['./test/setup.ts'] }
+ *     import '@ducatjs/money/testing/vitest';
+ */
+import { expect } from 'vitest';
+import { installMoneyMatchers, type MoneyMatchers } from './index.js';
+
+export * from './index.js';
+
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentation
+  interface Matchers<T = any> extends MoneyMatchers<T> {}
+}
+
+installMoneyMatchers(expect);