@ducatjs/money 0.2.1 → 0.3.0

package/src/plugins/core.ts

@@ -0,0 +1,195 @@
+/**
+ * The core Money methods (`a.add(b)`, `m.round('halfEven')`, `m.toDecimal()`...), installed on
+ * import. The root entry (`@ducatjs/money`) and `/all` import this, so methods are always there for
+ * them; `@ducatjs/money/fn` doesn't, so a program written with plain functions keeps only the
+ * functions it uses. Each method is a thin wrapper over the free function of the same name, so
+ * `a.add(b)` and `add(a, b)` are the same code. Operands are Money only: a bare number is never
+ * guessed to mean major or minor units.
+ */
+// every ISO 4217 code, so the root entry and /all take any code as a string
+import './iso.js';
+import { formatScaled, type Factor } from '../decimal.js';
+import type { Money } from '../index.js';
+import {
+  abs,
+  add,
+  clamp,
+  compare,
+  divide,
+  equals,
+  installCoreMethods,
+  identical,
+  majorPart,
+  max,
+  min,
+  minorPart,
+  multiply,
+  negate,
+  round,
+  sign,
+  subtract,
+  toMinor,
+  toMinorNumber,
+  toScale,
+  type RoundingInput,
+  type RoundingPolicy,
+} from '../money.js';
+import type { RoundingMode } from '../rounding.js';
+import { toBigInt } from '../scale.js';
+
+declare module '../index.js' {
+  interface Money<C extends string> {
+    /** this + other (same currency; any scale) */
+    add(other: Money<C>): Money<C>;
+    /** this - other */
+    subtract(other: Money<C>): Money<C>;
+    /**
+     * this * factor, rounded to this scale. `factor` is exact: integer, decimal string ('1.075'),
+     * bigint or ratio().
+     */
+    multiply(factor: Factor, rounding?: RoundingInput): Money<C>;
+    /** this / divisor, rounded to this scale (or to a policy's scale and increment) */
+    divide(divisor: Factor, rounding?: RoundingInput): Money<C>;
+    negate(): Money<C>;
+    abs(): Money<C>;
+    /**
+     * Rounds to the currency's exponent (or `scale`), or to a rounding policy. A scale is never
+     * negative; round to tens or hundreds with a policy's `increment` or `roundToIncrement`.
+     */
+    round(rounding: RoundingMode, scale?: number): Money<C>;
+    round(policy: RoundingPolicy): Money<C>;
+    /**
+     * Changes the scale (an integer from 0 to 1000); decreasing it rounds (default 'halfExpand').
+     * For tens or hundreds, use an increment: a rounding policy or `roundToIncrement`.
+     */
+    toScale(scale: number, rounding?: RoundingMode): Money<C>;
+    /** -1, 0 or 1; throws on currency mismatch */
+    compare(other: Money<C>): -1 | 0 | 1;
+    /** same currency and value; a different currency is simply not equal */
+    equals(other: Money): boolean;
+    lessThan(other: Money<C>): boolean;
+    lessThanOrEqual(other: Money<C>): boolean;
+    greaterThan(other: Money<C>): boolean;
+    greaterThanOrEqual(other: Money<C>): boolean;
+    isZero(): boolean;
+    isPositive(): boolean;
+    isNegative(): boolean;
+    sign(): -1 | 0 | 1;
+    min(...others: Money<C>[]): Money<C>;
+    max(...others: Money<C>[]): Money<C>;
+    clamp(lo: Money<C>, hi: Money<C>): Money<C>;
+    /** Same currency, value and scale: 1.0 EUR is not identical to 1.00 EUR. */
+    identical(other: Money): boolean;
+    /**
+     * Applies `operation` to this amount and returns its result, so a rounding policy or a
+     * conversion reads as one step in a chain: `price.multiply('1.075').with(toCash)`.
+     */
+    with<R>(operation: (money: Money<C>) => R): R;
+    /** The whole major units, truncated toward zero: 12 for 12.34 EUR, -12 for -12.34 EUR. */
+    majorPart(): number | bigint;
+    /** The rest in 10^-scale units, with the amount's sign: 34 for 12.34 EUR, -34 for -12.34. */
+    minorPart(): number | bigint;
+    /** Exact decimal string in major units: "12.34" */
+    toDecimal(): string;
+    /**
+     * Units of the currency's minor unit as a bigint (cents for EUR), for BIGINT columns. Exact at
+     * any scale; throws RoundingError if the amount has non-zero digits below the minor unit.
+     */
+    toMinor(): bigint;
+    /** Like `toMinor()`, as a number; also throws a RangeError beyond 2^53. */
+    toMinorNumber(): number;
+    /** Units of 10^-scale as a bigint: 12340n for 12.340 EUR at scale 3. Pair it with the scale. */
+    toScaledUnits(): bigint;
+  }
+}
+
+installCoreMethods({
+  add(this: Money, other: Money) {
+    return add(this, other);
+  },
+  subtract(this: Money, other: Money) {
+    return subtract(this, other);
+  },
+  multiply(this: Money, factor: Factor, rounding?: RoundingInput) {
+    return multiply(this, factor, rounding);
+  },
+  divide(this: Money, divisor: Factor, rounding?: RoundingInput) {
+    return divide(this, divisor, rounding);
+  },
+  negate(this: Money) {
+    return negate(this);
+  },
+  abs(this: Money) {
+    return abs(this);
+  },
+  round(this: Money, rounding: RoundingInput, scale?: number) {
+    // the free function handles both; the cast only picks its implementation signature
+    return round(this, rounding as RoundingMode, scale);
+  },
+  toScale(this: Money, scale: number, rounding?: RoundingMode) {
+    return toScale(this, scale, rounding);
+  },
+  compare(this: Money, other: Money) {
+    return compare(this, other);
+  },
+  equals(this: Money, other: Money) {
+    return equals(this, other);
+  },
+  lessThan(this: Money, other: Money) {
+    return compare(this, other) < 0;
+  },
+  lessThanOrEqual(this: Money, other: Money) {
+    return compare(this, other) <= 0;
+  },
+  greaterThan(this: Money, other: Money) {
+    return compare(this, other) > 0;
+  },
+  greaterThanOrEqual(this: Money, other: Money) {
+    return compare(this, other) >= 0;
+  },
+  isZero(this: Money) {
+    return this.minor == 0;
+  },
+  isPositive(this: Money) {
+    return this.minor > 0;
+  },
+  isNegative(this: Money) {
+    return this.minor < 0;
+  },
+  sign(this: Money) {
+    return sign(this);
+  },
+  min(this: Money, ...others: Money[]) {
+    return min(this, ...others);
+  },
+  max(this: Money, ...others: Money[]) {
+    return max(this, ...others);
+  },
+  clamp(this: Money, lo: Money, hi: Money) {
+    return clamp(this, lo, hi);
+  },
+  identical(this: Money, other: Money) {
+    return identical(this, other);
+  },
+  with<R>(this: Money, operation: (money: Money) => R) {
+    return operation(this);
+  },
+  majorPart(this: Money) {
+    return majorPart(this);
+  },
+  minorPart(this: Money) {
+    return minorPart(this);
+  },
+  toDecimal(this: Money) {
+    return formatScaled(this.minor, this.scale);
+  },
+  toMinor(this: Money) {
+    return toMinor(this);
+  },
+  toMinorNumber(this: Money) {
+    return toMinorNumber(this);
+  },
+  toScaledUnits(this: Money) {
+    return toBigInt(this.minor);
+  },
+});

package/src/plugins/exact.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/exact`: exact rational amounts that round once. Importing this module adds
  * `Money#exact`.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { exact, type ExactMoney } from '../exact.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';

package/src/plugins/fixed-money.ts

@@ -0,0 +1,57 @@
+/**
+ * `@ducatjs/money/fixed/money`: Fixed and Money together. Everything in `@ducatjs/money/fixed`, plus
+ * the conversions between the two; importing this module adds `Money#toFixedPoint()` and
+ * `Fixed#toMoney()`.
+ */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
+import { Fixed } from '../fixed.js';
+import { fixedToMoney, moneyToFixed } from '../fixed-money.js';
+import type { CurrencyInput, Money } from '../index.js';
+import { extendMoney } from '../money.js';
+import type { RoundingMode } from '../rounding.js';
+
+export * from '../fixed.js';
+export * from '../fixed-money.js';
+
+declare module '../index.js' {
+  interface Money<C extends string> {
+    /**
+     * The exact Fixed of this amount, at its scale: `money('12.34', 'EUR').toFixedPoint()` is
+     * 12.34. Not `toFixed`, which Number, decimal.js and big.js all use for `toFixed(places):
+     * string`.
+     */
+    toFixedPoint(): Fixed;
+  }
+}
+
+declare module '../fixed.js' {
+  interface Fixed {
+    /**
+     * Money in `currency`, at its exponent. Throws RoundingError when that would drop digits,
+     * unless `rounding` is given: `fixed('1.005').toMoney('EUR', 'halfEven')` is 1.00 EUR.
+     */
+    toMoney<C extends CurrencyInput>(currency: C, rounding?: RoundingMode): Money<C>;
+  }
+}
+
+extendMoney(
+  {
+    toFixedPoint(this: Money) {
+      return moneyToFixed(this);
+    },
+  },
+  { owner: '@ducatjs/money/fixed/money' },
+);
+
+// Non-enumerable, like a class method. Loading the module again replaces it with the same function.
+// This is outside extendMoney's owner registry, which is for Money; it's fine while this module is
+// the only one that defines Fixed#toMoney.
+Object.defineProperty(Fixed.prototype, 'toMoney', {
+  value: function toMoney(this: Fixed, currency: CurrencyInput, rounding?: RoundingMode) {
+    return fixedToMoney(this, currency, rounding);
+  },
+  writable: true,
+  configurable: true,
+  enumerable: false,
+});

package/src/plugins/format.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/format`: locale formatting through Intl. Importing this module adds the methods
  * below.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { format, formatToParts } from '../format.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';

package/src/plugins/iso.ts

@@ -0,0 +1,9 @@
+/**
+ * `@ducatjs/money/iso`: registers every ISO 4217 currency. Every entry that builds or reads Money
+ * imports it, so this matters only for `@ducatjs/money/fn`, which doesn't: a `/fn` program imports
+ * it to use any ISO code, or `@ducatjs/money/iso/EUR` (one module per code) to carry only the
+ * currencies it uses.
+ */
+import { registerIsoCurrencies } from '../currency.js';
+
+registerIsoCurrencies();

package/src/plugins/klarna.ts

@@ -1,4 +1,6 @@
 /** `@ducatjs/money/klarna`: Klarna's amount view. Importing this module adds `toKlarna`. */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { toKlarna, type KlarnaAmountOptions } from '../klarna.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';

package/src/plugins/math.ts

@@ -0,0 +1,43 @@
+/**
+ * `@ducatjs/money/math`: averages, ratios between amounts, integral division and scale trimming.
+ * Importing this module adds the methods below; `average` is a plain function, like `sum`.
+ */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
+import type { Ratio } from '../decimal.js';
+import { divideToIntegral, ratioOf, remainder, trimScale } from '../math.js';
+import type { Money } from '../index.js';
+import { extendMoney } from '../money.js';
+
+export * from '../math.js';
+
+declare module '../index.js' {
+  interface Money<C extends string> {
+    /** The exact ratio this / other, e.g. `part.ratioOf(total)` */
+    ratioOf(other: Money<C>): Ratio;
+    /** How many whole times `divisor` fits into this, truncated toward zero */
+    divideToIntegral(divisor: Money<C>): number | bigint;
+    /** What is left after taking `divisor` out a whole number of times (this amount's sign) */
+    remainder(divisor: Money<C>): Money<C>;
+    /** The smallest scale, not below `minimumScale` (default the ISO exponent), that is exact */
+    trimScale(minimumScale?: number): Money<C>;
+  }
+}
+
+extendMoney(
+  {
+    ratioOf(this: Money, other: Money) {
+      return ratioOf(this, other);
+    },
+    divideToIntegral(this: Money, divisor: Money) {
+      return divideToIntegral(this, divisor);
+    },
+    remainder(this: Money, divisor: Money) {
+      return remainder(this, divisor);
+    },
+    trimScale(this: Money, minimumScale?: number) {
+      return trimScale(this, minimumScale);
+    },
+  },
+  { owner: '@ducatjs/money/math' },
+);

package/src/plugins/paypal.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/paypal`: PayPal's amount view. Importing this module adds `toPayPal` and
  * `toPayPalValue`.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';
 import { toPayPal, toPayPalValue, type PayPalAmountOptions } from '../paypal.js';

package/src/plugins/prisma.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/prisma`: Prisma and SQL column helpers. Importing this module adds
  * `toDecimalValue`.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';
 import { toDecimalValue } from '../prisma.js';

package/src/plugins/stripe.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/stripe`: Stripe's minor-unit view. Importing this module adds `toStripe` and
  * `toStripeAmount`.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';
 import { toStripe, toStripeAmount, type StripeAmountOptions } from '../stripe.js';

package/src/plugins/tax.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/tax`: percentages, discounts and tax breakdowns. Importing this module adds the
  * methods below.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import type { Factor } from '../decimal.js';
 import type { Money } from '../index.js';
 import { extendMoney, type RoundingInput } from '../money.js';

package/src/policy.ts

@@ -5,7 +5,7 @@
  * this entry (or `cashPolicy` from `@ducatjs/money/cash`).
  */
 import { currencyExponent, isCurrency } from './currency.js';
-import { MAX_DECIMAL_SCALE, type Ratio } from './decimal.js';
+import { checkScale, type Ratio } from './decimal.js';
 import {
   CurrencyMismatchError,
   multiply,
@@ -31,8 +31,8 @@ export interface RoundingPolicyOptions {
   readonly currency?: string;
 }
 
-const ONE = ratio(1);
-const MODES = new Set<unknown>(Object.values(Rounding));
+const ONE = /* @__PURE__ */ ratio(1);
+const MODES = /* @__PURE__ */ new Set<unknown>(/* @__PURE__ */ Object.values(Rounding));
 
 /**
  * Builds a reusable rounding policy (see `RoundingPolicy`). The options are checked here, once, so
@@ -47,11 +47,8 @@ export function roundingPolicy(options: RoundingPolicyOptions = {}): RoundingPol
   const rounding = options.rounding ?? DEFAULT_ROUNDING;
   const currency = options.currency;
 
-  if (
-    scale !== undefined &&
-    !(Number.isInteger(scale) && scale >= 0 && scale <= MAX_DECIMAL_SCALE)
-  ) {
-    throw new RangeError(`Invalid scale ${scale}`);
+  if (scale !== undefined) {
+    checkScale(scale);
   }
   if (!(Number.isSafeInteger(increment) && increment >= 1)) {
     throw new RangeError(`Invalid increment ${increment}; it must be a positive integer`);

package/src/pricing.ts

@@ -0,0 +1,155 @@
+/**
+ * `@ducatjs/money/pricing`: retail price endings ("charm pricing") and, from `tiers.ts`, tiered
+ * and volume pricing. A rule such as "end in .99, rounding up" is a plain value passed explicitly,
+ * like a rounding policy, and every result is exact.
+ */
+import { formatScaled, MAX_DECIMAL_SCALE, parseDecimal, pow10n } from './decimal.js';
+import { make, type Money } from './money.js';
+import { divideAndRound, divideAndRoundBigint, Rounding, type RoundingMode } from './rounding.js';
+
+const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+const MODES = /* @__PURE__ */ new Set<unknown>(/* @__PURE__ */ Object.values(Rounding));
+
+/** Options for `priceEnding`. */
+export interface PriceEndingOptions {
+  /**
+   * What prices end in, in major units, as a decimal string or an integer: `'0.99'` for 23.99,
+   * `'9.90'` (with `step: 10`) for 29.90, `0` (with `step: 5`) for whole multiples of 5. It must be
+   * at least 0 and less than `step`.
+   */
+  readonly ending: string | number;
+  /**
+   * The distance between two allowed prices, in major units (default 1): `'0.99'` with step 1 allows
+   * 22.99, 23.99, 24.99, ...; with step `'0.5'`, `'0.49'` allows 23.49, 23.99, 24.49, ...
+   */
+  readonly step?: string | number;
+  /**
+   * Which allowed price to pick: 'ceil' (default) the nearest one at or above the price, 'floor'
+   * the nearest at or below, 'halfCeil' the nearest (ties go up), or any other rounding mode, applied
+   * to the count of steps. 'unnecessary' throws unless the price already has the ending.
+   */
+  readonly rounding?: RoundingMode;
+}
+
+/**
+ * A price-ending rule, built by `priceEnding()`. It is a function from an amount to the amount
+ * with the ending, so `price.with(rule)` and `prices.map(rule)` work.
+ */
+export interface PriceEnding {
+  /** `money` moved to the rule's ending, at `money`'s scale. */
+  <C extends string>(money: Money<C>): Money<C>;
+  /** The ending, as an exact decimal string in major units. */
+  readonly ending: string;
+  /** The step between allowed prices, as an exact decimal string in major units. */
+  readonly step: string;
+  /** How the allowed price is picked. */
+  readonly rounding: RoundingMode;
+}
+
+/** A decimal in major units: `digits` × 10^-scale. */
+interface Decimal {
+  readonly digits: bigint;
+  readonly scale: number;
+}
+
+function readDecimal(name: string, value: string | number): Decimal {
+  if (typeof value === 'number') {
+    // integers only: a non-integer number would be read through its float form
+    if (!Number.isSafeInteger(value)) {
+      throw new RangeError(`Invalid ${name} ${value}; pass a decimal string such as '0.99'`);
+    }
+    return { digits: BigInt(value), scale: 0 };
+  }
+  if (typeof value !== 'string') {
+    throw new TypeError(`Invalid ${name} ${String(value)}`);
+  }
+  return parseDecimal(value);
+}
+
+/** The decimal in 10^-scale units, or undefined if it has more decimals than `scale`. */
+function unitsAt(value: Decimal, scale: number): bigint | undefined {
+  if (value.scale <= scale) {
+    return value.digits * pow10n(scale - value.scale);
+  }
+  const divisor = pow10n(value.scale - scale);
+  return value.digits % divisor === 0n ? value.digits / divisor : undefined;
+}
+
+function decimalString(value: Decimal): string {
+  return formatScaled(value.digits, value.scale);
+}
+
+/**
+ * Builds a price-ending rule: the allowed prices are `ending + k × step` for every integer k, and
+ * the rule moves an amount to one of them, chosen by `rounding` (default 'ceil', the next allowed
+ * price at or above). The options are checked here, once.
+ *
+ *     const charm = priceEnding({ ending: '0.99' })
+ *     money('23.41', 'EUR').with(charm)                         // 23.99 EUR
+ *     priceEnding({ ending: '9.90', step: 10 })                 // 19.90, 29.90, ...
+ *     priceEnding({ ending: 0, step: 5, rounding: 'halfCeil' }) // the nearest 5
+ *
+ * The result keeps the amount's scale. An ending or step with more decimals than the amount (0.99
+ * for a whole-yen price) throws a RangeError when the rule is applied.
+ */
+export function priceEnding(options: PriceEndingOptions): PriceEnding {
+  const ending = readDecimal('ending', options.ending);
+  const step = readDecimal('step', options.step ?? 1);
+  const rounding = options.rounding ?? 'ceil';
+
+  if (step.digits <= 0n) {
+    throw new RangeError(`Invalid step ${decimalString(step)}; it must be positive`);
+  }
+  // compare at a common scale: 0 <= ending < step
+  const commonScale = Math.max(ending.scale, step.scale);
+  const endingUnits = unitsAt(ending, commonScale)!;
+  const stepUnits = unitsAt(step, commonScale)!;
+  if (endingUnits < 0n || endingUnits >= stepUnits) {
+    throw new RangeError(
+      `Invalid ending ${decimalString(ending)}; it must be at least 0 and less than the step ${decimalString(step)}`,
+    );
+  }
+  if (!MODES.has(rounding)) {
+    throw new RangeError(`Invalid rounding mode ${String(rounding)}`);
+  }
+
+  const apply = <C extends string>(money: Money<C>): Money<C> => {
+    const scale = money.scale;
+    const offset = unitsAt(ending, scale);
+    const stride = unitsAt(step, scale);
+    if (offset === undefined || stride === undefined || scale > MAX_DECIMAL_SCALE) {
+      throw new RangeError(
+        `A price ending ${decimalString(ending)} in steps of ${decimalString(step)} needs more than ${scale} decimal places for ${money.currency}`,
+      );
+    }
+
+    // The count of whole steps above the ending, rounded once, then back to an amount:
+    // ending + round((money - ending) / step) × step.
+    const minor = money.minor;
+    if (typeof minor === 'number') {
+      const offsetNumber = Number(offset);
+      const strideNumber = Number(stride);
+      const distance = minor - offsetNumber;
+      // With |distance| + stride within the safe range, |steps × stride| is at most that sum, so
+      // the product is exact; the sum with the offset is then checked like any other addition (a
+      // float sum beyond the safe range never rounds back into it).
+      if (distance + strideNumber <= MAX_SAFE_MINOR && distance - strideNumber >= -MAX_SAFE_MINOR) {
+        const steps = divideAndRound(distance, strideNumber, rounding);
+        const result = offsetNumber + steps * strideNumber;
+        if (result <= MAX_SAFE_MINOR && result >= -MAX_SAFE_MINOR) {
+          return make(money.currency, result + 0, scale);
+        }
+      }
+    }
+    const steps = divideAndRoundBigint(BigInt(minor) - offset, stride, rounding);
+    return make(money.currency, offset + steps * stride, scale);
+  };
+
+  return Object.assign(apply, {
+    ending: decimalString(ending),
+    step: decimalString(step),
+    rounding,
+  }) as PriceEnding;
+}
+
+export * from './tiers.js';

package/src/prisma.ts

@@ -14,6 +14,7 @@ import {
   money,
   toDecimal,
   toMinor,
+  toScaledUnits,
   type CurrencyInput,
   type Money,
   type MoneyOptions,
@@ -185,7 +186,11 @@ export function toMinorColumns(
   if (options === undefined) {
     return { [amount]: toMinorAtIsoScale(money), [currency]: money.currency };
   }
-  return { [amount]: toMinor(money), [currency]: money.currency, [options.scale]: money.scale };
+  return {
+    [amount]: toScaledUnits(money),
+    [currency]: money.currency,
+    [options.scale]: money.scale,
+  };
 }
 
 function toMinorAtIsoScale(money: Money): bigint {

package/src/provider.ts

@@ -358,8 +358,8 @@ export function snapshots(
 
       for (let i = 0; i <= lookback; i++) {
         const day = new Date(firstDayMs - i * DAY_MS).toISOString().slice(0, 10);
-        // Sequential on purpose: stop at the first day that has a table, without loading older
-        // days. oxlint-disable-next-line no-await-in-loop
+        // Sequential on purpose: stop at the first day that has a table, without loading older days.
+        // oxlint-disable-next-line no-await-in-loop
         const table = await loadDay(day);
         // A table not yet published at the instant asked for is passed over like a missing one.
         const availableAt = (table as Partial<RateTable> | undefined)?.availableAt;

package/src/rate-text.ts

@@ -3,7 +3,18 @@
 
 // What sources write for "no value this day": blank (ECB CSV, BoE), ND (Fed H.10), N/A (ECB CSV),
 // NA (IMF), and dashes and NaN in other files. Compared upper-cased.
-const MISSING_MARKERS = new Set(['', 'ND', 'N/A', 'NA', 'N.A.', '-', '–', '—', 'NAN', 'NULL']);
+const MISSING_MARKERS = /* @__PURE__ */ new Set([
+  '',
+  'ND',
+  'N/A',
+  'NA',
+  'N.A.',
+  '-',
+  '–',
+  '—',
+  'NAN',
+  'NULL',
+]);
 const PLAIN_DECIMAL = /^\d+(?:\.\d+)?$/;
 
 /**
@@ -149,3 +160,18 @@ export function addDayRate(
 export function newestFirst<T extends { readonly asOf?: string }>(tables: T[]): T[] {
   return tables.sort((table, other) => other.asOf!.localeCompare(table.asOf!));
 }
+
+/**
+ * @internal Checks an `availableAt` option, which untyped code could pass as anything: a string or a
+ * Date would otherwise be ignored on an empty file and fail obscurely, as "not a function", on the
+ * first day. Called once, before any parsing or fetching.
+ */
+export function checkAvailableAt(availableAt: unknown): void {
+  if (
+    availableAt !== undefined &&
+    typeof availableAt !== 'boolean' &&
+    typeof availableAt !== 'function'
+  ) {
+    throw new TypeError(`availableAt must be a boolean or a function, got ${typeof availableAt}`);
+  }
+}

package/src/rate.ts

@@ -1,7 +1,6 @@
 // Exchange rates as exact rationals with metadata. A Rate never loses digits: inverses,
 // compositions and margins are exact products of ratios, and rounding happens once, when an amount
 // is converted.
-import { currencyExponent } from './currency.js';
 import {
   formatScaled,
   POW10,
@@ -15,6 +14,7 @@ import {
 import {
   CurrencyMismatchError,
   make,
+  resolveScale,
   roundWithPolicy,
   type CurrencyInput,
   type Money,
@@ -410,7 +410,7 @@ export class Rate<From extends string = string, To extends string = string> {
     if (typeof rounding === 'function') {
       return convertWithPolicy(money, this.to, this.ratio, rounding, options);
     }
-    const scale = options?.scale ?? currencyExponent(this.to);
+    const scale = resolveScale(this.to, options?.scale);
     const minor = multiplyByRatioAtScale(money.minor, this.ratio, scale - money.scale, rounding);
     return make(this.to, minor, scale);
   }