@ducatjs/money 0.0.0 → 0.2.0

package/src/boe.ts

@@ -0,0 +1,131 @@
+// `@ducatjs/money/convert/boe`: an offline parser for the Bank of England's daily spot exchange
+// rates against sterling. Parser only: see parseBankOfEnglandCsv on licensing.
+import { quotedTable } from './history.js';
+import type { RateTable } from './provider.js';
+import { addDayRate, csvRows, isCalendarDay, newestFirst, readRateCell } from './rate-text.js';
+
+// The Bank's daily spot series against sterling, by code (currency units per £1).
+const BOE_SERIES: Readonly<Record<string, string>> = {
+  XUDLADS: 'AUD',
+  XUDLZOS3: 'BGN',
+  XUDLCDS: 'CAD',
+  XUDLBK89: 'CNY',
+  XUDLBK25: 'CZK',
+  XUDLDKS: 'DKK',
+  XUDLERS: 'EUR',
+  XUDLHDS: 'HKD',
+  XUDLBK33: 'HUF',
+  XUDLBK97: 'INR',
+  XUDLBK78: 'ILS',
+  XUDLJYS: 'JPY',
+  XUDLBK83: 'MYR',
+  XUDLNDS: 'NZD',
+  XUDLNKS: 'NOK',
+  XUDLBK47: 'PLN',
+  XUDLZOS4: 'RON',
+  XUDLSRS: 'SAR',
+  XUDLSGS: 'SGD',
+  XUDLZRS: 'ZAR',
+  XUDLBK93: 'KRW',
+  XUDLSKS: 'SEK',
+  XUDLSFS: 'CHF',
+  XUDLTWS: 'TWD',
+  XUDLBK87: 'THB',
+  XUDLBK95: 'TRY',
+  XUDLUSS: 'USD',
+};
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+function notBoe(why: string): never {
+  throw new SyntaxError(`Not a Bank of England spot rates CSV file: ${why}`);
+}
+
+/** '22 Dec 2025' as an ISO date, or SyntaxError. */
+function isoDate(text: string): string {
+  const match = /^(\d\d) ([A-Z][a-z]{2}) (\d{4})$/.exec(text.trim());
+  const month = match === null ? 0 : MONTHS.indexOf(match[2]!) + 1;
+  const day = match === null ? '' : `${match[3]}-${String(month).padStart(2, '0')}-${match[1]}`;
+  if (month === 0 || !isCalendarDay(day)) {
+    notBoe(`bad date ${JSON.stringify(text)}`);
+  }
+  return day;
+}
+
+/** Options for parseBankOfEnglandCsv. */
+export interface BankOfEnglandOptions {
+  /**
+   * The decimals the Bank publishes, rebuilt because its CSV strips trailing zeros ('1.35' for
+   * 1.3500). Default 4, as its database shows every spot series.
+   */
+  readonly decimals?: number;
+}
+
+/**
+ * Parses the Bank of England database's CSV of daily spot rates against sterling (series XUDL…,
+ * downloaded with codes as column titles: `DATE,XUDLUSS,XUDLERS,…` and dates like `22 Dec 2025`)
+ * into one GBP-based table per day, newest first. Rates are currency units per £1, with `source:
+ * 'BoE'` and `type: 'spot'`. The CSV strips trailing zeros, so they are rebuilt to `decimals`
+ * (default 4). Holidays have no row; an empty cell (before a series starts, or after it ends, as
+ * for BGN) is a missing value. An unknown series code, a bad date, two different values for a day
+ * or any other unreadable cell throws SyntaxError. No `availableAt` is set: the Bank says only
+ * that daily rates are updated "no more than two working days after the date to which they
+ * relate".
+ *
+ * **Licensing: you must check the licence of every Bank of England series you load.** The database
+ * is under the Open Government Licence,
+ * but the Bank's legal page says "selected exchange rate data and series are excluded from this
+ * licence" and "reproduced by the Bank under licence from third parties", and its spot rates
+ * page says LSEG and Bloomberg BFIX may be sources, with LSEG content not to be redistributed
+ * without LSEG's consent. No series is named either way, so ducat ships no Bank of England data
+ * and no fetcher. Parse only files you have downloaded and are allowed to use, and get the Bank's
+ * (or LSEG's) permission before you republish any of it. The Bank also says these "are not
+ * official rates". For a licensed UK source, see HMRC's monthly rates
+ * (@ducatjs/money/convert/hmrc).
+ */
+export function parseBankOfEnglandCsv(csv: string, options?: BankOfEnglandOptions): RateTable[] {
+  const decimals = options?.decimals ?? 4;
+  const [header, ...rows] = csvRows(csv.charCodeAt(0) === 0xfeff ? csv.slice(1) : csv);
+  if (header === undefined || header[0]?.trim() !== 'DATE' || header.length < 2) {
+    notBoe('no DATE column');
+  }
+  const currencies = header.slice(1).map((code) => {
+    const currency = BOE_SERIES[code.trim()];
+    if (currency === undefined) {
+      notBoe(`unknown series ${code} (use the daily spot series against sterling, XUDL…)`);
+    }
+    return currency;
+  });
+  if (new Set(currencies).size !== currencies.length) {
+    notBoe('a series appears twice');
+  }
+
+  // A download always has a row per business day, so none at all is a cut-off file, not a range
+  // of holidays.
+  if (rows.length === 0) {
+    notBoe('no observations');
+  }
+  const days = new Map<string, Record<string, string | null>>();
+  for (const cells of rows) {
+    if (cells.length !== header.length) {
+      notBoe(`a row has ${cells.length} cells, the header ${header.length}`);
+    }
+    const day = isoDate(cells[0]!);
+    currencies.forEach((currency, i) => {
+      addDayRate(days, day, currency, readRateCell(cells[i + 1]!, `${currency} on ${day}`));
+    });
+  }
+
+  const tables: RateTable[] = [];
+  for (const [day, rates] of days) {
+    if (Object.values(rates).some((rate) => rate !== null)) {
+      tables.push(
+        quotedTable({ base: 'GBP', source: 'BoE', type: 'spot', asOf: day, decimals, rates }),
+      );
+    }
+  }
+  // A download only has rows for business days, so rows without a single rate aren't data.
+  if (tables.length === 0) {
+    notBoe('no rates in any row');
+  }
+  return newestFirst(tables);
+}

package/src/braintree.ts

@@ -0,0 +1,71 @@
+/**
+ * Braintree's amount view (https://developer.paypal.com/braintree/docs/reference/general/currencies,
+ * encoded in data/braintree.json). `amount` is a decimal string in major units, "formatted like
+ * '10' or '10.00'":
+ * - zero-decimal currencies can't include decimals: BIF CLP DJF GNF ISK JPY KMF KRW LAK PYG RWF UGX
+ *   VND VUV XAF XOF XPF (LAK has 2 in ISO 4217);
+ * - the others take their ISO decimals ("10.00"). No three-decimal currency is listed.
+ * Amounts must be greater than zero, refunds and credits included.
+ */
+import { BRAINTREE_EXPONENTS } from './generated/braintree.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { fromProcessorDecimal, toProcessorDecimal } from './processor.js';
+import type { RoundingMode } from './rounding.js';
+
+export { BRAINTREE_EXPONENTS };
+
+/** "Can only contain numbers and one decimal point (e.g. x.xx)". */
+const AMOUNT_PATTERN = /^[0-9]+(\.[0-9]+)?$/;
+
+/** The number of decimals Braintree takes for a currency (JPY 0, LAK 0, USD 2). */
+export function braintreeExponent(currency: string): number {
+  const exponent = BRAINTREE_EXPONENTS[currency.toUpperCase()];
+  if (exponent === undefined) {
+    throw new RangeError(`${currency} is not a Braintree currency`);
+  }
+  return exponent;
+}
+
+/** Whether Braintree lists the currency (case-insensitive). */
+export function isBraintreeCurrency(currency: string): boolean {
+  return BRAINTREE_EXPONENTS[currency.toUpperCase()] !== undefined;
+}
+
+/** Options for the Braintree amount: how to round when Braintree needs a coarser amount. */
+export interface BraintreeAmountOptions {
+  /**
+   * How to round when Braintree needs fewer decimals than the value has (default 'unnecessary':
+   * throw).
+   */
+  readonly rounding?: RoundingMode;
+}
+
+/**
+ * The exact `amount` string: toBraintree(money('10', 'USD')) === '10.00', JPY 100 -> '100'.
+ * Braintree has no currency field on a transaction: the merchant account sets it.
+ * Throws a RangeError for zero or negative amounts.
+ */
+export function toBraintree(money: Money, options?: BraintreeAmountOptions): string {
+  const rounding = options?.rounding ?? 'unnecessary';
+
+  // 81531 "Amount must be greater than zero"; 81501: credits are positive too ("x.xx, not -x.xx").
+  return toProcessorDecimal(
+    'Braintree',
+    money,
+    braintreeExponent(money.currency),
+    rounding,
+    'positive',
+  );
+}
+
+/** Reads a Braintree amount string exactly: fromBraintree('10.00', 'USD'). */
+export function fromBraintree<C extends CurrencyInput>(
+  amount: string,
+  currency: C,
+): Money<Uppercase<C>> {
+  const code = currency.toUpperCase() as Uppercase<C>;
+
+  // Validates the currency before parsing, so an unlisted currency is the error reported.
+  braintreeExponent(code);
+  return fromProcessorDecimal('Braintree', amount, code, AMOUNT_PATTERN);
+}

package/src/cash.ts

@@ -0,0 +1,183 @@
+import { CASH_RULES, type CashRule } from './generated/cash.js';
+import {
+  CurrencyMismatchError,
+  make,
+  scaleUp,
+  toScale,
+  type Money,
+  type RoundingPolicy,
+} from './money.js';
+import { roundingPolicy } from './policy.js';
+import { divideAndRound, divideAndRoundBigint, type RoundingMode } from './rounding.js';
+import { currencyExponent } from './currency.js';
+
+/**
+ * Rounds to a multiple of `increment` (same currency): roundToIncrement(CHF 10.03, CHF 0.05) = CHF
+ * 10.05. Default rounding 'halfExpand' (nearest, ties away from zero), which is what the statutory
+ * cash-rounding rules (SE, NO, DK, HU, CZ, FI, BE ...) prescribe.
+ */
+export function roundToIncrement<C extends string>(
+  money: Money<C>,
+  increment: Money<NoInfer<C>>,
+  rounding: RoundingMode = 'halfExpand',
+): Money<C> {
+  if (money.currency !== increment.currency) {
+    throw new CurrencyMismatchError(money.currency, increment.currency);
+  }
+  if (!(increment.minor > 0)) {
+    throw new RangeError('increment must be positive');
+  }
+  const scale = Math.max(money.scale, increment.scale);
+  const minor = scaleUp(money.minor, scale - money.scale);
+  const step = scaleUp(increment.minor, scale - increment.scale);
+  if (typeof minor === 'number' && typeof step === 'number') {
+    const steps = divideAndRound(minor, step, rounding);
+    const rounded = steps * step;
+    if (Number.isSafeInteger(rounded)) {
+      return toScale(
+        make(money.currency, rounded, scale),
+        money.scale > scale ? money.scale : scale,
+      );
+    }
+  }
+  return make(
+    money.currency,
+    divideAndRoundBigint(BigInt(minor), BigInt(step), rounding) * BigInt(step),
+    scale,
+  );
+}
+
+/**
+ * The cash-rounding rule for a currency, optionally narrowed by country (ISO 3166 alpha-2).
+ * EUR has no euro-wide rule: pass the country (BE, NL, FI, IE, IT, SK, EE, LT).
+ */
+export function cashRule(currency: string, country?: string): CashRule | undefined {
+  const rules = cashRulesFor(currency);
+  if (rules === undefined) {
+    return undefined;
+  }
+  if (country !== undefined) {
+    for (let i = 0; i < rules.length; i++) {
+      if (rules[i]!.countries.includes(country)) {
+        return rules[i];
+      }
+    }
+    return undefined;
+  }
+  // EUR has no euro-wide rule, so it needs a country
+  if (currency === 'EUR') {
+    return undefined;
+  }
+  return rules[0];
+}
+
+// CASH_RULES grouped by currency, in table order. Built on first use, not at import, so the module
+// stays free of side effects; cashRound calls cashRule on every amount, and a scan of the whole table
+// was most of its cost.
+let rulesByCurrency: Map<string, CashRule[]> | undefined;
+
+function cashRulesFor(currency: string): readonly CashRule[] | undefined {
+  if (rulesByCurrency === undefined) {
+    rulesByCurrency = new Map();
+    for (let i = 0; i < CASH_RULES.length; i++) {
+      const rule = CASH_RULES[i]!;
+      const forCurrency = rulesByCurrency.get(rule.currency);
+      if (forCurrency === undefined) {
+        rulesByCurrency.set(rule.currency, [rule]);
+      } else {
+        forCurrency.push(rule);
+      }
+    }
+  }
+  return rulesByCurrency.get(currency);
+}
+
+/**
+ * Options for `cashRound`: the country (needed for EUR), the rounding mode, and whether to use
+ * unverified rules.
+ */
+export interface CashRoundOptions {
+  readonly country?: string;
+  readonly rounding?: RoundingMode;
+  /**
+   * Apply rules that are only backed by secondary sources (default true; see
+   * data/cash-rounding.json).
+   */
+  readonly includeUnverified?: boolean;
+}
+
+/**
+ * Rounds a cash total to the smallest legal/practical cash step (CHF 0.05, SEK 1, DKK 0.50, CAD
+ * 0.05, HUF 5, EUR 0.05 in BE/NL/FI/IE/...). Card and other electronic payments are NOT rounded:
+ * only call this for cash tenders. Returns m unchanged when no rule applies.
+ */
+export function cashRound<C extends string>(money: Money<C>, options?: CashRoundOptions): Money<C> {
+  const rule = cashRule(money.currency, options?.country);
+  if (!rule || (options?.includeUnverified === false && !rule.verified)) {
+    return money;
+  }
+  const inc = make(money.currency, rule.increment, currencyExponent(money.currency));
+  return roundToIncrement(money, inc, options?.rounding ?? rule.rounding ?? 'halfExpand');
+}
+
+/**
+ * The cash-rounding rule for a currency as a `RoundingPolicy`, to pass wherever a rounding mode
+ * goes: `m.multiply('1.075', cashPolicy('CHF'))` rounds once, straight to CHF 0.05. The policy only
+ * accepts amounts in `currency`. Throws a RangeError when no rule applies (EUR needs a country);
+ * use `isoPolicy` for currencies without cash rounding.
+ */
+export function cashPolicy(currency: string, options?: CashRoundOptions): RoundingPolicy {
+  const rule = cashRule(currency, options?.country);
+  if (!rule || (options?.includeUnverified === false && !rule.verified)) {
+    const where = options?.country === undefined ? '' : ` in ${options.country}`;
+    throw new RangeError(`No cash-rounding rule for ${currency}${where}`);
+  }
+  return roundingPolicy({
+    scale: currencyExponent(currency),
+    increment: rule.increment,
+    rounding: options?.rounding ?? rule.rounding ?? 'halfExpand',
+    currency,
+  });
+}
+
+/** Options for `currencyDigits`. */
+export interface CurrencyDigitsOptions {
+  /** 'standard' (the default): the ISO 4217 exponent. 'cash': the decimals of a cash amount. */
+  readonly usage?: 'standard' | 'cash';
+  /** For cash: the country (ISO 3166 alpha-2), which EUR needs. */
+  readonly country?: string;
+  /** For cash: whether to use rules backed only by secondary sources (default true). */
+  readonly includeUnverified?: boolean;
+}
+
+/**
+ * The number of decimals a currency's amounts are shown with: its ISO 4217 exponent, or with
+ * `{ usage: 'cash' }`, the decimals of a cash amount (what CLDR calls `cashDigits`): none when cash
+ * is rounded to whole units, the exponent otherwise.
+ *
+ *     currencyDigits('SEK')                       // 2
+ *     currencyDigits('SEK', { usage: 'cash' })    // 0: cash is rounded to whole kronor
+ *     currencyDigits('CHF', { usage: 'cash' })    // 2: CHF 0.05 still needs two decimals
+ *
+ * A currency without a cash rule (or EUR without a country that has one) takes its exponent.
+ * Throws for unknown codes, like `currencyExponent`.
+ */
+export function currencyDigits(currency: string, options?: CurrencyDigitsOptions): number {
+  const exponent = currencyExponent(currency);
+  if (options?.usage !== 'cash') {
+    return exponent;
+  }
+  const rule = cashRule(currency, options.country);
+  if (!rule || (options.includeUnverified === false && !rule.verified)) {
+    return exponent;
+  }
+
+  // Cash amounts show no decimals once the step is whole units (SEK 1, HUF 5, UZS 50), and the
+  // currency's usual decimals otherwise: DKK 0.50 is shown as 10.50, not 10.5, as in CLDR.
+  if (rule.increment % 10 ** exponent === 0) {
+    return 0;
+  }
+  return exponent;
+}
+
+export { CASH_RULES, type CashRule };

package/src/checkout.ts

@@ -0,0 +1,77 @@
+/**
+ * Checkout.com's amount view (https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value,
+ * encoded in data/checkout.json). `amount` is an integer:
+ * - the full amount: BIF DJF GNF ISK JPY KMF KRW PYG RWF UGX VUV VND XAF XOF XPF
+ * - divided by 1000, last digit 0: BHD IQD JOD KWD LYD OMR TND
+ * - divided by 100 for every other currency. CLP is here too (ISO says 0 decimals), and for payment
+ *   requests its last two digits must be 00 (5000 CLP -> 500000). Standalone authentication is
+ *   exempt.
+ */
+import { CHECKOUT_RULES } from './generated/checkout.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { fromProcessorAmount, toProcessorAmount } from './processor.js';
+import type { RoundingMode } from './rounding.js';
+
+export { CHECKOUT_RULES };
+
+/** Checkout.com's [exponent, payment multiple, Standalone API multiple] for a currency. */
+function rulesFor(currency: string) {
+  const rules = CHECKOUT_RULES[currency.toUpperCase()];
+  if (!rules) {
+    throw new RangeError(`${currency} is not a Checkout.com currency`);
+  }
+  return rules;
+}
+
+/** Whether Checkout.com lists the currency (case-insensitive). */
+export function isCheckoutCurrency(currency: string): boolean {
+  return CHECKOUT_RULES[currency.toUpperCase()] !== undefined;
+}
+
+/** The exponent Checkout.com's API uses for a currency (CLP 2, JPY 0, BHD 3). */
+export function checkoutExponent(currency: string): number {
+  return rulesFor(currency)[0];
+}
+
+/** Options for the Checkout.com amount: how to round when Checkout.com needs a coarser amount. */
+export interface CheckoutAmountOptions {
+  /** How to round when Checkout.com needs a coarser amount (default 'unnecessary': throw). */
+  readonly rounding?: RoundingMode;
+  /**
+   * An authentication request to the Standalone API, where CLP's "last two digits 00" rule does not
+   * apply.
+   */
+  readonly standalone?: boolean;
+}
+
+/**
+ * The integer `amount` to send, e.g. toCheckoutAmount(money('5000', 'CLP')) === 500000.
+ * Throws a RangeError for negative amounts (refunds are sent as positive amounts).
+ * SLL and XDR are on Checkout.com's list but not in ISO 4217's active list: call
+ * `defineCurrency('SLL', 2)` or `defineCurrency('XDR', 2)` before using them.
+ */
+export function toCheckoutAmount(money: Money, options?: CheckoutAmountOptions): number {
+  const [exponent, paymentMultiple, standaloneMultiple] = rulesFor(money.currency);
+  const multiple = options?.standalone ? standaloneMultiple : paymentMultiple;
+  const rounding = options?.rounding ?? 'unnecessary';
+
+  // "Be greater than zero", except 0 for a card verification (API reference); refunds are positive.
+  return toProcessorAmount('Checkout.com', money, exponent, multiple, rounding, 'nonNegative');
+}
+
+/** `{ amount, currency }` for a payment request. */
+export function toCheckout(
+  money: Money,
+  options?: CheckoutAmountOptions,
+): { amount: number; currency: string } {
+  return { amount: toCheckoutAmount(money, options), currency: money.currency.toUpperCase() };
+}
+
+/** Reads a Checkout.com amount: fromCheckout(500000, 'CLP') is 5000 CLP. */
+export function fromCheckout<C extends CurrencyInput>(
+  amount: number | bigint,
+  currency: C,
+): Money<Uppercase<C>> {
+  const code = currency.toUpperCase() as Uppercase<C>;
+  return fromProcessorAmount('Checkout.com', amount, code, checkoutExponent(code));
+}

package/src/convert.ts

@@ -0,0 +1,177 @@
+// `ducat/convert` free functions: exact exchange rates and conversion that rounds once.
+import { currencyExponent } from './currency.js';
+import { exact, type Rounded } from './exact.js';
+import { ratio, type Factor } from './decimal.js';
+import { make, type CurrencyInput, type Money, type RoundingInput } from './money.js';
+import { rateOf, type RateProvider } from './provider.js';
+import {
+  convertWithPolicy,
+  isRate,
+  multiplyByRatioAtScale,
+  type ConvertOptions,
+  type Rate,
+} from './rate.js';
+import { DEFAULT_ROUNDING } from './rounding.js';
+
+export {
+  exchangeRate,
+  impliedRate,
+  isRate,
+  multiplyByRatioAtScale,
+  Rate,
+  RateExpiredError,
+  rateFromJSON,
+  type ConvertOptions,
+  type RateInfo,
+  type RateJSON,
+  type RateQuote,
+  type RateType,
+} from './rate.js';
+export {
+  bag,
+  comparator,
+  MoneyBag,
+  sortByValue,
+  sumByCurrency,
+  type ComparatorOptions,
+  type TotalOptions,
+} from './bag.js';
+export {
+  chain,
+  identity,
+  rateOf,
+  rateTable,
+  RateUnavailableError,
+  reversed,
+  snapshots,
+  snapshotsFrom,
+  via,
+  type RateProvider,
+  type RateQuery,
+  type RateTable,
+  type RateTableSpec,
+  type SnapshotOptions,
+  type Snapshots,
+} from './provider.js';
+
+/** Options for converting through a provider. */
+export interface ProviderConvertOptions extends ConvertOptions {
+  /** The time the rate is wanted for (an ISO-8601 date or instant, or a Date). */
+  readonly asOf?: string | Date;
+}
+
+function isProvider(value: unknown): value is RateProvider {
+  return typeof (value as RateProvider | undefined)?.rate === 'function';
+}
+
+/**
+ * Converts `money` at a Rate, rounding once to the target currency's exponent (or `options.scale`),
+ * or with a rounding policy to its scale and increment (`@ducatjs/money/policy`).
+ * The rate's pair is checked, at compile time for literal currencies and at run time otherwise.
+ *
+ *     convert(money('100', 'EUR'), eurUsd, 'halfEven')               // 111.65 USD
+ *     convert(money('100', 'USD'), eurUsd.inverse().andThen(eurJpy))  // composed exactly, rounded once
+ */
+export function convert<From extends string, To extends string>(
+  money: Money<From>,
+  rate: Rate<NoInfer<From>, To>,
+  rounding?: RoundingInput,
+  options?: ConvertOptions,
+): Money<To>;
+/**
+ * Converts at a bare rate: units of `to` per unit of money's currency, as a decimal string so that
+ * no float is involved ('1.0832', every digit kept). Rounds once.
+ *
+ *     convert(money('100', 'EUR'), 'JPY', '162.457', 'halfEven')   // 16246 JPY
+ */
+export function convert<To extends CurrencyInput>(
+  money: Money,
+  to: To,
+  rate: Factor,
+  rounding?: RoundingInput,
+  options?: ConvertOptions,
+): Money<To>;
+/**
+ * Converts through a provider: looks up money's currency → `to` (as of `options.asOf`) and rounds
+ * once. Throws RateUnavailableError when the provider has no rate.
+ *
+ *     convert(money('100', 'USD'), 'JPY', via('EUR', ecb), 'halfEven')
+ */
+export function convert<To extends CurrencyInput>(
+  money: Money,
+  to: To,
+  provider: RateProvider,
+  rounding?: RoundingInput,
+  options?: ProviderConvertOptions,
+): Money<To>;
+export function convert(
+  money: Money,
+  rateOrTarget: Rate | string,
+  roundingOrRate?: RoundingInput | Factor | RateProvider,
+  optionsOrRounding?: ConvertOptions | RoundingInput,
+  maybeOptions?: ProviderConvertOptions,
+): Money {
+  if (isRate(rateOrTarget)) {
+    const rounding = roundingOrRate as RoundingInput | undefined;
+    return rateOrTarget.convert(money, rounding, optionsOrRounding as ConvertOptions | undefined);
+  }
+
+  const to = rateOrTarget;
+  if (isProvider(roundingOrRate)) {
+    let query: { asOf: string | Date } | undefined;
+    if (maybeOptions?.asOf !== undefined) {
+      query = { asOf: maybeOptions.asOf };
+    }
+    const rate = rateOf(roundingOrRate, money.currency, to, query);
+    return rate.convert(money, optionsOrRounding as RoundingInput | undefined, maybeOptions);
+  }
+
+  // The bare-rate form converts directly, without building a Rate, to keep it allocation-light.
+  let rate = ratio(roundingOrRate as Factor);
+  if (typeof roundingOrRate === 'object') {
+    // A hand-made Ratio object is passed through by ratio(); rebuild it so it is reduced and its
+    // number fields match its bigints. Strings and numbers are already normalised (and cached).
+    rate = ratio(rate.num, rate.den);
+  }
+  if (rate.num <= 0n) {
+    throw new RangeError('Exchange rate must be positive');
+  }
+  const rounding = (optionsOrRounding as RoundingInput | undefined) ?? DEFAULT_ROUNDING;
+  if (typeof rounding === 'function') {
+    return convertWithPolicy(money, to, rate, rounding, maybeOptions);
+  }
+  const scale = maybeOptions?.scale ?? currencyExponent(to);
+  const minor = multiplyByRatioAtScale(money.minor, rate, scale - money.scale, rounding);
+  return make(to, minor, scale);
+}
+
+/**
+ * A conversion's rounded value, what rounding left out, and the rate used (for the audit trail).
+ */
+export interface DetailedConversion<From extends string, To extends string> extends Rounded<To> {
+  readonly rate: Rate<From, To>;
+}
+
+/**
+ * Converts at `rate` like convert(), and also reports the residual: `value + residual` is exactly
+ * money × rate, so a ledger can book the rounding difference. With a rounding policy, the value
+ * is on the policy's scale and increment, and the residual is still the exact difference.
+ *
+ *     const { value, residual } = convertDetailed(money('0.07', 'EUR'), eurUsd, 'halfEven');
+ *     // value 0.08 USD, residual -0.001845 USD (as an exact ExactMoney)
+ */
+export function convertDetailed<From extends string, To extends string>(
+  money: Money<From>,
+  rate: Rate<NoInfer<From>, To>,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
+  options?: ConvertOptions,
+): DetailedConversion<From, To> {
+  const converted = exact(money).convert(rate);
+  if (typeof rounding === 'function') {
+    // The policy rounds; the residual is still exactly what it left out.
+    const value = rate.convert(money, rounding, options);
+    return { value, residual: converted.subtract(exact(value)), rate };
+  }
+  const rounded = converted.roundWithResidual(rounding, options?.scale);
+  return { value: rounded.value, residual: rounded.residual, rate };
+}