@ducatjs/money 0.1.0 → 0.2.1

package/src/generated/cash.ts

@@ -10,6 +10,8 @@ export interface CashRule {
   /** false: only secondary sources were found. */
   readonly verified: boolean;
   readonly source: string;
+  /** The tie rule the source prescribes, where it isn't halfExpand. */
+  readonly rounding?: import('../rounding.js').RoundingMode;
 }
 
 export const CASH_RULES: readonly CashRule[] = [
@@ -371,5 +373,106 @@ export const CASH_RULES: readonly CashRule[] = [
     "scope": "cash (permitted, not required; varies by state)",
     "verified": false,
     "source": "https://en.wikipedia.org/wiki/Cash_rounding"
+  },
+  {
+    "currency": "AMD",
+    "increment": 1000,
+    "countries": [
+      "AM"
+    ],
+    "scope": "cash (practice)",
+    "verified": true,
+    "source": "https://old.cba.am/en/SitePages/nccracoinscirculated.aspx"
+  },
+  {
+    "currency": "CRC",
+    "increment": 1000,
+    "countries": [
+      "CR"
+    ],
+    "scope": "cash (practice)",
+    "verified": true,
+    "source": "https://www.bccr.fi.cr/cr/es/noticias/listado-de-noticias/2026/monedas-de-5-10-y-25-del-diseno-anterior-dejaran-de-funcionar-como-medio-de-pago-el-1-de-julio-del-2.html"
+  },
+  {
+    "currency": "GYD",
+    "increment": 100,
+    "countries": [
+      "GY"
+    ],
+    "scope": "cash",
+    "verified": false,
+    "source": "https://bankofguyana.org.gy/bog/images/communications/press_release/Notice%20to%20stop%20minting%20one%20dollar%20coin.pdf"
+  },
+  {
+    "currency": "MNT",
+    "increment": 100,
+    "countries": [
+      "MN"
+    ],
+    "scope": "cash",
+    "verified": true,
+    "source": "https://www.mongolbank.mn/en/p/1416"
+  },
+  {
+    "currency": "MRU",
+    "increment": 20,
+    "countries": [
+      "MR"
+    ],
+    "scope": "cash",
+    "verified": false,
+    "source": "https://cridem.org/media/documents/bcm-presentation-gr-2017.pdf"
+  },
+  {
+    "currency": "PKR",
+    "increment": 100,
+    "countries": [
+      "PK"
+    ],
+    "scope": "cash",
+    "verified": true,
+    "source": "https://www.sbp.org.pk/press/2014/Coins-15-Sep-2014.pdf"
+  },
+  {
+    "currency": "RSD",
+    "increment": 100,
+    "countries": [
+      "RS"
+    ],
+    "scope": "cash (statutory)",
+    "verified": true,
+    "source": "https://www.nbs.rs/export/sites/NBS_site/documents/propisi/propisi-trz/opticaj_povlacenje_50_para.pdf",
+    "rounding": "halfTrunc"
+  },
+  {
+    "currency": "TZS",
+    "increment": 5000,
+    "countries": [
+      "TZ"
+    ],
+    "scope": "cash (practice)",
+    "verified": false,
+    "source": "https://www.bot.go.tz/Publications/Regular/Quarterly%20statistical%20Bulletin/en/2025090409030924.pdf"
+  },
+  {
+    "currency": "TWD",
+    "increment": 100,
+    "countries": [
+      "TW"
+    ],
+    "scope": "cash (practice)",
+    "verified": true,
+    "source": "https://www.cbc.gov.tw/tw/cp-769-26060-37841-1.html"
+  },
+  {
+    "currency": "UZS",
+    "increment": 5000,
+    "countries": [
+      "UZ"
+    ],
+    "scope": "cash (practice)",
+    "verified": true,
+    "source": "https://cbu.uz/en/banknotes-coins/coins/"
   }
 ];

package/src/generated/historic.ts

@@ -0,0 +1,67 @@
+// GENERATED by scripts/gen-currencies.mjs from data/iso4217-list-three.xml and data/historic.json. Do not edit by hand.
+/* eslint-disable */
+
+/** Publication date of the ISO 4217 List Three snapshot. */
+export const ISO_4217_LIST_THREE_PUBLISHED = "2026-01-01";
+
+/**
+ * Withdrawn ISO 4217 codes (with `numeric` and `withdrawn`, the year and month ISO lists) and
+ * non-ISO codes (without them), each with the exponent ISO gave it while it was current.
+ */
+export const HISTORIC_CURRENCY_TABLE = {
+  ADP: {"name":"Andorran Peseta","numeric":"020","exponent":0,"withdrawn":"2003-07"},
+  AFA: {"name":"Afghani","numeric":"004","exponent":2,"withdrawn":"2003-01"},
+  ANG: {"name":"Netherlands Antillean Guilder","numeric":"532","exponent":2,"withdrawn":"2025-03"},
+  ATS: {"name":"Schilling","numeric":"040","exponent":2,"withdrawn":"2002-03"},
+  AYM: {"name":"Azerbaijan Manat","numeric":"945","exponent":2,"withdrawn":"2005-10"},
+  AZM: {"name":"Azerbaijanian Manat","numeric":"031","exponent":2,"withdrawn":"2005-12"},
+  BEF: {"name":"Belgian Franc","numeric":"056","exponent":0,"withdrawn":"2002-03"},
+  BGL: {"name":"Lev","numeric":"100","exponent":2,"withdrawn":"2003-11"},
+  BGN: {"name":"Bulgarian Lev","numeric":"975","exponent":2,"withdrawn":"2026-01"},
+  BYB: {"name":"Belarusian Ruble","numeric":"112","exponent":0,"withdrawn":"2001-01"},
+  BYR: {"name":"Belarusian Ruble","numeric":"974","exponent":0,"withdrawn":"2017-01"},
+  CNH: {"name":"Chinese Yuan Renminbi (offshore)","exponent":2},
+  CSD: {"name":"Serbian Dinar","numeric":"891","exponent":2,"withdrawn":"2006-10"},
+  CUC: {"name":"Peso Convertible","numeric":"931","exponent":2,"withdrawn":"2021-06"},
+  CYP: {"name":"Cyprus Pound","numeric":"196","exponent":2,"withdrawn":"2008-01"},
+  DEM: {"name":"Deutsche Mark","numeric":"276","exponent":2,"withdrawn":"2002-03"},
+  EEK: {"name":"Kroon","numeric":"233","exponent":2,"withdrawn":"2011-01"},
+  ESP: {"name":"Spanish Peseta","numeric":"724","exponent":0,"withdrawn":"2002-03"},
+  FIM: {"name":"Markka","numeric":"246","exponent":2,"withdrawn":"2002-03"},
+  FRF: {"name":"French Franc","numeric":"250","exponent":2,"withdrawn":"2002-03"},
+  GHC: {"name":"Cedi","numeric":"288","exponent":2,"withdrawn":"2008-01"},
+  GRD: {"name":"Drachma","numeric":"300","exponent":0,"withdrawn":"2002-03"},
+  GWP: {"name":"Guinea-Bissau Peso","numeric":"624","exponent":2,"withdrawn":"1997-05"},
+  HRK: {"name":"Kuna","numeric":"191","exponent":2,"withdrawn":"2023-01"},
+  IEP: {"name":"Irish Pound","numeric":"372","exponent":2,"withdrawn":"2002-03"},
+  ITL: {"name":"Italian Lira","numeric":"380","exponent":0,"withdrawn":"2002-03"},
+  LTL: {"name":"Lithuanian Litas","numeric":"440","exponent":2,"withdrawn":"2014-12"},
+  LUF: {"name":"Luxembourg Franc","numeric":"442","exponent":0,"withdrawn":"2002-03"},
+  LVL: {"name":"Latvian Lats","numeric":"428","exponent":2,"withdrawn":"2014-01"},
+  MGF: {"name":"Malagasy Franc","numeric":"450","exponent":0,"withdrawn":"2004-12"},
+  MRO: {"name":"Ouguiya","numeric":"478","exponent":2,"withdrawn":"2017-12"},
+  MTL: {"name":"Maltese Lira","numeric":"470","exponent":2,"withdrawn":"2008-01"},
+  MZM: {"name":"Mozambique Metical","numeric":"508","exponent":2,"withdrawn":"2006-06"},
+  NLG: {"name":"Netherlands Guilder","numeric":"528","exponent":2,"withdrawn":"2002-03"},
+  PTE: {"name":"Portuguese Escudo","numeric":"620","exponent":0,"withdrawn":"2002-03"},
+  ROL: {"name":"Old Leu","numeric":"642","exponent":0,"withdrawn":"2005-06"},
+  RUR: {"name":"Russian Ruble","numeric":"810","exponent":2,"withdrawn":"2004-01"},
+  SDD: {"name":"Sudanese Dinar","numeric":"736","exponent":2,"withdrawn":"2007-07"},
+  SIT: {"name":"Tolar","numeric":"705","exponent":2,"withdrawn":"2007-01"},
+  SKK: {"name":"Slovak Koruna","numeric":"703","exponent":2,"withdrawn":"2009-01"},
+  SLL: {"name":"Leone","numeric":"694","exponent":2,"withdrawn":"2023-12"},
+  SRG: {"name":"Surinam Guilder","numeric":"740","exponent":2,"withdrawn":"2003-12"},
+  STD: {"name":"Dobra","numeric":"678","exponent":2,"withdrawn":"2017-12"},
+  TMM: {"name":"Turkmenistan Manat","numeric":"795","exponent":2,"withdrawn":"2009-01"},
+  TPE: {"name":"Timor Escudo","numeric":"626","exponent":0,"withdrawn":"2002-11"},
+  TRL: {"name":"Old Turkish Lira","numeric":"792","exponent":0,"withdrawn":"2005-12"},
+  USS: {"name":"US Dollar (Same day)","numeric":"998","exponent":2,"withdrawn":"2014-03"},
+  VEB: {"name":"Bolivar","numeric":"862","exponent":2,"withdrawn":"2008-01"},
+  VEF: {"name":"Bolívar","numeric":"937","exponent":2,"withdrawn":"2018-08"},
+  YUM: {"name":"New Dinar","numeric":"891","exponent":2,"withdrawn":"2003-07"},
+  ZMK: {"name":"Zambian Kwacha","numeric":"894","exponent":2,"withdrawn":"2012-12"},
+  ZWD: {"name":"Zimbabwe Dollar","numeric":"716","exponent":2,"withdrawn":"2008-08"},
+  ZWL: {"name":"Zimbabwe Dollar","numeric":"932","exponent":2,"withdrawn":"2024-09"},
+  ZWN: {"name":"Zimbabwe Dollar (new)","numeric":"942","exponent":2,"withdrawn":"2006-09"},
+  ZWR: {"name":"Zimbabwe Dollar","numeric":"935","exponent":2,"withdrawn":"2009-06"},
+} as const;

package/src/historic.ts

@@ -0,0 +1,77 @@
+/**
+ * `@ducatjs/money/historic`: withdrawn ISO 4217 codes and a few non-ISO ones, with the exponent
+ * each had and, for ISO codes, the month ISO withdrew it. Nothing is registered until you ask, so
+ * the core registry stays ISO 4217 as currently published:
+ *
+ *     defineHistoricCurrencies(['HRK', 'BGN']);
+ *     money('100', 'HRK'); // 100.00 HRK
+ *     historicCurrency('HRK')?.withdrawn; // '2023-01'
+ */
+import { defineCurrency } from './currency.js';
+import { HISTORIC_CURRENCY_TABLE, ISO_4217_LIST_THREE_PUBLISHED } from './generated/historic.js';
+
+export { ISO_4217_LIST_THREE_PUBLISHED };
+
+/** A code in the historic table. */
+export type HistoricCurrencyCode = keyof typeof HISTORIC_CURRENCY_TABLE;
+
+/**
+ * Every historic code, for the `CurrencyCode` type:
+ *
+ *     declare module '@ducatjs/money' {
+ *       interface CustomCurrencies extends HistoricCurrencies {}
+ *     }
+ */
+export type HistoricCurrencies = { readonly [Code in HistoricCurrencyCode]: true };
+
+/** One entry of the historic table. */
+export interface HistoricCurrency {
+  readonly code: HistoricCurrencyCode;
+  /** The name ISO 4217 List Three gives it (for non-ISO codes, a descriptive name). */
+  readonly name: string;
+  /** Its minor-unit exponent while it was current: what stored minor units of it mean. */
+  readonly exponent: number;
+  /** The ISO 4217 numeric code; absent for codes that were never ISO (CNH). */
+  readonly numeric?: string;
+  /**
+   * The year and month ISO 4217 withdrew it ('2023-01'), from List Three. A code withdrawn
+   * country by country has the last date. Absent for codes that were never ISO.
+   */
+  readonly withdrawn?: string;
+}
+
+const table: Readonly<Record<string, Omit<HistoricCurrency, 'code'>>> = HISTORIC_CURRENCY_TABLE;
+
+/** The table entry for a code, or undefined for a code that isn't in it. */
+export function historicCurrency(code: string): HistoricCurrency | undefined {
+  // own properties only, so 'toString' and friends are not currencies
+  if (!Object.hasOwn(table, code)) {
+    return undefined;
+  }
+  return { code: code as HistoricCurrencyCode, ...table[code]! };
+}
+
+/** Every entry of the table, by code. */
+export function historicCurrencies(): HistoricCurrency[] {
+  return Object.keys(table).map((code) => historicCurrency(code)!);
+}
+
+/**
+ * Registers historic codes with `defineCurrency`, so Money can hold them: all of them, or only
+ * `codes`. Registering one again is harmless; a code already defined with another exponent throws,
+ * as `defineCurrency` does.
+ */
+export function defineHistoricCurrencies(codes?: readonly HistoricCurrencyCode[]): 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 historic currency table`);
+    }
+  }
+
+  for (const code of selected) {
+    defineCurrency(code, table[code]!.exponent);
+  }
+}

package/src/history.ts

@@ -0,0 +1,333 @@
+// `@ducatjs/money/convert/history`: rates as central banks publish them (the other way round, per
+// 100 units, with stripped digits) and dated tables over a range, with lookups that say why they
+// fell back. Opt-in, so that converting at a rate you already hold doesn't pay for it.
+import type { CurrencyInput } from './money.js';
+import {
+  rateTable,
+  type RateProvider,
+  type RateQuery,
+  type RateTable,
+  type RateTableSpec,
+} from './provider.js';
+
+import { ratio, type Ratio } from './decimal.js';
+import { hasEnded, hasStarted, Rate, toIsoString } from './rate.js';
+import type { RateInfo, RateQuote } from './rate.js';
+import { withDecimals } from './rate-text.js';
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Why a lookup passed over a day: no table that day (a weekend or holiday), the table not yet
+ * published at the time asked for, its period over, or the pair not in it (`missing` when the
+ * source listed the currency without a value, `notQuoted` when it isn't listed at all).
+ */
+export type FallbackReason = 'noTable' | 'notYetAvailable' | 'expired' | 'missing' | 'notQuoted';
+
+/** A day a lookup passed over, and why. */
+export interface Fallback {
+  readonly day: string;
+  readonly reason: FallbackReason;
+}
+
+const PLAIN_DECIMAL = /^\d+(?:\.\d+)?$/;
+
+/** The exact rate a quote stands for, in the Rate's own direction. */
+function quoteRatio(quote: RateQuote): Ratio {
+  if (!PLAIN_DECIMAL.test(quote.rate)) {
+    throw new RangeError(`A quote is a plain decimal string, got ${quote.rate}`);
+  }
+  const per = quote.per ?? 1;
+  if (!Number.isSafeInteger(per) || per < 1) {
+    throw new RangeError(`A quote's per is a positive integer, got ${per}`);
+  }
+  const published = ratio(quote.rate);
+  if (quote.inverted === true) {
+    return ratio(published.den * BigInt(per), published.num);
+  }
+  return ratio(published.num, published.den * BigInt(per));
+}
+
+/**
+ * A Rate from a published quote: `per` units and the direction are applied exactly, and the quote
+ * is kept on the Rate.
+ *
+ *     rateFromQuote('JPY', 'NOK', { rate: '6.50', per: 100 })        // JPY→NOK 0.065
+ *     rateFromQuote('USD', 'EUR', { rate: '1.1650', inverted: true }) // USD→EUR 200/233
+ */
+export function rateFromQuote<From extends CurrencyInput, To extends CurrencyInput>(
+  from: From,
+  to: To,
+  quote: RateQuote,
+  info?: Omit<RateInfo, 'quote'>,
+): Rate<From, To> {
+  const exact = quoteRatio(quote);
+  // Stored in one form: per 1 and inverted false are the same as leaving them out, and a quote
+  // without them prints its own digits.
+  const kept: { rate: string; per?: number; inverted?: boolean } = { rate: quote.rate };
+  if (quote.per !== undefined && quote.per !== 1) {
+    kept.per = quote.per;
+  }
+  if (quote.inverted === true) {
+    kept.inverted = true;
+  }
+  return new Rate(from, to, exact, { ...info, quote: kept });
+}
+
+/** One published rate in a quoted table. */
+export interface QuotedRate {
+  /** The rate as published, a decimal string. */
+  readonly rate: string;
+  /**
+   * How many units the published number is for: of `base`, or of the currency when the rate is
+   * `inverted` ("NOK per 100 JPY" is `{ rate: '6.50', per: 100, inverted: true }` in a NOK table).
+   */
+  readonly per?: number;
+  /** Published as base per unit of the currency, the other way round from the table. */
+  readonly inverted?: boolean;
+  /**
+   * The decimals the source publishes, for feeds that strip trailing zeros: '1.175' with 4 is
+   * kept as '1.1750'.
+   */
+  readonly decimals?: number;
+}
+
+/** A one-base table of published quotes: a decimal string, a QuotedRate, or null (no value). */
+export interface QuotedTableSpec extends Omit<RateTableSpec, 'rates'> {
+  readonly rates: Readonly<Record<string, string | QuotedRate | null>>;
+  /**
+   * Every rate is published as base per unit of the currency (CAD per USD, as the Bank of Canada
+   * quotes), unless its entry says otherwise.
+   */
+  readonly inverted?: boolean;
+  /** The decimals every rate is published with, unless its entry says otherwise. */
+  readonly decimals?: number;
+}
+
+/**
+ * A rateTable from rates as a source published them: each is stored exactly in the table's
+ * direction, base → currency, and keeps its quote (`rate.quote`).
+ *
+ *     const boc = quotedTable({ base: 'CAD', inverted: true, asOf: '2026-11-06', rates: { USD: '1.3654' } });
+ *     boc.rate('CAD', 'USD')?.inverse().toString(); // '1.3654'
+ */
+export function quotedTable(spec: QuotedTableSpec): RateTable {
+  const rates: Record<string, Rate | null> = {};
+  for (const [currency, entry] of Object.entries(spec.rates)) {
+    if (entry === null) {
+      rates[currency] = null;
+      continue;
+    }
+    let quoted: QuotedRate;
+    if (typeof entry === 'string') {
+      quoted = { rate: entry };
+    } else {
+      quoted = entry;
+    }
+
+    let text = quoted.rate.trim();
+    const decimals = quoted.decimals ?? spec.decimals;
+    if (decimals !== undefined) {
+      text = withDecimals(text, decimals);
+    }
+    const quote: { rate: string; per?: number; inverted?: boolean } = { rate: text };
+    if (quoted.per !== undefined) {
+      quote.per = quoted.per;
+    }
+    if (quoted.inverted ?? spec.inverted ?? false) {
+      quote.inverted = true;
+    }
+    rates[currency] = rateFromQuote(spec.base, currency, quote, spec);
+  }
+  return rateTable({ ...spec, rates });
+}
+
+/** 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);
+}
+
+/** Options for rateHistory(). */
+export interface RateHistoryOptions {
+  /**
+   * How many days before the day asked for to look back for a daily table (weekends, holidays,
+   * currencies missing that day). Default 4, which covers Good Friday to Easter Monday. A table
+   * valid for a period (`validUntil`) answers for its whole period instead.
+   */
+  readonly lookback?: number;
+}
+
+/** A rate lookup with its reasons: the rate, or undefined, and the days passed over. */
+export interface RateLookup<From extends string = string, To extends string = string> {
+  readonly rate: Rate<From, To> | undefined;
+  /** Days passed over before the answer (or before giving up), newest first. */
+  readonly skipped: readonly Fallback[];
+}
+
+/** Dated tables held in memory, answering any day synchronously. */
+export interface RateHistory extends RateProvider {
+  /** The dated tables, newest first. */
+  readonly tables: readonly RateTable[];
+  /** The same lookup as `rate`, reporting the days it passed over and why. */
+  lookup<From extends string, To extends string>(
+    from: From,
+    to: To,
+    query?: RateQuery,
+  ): RateLookup<From, To>;
+}
+
+/**
+ * Why a table can't answer the pair at the time asked for, or undefined when it can. The table's
+ * own dates are checked first; a table built from a list of Rates has none, so its rate's are.
+ */
+function passOver(
+  table: RateTable,
+  from: string,
+  to: string,
+  query: RateQuery | undefined,
+  periodEnded: boolean,
+): FallbackReason | undefined {
+  const asOf = query?.asOf;
+  if (periodEnded) {
+    return 'expired';
+  }
+  if (
+    asOf !== undefined &&
+    table.availableAt !== undefined &&
+    !hasStarted(table.availableAt, asOf)
+  ) {
+    return 'notYetAvailable';
+  }
+  if (table.rate(from, to, query) !== undefined) {
+    return undefined;
+  }
+
+  if (table.missing?.includes(from) === true || table.missing?.includes(to) === true) {
+    return 'missing';
+  }
+  const held = table.rates.find((rate) => rate.from === from && rate.to === to);
+  if (held !== undefined && asOf !== undefined) {
+    if (held.isExpired(asOf)) {
+      return 'expired';
+    }
+    if (!held.isAvailable(asOf)) {
+      return 'notYetAvailable';
+    }
+  }
+  return 'notQuoted';
+}
+
+/** The ISO date `count` days before `day`. */
+function daysBefore(day: string, count: number): string {
+  return new Date(Date.parse(`${day}T00:00:00Z`) - count * DAY_MS).toISOString().slice(0, 10);
+}
+
+/**
+ * A provider over many dated tables, such as a date range loaded in one call: for each lookup it
+ * takes the latest table at or before `asOf` that has the pair, published by then and still
+ * valid, looking back up to `lookback` days. Each currency pair falls back on its own, so a
+ * currency missing on a holiday comes from the day before while the others stay current; the
+ * Rate's `asOf` says which day it is from. Without an `asOf`, the newest table with the pair
+ * answers. `lookup` reports why a lookup fell back.
+ *
+ *     const history = rateHistory(parseEcbXml(xml90Days));
+ *     history.rate('EUR', 'USD', { asOf: '2026-11-08' }); // Sunday: Friday's rate
+ *     history.lookup('EUR', 'USD', { asOf: '2026-11-08' }).skipped;
+ *     // [{ day: '2026-11-08', reason: 'noTable' }, { day: '2026-11-07', reason: 'noTable' }]
+ */
+export function rateHistory(
+  tables: readonly RateTable[],
+  options?: RateHistoryOptions,
+): RateHistory {
+  const lookback = options?.lookback ?? 4;
+  if (!Number.isSafeInteger(lookback) || lookback < 0) {
+    throw new RangeError(`lookback must be a non-negative integer, got ${lookback}`);
+  }
+  const dated: { day: string; table: RateTable }[] = [];
+  for (const table of tables) {
+    if (table.asOf === undefined) {
+      throw new RangeError('rateHistory needs tables with an asOf');
+    }
+    dated.push({ day: dayOf(table.asOf), table });
+  }
+  // Newest first; a stable sort keeps the caller's order within a day.
+  dated.sort((entry, other) => (other.day < entry.day ? -1 : Number(other.day > entry.day)));
+
+  const hasPeriods = dated.some((entry) => entry.table.validUntil !== undefined);
+
+  function lookup<From extends string, To extends string>(
+    from: From,
+    to: To,
+    query?: RateQuery,
+  ): RateLookup<From, To> {
+    const asOf = query?.asOf;
+    const skipped: Fallback[] = [];
+    let firstDay: string | undefined;
+    if (asOf !== undefined) {
+      firstDay = dayOf(asOf);
+    } else {
+      firstDay = dated[0]?.day;
+    }
+    if (firstDay === undefined) {
+      return { rate: undefined, skipped };
+    }
+    const lastDay = daysBefore(firstDay, lookback);
+    // The newest day of the lookback window not yet accounted for by a daily table.
+    let expectedDay = firstDay;
+
+    for (const { day, table } of dated) {
+      if (day > firstDay) {
+        continue;
+      }
+      const periodEnded =
+        asOf !== undefined && table.validUntil !== undefined && hasEnded(table.validUntil, asOf);
+      const coversPeriod = table.validUntil !== undefined && !periodEnded;
+      if (day < lastDay && !coversPeriod) {
+        // Older daily tables are out of the window; an older period table may still cover it.
+        if (!hasPeriods) {
+          break;
+        }
+        continue;
+      }
+
+      // Days between the last table and this one had no table. A period table that answers
+      // covers them, so for one they count only once it turns out not to answer.
+      // An older period table comes after every day of the window, so all of them are gaps.
+      const inWindow = day >= lastDay;
+      const accountedTo = inWindow ? day : daysBefore(lastDay, 1);
+      const gaps: Fallback[] = [];
+      for (let gap = expectedDay; gap > accountedTo; gap = daysBefore(gap, 1)) {
+        gaps.push({ day: gap, reason: 'noTable' });
+      }
+      if (!coversPeriod) {
+        skipped.push(...gaps);
+      }
+
+      const reason = passOver(table, from, to, query, periodEnded);
+      if (reason === undefined) {
+        return { rate: table.rate(from, to, query) as Rate<From, To>, skipped };
+      }
+      if (coversPeriod) {
+        skipped.push(...gaps);
+      }
+      skipped.push({ day, reason });
+      if (accountedTo <= expectedDay) {
+        expectedDay = inWindow ? daysBefore(day, 1) : accountedTo;
+      }
+    }
+
+    // Days left in the window without any table at all.
+    for (let gap = expectedDay; gap >= lastDay; gap = daysBefore(gap, 1)) {
+      skipped.push({ day: gap, reason: 'noTable' });
+    }
+    return { rate: undefined, skipped };
+  }
+
+  return {
+    tables: dated.map((entry) => entry.table),
+    rate(from, to, query) {
+      return lookup(from, to, query).rate;
+    },
+    lookup,
+  };
+}