@arki/money 0.0.0-stage → 0.0.4

package/src/exchange.ts

@@ -0,0 +1,280 @@
+/**
+ * Currency conversion with exact rates. A rate is a fraction, never a float:
+ * `1 EUR = 1.0832 USD` is stored as `677/625`. Inverse and cross
+ * rates stay exact, and a conversion rounds once, at the end.
+ *
+ * There is no network code. Fetch rates however you like (ECB, a bank, your
+ * own table), then build rates from them here.
+ *
+ * ```ts
+ * const converter = createConverter(ratesFrom({ base: 'EUR', rates: { USD: '1.0832', GBP: '0.8571' } }), {
+ *   inverse: true,
+ *   via: 'EUR',
+ * });
+ * converter.convert(money(100, 'USD'), 'GBP', { rounding: 'halfEven' }); // USD → EUR → GBP, rounded once
+ * ```
+ */
+
+import type { CurrencyLike } from './currency.js';
+import type { Units } from './internal/units.js';
+import type { Amount, MoneyOptions } from './money.js';
+import { assertSameCurrency, Currency, toCurrency } from './currency.js';
+import { ExchangeRateError } from './errors.js';
+import { divExact, gcdUnits, mulDiv, mulUnits, pow10, quantize } from './internal/units.js';
+import { Money, toFraction } from './money.js';
+
+const BRAND = Symbol('ExchangeRate');
+
+/** An exact, directed rate: one unit of `base` buys `numerator / denominator` units of `quote`. */
+export class ExchangeRate<B extends string = string, Q extends string = string> {
+  readonly base: Currency<B>;
+  readonly quote: Currency<Q>;
+  /** Positive, in lowest terms with `denominator`. */
+  readonly numerator: Units;
+  /** Positive. */
+  readonly denominator: Units;
+
+  private constructor(
+    base: Currency<B>,
+    quote: Currency<Q>,
+    numerator: Units,
+    denominator: Units,
+    brand: typeof BRAND,
+  ) {
+    if (brand !== BRAND) throw new TypeError('Use exchangeRate(base, quote, value) instead of new ExchangeRate()');
+    this.base = base;
+    this.quote = quote;
+    const divisor = gcdUnits(numerator, denominator);
+    this.numerator = divExact(numerator, divisor);
+    this.denominator = divExact(denominator, divisor);
+    Object.freeze(this);
+  }
+
+  /** @internal */
+  static create<B extends string, Q extends string>(
+    base: Currency<B>,
+    quote: Currency<Q>,
+    numerator: Units,
+    denominator: Units,
+  ): ExchangeRate<B, Q> {
+    return new ExchangeRate(base, quote, numerator, denominator, BRAND);
+  }
+
+  /** The reverse rate, exact: `EUR/USD 1.0832` → `USD/EUR 625/677`. */
+  inverse(): ExchangeRate<Q, B> {
+    return new ExchangeRate(this.quote, this.base, this.denominator, this.numerator, BRAND);
+  }
+
+  /** Chains two rates, exact: `EUR→USD` then `USD→JPY` gives `EUR→JPY`. */
+  chain<R extends string>(next: ExchangeRate<Q, R>): ExchangeRate<B, R> {
+    assertSameCurrency(this.quote, next.base);
+    return new ExchangeRate(
+      this.base,
+      next.quote,
+      mulUnits(this.numerator, next.numerator),
+      mulUnits(this.denominator, next.denominator),
+      BRAND,
+    );
+  }
+
+  /** `true` for the same pair and the same exact value. */
+  eq(other: ExchangeRate): boolean {
+    return (
+      this.base.eq(other.base) &&
+      this.quote.eq(other.quote) &&
+      this.numerator === other.numerator &&
+      this.denominator === other.denominator
+    );
+  }
+
+  /** `'EUR/USD 1.0832'`, or `'USD/EUR 625/677'` when the rate has no finite decimal form. */
+  toString(): string {
+    return `${this.base.code}/${this.quote.code} ${rateText(this.numerator, this.denominator)}`;
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return `ExchangeRate(${this.toString()})`;
+  }
+
+  [Symbol.for('Deno.customInspect')](): string {
+    return `ExchangeRate(${this.toString()})`;
+  }
+}
+
+function rateText(numerator: Units, denominator: Units): string {
+  // A fraction has a finite decimal form when its denominator has no prime factors other than 2 and 5.
+  let rest = BigInt(denominator);
+  let twos = 0;
+  let fives = 0;
+  while (rest % 2n === 0n) {
+    rest /= 2n;
+    twos++;
+  }
+  while (rest % 5n === 0n) {
+    rest /= 5n;
+    fives++;
+  }
+  if (rest !== 1n) return `${String(numerator)}/${String(denominator)}`;
+  const scale = Math.max(twos, fives);
+  const digits = String(mulDiv(numerator, pow10(scale), denominator)).padStart(scale + 1, '0');
+  return scale === 0 ? digits : `${digits.slice(0, -scale)}.${digits.slice(-scale)}`;
+}
+
+/** `exchangeRate('EUR', 'USD', '1.0832')`: one euro buys 1.0832 dollars. The value must be positive. */
+export function exchangeRate<const B extends string, const Q extends string>(
+  base: CurrencyLike<B>,
+  quote: CurrencyLike<Q>,
+  value: Amount,
+): ExchangeRate<B, Q> {
+  const from = toCurrency(base);
+  const to = toCurrency(quote);
+  const [numerator, denominator] = toFraction(value);
+  if (!(numerator > 0)) throw new ExchangeRateError(`An exchange rate must be positive (${from.code}/${to.code})`);
+  if (from.eq(to) && numerator !== denominator) {
+    throw new ExchangeRateError(`A rate from ${from.code} to itself must be 1`);
+  }
+  return ExchangeRate.create(from, to, numerator, denominator);
+}
+
+/** A table of rates from one base currency, as central banks publish them. */
+export type RateTable = {
+  base: CurrencyLike;
+  /** Quote code → units of that currency one unit of `base` buys. */
+  rates: Readonly<Record<string, Amount>>;
+  /** Custom currencies used as quote codes. */
+  currencies?: readonly Currency[];
+};
+
+/** `ratesFrom({ base: 'EUR', rates: { USD: '1.0832' } })` → `[EUR/USD 1.0832]`. */
+export function ratesFrom(table: RateTable): ExchangeRate[] {
+  const base = toCurrency(table.base);
+  return Object.entries(table.rates).map(([code, value]) => {
+    const quote = table.currencies?.find(currency => currency.code === code) ?? Currency.of(code);
+    return exchangeRate(base, quote, value);
+  });
+}
+
+/**
+ * Converts with one rate. The rate's base must be the amount's currency. The
+ * exact result is rounded once to the target scale (the quote currency's,
+ * or `options.scale`); an inexact result needs `options.rounding`.
+ */
+export function convert<B extends string, Q extends string>(
+  amount: Money<B>,
+  rate: ExchangeRate<NoInfer<B>, Q>,
+  options?: MoneyOptions,
+): Money<Q> {
+  assertSameCurrency(amount.currency, rate.base);
+  const scale = options?.scale ?? rate.quote.scale;
+  return Money.fromMinor(convertUnits(amount, rate, scale, options), rate.quote, scale);
+}
+
+/** The one rounding of a conversion: `units × rate × 10^(target − source scale)`. */
+function convertUnits(amount: Money, rate: ExchangeRate, scale: number, options: MoneyOptions | undefined): Units {
+  return mulDiv(
+    amount.units,
+    mulUnits(rate.numerator, pow10(scale)),
+    mulUnits(rate.denominator, pow10(amount.scale)),
+    options?.rounding,
+  );
+}
+
+export type ConverterOptions = {
+  /** Also use `B→A` reversed when only `A→B` is known. Off by default: a bid rate reversed is not an ask rate. */
+  inverse?: boolean;
+  /** Route through this currency when no direct rate exists: `USD→GBP` as `USD→EUR→GBP`. */
+  via?: CurrencyLike;
+};
+
+/** A fixed set of rates with lookups. Build it with `createConverter`. Immutable. */
+export class Converter {
+  private readonly rates: ReadonlyMap<string, ExchangeRate>;
+  private readonly inverse: boolean;
+  private readonly via: Currency | undefined;
+  /** Resolved lookups, including misses. Rates never change, so the cache never goes stale. */
+  private readonly resolved = new Map<string, ExchangeRate | null>();
+
+  constructor(rates: Iterable<ExchangeRate>, options: ConverterOptions = {}) {
+    const map = new Map<string, ExchangeRate>();
+    for (const rate of rates) {
+      if (!(rate instanceof ExchangeRate)) throw new TypeError('Expected ExchangeRate values');
+      const key = pairKey(rate.base, rate.quote);
+      const existing = map.get(key);
+      if (existing !== undefined && !existing.eq(rate)) {
+        throw new ExchangeRateError(`Two different rates for ${rate.base.code}/${rate.quote.code}`);
+      }
+      map.set(key, rate);
+    }
+    this.rates = map;
+    this.inverse = options.inverse === true;
+    this.via = options.via === undefined ? undefined : toCurrency(options.via);
+  }
+
+  /** The exact rate used for `from → to`. Throws `ExchangeRateError` when none can be found. */
+  rate<const F extends string, const T extends string>(from: CurrencyLike<F>, to: CurrencyLike<T>): ExchangeRate<F, T> {
+    const a = toCurrency(from);
+    const b = toCurrency(to);
+    const found = this.resolve(a, b);
+    return ExchangeRate.create(a, b, found.numerator, found.denominator);
+  }
+
+  /** `true` when `rate(from, to)` would succeed. */
+  has(from: CurrencyLike, to: CurrencyLike): boolean {
+    const a = toCurrency(from);
+    const b = toCurrency(to);
+    try {
+      this.resolve(a, b);
+      return true;
+    } catch (error) {
+      if (error instanceof ExchangeRateError) return false;
+      throw error;
+    }
+  }
+
+  /** Converts and rounds once. Same-currency conversion needs no rate and only changes the scale. */
+  convert<const T extends string>(amount: Money, to: CurrencyLike<T>, options?: MoneyOptions): Money<T> {
+    const target = toCurrency(to);
+    if (amount.currency.eq(target)) {
+      const scale = options?.scale ?? target.scale;
+      return Money.fromMinor(quantize(amount.units, amount.scale, scale, options?.rounding), target, scale);
+    }
+    const scale = options?.scale ?? target.scale;
+    return Money.fromMinor(convertUnits(amount, this.resolve(amount.currency, target), scale, options), target, scale);
+  }
+
+  private resolve(from: Currency, to: Currency): ExchangeRate {
+    const key = pairKey(from, to);
+    let found = this.resolved.get(key);
+    if (found === undefined) {
+      found = this.lookup(from, to) ?? this.lookupVia(from, to) ?? null;
+      this.resolved.set(key, found);
+    }
+    if (found === null) throw new ExchangeRateError(`No exchange rate from ${from.code} to ${to.code}`);
+    return found;
+  }
+
+  private lookup(from: Currency, to: Currency): ExchangeRate | undefined {
+    if (from.eq(to)) return ExchangeRate.create(from, to, 1, 1);
+    const direct = this.rates.get(pairKey(from, to));
+    if (direct !== undefined) return direct;
+    if (this.inverse) return this.rates.get(pairKey(to, from))?.inverse();
+    return undefined;
+  }
+
+  private lookupVia(from: Currency, to: Currency): ExchangeRate | undefined {
+    const via = this.via;
+    if (via === undefined || via.eq(from) || via.eq(to)) return undefined;
+    const first = this.lookup(from, via);
+    const second = this.lookup(via, to);
+    return first === undefined || second === undefined ? undefined : first.chain(second);
+  }
+}
+
+function pairKey(from: Currency, to: Currency): string {
+  return `${from.code}>${to.code}`;
+}
+
+/** `createConverter(rates, { inverse: true, via: 'EUR' })`. */
+export function createConverter(rates: Iterable<ExchangeRate>, options?: ConverterOptions): Converter {
+  return new Converter(rates, options);
+}

package/src/format.ts

@@ -0,0 +1,148 @@
+/**
+ * Localized display through `Intl.NumberFormat`. The amount reaches `Intl` as
+ * exact decimal text, never as a float, so digits past 2^53 survive on runtimes
+ * that support string input (ES2023). Where a runtime lacks a feature you asked
+ * for (React Native's Hermes on iOS lacks some), the call throws
+ * `UnsupportedFeatureError` instead of quietly printing something else.
+ *
+ * Rounding for display is done exactly by this package, not by `Intl`, so it
+ * matches arithmetic rounding everywhere.
+ */
+
+import type { RoundingMode } from '@arki/math/rounding';
+import { UnsupportedFeatureError } from '@arki/math/errors';
+
+import type { Money } from './money.js';
+
+export type FormatOptions = {
+  /** BCP 47 locale. Defaults to `'en-US'`; there is no global locale. */
+  locale?: string;
+  /** How to show the currency. Defaults to `'symbol'` for ISO currencies and `'code'` for custom ones. */
+  display?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+  /** `($5.00)` instead of `-$5.00` where the locale has an accounting style. */
+  accounting?: boolean;
+  signDisplay?: 'auto' | 'always' | 'exceptZero' | 'negative' | 'never';
+  /** Defaults to `true`. */
+  useGrouping?: boolean;
+  /** Decimals to show. Defaults to the amount's scale, so nothing is hidden. */
+  fractionDigits?: number;
+  /** Needed when `fractionDigits` drops non-zero digits. */
+  rounding?: RoundingMode;
+};
+
+export type MoneyFormatter = {
+  format(money: Money): string;
+  formatToParts(money: Money): Intl.NumberFormatPart[];
+};
+
+const CACHE_LIMIT = 64;
+const cache = new Map<string, Intl.NumberFormat>();
+let exactStrings: boolean | undefined;
+
+function isNumericText(text: string): text is `${number}` {
+  return /^-?\d+(?:\.\d+)?$/.test(text);
+}
+
+/** Whether `format('9007199254740993')` keeps every digit (ES2023 string input). */
+function supportsExactStrings(): boolean {
+  if (exactStrings === undefined) {
+    try {
+      exactStrings =
+        new Intl.NumberFormat('en-US', { useGrouping: false, maximumFractionDigits: 0 }).format('9007199254740993') ===
+        '9007199254740993';
+    } catch {
+      exactStrings = false;
+    }
+  }
+  return exactStrings;
+}
+
+function formatterFor(money: Money, options: FormatOptions, digits: number): Intl.NumberFormat {
+  const currency = money.currency;
+  const locale = options.locale ?? 'en-US';
+  const display = options.display ?? (currency.iso ? 'symbol' : 'code');
+  if (!currency.iso && display !== 'code') {
+    throw new UnsupportedFeatureError(`${currency.code} is a custom currency; only display: 'code' is available`);
+  }
+  const key = `${locale}|${currency.iso ? currency.code : ''}|${display}|${options.accounting === true ? 1 : 0}|${options.signDisplay ?? ''}|${options.useGrouping === false ? 0 : 1}|${digits}`;
+  const cached = cache.get(key);
+  if (cached !== undefined) return cached;
+
+  const intlOptions: Intl.NumberFormatOptions = {
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+    useGrouping: options.useGrouping !== false,
+  };
+  if (currency.iso) {
+    intlOptions.style = 'currency';
+    intlOptions.currency = currency.code;
+    intlOptions.currencyDisplay = display;
+    if (options.accounting === true) intlOptions.currencySign = 'accounting';
+  }
+  if (options.signDisplay !== undefined) intlOptions.signDisplay = options.signDisplay;
+
+  let formatter: Intl.NumberFormat;
+  try {
+    formatter = new Intl.NumberFormat(locale, intlOptions);
+  } catch (error) {
+    throw new UnsupportedFeatureError(`This runtime's Intl cannot format with these options`, { cause: error });
+  }
+  const resolved = formatter.resolvedOptions();
+  if (options.accounting === true && resolved.currencySign !== 'accounting') {
+    throw new UnsupportedFeatureError('This runtime does not support accounting currency format');
+  }
+  if (options.signDisplay !== undefined && resolved.signDisplay !== options.signDisplay) {
+    throw new UnsupportedFeatureError(`This runtime does not support signDisplay: '${options.signDisplay}'`);
+  }
+  if (resolved.maximumFractionDigits !== digits) {
+    throw new UnsupportedFeatureError(`This runtime cannot show ${digits} decimals`);
+  }
+  if (cache.size >= CACHE_LIMIT) cache.clear();
+  cache.set(key, formatter);
+  return formatter;
+}
+
+function prepare(money: Money, options: FormatOptions): [Intl.NumberFormat, `${number}` | number] {
+  const digits = options.fractionDigits ?? money.scale;
+  const shown = digits === money.scale ? money : money.toScale(digits, options.rounding);
+  const formatter = formatterFor(shown, options, digits);
+  const text = shown.toDecimalString();
+  if (!isNumericText(text)) throw new TypeError(`Unexpected decimal text ${text}`);
+  if (supportsExactStrings()) return [formatter, text];
+  // Without string input, Intl converts to a double; up to 15 significant digits survive that exactly.
+  if (text.replaceAll(/[-.]/g, '').replace(/^0+/, '').length > 15) {
+    throw new UnsupportedFeatureError('This runtime cannot format more than 15 significant digits exactly');
+  }
+  return [formatter, Number(text)];
+}
+
+/**
+ * `formatMoney(money('1234.5', 'EUR'), { locale: 'de-DE' })` → `'1.234,50 €'`.
+ * Custom currencies print the number and the code: `'0.00012000 BTC'`.
+ */
+export function formatMoney(money: Money, options: FormatOptions = {}): string {
+  const [formatter, value] = prepare(money, options);
+  const text = formatter.format(value);
+  return money.currency.iso ? text : `${text} ${money.currency.code}`;
+}
+
+/** The parts `Intl` produces (currency, integer, group, decimal, fraction, ...), for custom rendering. */
+export function formatMoneyToParts(money: Money, options: FormatOptions = {}): Intl.NumberFormatPart[] {
+  const [formatter, value] = prepare(money, options);
+  if (typeof formatter.formatToParts !== 'function') {
+    throw new UnsupportedFeatureError('This runtime does not support Intl.NumberFormat#formatToParts');
+  }
+  const parts = formatter.formatToParts(value);
+  if (!money.currency.iso)
+    parts.push({ type: 'literal', value: ' ' }, { type: 'currency', value: money.currency.code });
+  return parts;
+}
+
+/** Binds options once for loops: `const eur = createMoneyFormatter({ locale: 'de-DE' }); eur.format(price)`. */
+export function createMoneyFormatter(options: FormatOptions = {}): MoneyFormatter {
+  const bound = { ...options };
+  return {
+    format: money => formatMoney(money, bound),
+    formatToParts: money => formatMoneyToParts(money, bound),
+  };
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { Currency, ISO_4217_VERSION } from './currency.js';
+export type { CurrencyDefinition, CurrencyLike } from './currency.js';
+export { Factor, Money, average, factor, isMoney, max, min, money, sum } from './money.js';
+export type {
+  AllocateOptions,
+  Amount,
+  DecimalLike,
+  FactorInput,
+  MoneyJSON,
+  MoneyOptions,
+  RationalLike,
+  RemainderPolicy,
+  Units,
+} from './money.js';
+export * from './errors.js';
+export type { RoundingMode } from '@arki/math/rounding';

package/src/internal/columns.ts

@@ -0,0 +1,74 @@
+/**
+ * The value conversions behind the Drizzle columns, shared by every SQL
+ * dialect. Each dialect file only says which column type to declare.
+ */
+
+import { InvalidArgumentError, NumericRangeError } from '@arki/math/errors';
+
+import type { Currency } from '../currency.js';
+import type { Money } from '../money.js';
+import type { Units } from './units.js';
+import { assertSameCurrency, resolveCurrency } from '../currency.js';
+import { Money as MoneyClass } from '../money.js';
+import { quantize } from './units.js';
+
+/** What drivers hand back for an integer column. */
+export type IntegerDriverValue = number | bigint | string;
+
+/** Minor units at the column's scale, in canonical form. Throws if the value is in another currency or needs rounding. */
+export function minorToDriver(value: Money, currency: Currency, scale: number): Units {
+  assertSameCurrency(value.currency, currency);
+  return quantize(value.units, value.scale, scale);
+}
+
+/**
+ * Reads an integer column. A `number` that is not a safe integer was already
+ * rounded by the driver, so it throws instead of becoming a wrong amount.
+ */
+export function minorFromDriver<C extends string>(
+  value: IntegerDriverValue,
+  currency: Currency<C>,
+  scale: number,
+): Money<C> {
+  if (typeof value === 'number' && !Number.isSafeInteger(value)) {
+    throw new NumericRangeError(
+      `The database driver returned ${value}, which a JavaScript number cannot hold exactly; ` +
+        'configure the driver to return big integers as strings or bigint',
+    );
+  }
+  return MoneyClass.fromMinor(
+    typeof value === 'number' || typeof value === 'bigint' ? value : String(value),
+    currency,
+    scale,
+  );
+}
+
+/** Exact decimal text at the column's scale. */
+export function decimalToDriver(value: Money, currency: Currency, scale: number): string {
+  assertSameCurrency(value.currency, currency);
+  return value.toScale(scale).toDecimalString();
+}
+
+/** Reads decimal text (or a driver's number for a whole value) at the column's scale. */
+export function decimalFromDriver<C extends string>(
+  value: string | number,
+  currency: Currency<C>,
+  scale: number,
+): Money<C> {
+  return MoneyClass.of(typeof value === 'number' ? value : String(value), currency, { scale });
+}
+
+/** `{ amount, currency }` as JSON text. */
+export function jsonToDriver(value: Money): string {
+  return JSON.stringify(value.toJSON());
+}
+
+/** Reads JSON text, or an object for drivers that parse JSON columns themselves. */
+export function jsonFromDriver(value: unknown, currencies: readonly Currency[] | undefined): Money {
+  const parsed: unknown = typeof value === 'string' ? JSON.parse(value) : value;
+  if (typeof parsed !== 'object' || parsed === null || !('currency' in parsed) || typeof parsed.currency !== 'string') {
+    throw new InvalidArgumentError('A money JSON column holds { amount, currency }');
+  }
+  resolveCurrency(parsed.currency, currencies);
+  return MoneyClass.fromJSON(parsed, currencies);
+}