@ducatjs/money 0.0.0 → 0.1.0

package/src/cash.ts

@@ -0,0 +1,115 @@
+import { CASH_RULES, type CashRule } from './generated/cash.js';
+import { CurrencyMismatchError, make, scaleUp, toScale, type Money } from './money.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 ?? 'halfExpand');
+}
+
+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,159 @@
+// `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 } from './money.js';
+import { rateOf, type RateProvider } from './provider.js';
+import { isRate, multiplyByRatioAtScale, type ConvertOptions, type Rate } from './rate.js';
+import { DEFAULT_ROUNDING, type RoundingMode } from './rounding.js';
+
+export {
+  exchangeRate,
+  impliedRate,
+  isRate,
+  multiplyByRatioAtScale,
+  Rate,
+  RateExpiredError,
+  rateFromJSON,
+  type ConvertOptions,
+  type RateInfo,
+  type RateJSON,
+  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`).
+ * 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?: RoundingMode,
+  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?: RoundingMode,
+  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?: RoundingMode,
+  options?: ProviderConvertOptions,
+): Money<To>;
+export function convert(
+  money: Money,
+  rateOrTarget: Rate | string,
+  roundingOrRate?: RoundingMode | Factor | RateProvider,
+  optionsOrRounding?: ConvertOptions | RoundingMode,
+  maybeOptions?: ProviderConvertOptions,
+): Money {
+  if (isRate(rateOrTarget)) {
+    const rounding = roundingOrRate as RoundingMode | 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 RoundingMode | 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 RoundingMode | undefined) ?? DEFAULT_ROUNDING;
+  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.
+ *
+ *     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: RoundingMode = DEFAULT_ROUNDING,
+  options?: ConvertOptions,
+): DetailedConversion<From, To> {
+  const rounded = exact(money).convert(rate).roundWithResidual(rounding, options?.scale);
+  return { value: rounded.value, residual: rounded.residual, rate };
+}

package/src/currency.ts

@@ -0,0 +1,61 @@
+import { ISO_EXPONENTS, type IsoCurrencyCode } from './generated/iso4217.js';
+
+/**
+ * Augment this interface to add non-ISO currencies to the `CurrencyCode` type:
+ *
+ *     declare module '@ducatjs/money' { interface CustomCurrencies { BTC: true; USDC: true } }
+ *     defineCurrency('BTC', 8);
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface CustomCurrencies {}
+
+/** A known currency code: ISO 4217, or one added to `CustomCurrencies`. */
+export type CurrencyCode = IsoCurrencyCode | (keyof CustomCurrencies & string);
+
+const custom = new Map<string, number>();
+const iso = ISO_EXPONENTS as Readonly<Record<string, number>>;
+
+/**
+ * Registers a currency that is not in ISO 4217 (crypto, loyalty points, withdrawn codes you still
+ * hold balances in). ISO codes cannot be redefined: use an explicit `scale` for extra precision.
+ */
+export function defineCurrency(code: string, exponent: number): void {
+  if (!Number.isInteger(exponent) || exponent < 0 || exponent > 30) {
+    throw new RangeError(`Invalid exponent ${exponent}`);
+  }
+  if (typeof iso[code] === 'number') {
+    throw new TypeError(`${code} is an ISO 4217 currency and cannot be redefined`);
+  }
+  const prev = custom.get(code);
+  if (prev !== undefined && prev !== exponent) {
+    throw new TypeError(`${code} is already defined with exponent ${prev}`);
+  }
+  custom.set(code, exponent);
+}
+
+/** The minor-unit exponent of a currency (EUR 2, JPY 0, KWD 3). Throws for unknown codes. */
+export function currencyExponent(code: string): number {
+  const isoExponent = iso[code];
+  if (typeof isoExponent === 'number') {
+    return isoExponent;
+  }
+  const customExponent = custom.get(code);
+  if (customExponent !== undefined) {
+    return customExponent;
+  }
+  throw new RangeError(
+    `Unknown currency "${code}" (not ISO 4217 and not registered with defineCurrency)`,
+  );
+}
+
+/** Whether the code is an ISO 4217 currency or one registered with `defineCurrency`. */
+export function isCurrency(code: string): code is CurrencyCode {
+  return typeof iso[code] === 'number' || custom.has(code);
+}
+
+export {
+  ISO_EXPONENTS,
+  ISO_4217_PUBLISHED,
+  ISO_NON_MONETARY,
+  type IsoCurrencyCode,
+} from './generated/iso4217.js';

package/src/decimal.ts

@@ -0,0 +1,283 @@
+// Exact decimal-string handling. No floating point is used on amounts: numbers given as factors are
+// converted through their shortest round-trip decimal representation (String(x)), never multiplied.
+
+/** The largest minor-unit count held as a number (2^53 - 1); larger values are bigints. */
+const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+const MAXN = BigInt(MAX_SAFE_MINOR);
+
+/**
+ * An exact rational factor num/den (den > 0). `n`/`d` hold the same values as numbers when both are
+ * safe.
+ */
+export interface Ratio {
+  readonly num: bigint;
+  readonly den: bigint;
+  /** num as a number, or NaN when it is not a safe integer */
+  readonly n: number;
+  /** den as a number, or NaN when it is not a safe integer */
+  readonly d: number;
+}
+
+/** Anything accepted where a multiplier, rate or percentage is expected. */
+export type Factor = number | bigint | string | Ratio;
+
+const POW10N: bigint[] = [];
+/** 10^exponent as a bigint, cached. */
+export function pow10n(exponent: number): bigint {
+  return (POW10N[exponent] ??= 10n ** BigInt(exponent));
+}
+/** 10^e as a number for 0 <= e <= 15 (all exact and safe). */
+export const POW10 = [
+  1, 10, 100, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14, 1e15,
+] as const;
+
+/**
+ * A bigint as a number when it is a safe integer, else unchanged: the representation Money keeps.
+ */
+export const normalizeMinor = (value: bigint): number | bigint =>
+  value <= MAXN && value >= -MAXN ? Number(value) : value;
+
+/**
+ * Parses a plain decimal string ("-12.345", "+7", "0.50") into digits/10^scale. Returns the integer
+ * of all digits (number when safe, else bigint) and the count of fraction digits. Hand-rolled (no
+ * regex, no BigInt for short inputs): this is the hot path of `money("12.34", ...)`.
+ */
+export function parsePlainDecimal(
+  input: string,
+): { digits: number | bigint; scale: number } | null {
+  const len = input.length;
+  let i = 0;
+  let neg = false;
+  let code = input.charCodeAt(0);
+  if (code === 45 /* - */ || code === 43 /* + */) {
+    neg = code === 45;
+    i = 1;
+  }
+  let acc = 0;
+  let digitsSeen = 0;
+  let scale = -1;
+  let big = false;
+  const start = i;
+  for (; i < len; i++) {
+    code = input.charCodeAt(i);
+    if (code >= 48 && code <= 57) {
+      digitsSeen++;
+      if (scale >= 0) {
+        scale++;
+      }
+      if (!big) {
+        // 15 digits always fit exactly in a double; beyond that use BigInt
+        if (digitsSeen > 15) {
+          big = true;
+        } else {
+          acc = acc * 10 + (code - 48);
+        }
+      }
+    } else if (code === 46 /* . */ && scale < 0 && digitsSeen > 0) {
+      scale = 0;
+    } else {
+      return null;
+    }
+  }
+  // "", "-" and "12." are not decimals
+  if (digitsSeen === 0 || scale === 0) {
+    return null;
+  }
+  // parseDecimal reports fractions longer than MAX_DECIMAL_SCALE
+  if (scale > MAX_DECIMAL_SCALE) {
+    return null;
+  }
+  if (scale < 0) {
+    scale = 0;
+  }
+  if (big) {
+    const raw = input.slice(start).replace('.', '');
+    const value = BigInt(raw);
+    return { digits: normalizeMinor(neg ? -value : value), scale };
+  }
+  return { digits: neg ? 0 - acc : acc, scale };
+}
+
+const EXP_RE = /^([+-]?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+
+/**
+ * The largest exponent and number of fraction digits a decimal string may have. Far beyond any real
+ * amount or rate, and it keeps input such as "1e999999999" from building enormous powers of ten.
+ */
+export const MAX_DECIMAL_SCALE = 1000;
+
+/** Parses a decimal string, allowing exponent notation ("1e-7", as produced by String(1e-7)). */
+export function parseDecimal(input: string): { digits: bigint; scale: number } {
+  const match = EXP_RE.exec(input.trim());
+  if (!match) {
+    throw new SyntaxError(`Invalid decimal string "${input}"`);
+  }
+  const [, sign, int, frac = '', exp = '0'] = match;
+  const exponent = Number(exp);
+  let scale = frac.length - exponent;
+  if (!(Math.abs(exponent) <= MAX_DECIMAL_SCALE) || scale > MAX_DECIMAL_SCALE) {
+    // The input itself is not quoted: it may be huge.
+    throw new RangeError(`Decimal string exponent or fraction digits beyond ${MAX_DECIMAL_SCALE}`);
+  }
+  let digits = BigInt(int! + frac);
+  if (scale < 0) {
+    digits *= pow10n(-scale);
+    scale = 0;
+  }
+  return { digits: sign === '-' ? -digits : digits, scale };
+}
+
+function gcd(left: bigint, right: bigint): bigint {
+  if (left < 0n) {
+    left = -left;
+  }
+  // a temporary, not a destructuring swap: `[a, b] = [b, a % b]` builds an array per step until the
+  // optimiser removes it, and this loop runs for every ratio that is built
+  while (right) {
+    const remainder = left % right;
+    left = right;
+    right = remainder;
+  }
+  return left;
+}
+
+/** The value as a number when it is a safe integer, otherwise NaN (a Ratio's `n` and `d`). */
+function safeNumberOrNaN(value: bigint): number {
+  return value <= MAXN && value >= -MAXN ? Number(value) : NaN;
+}
+
+function makeRatio(num: bigint, den: bigint): Ratio {
+  if (den === 0n) {
+    throw new RangeError('Division by zero');
+  }
+  if (den < 0n) {
+    num = -num;
+    den = -den;
+  }
+  // an integer (den 1) is already in lowest terms
+  if (den !== 1n) {
+    const divisor = gcd(num, den);
+    if (divisor > 1n) {
+      num /= divisor;
+      den /= divisor;
+    }
+  }
+  return { num, den, n: safeNumberOrNaN(num), d: safeNumberOrNaN(den) };
+}
+
+const cache = new Map<string, Ratio>();
+const INT_RATIOS: Ratio[] = [];
+
+/**
+ * Builds an exact ratio. `ratio('1.075')`, `ratio(3, 4)`, `ratio(10n)`, `ratio('1/3')`.
+ * Numbers are taken at their shortest decimal representation: `ratio(0.1)` is exactly 1/10.
+ * Pre-build ratios you use in hot loops; strings are also cached (up to 1024 entries).
+ */
+export function ratio(value: Factor, den?: Factor): Ratio {
+  if (den !== undefined) {
+    // two bigints (divide, percentages, tax): one reduction instead of three
+    if (typeof value === 'bigint' && typeof den === 'bigint') {
+      return makeRatio(value, den);
+    }
+    const numeratorRatio = ratio(value);
+    const denominatorRatio = ratio(den);
+    return makeRatio(
+      numeratorRatio.num * denominatorRatio.den,
+      numeratorRatio.den * denominatorRatio.num,
+    );
+  }
+  if (typeof value === 'object') {
+    return value;
+  }
+  if (typeof value === 'number') {
+    if (Number.isSafeInteger(value)) {
+      if (value >= 0 && value < 128) {
+        return (INT_RATIOS[value] ??= makeRatio(BigInt(value), 1n));
+      }
+      return makeRatio(BigInt(value), 1n);
+    }
+    if (!Number.isFinite(value)) {
+      throw new RangeError(`Invalid factor ${value}`);
+    }
+    value = String(value);
+  }
+  if (typeof value === 'bigint') {
+    return makeRatio(value, 1n);
+  }
+  let cached = cache.get(value);
+  if (cached === undefined) {
+    const slash = value.indexOf('/');
+    if (slash > 0) {
+      cached = ratio(value.slice(0, slash).trim(), value.slice(slash + 1).trim());
+    } else {
+      const { digits, scale } = parseDecimal(value);
+      cached = makeRatio(digits, pow10n(scale));
+    }
+    if (cache.size >= 1024) {
+      cache.clear();
+    }
+    cache.set(value, cached);
+  }
+  return cached;
+}
+
+/** num/den -> exact decimal string if the expansion terminates, else null. */
+export function ratioToDecimal(value: Ratio): string | null {
+  let remainingDenominator = value.den;
+  let twos = 0;
+  let fives = 0;
+  while (remainingDenominator % 2n === 0n) {
+    remainingDenominator /= 2n;
+    twos++;
+  }
+  while (remainingDenominator % 5n === 0n) {
+    remainingDenominator /= 5n;
+    fives++;
+  }
+  if (remainingDenominator !== 1n) {
+    return null;
+  }
+  const scale = Math.max(twos, fives);
+  return formatScaled(value.num * (pow10n(scale) / value.den), scale);
+}
+
+// Zero padding for the fraction digits, built once: indexing it is faster than padStart.
+const ZPAD = Array.from({ length: 16 }, (_, length) => '0'.repeat(length));
+
+/** Formats an integer at `scale` as a plain decimal string ("-0.05"). */
+export function formatScaled(minor: number | bigint, scale: number): string {
+  if (typeof minor === 'number' && scale <= 15) {
+    if (scale === 0) {
+      return String(minor);
+    }
+    // integer/fraction split with exact integer arithmetic (the float quotient is corrected)
+    const magnitude = minor < 0 ? 0 - minor : minor;
+    const unit = POW10[scale]!;
+    if (magnitude + unit <= MAX_SAFE_MINOR) {
+      let whole = Math.floor(magnitude / unit);
+      let fraction = magnitude - whole * unit;
+      if (fraction < 0) {
+        whole -= 1;
+        fraction += unit;
+      } else if (fraction >= unit) {
+        whole += 1;
+        fraction -= unit;
+      }
+      let fractionDigits = String(fraction);
+      if (fractionDigits.length < scale) {
+        fractionDigits = ZPAD[scale - fractionDigits.length] + fractionDigits;
+      }
+      return (minor < 0 ? '-' : '') + whole + '.' + fractionDigits;
+    }
+  }
+  const neg = minor < 0;
+  let digits =
+    typeof minor === 'number' ? String(neg ? 0 - minor : minor) : (neg ? -minor : minor).toString();
+  if (scale > 0) {
+    if (digits.length <= scale) {
+      digits = '0'.repeat(scale - digits.length + 1) + digits;
+    }
+    digits = digits.slice(0, digits.length - scale) + '.' + digits.slice(digits.length - scale);
+  }
+  return neg ? '-' + digits : digits;
+}