@ducatjs/money 0.1.0 → 0.2.0

package/src/pg.ts

@@ -0,0 +1,410 @@
+/**
+ * `@ducatjs/money/pg`: node-postgres type parsers that keep NUMERIC and BIGINT exact, a Postgres
+ * composite type for Money with a `sum` aggregate, and a guard for NUMERIC(p, s) columns.
+ *
+ *     import pg from 'pg';
+ *     import { exactTypes } from '@ducatjs/money/pg';
+ *
+ *     const pool = new pg.Pool({ types: exactTypes(pg.types) });
+ *
+ * It imports nothing from pg at run time: pass `pg.types` in.
+ */
+import { currencyExponent } from './currency.js';
+import { money as parseMoney, toDecimal, type CurrencyInput, type Money } from './money.js';
+import { checkDecimalSize, checkIntegerDigits, type DecimalColumnSize } from './sql.js';
+
+export { DEFAULT_DECIMAL_SIZE, type DecimalColumnSize } from './sql.js';
+
+/** A text-format value parser, as node-postgres calls it. */
+export type TypeParser = (text: string) => unknown;
+
+/** The part of `pg.types` (or a client's `types` option) these parsers build on. */
+export interface TypeParserSource {
+  getTypeParser(oid: number, format?: 'text' | 'binary'): TypeParser;
+}
+
+/** The OIDs of a composite money type and its array type, from `moneyTypeOids`. */
+export interface MoneyTypeOids {
+  readonly oid: number;
+  readonly arrayOid: number;
+}
+
+/** Options for `exactTypes`. */
+export interface ExactTypesOptions {
+  /** Also parse this composite money type (and its array) into Money. */
+  readonly money?: MoneyTypeOids;
+  /**
+   * How BIGINT (and BIGINT[]) values come back: `'bigint'` (the default) or `'string'`, pg's own
+   * exact format. A bigint is what `fromMinor` takes, but it applies to every BIGINT on the client,
+   * `count(*)` and bigserial ids included, and `JSON.stringify` throws on it.
+   */
+  readonly int8?: 'bigint' | 'string';
+}
+
+const INT8_OID = 20;
+const NUMERIC_OID = 1700;
+const INT8_ARRAY_OID = 1016;
+const NUMERIC_ARRAY_OID = 1231;
+
+const INTEGER_TEXT = /^-?\d+$/;
+const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
+
+/**
+ * BIGINT text as a bigint. node-postgres returns it as a string by default, which is exact but not
+ * a number type the Money constructors accept.
+ */
+export function parseBigInt(text: string): bigint {
+  if (!INTEGER_TEXT.test(text)) {
+    throw new SyntaxError(`Expected BIGINT text, got "${text}"`);
+  }
+  return BigInt(text);
+}
+
+/** BIGINT text, checked and kept as the string. */
+function checkBigIntText(text: string): string {
+  parseBigInt(text);
+  return text;
+}
+
+/**
+ * NUMERIC text, checked and returned as the exact decimal string. Postgres NUMERIC can hold `NaN`
+ * and `±Infinity`, which are not amounts, so they throw.
+ */
+export function parseNumeric(text: string): string {
+  if (!NUMERIC_TEXT.test(text)) {
+    throw new SyntaxError(`Expected a finite NUMERIC, got "${text}"`);
+  }
+  return text;
+}
+
+/**
+ * Splits Postgres array text (`{1,2,NULL}`, `{{1,2},{3,4}}`, `{"(1.00,EUR)"}`) into nested arrays of
+ * element text, with `null` for NULL. Quoted elements are unescaped.
+ */
+export function parseArray(text: string): unknown[] {
+  let position = 0;
+
+  // an array may start with explicit bounds, `[1:2]={...}`
+  if (text.startsWith('[')) {
+    position = text.indexOf('=') + 1;
+  }
+
+  function parseLevel(): unknown[] {
+    if (text[position] !== '{') {
+      throw new SyntaxError(`Malformed array text "${text}"`);
+    }
+    position++;
+    const items: unknown[] = [];
+    if (text[position] === '}') {
+      position++;
+      return items;
+    }
+
+    for (;;) {
+      if (text[position] === '{') {
+        items.push(parseLevel());
+      } else if (text[position] === '"') {
+        position++;
+        let value = '';
+        while (text[position] !== '"') {
+          if (position >= text.length) {
+            throw new SyntaxError(`Unterminated quote in array text "${text}"`);
+          }
+          if (text[position] === '\\') {
+            position++;
+          }
+          value += text[position];
+          position++;
+        }
+        position++;
+        items.push(value);
+      } else {
+        const start = position;
+        while (position < text.length && text[position] !== ',' && text[position] !== '}') {
+          position++;
+        }
+        const value = text.slice(start, position);
+        items.push(value === 'NULL' ? null : value);
+      }
+
+      if (text[position] === ',') {
+        position++;
+        continue;
+      }
+      if (text[position] === '}') {
+        position++;
+        return items;
+      }
+      throw new SyntaxError(`Malformed array text "${text}"`);
+    }
+  }
+
+  const result = parseLevel();
+  if (position !== text.length) {
+    throw new SyntaxError(`Malformed array text "${text}"`);
+  }
+  return result;
+}
+
+function mapArray(items: unknown[], parseElement: (text: string) => unknown): unknown[] {
+  return items.map((item) => {
+    if (item === null) {
+      return null;
+    }
+    if (Array.isArray(item)) {
+      return mapArray(item, parseElement);
+    }
+    return parseElement(item as string);
+  });
+}
+
+/**
+ * Splits record text, `(12.34,EUR)` or `(12.34,"A\\B")`, into its fields, with `null` for an empty
+ * unquoted field. Quoted fields are unescaped: Postgres doubles `"` and `\` inside them on output,
+ * and accepts a backslash before any character on input.
+ */
+function parseRecord(text: string): (string | null)[] {
+  if (!text.startsWith('(') || !text.endsWith(')')) {
+    throw new SyntaxError(`Expected record text in parentheses, got "${text}"`);
+  }
+  const fields: (string | null)[] = [];
+  let position = 1;
+  const end = text.length - 1;
+
+  for (;;) {
+    let field = '';
+    let isQuotedOrNonEmpty = false;
+    while (position < end && text[position] !== ',') {
+      const character = text[position]!;
+      if (character === '"') {
+        isQuotedOrNonEmpty = true;
+        position++;
+        for (;;) {
+          if (position >= end) {
+            throw new SyntaxError(`Unbalanced quote in record text "${text}"`);
+          }
+          const quoted = text[position]!;
+          if (quoted === '\\') {
+            field += text[position + 1] ?? '';
+            position += 2;
+          } else if (quoted === '"' && text[position + 1] === '"') {
+            field += '"';
+            position += 2;
+          } else if (quoted === '"') {
+            position++;
+            break;
+          } else {
+            field += quoted;
+            position++;
+          }
+        }
+        continue;
+      }
+      if (character === '\\') {
+        field += text[position + 1] ?? '';
+        position += 2;
+      } else {
+        field += character;
+        position++;
+      }
+      isQuotedOrNonEmpty = true;
+    }
+    fields.push(isQuotedOrNonEmpty ? field : null);
+    if (position >= end) {
+      return fields;
+    }
+    position++;
+  }
+}
+
+/**
+ * Money from the text of the composite type, `(12.34,EUR)`. The amount keeps the scale it was
+ * stored with, and never less than the currency's exponent. NULL fields, `NaN`, `Infinity` and
+ * malformed text throw.
+ */
+export function parseMoneyComposite(text: string): Money {
+  const fields = parseRecord(text);
+  if (fields.length !== 2) {
+    throw new SyntaxError(`Expected (amount,currency) composite text, got "${text}"`);
+  }
+  const [amount, currency] = fields;
+  if (amount === null || amount === undefined || currency === null || currency === undefined) {
+    throw new TypeError(`A money composite needs both an amount and a currency, got "${text}"`);
+  }
+  parseNumeric(amount);
+
+  const fractionDigits = amount.includes('.') ? amount.length - amount.indexOf('.') - 1 : 0;
+  const scale = Math.max(fractionDigits, currencyExponent(currency));
+  return parseMoney(amount, currency, { scale });
+}
+
+/**
+ * The composite type's text for a query parameter: `(12.34,"EUR")`, at the Money's own scale. The
+ * currency is always quoted and escaped, so custom codes containing `\`, `"`, `,` or `)` survive.
+ * Cast it in SQL (`$1::ducat_money`) where Postgres can't infer the type.
+ */
+export function toMoneyComposite(money: Money): string {
+  const currency = money.currency.replace(/["\\]/g, (character) => `\\${character}`);
+  return `(${toDecimal(money)},"${currency}")`;
+}
+
+/**
+ * Type parsers for node-postgres that never turn an amount into a float: BIGINT as bigint, NUMERIC
+ * as an exact string (rejecting `NaN` and `Infinity`), their arrays the same way (pg's default
+ * parses NUMERIC arrays as floats), and optionally the composite money type as Money. Every other
+ * type uses `base`.
+ *
+ *     new pg.Pool({ types: exactTypes(pg.types, { money: await moneyTypeOids(client) }) })
+ */
+export function exactTypes(base: TypeParserSource, options?: ExactTypesOptions): TypeParserSource {
+  const moneyOids = options?.money;
+  const parseInt8 = options?.int8 === 'string' ? checkBigIntText : parseBigInt;
+
+  return {
+    getTypeParser(oid: number, format?: 'text' | 'binary'): TypeParser {
+      // the binary format is only used when a query asks for it; leave it to pg
+      if (format === 'binary') {
+        return base.getTypeParser(oid, format);
+      }
+      if (oid === INT8_OID) {
+        return parseInt8;
+      }
+      if (oid === NUMERIC_OID) {
+        return parseNumeric;
+      }
+      if (oid === INT8_ARRAY_OID) {
+        return (text) => mapArray(parseArray(text), parseInt8);
+      }
+      if (oid === NUMERIC_ARRAY_OID) {
+        return (text) => mapArray(parseArray(text), parseNumeric);
+      }
+      if (moneyOids !== undefined && oid === moneyOids.oid) {
+        return parseMoneyComposite;
+      }
+      if (moneyOids !== undefined && oid === moneyOids.arrayOid) {
+        return (text) => mapArray(parseArray(text), parseMoneyComposite);
+      }
+      return base.getTypeParser(oid, format);
+    },
+  };
+}
+
+/** The default name of the composite money type. */
+export const MONEY_TYPE_NAME = 'ducat_money';
+
+const IDENTIFIER = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?$/;
+// Postgres truncates longer names, which would make `name` and `name_add` collide with others
+const MAX_IDENTIFIER_LENGTH = 63;
+
+/**
+ * The DDL for a composite money type, `(amount numeric, currency text)`, and a `sum` aggregate over
+ * it that throws on mixed currencies, and on a value with a NULL amount or currency. The amount is
+ * an unconstrained NUMERIC, so it keeps every digit and its scale. A schema-qualified name puts the
+ * type, its add function and the aggregate in that schema.
+ *
+ * Run the statements once, in order, in a migration: they are not idempotent, and a second run
+ * fails with `duplicate_object`.
+ *
+ *     for (const statement of moneyTypeSql()) await client.query(statement);
+ *     SELECT sum(price) FROM items;   -- (37.50,EUR)
+ */
+export function moneyTypeSql(name: string = MONEY_TYPE_NAME): string[] {
+  if (!IDENTIFIER.test(name)) {
+    throw new RangeError(`"${name}" is not a plain lower-case SQL name (optionally schema.name)`);
+  }
+  const dot = name.indexOf('.');
+  const schemaPrefix = dot < 0 ? '' : name.slice(0, dot + 1);
+  const typeName = name.slice(dot + 1);
+  if (`${typeName}_add`.length > MAX_IDENTIFIER_LENGTH) {
+    throw new RangeError(`"${typeName}" is too long for a Postgres name with an "_add" suffix`);
+  }
+  const add = `${name}_add`;
+
+  return [
+    `CREATE TYPE ${name} AS (amount numeric, currency text)`,
+    // search_path FROM CURRENT: the cast below resolves the same way whatever the caller's path
+    `CREATE FUNCTION ${add}(total ${name}, item ${name}) RETURNS ${name}
+LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE SET search_path FROM CURRENT AS $$
+BEGIN
+  IF item IS NULL THEN
+    RETURN total;
+  END IF;
+  IF item.amount IS NULL OR item.currency IS NULL THEN
+    RAISE EXCEPTION 'a money value needs both an amount and a currency'
+      USING ERRCODE = 'null_value_not_allowed';
+  END IF;
+  IF total IS NULL THEN
+    RETURN item;
+  END IF;
+  IF total.currency IS DISTINCT FROM item.currency THEN
+    RAISE EXCEPTION 'cannot add % and % amounts', total.currency, item.currency
+      USING ERRCODE = 'data_exception';
+  END IF;
+  RETURN ROW(total.amount + item.amount, total.currency)::${name};
+END
+$$`,
+    `CREATE AGGREGATE ${schemaPrefix}sum(${name}) ` +
+      `(SFUNC = ${add}, STYPE = ${name}, COMBINEFUNC = ${add}, PARALLEL = SAFE)`,
+  ];
+}
+
+/** The part of a pg Client or Pool that `moneyTypeOids` uses. */
+export interface Queryable {
+  query(
+    sql: string,
+    values: unknown[],
+  ): Promise<{ rows: { oid: number | string; typarray: number | string }[] }>;
+}
+
+/**
+ * Looks up the OIDs of the composite money type, for `exactTypes`. Run it once at start-up on a
+ * client without the money parser. OIDs differ between databases, and change if the type is
+ * dropped and recreated; values of a type whose OID `exactTypes` wasn't given come back as pg's
+ * raw text. With a type per schema, look up and pass each one's OIDs.
+ */
+export async function moneyTypeOids(
+  client: Queryable,
+  name: string = MONEY_TYPE_NAME,
+): Promise<MoneyTypeOids> {
+  const result = await client.query(
+    'SELECT oid, typarray FROM pg_type WHERE oid = to_regtype($1)',
+    [name],
+  );
+  const row = result.rows[0];
+  if (row === undefined) {
+    throw new RangeError(`No type "${name}" in this database; run moneyTypeSql() first`);
+  }
+  return { oid: Number(row.oid), arrayOid: Number(row.typarray) };
+}
+
+/**
+ * The exact decimal string for a NUMERIC(precision, scale) column, or a throw if Postgres would
+ * change it: it rounds extra decimals silently on insert, and rejects too many integer digits.
+ * Unlike the column types, any scale up to the column's is accepted, and trailing zeros beyond it
+ * are dropped since they don't change the value.
+ */
+export function toNumeric<C extends CurrencyInput>(
+  money: Money<C>,
+  size: DecimalColumnSize,
+): string {
+  checkDecimalSize(money.currency, size);
+  const decimal = toDecimal(money);
+  const [integerPart, fraction = ''] = decimal.replace('-', '').split('.');
+
+  const significantFraction = fraction.replace(/0+$/, '');
+  if (significantFraction.length > size.scale) {
+    throw new RangeError(
+      `${money} has ${significantFraction.length} decimals; NUMERIC(${size.precision},${size.scale}) ` +
+        `would round it to ${size.scale}`,
+    );
+  }
+
+  checkIntegerDigits(money, decimal, size);
+
+  if (fraction.length <= size.scale) {
+    return decimal;
+  }
+  const sign = decimal.startsWith('-') ? '-' : '';
+  const kept = fraction.slice(0, size.scale);
+  return kept === '' ? `${sign}${integerPart}` : `${sign}${integerPart}.${kept}`;
+}

package/src/plugins/all.ts

@@ -12,6 +12,7 @@ export {
   toScale,
   compare,
   equals,
+  identical,
   lessThan,
   lessThanOrEqual,
   greaterThan,
@@ -23,18 +24,27 @@ export {
   min,
   max,
   clamp,
+  majorPart,
+  minorPart,
   toDecimal,
   toMinor,
   toMinorNumber,
 } from '../money.js';
+export { roundingPolicy, isoPolicy, assertScale, type RoundingPolicyOptions } from '../policy.js';
 export * from './allocate.js';
 export * from './tax.js';
 export * from './convert.js';
 export * from './exact.js';
 export * from '../ecb.js';
+export * from '../boc.js';
+export * from '../boe.js';
+export * from '../hmrc.js';
+export * from '../fed.js';
+export * from '../history.js';
 export * from '../stripe-fx.js';
 export * from '../adyen-fx.js';
 export * from './cash.js';
+export * from '../historic.js';
 export * from './format.js';
 export * from '../parse.js';
 export * from './stripe.js';

package/src/plugins/convert.ts

@@ -4,11 +4,10 @@
  */
 import { convert } from '../convert.js';
 import type { Factor } from '../decimal.js';
-import { extendMoney, type CurrencyInput, type Money } from '../money.js';
+import { extendMoney, type CurrencyInput, type Money, type RoundingInput } from '../money.js';
 import type { ProviderConvertOptions } from '../convert.js';
 import type { RateProvider } from '../provider.js';
 import type { ConvertOptions, Rate } from '../rate.js';
-import type { RoundingMode } from '../rounding.js';
 
 export * from '../convert.js';
 
@@ -17,14 +16,14 @@ declare module '../money.js' {
     /** Converts at a Rate, rounding once: `eur.convert(eurUsd, 'halfEven')`. */
     convert<To extends string>(
       rate: Rate<NoInfer<C>, To>,
-      rounding?: RoundingMode,
+      rounding?: RoundingInput,
       options?: ConvertOptions,
     ): Money<To>;
     /** Converts at an exact decimal-string rate: `eur.convert('USD', '1.0832', 'halfEven')`. */
     convert<To extends CurrencyInput>(
       to: To,
       rate: Factor,
-      rounding?: RoundingMode,
+      rounding?: RoundingInput,
       options?: ConvertOptions,
     ): Money<To>;
     /**
@@ -34,7 +33,7 @@ declare module '../money.js' {
     convert<To extends CurrencyInput>(
       to: To,
       provider: RateProvider,
-      rounding?: RoundingMode,
+      rounding?: RoundingInput,
       options?: ProviderConvertOptions,
     ): Money<To>;
   }

package/src/plugins/tax.ts

@@ -3,8 +3,7 @@
  * methods below.
  */
 import type { Factor } from '../decimal.js';
-import { extendMoney, type Money } from '../money.js';
-import type { RoundingMode } from '../rounding.js';
+import { extendMoney, type Money, type RoundingInput } from '../money.js';
 import { addTax, discount, extractTax, percentage, type TaxBreakdown } from '../tax.js';
 
 export * from '../tax.js';
@@ -12,28 +11,28 @@ export * from '../tax.js';
 declare module '../money.js' {
   interface Money<C extends string> {
     /** `percent`% of this, e.g. `price.percentage(15, 'halfEven')` */
-    percentage(percent: Factor, rounding?: RoundingMode): Money<C>;
+    percentage(percent: Factor, rounding?: RoundingInput): Money<C>;
     /** this minus `percent`% */
-    discount(percent: Factor, rounding?: RoundingMode): Money<C>;
+    discount(percent: Factor, rounding?: RoundingInput): Money<C>;
     /** Treats this as net: `{ net, tax, gross }`, net + tax = gross exactly. */
-    addTax(percent: Factor, rounding?: RoundingMode): TaxBreakdown<C>;
+    addTax(percent: Factor, rounding?: RoundingInput): TaxBreakdown<C>;
     /** Treats this as gross: `{ net, tax, gross }`, net + tax = gross exactly. */
-    extractTax(percent: Factor, rounding?: RoundingMode): TaxBreakdown<C>;
+    extractTax(percent: Factor, rounding?: RoundingInput): TaxBreakdown<C>;
   }
 }
 
 extendMoney(
   {
-    percentage(this: Money, percent: Factor, rounding?: RoundingMode) {
+    percentage(this: Money, percent: Factor, rounding?: RoundingInput) {
       return percentage(this, percent, rounding);
     },
-    discount(this: Money, percent: Factor, rounding?: RoundingMode) {
+    discount(this: Money, percent: Factor, rounding?: RoundingInput) {
       return discount(this, percent, rounding);
     },
-    addTax(this: Money, percent: Factor, rounding?: RoundingMode) {
+    addTax(this: Money, percent: Factor, rounding?: RoundingInput) {
       return addTax(this, percent, rounding);
     },
-    extractTax(this: Money, percent: Factor, rounding?: RoundingMode) {
+    extractTax(this: Money, percent: Factor, rounding?: RoundingInput) {
       return extractTax(this, percent, rounding);
     },
   },

package/src/policy.ts

@@ -0,0 +1,124 @@
+/**
+ * `@ducatjs/money/policy`: rounding policies, reusable values for a scale, an increment and a
+ * rounding mode ("CHF cash", "4 decimals, half even"), accepted wherever a rounding mode is. The
+ * core only hands the work to the policy, so none of this code is in a bundle that never imports
+ * this entry (or `cashPolicy` from `@ducatjs/money/cash`).
+ */
+import { currencyExponent, isCurrency } from './currency.js';
+import { MAX_DECIMAL_SCALE, type Ratio } from './decimal.js';
+import {
+  CurrencyMismatchError,
+  multiply,
+  multiplyByRatio,
+  ratio,
+  ROUND_PRODUCT,
+  type Money,
+  type RoundingPolicy,
+} from './money.js';
+import { DEFAULT_ROUNDING, Rounding, type RoundingMode } from './rounding.js';
+
+export type { RoundingInput, RoundingPolicy } from './money.js';
+
+/** Options for `roundingPolicy`. Every field is optional. */
+export interface RoundingPolicyOptions {
+  /** Decimal places of the result (default: the currency's ISO exponent). */
+  readonly scale?: number;
+  /** A positive safe integer count of 10^-scale units to round to (default 1). */
+  readonly increment?: number;
+  /** The rounding mode (default 'halfExpand'). */
+  readonly rounding?: RoundingMode;
+  /** Restrict the policy to one currency. */
+  readonly currency?: string;
+}
+
+const ONE = ratio(1);
+const MODES = new Set<unknown>(Object.values(Rounding));
+
+/**
+ * Builds a reusable rounding policy (see `RoundingPolicy`). The options are checked here, once, so
+ * applying the policy needs no checks.
+ *
+ *     const unitPrice = roundingPolicy({ scale: 4, rounding: 'halfEven' })
+ *     const fiveCents = roundingPolicy({ increment: 5 })   // 0.05 in a 2-decimal currency
+ */
+export function roundingPolicy(options: RoundingPolicyOptions = {}): RoundingPolicy {
+  const scale = options.scale;
+  const increment = options.increment ?? 1;
+  const rounding = options.rounding ?? DEFAULT_ROUNDING;
+  const currency = options.currency;
+
+  if (
+    scale !== undefined &&
+    !(Number.isInteger(scale) && scale >= 0 && scale <= MAX_DECIMAL_SCALE)
+  ) {
+    throw new RangeError(`Invalid scale ${scale}`);
+  }
+  if (!(Number.isSafeInteger(increment) && increment >= 1)) {
+    throw new RangeError(`Invalid increment ${increment}; it must be a positive integer`);
+  }
+  if (!MODES.has(rounding)) {
+    throw new RangeError(`Invalid rounding mode ${String(rounding)}`);
+  }
+  // A typo such as 'chf' would otherwise make a policy that rejects every amount.
+  if (currency !== undefined && !isCurrency(currency)) {
+    throw new RangeError(`Unknown currency ${currency}`);
+  }
+
+  const incrementAsBigint = BigInt(increment);
+
+  // money × factor rounded once to the policy: with an increment, count whole increments
+  // (money × factor / increment, rounded at the policy's scale) and multiply back, which is
+  // rounding to the nearest multiple of the increment. The count's ratio is left unreduced: the
+  // division rounds the same either way, and a gcd per call would cost more than it saves.
+  const roundProduct = <C extends string>(money: Money<C>, factor: Ratio): Money<C> => {
+    if (currency !== undefined && currency !== money.currency) {
+      throw new CurrencyMismatchError(currency, money.currency);
+    }
+    const resultScale = scale ?? currencyExponent(money.currency);
+    if (increment === 1) {
+      return multiplyByRatio(money, factor, rounding, resultScale);
+    }
+    const stepDenominator = factor.d * increment;
+    const perStep: Ratio = {
+      num: factor.num,
+      den: factor.den * incrementAsBigint,
+      n: factor.n,
+      // NaN (not a safe integer) sends multiplyByRatio down its bigint path
+      d: Number.isSafeInteger(stepDenominator) ? stepDenominator : NaN,
+    };
+    return multiply(multiplyByRatio(money, perStep, rounding, resultScale), increment);
+  };
+
+  const policy = <C extends string>(money: Money<C>): Money<C> => roundProduct(money, ONE);
+  return Object.freeze(
+    Object.assign(policy, { scale, increment, rounding, currency, [ROUND_PRODUCT]: roundProduct }),
+  );
+}
+
+/**
+ * Rounding to the currency's ISO exponent, half up: the policy most amounts should end with.
+ * `assertScale(m, isoPolicy)` checks that an amount is already there.
+ */
+export const isoPolicy: RoundingPolicy = /* @__PURE__ */ roundingPolicy();
+
+/**
+ * Throws a RangeError unless `money` is exactly what `policy` produces: at the policy's scale and a
+ * multiple of its increment (and in its currency, if it has one). Use it where an amount must
+ * already be rounded, such as before booking it or sending it to a processor.
+ */
+export function assertScale(money: Money, policy: RoundingPolicy): void {
+  if (policy.currency !== undefined && policy.currency !== money.currency) {
+    throw new CurrencyMismatchError(policy.currency, money.currency);
+  }
+  const scale = policy.scale ?? currencyExponent(money.currency);
+  if (money.scale !== scale) {
+    throw new RangeError(`${money} has scale ${money.scale}, expected ${scale}`);
+  }
+  const minor = money.minor;
+  const increment = policy.increment;
+  const isMultiple =
+    typeof minor === 'number' ? minor % increment === 0 : minor % BigInt(increment) === 0n;
+  if (!isMultiple) {
+    throw new RangeError(`${money} is not a multiple of ${increment} at scale ${scale}`);
+  }
+}