@ducatjs/money 0.0.0-stage → 0.1.0

package/src/plugins/stripe.ts

@@ -0,0 +1,29 @@
+/**
+ * `@ducatjs/money/stripe`: Stripe's minor-unit view. Importing this module adds `toStripe` and
+ * `toStripeAmount`.
+ */
+import { extendMoney, type Money } from '../money.js';
+import { toStripe, toStripeAmount, type StripeAmountOptions } from '../stripe.js';
+
+export * from '../stripe.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** The integer `amount` to send to Stripe: `money('5', 'ISK').toStripeAmount()` is 500. */
+    toStripeAmount(options?: StripeAmountOptions): number;
+    /** `{ amount, currency }` with Stripe's lowercase currency code, ready for a PaymentIntent. */
+    toStripe(options?: StripeAmountOptions): { amount: number; currency: string };
+  }
+}
+
+extendMoney(
+  {
+    toStripeAmount(this: Money, options?: StripeAmountOptions) {
+      return toStripeAmount(this, options);
+    },
+    toStripe(this: Money, options?: StripeAmountOptions) {
+      return toStripe(this, options);
+    },
+  },
+  { owner: '@ducatjs/money/stripe' },
+);

package/src/plugins/tax.ts

@@ -0,0 +1,41 @@
+/**
+ * `@ducatjs/money/tax`: percentages, discounts and tax breakdowns. Importing this module adds the
+ * methods below.
+ */
+import type { Factor } from '../decimal.js';
+import { extendMoney, type Money } from '../money.js';
+import type { RoundingMode } from '../rounding.js';
+import { addTax, discount, extractTax, percentage, type TaxBreakdown } from '../tax.js';
+
+export * from '../tax.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** `percent`% of this, e.g. `price.percentage(15, 'halfEven')` */
+    percentage(percent: Factor, rounding?: RoundingMode): Money<C>;
+    /** this minus `percent`% */
+    discount(percent: Factor, rounding?: RoundingMode): Money<C>;
+    /** Treats this as net: `{ net, tax, gross }`, net + tax = gross exactly. */
+    addTax(percent: Factor, rounding?: RoundingMode): TaxBreakdown<C>;
+    /** Treats this as gross: `{ net, tax, gross }`, net + tax = gross exactly. */
+    extractTax(percent: Factor, rounding?: RoundingMode): TaxBreakdown<C>;
+  }
+}
+
+extendMoney(
+  {
+    percentage(this: Money, percent: Factor, rounding?: RoundingMode) {
+      return percentage(this, percent, rounding);
+    },
+    discount(this: Money, percent: Factor, rounding?: RoundingMode) {
+      return discount(this, percent, rounding);
+    },
+    addTax(this: Money, percent: Factor, rounding?: RoundingMode) {
+      return addTax(this, percent, rounding);
+    },
+    extractTax(this: Money, percent: Factor, rounding?: RoundingMode) {
+      return extractTax(this, percent, rounding);
+    },
+  },
+  { owner: '@ducatjs/money/tax' },
+);

package/src/prisma.ts

@@ -0,0 +1,118 @@
+/**
+ * Prisma / SQL interop with no dependency on @prisma/client (works with any Decimal class that has
+ * toFixed(): Prisma.Decimal, decimal.js, big.js).
+ *
+ * Storage options (see README "Databases"):
+ *  1. two columns: amount_minor BIGINT + currency CHAR(3)
+ *     -> minorMoneyField / toMinorColumns
+ *  2. a DECIMAL/NUMERIC column (+ a currency column or constant)
+ *     -> decimalMoneyField / toDecimalValue
+ */
+import {
+  fromMinor,
+  money,
+  toDecimal,
+  toMinor,
+  type CurrencyInput,
+  type Money,
+  type MoneyOptions,
+} from './money.js';
+
+/** Structural type of Prisma.Decimal / decimal.js / big.js values. */
+export interface DecimalLike {
+  toFixed(): string;
+}
+
+/**
+ * Money from a Decimal (or decimal string) column. Exact; throws if it has more decimals than the
+ * currency.
+ */
+export function fromDecimal<C extends CurrencyInput>(
+  value: DecimalLike | string,
+  currency: C,
+  options?: MoneyOptions,
+): Money<C> {
+  return money(typeof value === 'string' ? value : value.toFixed(), currency, options);
+}
+
+/** A Decimal for a NUMERIC column: toDecimalValue(m, Prisma.Decimal). */
+export function toDecimalValue<D>(money: Money, Decimal: new (value: string) => D): D {
+  return new Decimal(toDecimal(money));
+}
+
+type Row<A extends string, V> = { [P in A]: V };
+
+/**
+ * A Prisma result-extension field that exposes a Money built from `amount_minor` + `currency`
+ * columns:
+ *
+ *     const db = new PrismaClient().$extends({
+ *       result: { order: { total: minorMoneyField('totalMinor', 'currency') } },
+ *     });
+ *     (await db.order.findFirstOrThrow()).total   // Money
+ */
+export function minorMoneyField<const A extends string, const K extends string>(
+  amount: A,
+  currency: K,
+) {
+  return {
+    needs: { [amount]: true, [currency]: true } as { [P in A | K]: true },
+    compute: (row: Row<A, bigint | number> & Row<K, string>): Money =>
+      fromMinor(row[amount], row[currency]),
+  };
+}
+
+/**
+ * A Prisma result-extension field for a Decimal column, with the currency taken from another column
+ * (`{ currencyField: 'currency' }`) or fixed (`{ currency: 'EUR' }`).
+ */
+export function decimalMoneyField<const A extends string, const K extends string>(
+  amount: A,
+  currency: { currencyField: K },
+): { needs: { [P in A | K]: true }; compute: (row: Row<A, DecimalLike> & Row<K, string>) => Money };
+export function decimalMoneyField<const A extends string, const C extends CurrencyInput>(
+  amount: A,
+  currency: { currency: C },
+): { needs: { [P in A]: true }; compute: (row: Row<A, DecimalLike>) => Money<C> };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function decimalMoneyField(
+  amount: string,
+  currencySource: { currencyField: string } | { currency: string },
+): { needs: Record<string, true>; compute: (row: any) => Money } {
+  if ('currencyField' in currencySource) {
+    return {
+      needs: { [amount]: true, [currencySource.currencyField]: true },
+      compute: (row: Record<string, unknown>) =>
+        fromDecimal(row[amount] as DecimalLike, row[currencySource.currencyField] as string),
+    };
+  }
+  return {
+    needs: { [amount]: true },
+    compute: (row: Record<string, unknown>) =>
+      fromDecimal(row[amount] as DecimalLike, currencySource.currency),
+  };
+}
+
+/**
+ * Column values for writes: `data: { ...toMinorColumns(total, 'totalMinor', 'currency') }`.
+ * Minor units are a bigint (Prisma BigInt). Throws if the value has a non-standard scale, because
+ * the column cannot record it.
+ */
+export function toMinorColumns<const A extends string, const K extends string>(
+  money: Money,
+  amount: A,
+  currency: K,
+): Row<A, bigint> & Row<K, string> {
+  return { [amount]: toMinorAtIsoScale(money), [currency]: money.currency } as Row<A, bigint> &
+    Row<K, string>;
+}
+
+function toMinorAtIsoScale(money: Money): bigint {
+  const iso = fromMinor(0, money.currency).scale;
+  if (money.scale !== iso) {
+    throw new RangeError(
+      `${money} has scale ${money.scale}; round() it to ${iso} decimals before storing minor units`,
+    );
+  }
+  return toMinor(money);
+}

package/src/processor.ts

@@ -0,0 +1,181 @@
+import { currencyExponent } from './currency.js';
+import { formatScaled, parseDecimal, parsePlainDecimal, normalizeMinor } from './decimal.js';
+import { fromMinor, scaleDown, scaleUp, toScale, type CurrencyInput, type Money } from './money.js';
+import {
+  divideAndRound,
+  divideAndRoundBigint,
+  RoundingError,
+  type RoundingMode,
+} from './rounding.js';
+
+/**
+ * Which signs a processor field accepts, checked after rounding:
+ * - 'any': negative amounts are documented (Klarna's discount order lines);
+ * - 'nonNegative': zero is documented but negatives aren't (refunds are sent as positive amounts);
+ * - 'positive': the processor rejects zero too (Braintree's transaction amount).
+ */
+export type SignRule = 'any' | 'nonNegative' | 'positive';
+
+/**
+ * Rescales Money's minor units to a processor's exponent, then to a multiple of `multiple` minor
+ * units (Checkout.com's CLP, Stripe's ISK). Throws a RoundingError naming the processor when
+ * precision would be lost and `rounding` is 'unnecessary'.
+ */
+function rescaleForProcessor(
+  processor: string,
+  money: Money,
+  exponent: number,
+  multiple: number,
+  rounding: RoundingMode,
+): number | bigint {
+  // Going up in scale is always exact; going down (e.g. IDR on Adyen) may need rounding.
+  let minor: number | bigint;
+  try {
+    if (exponent >= money.scale) {
+      minor = scaleUp(money.minor, exponent - money.scale);
+    } else {
+      minor = scaleDown(money.minor, money.scale - exponent, rounding);
+    }
+  } catch (error) {
+    if (error instanceof RoundingError) {
+      throw new RoundingError(
+        `${money} has more precision than ${processor} accepts for ${money.currency} ` +
+          `(${exponent} decimals); pass a rounding mode`,
+      );
+    }
+    throw error;
+  }
+
+  if (multiple === 1) {
+    return minor;
+  }
+
+  const isMultiple =
+    typeof minor === 'number' ? minor % multiple === 0 : minor % BigInt(multiple) === 0n;
+  if (isMultiple) {
+    return minor;
+  }
+  if (rounding === 'unnecessary') {
+    throw new RoundingError(
+      `${processor} requires ${money.currency} amounts to be a multiple of ${multiple} minor units; ` +
+        `${money} is not (pass a rounding mode)`,
+    );
+  }
+
+  if (typeof minor === 'number') {
+    return divideAndRound(minor, multiple, rounding) * multiple;
+  }
+  const bigMultiple = BigInt(multiple);
+  return normalizeMinor(divideAndRoundBigint(minor, bigMultiple, rounding) * bigMultiple);
+}
+
+/** Throws a RangeError when the rounded amount has a sign the processor doesn't accept. */
+function checkSign(processor: string, money: Money, minor: number | bigint, sign: SignRule): void {
+  // Checked on the rounded amount, so -0.004 USD rounded to 0 counts as zero, not as negative.
+  if (sign === 'any') {
+    return;
+  }
+  if (minor < 0) {
+    throw new RangeError(
+      `${processor} amounts can't be negative (${money}); send refunds as positive amounts`,
+    );
+  }
+  if (sign === 'positive' && (minor === 0 || minor === 0n)) {
+    throw new RangeError(`${processor} amounts must be greater than zero (${money})`);
+  }
+}
+
+/**
+ * @internal Money -> a processor's integer amount at the processor's exponent.
+ * Throws a RangeError when the amount doesn't fit in a safe integer or has a sign `sign` rules out.
+ */
+export function toProcessorAmount(
+  processor: string,
+  money: Money,
+  exponent: number,
+  multiple: number,
+  rounding: RoundingMode,
+  sign: SignRule = 'any',
+): number {
+  const minor = rescaleForProcessor(processor, money, exponent, multiple, rounding);
+  if (typeof minor !== 'number') {
+    throw new RangeError(`${money} is too large for ${processor}`);
+  }
+  checkSign(processor, money, minor, sign);
+
+  // `+ 0` turns -0 into 0, so a zero amount never serialises as "-0".
+  return minor + 0;
+}
+
+/**
+ * @internal Money -> a processor's decimal string with exactly `exponent` decimals
+ * ("10.00", or "1000" for JPY), built from the integer so it never goes through a float.
+ */
+export function toProcessorDecimal(
+  processor: string,
+  money: Money,
+  exponent: number,
+  rounding: RoundingMode,
+  sign: SignRule = 'any',
+): string {
+  const minor = rescaleForProcessor(processor, money, exponent, 1, rounding);
+  checkSign(processor, money, minor, sign);
+
+  // `+ 0` turns -0 into 0, so a zero amount never serialises as "-0".
+  return formatScaled(typeof minor === 'number' ? minor + 0 : minor, exponent);
+}
+
+/**
+ * Returns Money at the currency's ISO scale when that is exact, and otherwise at the scale it
+ * came with, so a processor's extra precision (Stripe's ISK 12.34) is kept rather than lost.
+ */
+function toIsoScaleWhenExact<C extends string>(money: Money<C>, currency: C): Money<C> {
+  const isoExponent = currencyExponent(currency);
+  if (isoExponent >= money.scale) {
+    return toScale(money, isoExponent);
+  }
+
+  try {
+    return toScale(money, isoExponent, 'unnecessary');
+  } catch {
+    return money;
+  }
+}
+
+/** @internal A processor's integer amount -> Money (see `toIsoScaleWhenExact` for the scale). */
+export function fromProcessorAmount<C extends CurrencyInput>(
+  processor: string,
+  amount: number | bigint,
+  currency: C,
+  exponent: number,
+): Money<C> {
+  if (typeof amount === 'number' && !Number.isSafeInteger(amount)) {
+    throw new RangeError(`${processor} amount must be an integer, got ${amount}`);
+  }
+
+  return toIsoScaleWhenExact(fromMinor(amount, currency, exponent), currency);
+}
+
+/**
+ * @internal A processor's decimal string -> Money, exactly (never via a float). `pattern` is the
+ * processor's documented format and `maxLength` its length limit, if any. The scale follows
+ * `toIsoScaleWhenExact`.
+ */
+export function fromProcessorDecimal<C extends CurrencyInput>(
+  processor: string,
+  value: string,
+  currency: C,
+  pattern: RegExp,
+  maxLength = Infinity,
+): Money<C> {
+  if (typeof value !== 'string' || value.length > maxLength || !pattern.test(value)) {
+    throw new SyntaxError(
+      `${processor} amount must be a decimal string, got ${JSON.stringify(value)}`,
+    );
+  }
+
+  // PayPal's pattern allows a bare fraction (".5"), which the decimal parsers don't.
+  const withLeadingZero = value.replace(/^(-?)\./, '$10.');
+  const parsed = parsePlainDecimal(withLeadingZero) ?? parseDecimal(withLeadingZero);
+  return toIsoScaleWhenExact(fromMinor(parsed.digits, currency, parsed.scale), currency);
+}

package/src/provider.ts

@@ -0,0 +1,324 @@
+// Rate providers: synchronous lookups over rates you already hold, and combinators over them.
+// Loading rates (network, files, databases) is async and stays outside; `snapshots()` is the one
+// async boundary.
+import type { Factor } from './decimal.js';
+import { CurrencyMismatchError } from './money.js';
+import { exchangeRate, isRate, toIsoString, type Rate, type RateInfo } from './rate.js';
+
+const DAY_MS = 86_400_000;
+
+/** When a rate is wanted for. */
+export interface RateQuery {
+  /** An ISO-8601 date or instant, or a Date. */
+  readonly asOf?: string | Date;
+}
+
+/** Looks up a rate synchronously. `undefined` when it has none for the pair (or for `asOf`). */
+export interface RateProvider {
+  rate<From extends string, To extends string>(
+    from: From,
+    to: To,
+    query?: RateQuery,
+  ): Rate<From, To> | undefined;
+}
+
+/** A fixed set of rates, as built by rateTable() and returned by the ECB parsers and fetchers. */
+export interface RateTable extends RateProvider {
+  readonly rates: readonly Rate[];
+  /** The quoted currency, for a one-base table. */
+  readonly base?: string;
+  /** The table's date, when it has one. */
+  readonly asOf?: string;
+}
+
+/** Thrown when no provider has a rate for the pair. */
+export class RateUnavailableError extends Error {
+  readonly from: string;
+  readonly to: string;
+  readonly asOf: string | undefined;
+
+  constructor(from: string, to: string, asOf?: string | Date) {
+    let when: string | undefined;
+    if (asOf !== undefined) {
+      when = toIsoString(asOf);
+    }
+    let message = `No exchange rate ${from}→${to}`;
+    if (when !== undefined) {
+      message += ` as of ${when}`;
+    }
+    super(message);
+    this.name = 'RateUnavailableError';
+    this.from = from;
+    this.to = to;
+    this.asOf = when;
+  }
+}
+
+/** The UTC date ('2026-11-06') of a date, an instant (any offset) or a Date. */
+function dayOf(time: string | Date): string {
+  return toIsoString(time).slice(0, 10);
+}
+
+/** The rate for the pair, or RateUnavailableError: a lookup that must succeed. */
+export function rateOf<From extends string, To extends string>(
+  provider: RateProvider,
+  from: From,
+  to: To,
+  query?: RateQuery,
+): Rate<From, To> {
+  const rate = provider.rate(from, to, query);
+  if (rate === undefined) {
+    throw new RateUnavailableError(from, to, query?.asOf);
+  }
+
+  // A provider is user code: a wrong pair here would produce Money labelled with the wrong
+  // currency.
+  if (rate.from !== from) {
+    throw new CurrencyMismatchError(from, rate.from);
+  }
+  if (rate.to !== to) {
+    throw new CurrencyMismatchError(to, rate.to);
+  }
+  return rate;
+}
+
+/** 1:1 for a currency to itself; nothing otherwise. */
+export function identity(): RateProvider {
+  return {
+    rate(from, to) {
+      // Compared as strings: From and To are independent type parameters.
+      if ((from as string) !== to) {
+        return undefined;
+      }
+      return exchangeRate(from, to, 1n);
+    },
+  };
+}
+
+/** A one-base table: `rates.USD` is the number of USD per 1 `base`. */
+export interface RateTableSpec extends RateInfo {
+  readonly base: string;
+  readonly rates: Readonly<Record<string, Factor>>;
+}
+
+/**
+ * A fixed table of rates: one base currency against many (ECB style), or a list of Rates. Only the
+ * pairs given are answered; wrap it in `reversed()` or `via()` for the others.
+ *
+ * Lookups are by whole UTC day: a query for a day before a rate's asOf gets nothing, and a query at
+ * any time on the rate's own day gets the rate, even before its publication time (the ECB publishes
+ * at about 15:00 UTC). If that matters, query with the previous day until the table is published.
+ *
+ *     const ecb = rateTable({ base: 'EUR', source: 'ECB', asOf: '2026-11-06', rates: { USD: '1.1165' } });
+ */
+export function rateTable(spec: RateTableSpec | readonly Rate[]): RateTable {
+  let rates: Rate[];
+  const header: { base?: string; asOf?: string } = {};
+  if (isRateList(spec)) {
+    rates = [...spec];
+  } else {
+    rates = Object.entries(spec.rates).map(([to, rate]) => exchangeRate(spec.base, to, rate, spec));
+    header.base = spec.base;
+    if (spec.asOf !== undefined) {
+      header.asOf = toIsoString(spec.asOf);
+    }
+  }
+
+  const byPair = new Map<string, Rate>();
+  for (const rate of rates) {
+    byPair.set(`${rate.from}/${rate.to}`, rate);
+  }
+
+  return {
+    ...header,
+    rates,
+    rate<From extends string, To extends string>(from: From, to: To, query?: RateQuery) {
+      const rate = byPair.get(`${from}/${to}`);
+      if (rate === undefined) {
+        return undefined;
+      }
+      const askedBeforeRateExisted =
+        query?.asOf !== undefined &&
+        rate.asOf !== undefined &&
+        dayOf(query.asOf) < dayOf(rate.asOf);
+      if (askedBeforeRateExisted) {
+        return undefined;
+      }
+      // The key matched, so the rate's currencies are exactly `from` and `to`.
+      return rate as Rate<From, To>;
+    },
+  };
+}
+
+function isRateList(spec: RateTableSpec | readonly Rate[]): spec is readonly Rate[] {
+  return Array.isArray(spec) && spec.every(isRate);
+}
+
+/** Asks each provider in turn; the first with an answer wins. */
+export function chain(...providers: readonly RateProvider[]): RateProvider {
+  return {
+    rate(from, to, query) {
+      for (const provider of providers) {
+        const rate = provider.rate(from, to, query);
+        if (rate !== undefined) {
+          return rate;
+        }
+      }
+      return undefined;
+    },
+  };
+}
+
+/** Answers to→from lookups with the exact inverse of the provider's from→to rate. */
+export function reversed(provider: RateProvider): RateProvider {
+  return {
+    rate(from, to, query) {
+      return provider.rate(to, from, query)?.inverse();
+    },
+  };
+}
+
+/**
+ * Triangulates through `base`: from→base, then base→to, composed exactly (converting rounds once).
+ * Each leg is looked up directly or as an exact inverse, so an ECB table (EUR→X only) answers X→Y.
+ */
+export function via(base: string, provider: RateProvider): RateProvider {
+  function leg<From extends string, To extends string>(
+    from: From,
+    to: To,
+    query?: RateQuery,
+  ): Rate<From, To> | undefined {
+    return provider.rate(from, to, query) ?? provider.rate(to, from, query)?.inverse();
+  }
+
+  return {
+    rate(from, to, query) {
+      if ((from as string) === to) {
+        return undefined;
+      }
+      if (from === base || to === base) {
+        return leg(from, to, query);
+      }
+
+      const toBase = leg(from, base, query);
+      if (toBase === undefined) {
+        return undefined;
+      }
+      const fromBase = leg(base, to, query);
+      if (fromBase === undefined) {
+        return undefined;
+      }
+      return toBase.andThen(fromBase);
+    },
+  };
+}
+
+/** Options for snapshots(). */
+export interface SnapshotOptions {
+  /**
+   * How many earlier days to try when a day has no table (weekends, holidays). Default 4, which
+   * covers Good Friday to Easter Monday.
+   */
+  readonly lookback?: number;
+  /** How many loaded days to keep; the least recently used are dropped. Default 32. */
+  readonly max?: number;
+}
+
+/** Dated tables, loaded on demand. */
+export interface Snapshots {
+  /** The latest table at or before `asOf` (a date, an instant or a Date), within the lookback. */
+  at(asOf: string | Date): Promise<RateProvider>;
+}
+
+/**
+ * Dated tables from a loader you supply: `load('2026-11-06')` resolves to that day's table, or to
+ * undefined when there is none. Days are UTC days. Loaded tables are cached by day. Misses and
+ * failures are not cached, so a table that isn't published yet is tried again next time. A loader
+ * that throws fails the lookup rather than falling back to an older day, so an outage doesn't
+ * silently become a stale rate. The rates carry the day they're from.
+ *
+ *     const history = snapshots(async (day) => parseEcbXml(await readFile(`ecb/${day}.xml`, 'utf8'))[0]);
+ *     const fx = await history.at('2026-11-08');   // a Sunday: Friday 2026-11-06's table
+ */
+export function snapshots(
+  load: (day: string) => Promise<RateProvider | undefined>,
+  options?: SnapshotOptions,
+): Snapshots {
+  const lookback = options?.lookback ?? 4;
+  const max = options?.max ?? 32;
+  if (!Number.isSafeInteger(lookback) || lookback < 0) {
+    throw new RangeError(`lookback must be a non-negative integer, got ${lookback}`);
+  }
+  if (!Number.isSafeInteger(max) || max < 1) {
+    throw new RangeError(`max must be a positive integer, got ${max}`);
+  }
+  // Map iteration order is insertion order, so re-inserting on every use makes it an LRU.
+  const cache = new Map<string, Promise<RateProvider | undefined>>();
+
+  // Only drop the entry this load created: a newer load for the same day may have replaced it.
+  function forget(day: string, loading: Promise<RateProvider | undefined>): void {
+    if (cache.get(day) === loading) {
+      cache.delete(day);
+    }
+  }
+
+  function loadDay(day: string): Promise<RateProvider | undefined> {
+    let pending = cache.get(day);
+    if (pending === undefined) {
+      const loading: Promise<RateProvider | undefined> = load(day).then((table) => {
+        if (table === undefined) {
+          forget(day, loading);
+        }
+        return table;
+      });
+      loading.catch(() => forget(day, loading));
+      pending = loading;
+    } else {
+      cache.delete(day);
+    }
+
+    cache.set(day, pending);
+    if (cache.size > max) {
+      const leastRecentlyUsed = cache.keys().next().value!;
+      cache.delete(leastRecentlyUsed);
+    }
+    return pending;
+  }
+
+  return {
+    async at(asOf) {
+      const firstDay = dayOf(asOf);
+      const firstDayMs = Date.parse(`${firstDay}T00:00:00Z`);
+      if (Number.isNaN(firstDayMs)) {
+        throw new RangeError(`Invalid asOf ${String(asOf)}`);
+      }
+
+      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
+        const table = await loadDay(day);
+        if (table !== undefined) {
+          return table;
+        }
+      }
+      throw new RateUnavailableError('*', '*', firstDay);
+    },
+  };
+}
+
+/**
+ * Snapshots over tables you already hold (e.g. an ECB 90-day history), keyed by their asOf day.
+ *
+ *     const history = snapshotsFrom(parseEcbXml(xml90d));
+ *     const fx = await history.at('2026-11-08');
+ */
+export function snapshotsFrom(tables: readonly RateTable[], options?: SnapshotOptions): Snapshots {
+  const byDay = new Map<string, RateTable>();
+  for (const table of tables) {
+    if (table.asOf !== undefined) {
+      byDay.set(dayOf(table.asOf), table);
+    }
+  }
+  return snapshots(async (day) => byDay.get(day), options);
+}