@ducatjs/money 0.0.0 → 0.2.0

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);

package/src/valibot.ts

@@ -0,0 +1,87 @@
+/**
+ * `@ducatjs/money/valibot`: Valibot schemas for the JSON form of Money, `{ "amount": "12.34",
+ * "currency": "EUR" }`, for API boundaries. Valibot is an optional peer dependency: only this entry
+ * imports it.
+ */
+import * as valibot from 'valibot';
+import { isMoney, type Money, type MoneyJSON } from './money.js';
+import {
+  checkSchemaOptions,
+  readMoneyJSON,
+  type MoneyFor,
+  type MoneyIssue,
+  type MoneySchemaOptions,
+} from './schema.js';
+
+export type { MoneyFor, MoneySchemaOptions } from './schema.js';
+
+const jsonShape = valibot.object({ amount: valibot.string(), currency: valibot.string() });
+
+/** The schema type both functions return: the JSON shape, then a transformation. */
+export type MoneySchema<TOutput> = valibot.SchemaWithPipe<
+  readonly [typeof jsonShape, valibot.RawTransformAction<MoneyJSON, TOutput>]
+>;
+
+/** A Valibot issue path pointing at the field that is wrong. */
+function pathTo(json: MoneyJSON, issue: MoneyIssue): [valibot.ObjectPathItem] {
+  return [
+    {
+      type: 'object',
+      origin: 'value',
+      input: json as unknown as Record<string, unknown>,
+      key: issue.field,
+      value: json[issue.field],
+    },
+  ];
+}
+
+/**
+ * Parses `{ amount, currency }` into Money, accepting exactly what the Zod entry accepts (see its
+ * `moneySchema`): an exact decimal string with no more decimals than the scale and at most
+ * `maxDigits` digits, padded to the scale, and a listed or known currency. Problems are Valibot
+ * issues on `amount` or `currency`; other keys are dropped. Bad options throw when the schema is
+ * built. Valibot has no codecs, so encode with `money.toJSON()` (or `JSON.stringify`), which this
+ * schema reads back.
+ *
+ *     const Order = valibot.object({ total: moneySchema({ currency: 'EUR' }) })
+ *     v.parse(Order, { total: { amount: '12.34', currency: 'EUR' } }).total   // Money<'EUR'>
+ */
+export function moneySchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): MoneySchema<MoneyFor<C>> {
+  checkSchemaOptions(options);
+  return valibot.pipe(
+    jsonShape,
+    valibot.rawTransform<MoneyJSON, MoneyFor<C>>(({ dataset, addIssue, NEVER }) => {
+      const json = dataset.value;
+      const result = readMoneyJSON(json, options);
+      if (isMoney(result)) {
+        return result as Money as MoneyFor<C>;
+      }
+      addIssue({ message: result.message, path: pathTo(json, result) });
+      return NEVER;
+    }),
+  );
+}
+
+/**
+ * Like `moneySchema`, but the output stays the JSON object: it checks that the input would parse,
+ * for code that passes the JSON on rather than computing with it.
+ */
+export function moneyJSONSchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): MoneySchema<MoneyJSON<C>> {
+  checkSchemaOptions(options);
+  return valibot.pipe(
+    jsonShape,
+    valibot.rawTransform<MoneyJSON, MoneyJSON<C>>(({ dataset, addIssue, NEVER }) => {
+      const json = dataset.value;
+      const result = readMoneyJSON(json, options);
+      if (isMoney(result)) {
+        return json as MoneyJSON<C>;
+      }
+      addIssue({ message: result.message, path: pathTo(json, result) });
+      return NEVER;
+    }),
+  );
+}

package/src/zod.ts

@@ -0,0 +1,78 @@
+/**
+ * `@ducatjs/money/zod`: Zod schemas for the JSON form of Money, `{ "amount": "12.34", "currency":
+ * "EUR" }`, for API boundaries. Zod is an optional peer dependency: only this entry imports it.
+ */
+import { z } from 'zod';
+import { isMoney, type Money, type MoneyJSON } from './money.js';
+import {
+  checkSchemaOptions,
+  readMoneyJSON,
+  type MoneyFor,
+  type MoneySchemaOptions,
+} from './schema.js';
+
+export type { MoneyFor, MoneySchemaOptions } from './schema.js';
+
+const jsonShape = z.object({ amount: z.string(), currency: z.string() });
+
+/** The schema `moneySchema` returns: a Zod codec between the JSON form and Money. */
+export type MoneyCodec<C extends string> = z.ZodCodec<typeof jsonShape, z.ZodCustom<MoneyFor<C>>>;
+
+/**
+ * Parses `{ amount, currency }` into Money, and encodes Money back to that JSON form. It is a Zod
+ * codec, so `schema.parse(json)` (or `z.decode`) gives Money and `z.encode(schema, money)` gives
+ * `{ amount, currency }`, written at the amount's own scale.
+ *
+ * The amount must be an exact decimal string with no more decimals than the scale (the
+ * currency's exponent unless `scale` is given; `rounding` allows more), and at most `maxDigits`
+ * digits. The currency must be one of `currency`, or any known code. Shorter amounts are padded to
+ * the scale ("1.5" EUR gives 1.50 EUR). Problems are Zod issues on `amount` or `currency`; keys
+ * other than those two are dropped. Bad options throw when the schema is built.
+ *
+ *     const Order = z.object({ total: moneySchema({ currency: 'EUR' }) })
+ *     Order.parse({ total: { amount: '12.34', currency: 'EUR' } }).total   // Money<'EUR'>
+ */
+export function moneySchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): MoneyCodec<C> {
+  checkSchemaOptions(options);
+  return z.codec(
+    jsonShape,
+    z.custom<MoneyFor<C>>((value) => isMoney(value)),
+    {
+      decode: (json, payload) => {
+        const result = readMoneyJSON(json, options);
+        if (isMoney(result)) {
+          return result as Money as MoneyFor<C>;
+        }
+        payload.issues.push({
+          code: 'custom',
+          message: result.message,
+          input: json,
+          path: [result.field],
+        });
+        return z.NEVER;
+      },
+      encode: (value) => (value as Money).toJSON(),
+    },
+  );
+}
+
+/**
+ * Like `moneySchema`, but the output stays the JSON object (with only `amount` and `currency`): it
+ * checks that the input would parse, for code that passes the JSON on rather than computing with
+ * it.
+ */
+export function moneyJSONSchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): z.ZodType<MoneyJSON<C>, MoneyJSON> {
+  checkSchemaOptions(options);
+  return jsonShape.transform((json, context) => {
+    const result = readMoneyJSON(json, options);
+    if (isMoney(result)) {
+      return json as MoneyJSON<C>;
+    }
+    context.addIssue({ code: 'custom', message: result.message, path: [result.field] });
+    return z.NEVER;
+  });
+}