@ducatjs/money 0.2.1 → 0.3.0

package/src/allocate.ts

@@ -1,4 +1,4 @@
-import { parseDecimal, pow10n, normalizeMinor } from './decimal.js';
+import { faithfulDecimal, parseDecimal, pow10n, normalizeMinor } from './decimal.js';
 import {
   CurrencyMismatchError,
   compare,
@@ -45,8 +45,9 @@ function weightsScaled(ws: readonly Weight[]): { ws: bigint[]; scale: number } {
     if (typeof weight === 'number' && Number.isSafeInteger(weight)) {
       return { digits: BigInt(weight), scale: 0 };
     }
-    const item = parseDecimal(String(weight));
-    return item;
+    return parseDecimal(
+      typeof weight === 'number' ? faithfulDecimal(weight, 'pass weights as strings') : weight,
+    );
   });
   for (const item of parsed) {
     if (item.digits < 0n) {

package/src/cash.ts

@@ -10,6 +10,7 @@ import {
 import { roundingPolicy } from './policy.js';
 import { divideAndRound, divideAndRoundBigint, type RoundingMode } from './rounding.js';
 import { currencyExponent } from './currency.js';
+import { formatScaled } from './decimal.js';
 
 /**
  * Rounds to a multiple of `increment` (same currency): roundToIncrement(CHF 10.03, CHF 0.05) = CHF
@@ -180,4 +181,29 @@ export function currencyDigits(currency: string, options?: CurrencyDigitsOptions
   return exponent;
 }
 
+/** Options for `cashUnit`. */
+export interface CashUnitOptions {
+  /** The country (ISO 3166 alpha-2), which EUR needs. */
+  readonly country?: string;
+  /** Whether to use rules backed only by secondary sources (default true). */
+  readonly includeUnverified?: boolean;
+}
+
+/**
+ * The smallest cash step, in major units, as an exact decimal string with the currency's decimals:
+ * the smallest coin in use where the cash rules know one. `cashUnit('CHF')` is '0.05',
+ * `cashUnit('DKK')` is '0.50', `cashUnit('SEK')` is '1.00' and `cashUnit('EUR', { country: 'NL' })`
+ * is '0.05'. A currency without a cash rule (or EUR without a country that has one) gives its minor
+ * unit, '0.01' for GBP. Throws for unknown codes, like `currencyExponent`.
+ */
+export function cashUnit(currency: string, options?: CashUnitOptions): string {
+  const exponent = currencyExponent(currency);
+  const rule = cashRule(currency, options?.country);
+  if (!rule || (options?.includeUnverified === false && !rule.verified)) {
+    return formatScaled(1, exponent);
+  }
+  // with the currency's decimals, as amounts are written everywhere else: SEK's step is '1.00'
+  return formatScaled(rule.increment, exponent);
+}
+
 export { CASH_RULES, type CashRule };

package/src/convert.ts

@@ -1,8 +1,7 @@
 // `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 { make, resolveScale, type CurrencyInput, type Money, type RoundingInput } from './money.js';
 import { rateOf, type RateProvider } from './provider.js';
 import {
   convertWithPolicy,
@@ -140,7 +139,7 @@ export function convert(
   if (typeof rounding === 'function') {
     return convertWithPolicy(money, to, rate, rounding, maybeOptions);
   }
-  const scale = maybeOptions?.scale ?? currencyExponent(to);
+  const scale = resolveScale(to, maybeOptions?.scale);
   const minor = multiplyByRatioAtScale(money.minor, rate, scale - money.scale, rounding);
   return make(to, minor, scale);
 }

package/src/crypto.ts

@@ -0,0 +1,129 @@
+/**
+ * `@ducatjs/money/crypto`: crypto currencies and tokens as an opt-in table (BTC with 8 decimals,
+ * ETH with 18, SOL with 9, and common Ethereum tokens), and exact conversions to and from base
+ * units (satoshi, wei, lamport). Nothing is registered until you ask:
+ *
+ *     defineCryptoCurrencies(['BTC', 'ETH']);
+ *     money('0.5', 'ETH').toString()            // '0.500000000000000000 ETH'
+ *     toBaseUnits(money('0.00000001', 'BTC'))  // 1n
+ *     fromBaseUnits('1000000000000000000', 'ETH').toString() // '1.000000000000000000 ETH'
+ *
+ * Amounts beyond 2^53 base units (most ETH amounts in wei) use Money's bigint path, so they stay
+ * exact. The decimals come from each unit's defining source (see data/crypto-units.json).
+ */
+import { currencyExponent, defineCurrency } from './currency.js';
+import { pow10n } from './decimal.js';
+import { CRYPTO_UNIT_TABLE } from './generated/crypto.js';
+import { fromMinor, type CurrencyInput, type Money } from './money.js';
+import { RoundingError } from './rounding.js';
+
+/** A code in the crypto table. */
+export type CryptoCurrencyCode = keyof typeof CRYPTO_UNIT_TABLE;
+
+/**
+ * Every crypto code, for the `CurrencyCode` type:
+ *
+ *     declare module '@ducatjs/money' {
+ *       interface CustomCurrencies extends CryptoCurrencies {}
+ *     }
+ */
+export type CryptoCurrencies = { readonly [Code in CryptoCurrencyCode]: true };
+
+/** One entry of the crypto table. */
+export interface CryptoUnit {
+  readonly code: CryptoCurrencyCode;
+  readonly name: string;
+  /** Decimal places of one unit in base units: 8 for BTC (satoshi), 18 for ETH (wei). */
+  readonly decimals: number;
+  /** The base unit's name, for native currencies: 'satoshi', 'wei', 'lamport'. */
+  readonly baseUnit?: string;
+  /** The network the decimals are for. A token's decimals can differ on another network. */
+  readonly network: string;
+  /** The token's contract address on that network, for tokens. */
+  readonly contract?: string;
+}
+
+const table: Readonly<Record<string, Omit<CryptoUnit, 'code'>>> = CRYPTO_UNIT_TABLE;
+
+/** The table entry for a code, or undefined for a code that isn't in it. */
+export function cryptoUnit(code: string): CryptoUnit | undefined {
+  // own properties only, so 'toString' and friends are not currencies
+  if (!Object.hasOwn(table, code)) {
+    return undefined;
+  }
+  return { code: code as CryptoCurrencyCode, ...table[code]! };
+}
+
+/** Every entry of the table, by code. */
+export function cryptoUnits(): CryptoUnit[] {
+  return Object.keys(table).map((code) => cryptoUnit(code)!);
+}
+
+/**
+ * Registers crypto codes with `defineCurrency`, with their decimals as the exponent: all of them,
+ * or only `codes`. Registering one again is harmless; a code already defined with other decimals
+ * throws, as `defineCurrency` does.
+ */
+export function defineCryptoCurrencies(codes?: readonly CryptoCurrencyCode[]): void {
+  const selected: readonly string[] = codes ?? Object.keys(table);
+
+  // check every code first, so a typo registers nothing
+  for (const code of selected) {
+    if (!Object.hasOwn(table, code)) {
+      throw new RangeError(`${code} is not in the crypto currency table`);
+    }
+  }
+
+  for (const code of selected) {
+    defineCurrency(code, table[code]!.decimals);
+  }
+}
+
+/**
+ * The amount as a count of the currency's base units (satoshi for BTC, wei for ETH), always a
+ * bigint since wei amounts are rarely safe integers. The base unit is 10^-exponent of the currency
+ * (its decimals, once registered), so this works for any registered code. An amount with more
+ * decimals than that throws a RoundingError: there is no fraction of a base unit.
+ */
+export function toBaseUnits(money: Money): bigint {
+  const decimals = currencyExponent(money.currency);
+  const minor = BigInt(money.minor);
+  if (money.scale <= decimals) {
+    return minor * pow10n(decimals - money.scale);
+  }
+
+  // more decimals than the currency has: only exact when the extra digits are zeros
+  const divisor = pow10n(money.scale - decimals);
+  if (minor % divisor !== 0n) {
+    throw new RoundingError(
+      `${money.toString()} is not a whole number of base units (${decimals} decimals)`,
+    );
+  }
+  return minor / divisor;
+}
+
+// A plain integer: an optional minus sign and digits, no leading zeros, nothing else.
+const BASE_UNITS = /^-?(?:0|[1-9]\d*)$/;
+
+/**
+ * Money from a count of base units: `fromBaseUnits('100000000', 'BTC')` is 1.00000000 BTC. The
+ * count is a bigint, a safe integer or a decimal string. Strings are parsed strictly, since they
+ * usually come from an API or a node: digits with an optional minus sign, and nothing else (no
+ * spaces, signs, decimal points, exponents, separators or leading zeros). Anything else throws a
+ * SyntaxError. A hexadecimal quantity from an Ethereum node goes through `BigInt('0x…')` first.
+ * The result has the currency's exponent as its scale.
+ */
+export function fromBaseUnits<C extends CurrencyInput>(
+  units: bigint | number | string,
+  currency: C,
+): Money<C> {
+  const decimals = currencyExponent(currency);
+  if (typeof units === 'string') {
+    // 1000 digits is far beyond any real amount, and bounds the work for untrusted input
+    if (units.length > 1001 || !BASE_UNITS.test(units)) {
+      throw new SyntaxError(`Invalid base-unit count "${units}": expected an integer like "1000"`);
+    }
+    return fromMinor(BigInt(units), currency, decimals);
+  }
+  return fromMinor(units, currency, decimals);
+}

package/src/currencies.ts

@@ -0,0 +1,123 @@
+/**
+ * `@ducatjs/money/currencies`: currency facts beyond the exponent. ISO 4217 numeric codes both
+ * ways, the size of the minor unit, and names and symbols per locale, which come from the runtime's
+ * `Intl` rather than a bundled table. Which currencies a territory uses is in
+ * `@ducatjs/money/territories`.
+ */
+import { currencyExponent } from './currency.js';
+import { formatScaled } from './decimal.js';
+import { ISO_NUMERIC_CODES } from './generated/iso4217-numeric.js';
+
+// ---------------------------------------------------------------------------------------------
+// Numeric codes
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * The ISO 4217 numeric code of an active currency, three digits as published: `'978'` for EUR,
+ * `'008'` for ALL. Card networks, ISO 8583 and some ISO 20022 messages carry currencies this way.
+ * `undefined` for a code ISO doesn't list (a custom or withdrawn currency).
+ */
+export function numericCode(currency: string): string | undefined {
+  return Object.hasOwn(ISO_NUMERIC_CODES, currency) ? ISO_NUMERIC_CODES[currency] : undefined;
+}
+
+let currenciesByNumeric: Map<string, string> | undefined;
+
+/**
+ * The active ISO 4217 currency with a numeric code: `currencyFromNumeric('978')` and
+ * `currencyFromNumeric(978)` are `'EUR'`, and `'008'`, `'8'` and `8` are all `'ALL'`. `undefined`
+ * for a number ISO doesn't assign; a value that isn't a whole number from 0 to 999 throws a
+ * RangeError.
+ */
+export function currencyFromNumeric(numeric: string | number): string | undefined {
+  const text = typeof numeric === 'number' ? String(numeric) : numeric.trim();
+  if (!/^\d{1,3}$/.test(text)) {
+    throw new RangeError(`Not an ISO 4217 numeric code: ${String(numeric)}`);
+  }
+  if (currenciesByNumeric === undefined) {
+    currenciesByNumeric = new Map();
+    for (const [currency, code] of Object.entries(ISO_NUMERIC_CODES)) {
+      currenciesByNumeric.set(code, currency);
+    }
+  }
+  return currenciesByNumeric.get(text.padStart(3, '0'));
+}
+
+// ---------------------------------------------------------------------------------------------
+// Minor unit
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * The size of the currency's minor unit, in major units, as an exact decimal string: `'0.01'` for
+ * EUR, `'1'` for JPY (no minor unit), `'0.001'` for KWD and BHD. It follows the exponent, so a
+ * currency registered with `defineCurrency` works too; an unknown code throws, as
+ * `currencyExponent` does. For the smallest coin, see `cashUnit` in `@ducatjs/money/cash`.
+ */
+export function minorUnit(currency: string): string {
+  return formatScaled(1, currencyExponent(currency));
+}
+
+// ---------------------------------------------------------------------------------------------
+// Names and symbols, from Intl
+// ---------------------------------------------------------------------------------------------
+
+const displayNames = /* @__PURE__ */ new Map<string, Intl.DisplayNames>();
+const symbolFormats = /* @__PURE__ */ new Map<string, Intl.NumberFormat>();
+
+function cached<T>(cache: Map<string, T>, key: string, build: () => T): T {
+  let value = cache.get(key);
+  if (value === undefined) {
+    // a handful of locales in practice; the bound keeps a server that sees many from growing
+    if (cache.size >= 64) {
+      cache.clear();
+    }
+    value = build();
+    cache.set(key, value);
+  }
+  return value;
+}
+
+/**
+ * The currency's name in a locale, from the runtime's `Intl.DisplayNames`: `currencyName('EUR',
+ * 'en')` is 'Euro' and `currencyName('EUR', 'de')` is 'Euro'; `currencyName('CHF', 'fr')` is 'franc
+ * suisse'. `undefined` when the runtime has no name for the code. Names follow the runtime's CLDR
+ * data, so they can differ between runtimes and versions.
+ */
+export function currencyName(currency: string, locale: string): string | undefined {
+  const names = cached(
+    displayNames,
+    locale,
+    () => new Intl.DisplayNames(locale, { type: 'currency', fallback: 'none' }),
+  );
+  return names.of(currency);
+}
+
+/** Options for `currencySymbol`. */
+export interface CurrencySymbolOptions {
+  /**
+   * 'symbol' (default) is the symbol the locale uses where it must not be ambiguous ('US$' in
+   * en-CA, 'CA$' in en-US); 'narrow' is the shortest form ('$'), as `Intl.NumberFormat`'s
+   * `narrowSymbol`.
+   */
+  readonly display?: 'symbol' | 'narrow';
+}
+
+/**
+ * The currency's symbol in a locale, from the runtime's `Intl.NumberFormat`: `currencySymbol('EUR',
+ * 'en-US')` is '€', `currencySymbol('USD', 'en-CA')` is 'US$', and `currencySymbol('USD', 'en-CA',
+ * { display: 'narrow' })` is '$'. A currency without a symbol in that locale gives its code.
+ */
+export function currencySymbol(
+  currency: string,
+  locale: string,
+  options?: CurrencySymbolOptions,
+): string {
+  const display = options?.display === 'narrow' ? 'narrowSymbol' : 'symbol';
+  const format = cached(
+    symbolFormats,
+    `${locale}\u0000${currency}\u0000${display}`,
+    () => new Intl.NumberFormat(locale, { style: 'currency', currency, currencyDisplay: display }),
+  );
+  const part = format.formatToParts(0).find((candidate) => candidate.type === 'currency');
+  return part?.value ?? currency;
+}

package/src/currency.ts

@@ -12,9 +12,34 @@ 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>>;
 
+// The exponents of the currencies this program can use. `@ducatjs/money/iso/<CODE>` and
+// `defineCurrency` add codes to `known` one at a time; `@ducatjs/money/iso` (which every entry except
+// `/fn` imports) makes the ISO table literal its prototype rather than copying it. That keeps the
+// lookup as fast as reading the literal directly: V8 folds a load through a stable prototype, while
+// a copy of 165 keys, or a null-prototype object, is a slow dictionary (#243 doubled fromMinor's
+// time that way). `known` has a prototype, so a value counts only when it's a number: `toString`
+// is a function and `__proto__` an object. A number someone puts on Object.prototype would count,
+// as it did when main read the ISO literal directly; the alternative is an own-property check on
+// every lookup.
+const known: Record<string, number> = {};
+
+function exponentOf(code: string): number | undefined {
+  const exponent = known[code];
+  return typeof exponent === 'number' ? exponent : undefined;
+}
+
+/** @internal Registers an ISO 4217 code; the generated `iso/<CODE>` modules call it. */
+export function isoCurrency(code: string, exponent: number): void {
+  known[code] = exponent;
+}
+
+/** @internal Registers every ISO 4217 code, for `@ducatjs/money/iso`. */
+export function registerIsoCurrencies(): void {
+  Object.setPrototypeOf(known, iso);
+}
+
 /**
  * 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.
@@ -26,31 +51,37 @@ export function defineCurrency(code: string, exponent: number): void {
   if (typeof iso[code] === 'number') {
     throw new TypeError(`${code} is an ISO 4217 currency and cannot be redefined`);
   }
-  const prev = custom.get(code);
+  // `known` has a prototype, where `__proto__` is a setter and `toString` a method
+  if (code in Object.prototype) {
+    throw new TypeError(`${code} can't be a currency code`);
+  }
+  const prev = exponentOf(code);
   if (prev !== undefined && prev !== exponent) {
     throw new TypeError(`${code} is already defined with exponent ${prev}`);
   }
-  custom.set(code, exponent);
+  known[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;
-  }
+  const exponent = exponentOf(code);
+  return exponent === undefined ? unknownCurrency(code) : exponent;
+}
+
+function unknownCurrency(code: string): never {
   throw new RangeError(
-    `Unknown currency "${code}" (not ISO 4217 and not registered with defineCurrency)`,
+    // true wherever it's thrown: with the root entry every ISO code is registered already
+    `Unknown currency "${code}" (ISO codes with /fn alone: import @ducatjs/money/iso; others: defineCurrency)`,
   );
 }
 
-/** Whether the code is an ISO 4217 currency or one registered with `defineCurrency`. */
+/**
+ * Whether the code is registered: an ISO 4217 code (every one wherever an entry other than `/fn` is
+ * imported; in a `/fn`-only program, the ones imported from `@ducatjs/money/iso`), or a code from
+ * `defineCurrency`.
+ */
 export function isCurrency(code: string): code is CurrencyCode {
-  return typeof iso[code] === 'number' || custom.has(code);
+  return exponentOf(code) !== undefined;
 }
 
 export {

package/src/decimal.ts

@@ -1,9 +1,11 @@
 // 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.
 
+import type { Fixed } from './fixed.js';
+
 /** 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);
+const MAXN = /* @__PURE__ */ BigInt(MAX_SAFE_MINOR);
 
 /**
  * An exact rational factor num/den (den > 0). `n`/`d` hold the same values as numbers when both are
@@ -18,8 +20,11 @@ export interface Ratio {
   readonly d: number;
 }
 
-/** Anything accepted where a multiplier, rate or percentage is expected. */
-export type Factor = number | bigint | string | Ratio;
+/**
+ * Anything accepted where a multiplier, rate or percentage is expected. A `Fixed` is read exactly,
+ * as its scaled integer over 10^scale.
+ */
+export type Factor = number | bigint | string | Ratio | Fixed;
 
 const POW10N: bigint[] = [];
 /** 10^exponent as a bigint, cached. */
@@ -108,7 +113,7 @@ 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());
+  const match = EXP_RE.exec(input);
   if (!match) {
     throw new SyntaxError(`Invalid decimal string "${input}"`);
   }
@@ -127,6 +132,53 @@ export function parseDecimal(input: string): { digits: bigint; scale: number } {
   return { digits: sign === '-' ? -digits : digits, scale };
 }
 
+/**
+ * A double holds 15 significant decimal digits faithfully (DBL_DIG): a number whose shortest form
+ * has no more than that is the decimal its author wrote. 0.1 + 0.2 reads back as
+ * 0.30000000000000004 and 1 / 0.52 as 1.9230769230769231 (17 digits): those are float artefacts.
+ */
+export const MAX_FAITHFUL_DIGITS = 15;
+
+/**
+ * A number's shortest decimal form, which must have at most 15 significant digits (see
+ * MAX_FAITHFUL_DIGITS). `fix` says what to do instead, for the error message.
+ */
+export function faithfulDecimal(value: number, fix: string): string {
+  // The shortest form has at most 15 digits exactly when rounding to 15 digits gives the same
+  // double back: shortest means the fewest digits that round-trip.
+  // Safe integers are exact whatever their digit count, and NaN and the infinities pass through
+  // for the caller's parser to reject. (Today's callers take safe integers on a path of their own.)
+  if (
+    !Number.isSafeInteger(value) &&
+    Number.isFinite(value) &&
+    Number(value.toPrecision(MAX_FAITHFUL_DIGITS)) !== value
+  ) {
+    throw new RangeError(
+      `${value} has more than ${MAX_FAITHFUL_DIGITS} significant digits; ${fix}`,
+    );
+  }
+  return String(value);
+}
+
+/**
+ * Returns `scale` if it is a valid scale: an integer from 0 to MAX_DECIMAL_SCALE. Scales are never
+ * negative: round to tens or hundreds with an increment (`roundToIncrement`, a rounding policy).
+ */
+export function checkScale(scale: number): number {
+  // On hot paths (Fixed, ExactMoney, policies), so one comparison does most of the work: `>>> 0`
+  // leaves an integer from 0 to 2^32 - 1 unchanged and changes negatives, fractions, NaN and the
+  // infinities.
+  if (scale >>> 0 !== scale || scale > MAX_DECIMAL_SCALE) {
+    invalidScale(scale);
+  }
+  return scale;
+}
+
+// Kept out of checkScale, so the check stays small enough to inline.
+function invalidScale(scale: number): never {
+  throw new RangeError(`Invalid scale ${scale}: use an integer from 0 to ${MAX_DECIMAL_SCALE}`);
+}
+
 function gcd(left: bigint, right: bigint): bigint {
   if (left < 0n) {
     left = -left;
@@ -165,12 +217,25 @@ function makeRatio(num: bigint, den: bigint): Ratio {
   return { num, den, n: safeNumberOrNaN(num), d: safeNumberOrNaN(den) };
 }
 
-const cache = new Map<string, Ratio>();
+/**
+ * The error for a value that isn't a factor. Untyped code passes all sorts here (a Fixed, a
+ * `{ num: 1, den: 2 }` of numbers, null), and without this check they fail later with an unrelated
+ * BigInt error, or are returned as if they were a Ratio.
+ */
+function notAFactor(value: unknown): TypeError {
+  return new TypeError(
+    `Expected a number, bigint, decimal string, Ratio or Fixed, got ${typeof value} ${String(value)}`,
+  );
+}
+
+const cache = /* @__PURE__ */ 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.
+ * Numbers are taken at their shortest decimal representation: `ratio(0.1)` is exactly 1/10. One
+ * with more than 15 significant digits (`1 / 0.52` is 1.9230769230769231) throws a RangeError,
+ * since a float artefact can't be told from a decimal someone wrote; pass a string instead.
  * Pre-build ratios you use in hot loops; strings are also cached (up to 1024 entries).
  */
 export function ratio(value: Factor, den?: Factor): Ratio {
@@ -187,7 +252,27 @@ export function ratio(value: Factor, den?: Factor): Ratio {
     );
   }
   if (typeof value === 'object') {
-    return value;
+    // A Ratio from ratio() passes straight through: the hot path for factors built once. A
+    // hand-made { num, den } of bigints is rebuilt, so it is reduced and has `n` and `d`.
+    const asRatio = value as Partial<Ratio> | null;
+    if (typeof asRatio?.num === 'bigint' && typeof asRatio.den === 'bigint') {
+      return typeof asRatio.n === 'number' && typeof asRatio.d === 'number'
+        ? (asRatio as Ratio)
+        : makeRatio(asRatio.num, asRatio.den);
+    }
+    // A Fixed, read through its scaled form rather than `instanceof`, so the core doesn't load
+    // `/fixed`. The scale is checked because a lookalike object could carry any value.
+    const scaled = (value as Partial<Fixed> | null)?.value;
+    const scale = (value as Partial<Fixed> | null)?.scale;
+    if (
+      (typeof scaled === 'bigint' || Number.isSafeInteger(scaled)) &&
+      typeof scale === 'number' &&
+      scale >>> 0 === scale &&
+      scale <= MAX_DECIMAL_SCALE
+    ) {
+      return makeRatio(BigInt(scaled as number | bigint), pow10n(scale));
+    }
+    throw notAFactor(value);
   }
   if (typeof value === 'number') {
     if (Number.isSafeInteger(value)) {
@@ -199,16 +284,19 @@ export function ratio(value: Factor, den?: Factor): Ratio {
     if (!Number.isFinite(value)) {
       throw new RangeError(`Invalid factor ${value}`);
     }
-    value = String(value);
+    value = faithfulDecimal(value, 'pass it as a string');
   }
   if (typeof value === 'bigint') {
     return makeRatio(value, 1n);
   }
+  if (typeof value !== 'string') {
+    throw notAFactor(value);
+  }
   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());
+      cached = ratio(value.slice(0, slash), value.slice(slash + 1));
     } else {
       const { digits, scale } = parseDecimal(value);
       cached = makeRatio(digits, pow10n(scale));
@@ -242,7 +330,7 @@ export function ratioToDecimal(value: Ratio): string | null {
 }
 
 // Zero padding for the fraction digits, built once: indexing it is faster than padStart.
-const ZPAD = Array.from({ length: 16 }, (_, length) => '0'.repeat(length));
+const ZPAD = /* @__PURE__ */ 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 {