money.convert

export function convertMoney(amount: Money, rate: ExchangeRate, mode: RoundingMode): Money

/** A quoted rate: one unit of base buys rate units of quote, both in major units. */
export interface ExchangeRate {
  /** ISO 4217 code converted from */
  readonly base: string;
  /** ISO 4217 code converted to */
  readonly quote: string;
  /** exact, e.g. 1.1734 is {numerator 11734, denominator 10000} */
  readonly rate: Rational;
}

import { convertMoney } from "#fune/money.convert@^1";

import { multiplyRational, rational, rationalToInteger } from "./math_rational.ts";  ← from math.rational ^1.0.0 · built alongside by fune
import { type RoundingMode } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type Money, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { currencyDigits } from "./money_currency_digits.ts";  ← from money.currency-digits ^1.0.0 · built alongside by fune
import { type ExchangeRate } from "./money_convert_types.ts";

/**
 * Convert `amount` into the rate's quote currency.
 *
 * Exact up to one final rounding into the quote currency's minor unit; the
 * rate is a fraction in major units and each currency's decimal places are
 * looked up rather than assumed to be two.
 */
export function convertMoney(amount: Money, rate: ExchangeRate, mode: RoundingMode): Money {
  if (amount.currency !== rate.base) {
    throw new RangeError(`exchange rate converts ${rate.base} to ${rate.quote}, not ${amount.currency}`);
  }
  const r = rational(rate.rate.numerator, rate.rate.denominator);
  if (r.numerator <= 0) {
    throw new RangeError("exchange rate must be positive");
  }
  const fromDigits = currencyDigits(rate.base);
  const toDigits = currencyDigits(rate.quote);

  // minor units of quote per minor unit of base: rate x 10^toDigits / 10^fromDigits
  const scale = rational(10 ** toDigits, 10 ** fromDigits);
  const perMinor = multiplyRational(r, scale);
  const exact = multiplyRational(rational(amount.minor, 1), perMinor);
  return money(rationalToInteger(exact, mode), rate.quote);
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 4 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add money.convert

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./money.convert-1.0.0-typescript.fune, or fetch it from a terminal with fune pull money.convert@1.0.0:typescript.

The whole function, every language, is one file too: money.convert-1.0.0.fune, 17,457 bytes, sha256 5f212485febe18b862f284258bf82a2443c493df5d26c3d20f0303bc6fdf5691. It installs into a project of any language.

// fune: before money.convert

// fune: after money.convert

// fune: replace math.rational in money.convert
// fune: replace math.round-div in money.convert
// fune: replace money.amount in money.convert
// fune: replace money.currency-digits in money.convert

// fune: step money.convert after <n|label>

More from the author

**Minor units are handled for you.** The rate is in major units, so the amount is scaled by each currency's ISO 4217 decimal places (from `money.currency-digits`): 10.00 GBP at 190.12 is 1,901 JPY, not 190,120.

**One rounding**, at the end, to the quote currency's minor unit, with the `math.round-div` mode you pass. Everything before it is exact. 1.00 EUR at 1.005 is exactly 1.005 USD; `half-up` gives 1.01, where a float computes 100 × 1.005 as 100.49999999999999 and rounds it to 1.00.

**The rate carries its currencies.** Applying a GBP-to-EUR rate to a USD amount is an error, not a conversion. To go the other way, swap `base` and `quote` and turn the fraction over; this never inverts a rate on its own.

Edges: the rate must be positive; zero converts to zero; negative amounts (refunds) convert symmetrically under `half-up` and `half-even`. Intermediate values follow `math.rational`'s limits (numerator and denominator within 2^53 - 1 after reducing); an amount and rate so large that the exact product does not fit is refused with "rational overflow" rather than rounded.

Files