@ducatjs/money 0.0.0 → 0.2.0

package/src/ecb.ts

@@ -0,0 +1,328 @@
+// Offline parsers for the ECB euro foreign exchange reference rates (eurofxref). No I/O: fetch or
+// read the files yourself, or use ducat/convert/fetch. Rates are kept exactly as published.
+import { rateTable, type RateTable } from './provider.js';
+import { addDayRate, csvRows, newestFirst, readRateCell, withDecimals } from './rate-text.js';
+
+const MONTHS = [
+  'january',
+  'february',
+  'march',
+  'april',
+  'may',
+  'june',
+  'july',
+  'august',
+  'september',
+  'october',
+  'november',
+  'december',
+];
+const DAY_CUBE = /<Cube\s+time=["'](\d{4}-\d\d-\d\d)["']\s*>([\s\S]*?)<\/Cube>/g;
+// One <Cube .../> element, and its attributes in any order and with any quoting or spacing.
+const INNER_CUBE = /<Cube\b([^>]*?)\/?>/g;
+const ATTRIBUTE = /([A-Za-z]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const RATE_TEXT = /^\d+(?:\.\d+)?$/;
+const ISO_DAY = /^(\d{4})-(\d\d)-(\d\d)$/;
+
+/**
+ * The ECB's rates are typed 'reference', not 'mid': they are set once a day, around 14:10 CET, from
+ * a regular concertation between central banks, and published for information only. They are not a
+ * market mid-rate that anyone deals at.
+ */
+function ecbTable(asOf: string, rates: Record<string, string | null>): RateTable {
+  return rateTable({ base: 'EUR', asOf, source: 'ECB', type: 'reference', rates });
+}
+
+function notAnEcbFile(): never {
+  throw new SyntaxError('Not an ECB reference rate file');
+}
+
+function withoutByteOrderMark(text: string): string {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/** The currency → rate attributes of the <Cube> elements in one day's cube. */
+function ratesOfDay(body: string): Record<string, string> {
+  const rates: Record<string, string> = {};
+  for (const [, attributeText] of body.matchAll(INNER_CUBE)) {
+    const attributes: Record<string, string> = {};
+    for (const [, name, doubleQuoted, singleQuoted] of attributeText!.matchAll(ATTRIBUTE)) {
+      attributes[name!] = doubleQuoted ?? singleQuoted!;
+    }
+    const currency = attributes['currency'];
+    const rate = attributes['rate'];
+    if (currency === undefined && rate === undefined) {
+      continue;
+    }
+    // Fail rather than silently drop a currency: a missing rate would look like "not quoted".
+    if (
+      currency === undefined ||
+      !/^[A-Z]{3}$/.test(currency) ||
+      rate === undefined ||
+      !RATE_TEXT.test(rate)
+    ) {
+      throw new SyntaxError(`Malformed ECB rate entry <Cube${attributeText}>`);
+    }
+    rates[currency] = rate;
+  }
+  return rates;
+}
+
+/**
+ * Parses eurofxref-daily.xml, eurofxref-hist-90d.xml or eurofxref-hist.xml into one EUR-based table
+ * per day, newest first. Each rate is EUR → currency, with `source: 'ECB'`, `type: 'reference'` and
+ * `asOf` the publication day. A day without any rates is left out, so a lookback goes on to the day
+ * before. A rate entry that can't be read throws SyntaxError.
+ *
+ *     const [latest] = parseEcbXml(await readFile('eurofxref-daily.xml', 'utf8'));
+ */
+export function parseEcbXml(xml: string): RateTable[] {
+  let days = 0;
+  const tables: RateTable[] = [];
+  for (const [, asOf, body] of withoutByteOrderMark(xml).matchAll(DAY_CUBE)) {
+    days++;
+    const day = isoDay(asOf!);
+    const rates = ratesOfDay(body!);
+    if (Object.keys(rates).length > 0) {
+      tables.push(ecbTable(day, rates));
+    }
+  }
+
+  if (days === 0) {
+    notAnEcbFile();
+  }
+  return newestFirst(tables);
+}
+
+/** The ISO date of year-month-day, or a SyntaxError when that day doesn't exist (32 November). */
+function calendarDay(year: number, month: number, day: number): string {
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    throw new SyntaxError(`Not a calendar day: ${year}-${month}-${day}`);
+  }
+  return date.toISOString().slice(0, 10);
+}
+
+/** '2026-11-06', or '06 November 2026' as in the daily CSV, as an ISO date. */
+function isoDay(text: string): string {
+  const iso = ISO_DAY.exec(text);
+  if (iso !== null) {
+    return calendarDay(Number(iso[1]), Number(iso[2]), Number(iso[3]));
+  }
+  const match = /^(\d{1,2}) ([A-Za-z]+) (\d{4})$/.exec(text);
+  if (match === null) {
+    notAnEcbFile();
+  }
+  const [, day, monthName, year] = match;
+  const month = MONTHS.indexOf(monthName!.toLowerCase()) + 1;
+  if (month === 0) {
+    notAnEcbFile();
+  }
+  return calendarDay(Number(year), month, Number(day));
+}
+
+/**
+ * Parses eurofxref.csv or eurofxref-hist.csv (from the ECB's zips) the way parseEcbXml does.
+ * 'N/A' and blank cells (currencies not quoted that day) are listed in the table's `missing`, and a
+ * day with no rates at all is left out, so a lookback goes on to the day before.
+ */
+export function parseEcbCsv(csv: string): RateTable[] {
+  const lines = withoutByteOrderMark(csv)
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== '');
+  const columns = (lines[0] ?? '').split(',').map((cell) => cell.trim());
+  if (columns[0] !== 'Date') {
+    notAnEcbFile();
+  }
+
+  const tables: RateTable[] = [];
+  for (const line of lines.slice(1)) {
+    const cells = line.split(',').map((cell) => cell.trim());
+    const day = isoDay(cells[0]!);
+    const rates: Record<string, string | null> = {};
+    let quoted = 0;
+    for (let i = 1; i < columns.length; i++) {
+      const currency = columns[i];
+      if (!currency) {
+        continue;
+      }
+      const rate = readRateCell(cells[i] ?? '', `${currency} on ${day}`);
+      rates[currency] = rate;
+      if (rate !== null) {
+        quoted++;
+      }
+    }
+    if (quoted > 0) {
+      tables.push(ecbTable(day, rates));
+    }
+  }
+  return newestFirst(tables);
+}
+
+// Series whose DECIMALS attribute says more than the ECB has ever published for them. Evidence:
+// eurofxref-daily.xml publishes THB to 3 decimals (37.459 on 2026-11-06) while DECIMALS says 4,
+// and eurofxref-hist.xml (1999 to 2026) never has more than 4 for LTL, whose DECIMALS says 5.
+// Padding to the attribute would invent a digit. A cap only limits padding: a value published
+// with more digits keeps them all (withDecimals never drops digits).
+const PUBLISHED_DECIMALS: Readonly<Record<string, number>> = { THB: 3, LTL: 4 };
+
+/** Options for parseEcbSdmxCsv. */
+export interface EcbSdmxOptions {
+  /**
+   * The decimals each currency is published with, for a file without the DECIMALS column (as
+   * fetched with `detail=dataonly`). A DECIMALS column in the file takes precedence.
+   */
+  readonly decimals?: Readonly<Record<string, number>>;
+}
+
+/** A DECIMALS cell as a number of decimals, or SyntaxError. */
+function readDecimals(text: string, where: string): number {
+  if (!/^\d{1,2}$/.test(text) || Number(text) > 30) {
+    throw new SyntaxError(`Malformed DECIMALS ${JSON.stringify(text)} (${where})`);
+  }
+  return Number(text);
+}
+
+/** A series' stated decimals, capped at what the ECB actually publishes for it. */
+function statedDecimals(currency: string, text: string): number {
+  const stated = readDecimals(text, currency);
+  const published = PUBLISHED_DECIMALS[currency];
+  if (published !== undefined && published < stated) {
+    return published;
+  }
+  return stated;
+}
+
+/** The records of an SDMX-CSV file after its header, each with as many cells as the header. */
+function sdmxRecords(csv: string): { header: string[]; rows: string[][] } {
+  const [header, ...rows] = csvRows(withoutByteOrderMark(csv));
+  if (header === undefined) {
+    throw new SyntaxError('Not an ECB SDMX-CSV file: it is empty');
+  }
+  for (const cells of rows) {
+    if (cells.length !== header.length) {
+      throw new SyntaxError(
+        `Malformed ECB SDMX-CSV row: ${cells.length} cells, the header has ${header.length}`,
+      );
+    }
+  }
+  return { header, rows };
+}
+
+/** The columns of an SDMX-CSV file, by name, or SyntaxError when a required one is missing. */
+function sdmxColumns(header: readonly string[], required: readonly string[]): Map<string, number> {
+  const columns = new Map(header.map((name, i) => [name.trim(), i] as const));
+  for (const name of required) {
+    if (!columns.has(name)) {
+      throw new SyntaxError(`Not an ECB SDMX-CSV file: no ${name} column`);
+    }
+  }
+  return columns;
+}
+
+/**
+ * The DECIMALS of each series in an ECB SDMX-CSV file: the data file itself with full detail, or
+ * the series file the API returns with `detail=nodata`.
+ */
+export function parseEcbSdmxDecimals(csv: string): Record<string, number> {
+  const { header, rows } = sdmxRecords(csv);
+  const columns = sdmxColumns(header, ['CURRENCY', 'DECIMALS']);
+  const decimals: Record<string, number> = {};
+  for (const cells of rows) {
+    const currency = cells[columns.get('CURRENCY')!]!.trim();
+    decimals[currency] = statedDecimals(currency, cells[columns.get('DECIMALS')!]!.trim());
+  }
+  return decimals;
+}
+
+/** The value of an optional column, or undefined when the file doesn't have it. */
+function optionalCell(cells: readonly string[], columns: Map<string, number>, name: string) {
+  const index = columns.get(name);
+  if (index === undefined) {
+    return undefined;
+  }
+  return cells[index]?.trim();
+}
+
+/**
+ * Parses the ECB Data Portal's SDMX-CSV (`format=csvdata`) for the daily euro reference rates
+ * (dataflow EXR, key `D.<currencies>.EUR.SP00.A`) into one EUR-based table per day, newest first,
+ * like parseEcbXml. Any date range back to 1999 comes in one file.
+ *
+ * The API strips trailing zeros ('136.8' for the published 136.80), so the published digits are
+ * rebuilt from each series' DECIMALS attribute: in the file with full detail, or from `decimals`
+ * (see parseEcbSdmxDecimals) for a `detail=dataonly` file. Two series overstate it (THB and LTL),
+ * and are padded only to the decimals the ECB actually published. Without DECIMALS, the digits
+ * stay as the file gives them; the values are exact either way. An empty or `NaN` value is a missing value.
+ * A row for another frequency, rate type or base currency, or with a UNIT_MULT other than 0,
+ * throws SyntaxError rather than being read as a daily rate. Discontinued series simply end, so
+ * the tables of their last days include them.
+ *
+ * No `availableAt` is set, as with parseEcbXml: the API gives no publication time, and the ECB
+ * publishes at about 16:00 CET. So a backtest that asks for 10:00 CET on a day still gets that
+ * day's rate; ask for the day before if that matters.
+ *
+ *     const tables = parseEcbSdmxCsv(await (await fetch(url)).text());
+ *     const history = rateHistory(tables); // from @ducatjs/money/convert/history
+ */
+export function parseEcbSdmxCsv(csv: string, options?: EcbSdmxOptions): RateTable[] {
+  const { header, rows } = sdmxRecords(csv);
+  const columns = sdmxColumns(header, ['CURRENCY', 'CURRENCY_DENOM', 'TIME_PERIOD', 'OBS_VALUE']);
+  const at = (cells: readonly string[], name: string): string =>
+    cells[columns.get(name)!]?.trim() ?? '';
+
+  const days = new Map<string, Record<string, string | null>>();
+  for (const cells of rows) {
+    const currency = at(cells, 'CURRENCY');
+    const day = at(cells, 'TIME_PERIOD');
+    const where = `${currency} on ${day}`;
+    const unexpected =
+      at(cells, 'CURRENCY_DENOM') !== 'EUR' ||
+      (optionalCell(cells, columns, 'FREQ') ?? 'D') !== 'D' ||
+      (optionalCell(cells, columns, 'EXR_TYPE') ?? 'SP00') !== 'SP00' ||
+      (optionalCell(cells, columns, 'EXR_SUFFIX') ?? 'A') !== 'A';
+    if (unexpected) {
+      throw new SyntaxError(`Not a daily EUR reference rate: ${cells.join(',')}`);
+    }
+    if (!/^[A-Z]{3}$/.test(currency) || !ISO_DAY.test(day)) {
+      throw new SyntaxError(`Malformed ECB SDMX-CSV row: ${cells.join(',')}`);
+    }
+    const multiplier = optionalCell(cells, columns, 'UNIT_MULT');
+    if (multiplier !== undefined && multiplier !== '' && multiplier !== '0') {
+      throw new SyntaxError(`Unsupported UNIT_MULT ${multiplier} (${where})`);
+    }
+
+    const value = at(cells, 'OBS_VALUE');
+    let rate = readRateCell(value, where);
+    if (rate !== null) {
+      // The file's own DECIMALS, capped like parseEcbSdmxDecimals; else the caller's, as given.
+      const stated = optionalCell(cells, columns, 'DECIMALS');
+      let decimals = options?.decimals?.[currency];
+      if (stated !== undefined && stated !== '') {
+        decimals = statedDecimals(currency, stated);
+      }
+      if (decimals !== undefined) {
+        rate = withDecimals(rate, decimals);
+      }
+    }
+
+    const isoDay = calendarDay(
+      Number(day.slice(0, 4)),
+      Number(day.slice(5, 7)),
+      Number(day.slice(8)),
+    );
+    addDayRate(days, isoDay, currency, rate);
+  }
+
+  const tables: RateTable[] = [];
+  for (const [day, rates] of days) {
+    if (Object.values(rates).some((rate) => rate !== null)) {
+      tables.push(ecbTable(day, rates));
+    }
+  }
+  return newestFirst(tables);
+}

package/src/exact.ts

@@ -0,0 +1,182 @@
+// ExactMoney: an exact rational amount for chains of arithmetic that should round once, at the end.
+// It has no formatting, JSON or minor units on purpose: it must be rounded back to Money before it
+// leaves the process.
+import { currencyExponent } from './currency.js';
+import { pow10n, ratio, type Factor } from './decimal.js';
+import { CurrencyMismatchError, make, type Money } from './money.js';
+import type { Rate } from './rate.js';
+import { DEFAULT_ROUNDING, divideAndRoundBigint, type RoundingMode } from './rounding.js';
+
+/**
+ * A rounded value and what rounding left out: `value + residual` is exactly the unrounded amount.
+ */
+export interface Rounded<C extends string> {
+  readonly value: Money<C>;
+  readonly residual: ExactMoney<C>;
+}
+
+/**
+ * An exact amount of `currency`: num/den major units, reduced, den > 0. Build it with `exact()`.
+ */
+export class ExactMoney<C extends string = string> {
+  readonly currency: C;
+  readonly num: bigint;
+  readonly den: bigint;
+
+  /** @internal use exact() */
+  constructor(currency: C, numerator: bigint, denominator: bigint) {
+    const reduced = ratio(numerator, denominator); // reduces and makes the denominator positive
+    this.currency = currency;
+    this.num = reduced.num;
+    this.den = reduced.den;
+  }
+
+  /** this + other, exactly. */
+  add(other: ExactMoney<C>): ExactMoney<C> {
+    assertSameCurrency(this, other);
+    const numerator = this.num * other.den + other.num * this.den;
+    return new ExactMoney(this.currency, numerator, this.den * other.den);
+  }
+
+  /** this − other, exactly. */
+  subtract(other: ExactMoney<C>): ExactMoney<C> {
+    return this.add(other.negate());
+  }
+
+  /** −this. */
+  negate(): ExactMoney<C> {
+    return new ExactMoney(this.currency, -this.num, this.den);
+  }
+
+  /** this × factor, exactly. */
+  multiply(factor: Factor): ExactMoney<C> {
+    const factorRatio = ratio(factor);
+    return new ExactMoney(this.currency, this.num * factorRatio.num, this.den * factorRatio.den);
+  }
+
+  /** this ÷ divisor, exactly. */
+  divide(divisor: Factor): ExactMoney<C> {
+    const divisorRatio = ratio(divisor);
+    if (divisorRatio.num === 0n) {
+      throw new RangeError('Division by zero');
+    }
+    return new ExactMoney(this.currency, this.num * divisorRatio.den, this.den * divisorRatio.num);
+  }
+
+  /** Converts exactly at `rate`; nothing is rounded. */
+  convert<To extends string>(rate: Rate<C, To>): ExactMoney<To> {
+    if (rate.from !== this.currency) {
+      throw new CurrencyMismatchError(rate.from, this.currency);
+    }
+    return new ExactMoney(rate.to, this.num * rate.ratio.num, this.den * rate.ratio.den);
+  }
+
+  /** −1, 0 or 1. */
+  compare(other: ExactMoney<C>): -1 | 0 | 1 {
+    assertSameCurrency(this, other);
+    // Both denominators are positive, so cross-multiplying keeps the order.
+    const left = this.num * other.den;
+    const right = other.num * this.den;
+    if (left < right) {
+      return -1;
+    }
+    if (left > right) {
+      return 1;
+    }
+    return 0;
+  }
+
+  /** Same currency and the same exact value. */
+  equals(other: ExactMoney): boolean {
+    return this.currency === other.currency && this.num === other.num && this.den === other.den;
+  }
+
+  /** −1, 0 or 1. */
+  sign(): -1 | 0 | 1 {
+    if (this.num > 0n) {
+      return 1;
+    }
+    if (this.num < 0n) {
+      return -1;
+    }
+    return 0;
+  }
+
+  /** Whether the amount is zero. */
+  isZero(): boolean {
+    return this.num === 0n;
+  }
+
+  /** Whether the amount fits `scale` (default: the currency's exponent) without rounding. */
+  isExact(scale: number = currencyExponent(this.currency)): boolean {
+    return (this.num * pow10n(scale)) % this.den === 0n;
+  }
+
+  /** Rounds once to `scale` (default: the currency's exponent). */
+  round(
+    rounding: RoundingMode = DEFAULT_ROUNDING,
+    scale: number = currencyExponent(this.currency),
+  ): Money<C> {
+    const minor = divideAndRoundBigint(this.num * pow10n(scale), this.den, rounding);
+    return make(this.currency, minor, scale);
+  }
+
+  /** Rounds once and reports the difference, for booking it (e.g. an "FX rounding" ledger line). */
+  roundWithResidual(rounding: RoundingMode = DEFAULT_ROUNDING, scale?: number): Rounded<C> {
+    const value = this.round(rounding, scale);
+    const residual = this.subtract(exact(value));
+    return { value, residual };
+  }
+
+  /** "10/3 EUR", for debugging only. */
+  toString(): string {
+    if (this.den === 1n) {
+      return `${this.num} ${this.currency}`;
+    }
+    return `${this.num}/${this.den} ${this.currency}`;
+  }
+
+  /** Blocks `a + b` and `a > b`: round() first. */
+  [Symbol.toPrimitive](hint: string): string {
+    if (hint === 'string') {
+      return this.toString();
+    }
+    throw new TypeError('ExactMoney cannot be converted to a number; round() it first');
+  }
+}
+
+function assertSameCurrency(money: ExactMoney, other: ExactMoney): void {
+  if (money.currency !== other.currency) {
+    throw new CurrencyMismatchError(money.currency, other.currency);
+  }
+}
+
+/**
+ * The exact value of `money`, for chained arithmetic: `exact(price).divide(3).round('halfEven')`.
+ */
+export function exact<C extends string>(money: Money<C>): ExactMoney<C> {
+  return new ExactMoney(money.currency, BigInt(money.minor), pow10n(money.scale));
+}
+
+/**
+ * The exact sum (zero of `currency` for an empty list). Round it once for a batch's rounding line.
+ */
+export function sumExact<C extends string>(
+  items: readonly ExactMoney<C>[],
+  currency?: C,
+): ExactMoney<C> {
+  const sumCurrency = currency ?? items[0]?.currency;
+  if (sumCurrency === undefined) {
+    throw new RangeError('sumExact of an empty list needs a currency');
+  }
+  let sum = new ExactMoney(sumCurrency, 0n, 1n);
+  for (const item of items) {
+    sum = sum.add(item);
+  }
+  return sum;
+}
+
+/** Whether `value` is an ExactMoney. */
+export function isExactMoney(value: unknown): value is ExactMoney {
+  return value instanceof ExactMoney;
+}

package/src/fed.ts

@@ -0,0 +1,146 @@
+// `@ducatjs/money/convert/fed`: an offline parser for the Federal Reserve Board's H.10 foreign
+// exchange rates. Parser only, no fetcher: see parseFedH10Csv for where the files come from.
+import { quotedTable } from './history.js';
+import type { RateTable } from './provider.js';
+import { addDayRate, csvRows, isCalendarDay, newestFirst, readRateCell } from './rate-text.js';
+
+// RXI$US_N.B.EU is USD per euro; RXI_N.B.JA is yen per USD.
+const SERIES = /^(?:H10\/H10\/)?RXI(\$US)?_N\.B\.([A-Z]{2,3})$/;
+
+// The country codes in H.10 series IDs, and the currency each one's column must carry.
+const FED_COUNTRIES: Readonly<Record<string, string>> = {
+  AL: 'AUD',
+  EU: 'EUR',
+  NZ: 'NZD',
+  UK: 'GBP',
+  BZ: 'BRL',
+  CA: 'CAD',
+  CH: 'CNY',
+  DN: 'DKK',
+  HK: 'HKD',
+  IN: 'INR',
+  JA: 'JPY',
+  MA: 'MYR',
+  MX: 'MXN',
+  NO: 'NOK',
+  SF: 'ZAR',
+  SI: 'SGD',
+  KO: 'KRW',
+  SL: 'LKR',
+  SD: 'SEK',
+  SZ: 'CHF',
+  TA: 'TWD',
+  TH: 'THB',
+  VES: 'VEB',
+};
+
+function notH10(why: string): never {
+  throw new SyntaxError(`Not a Federal Reserve H.10 CSV file: ${why}`);
+}
+
+/**
+ * Parses the Federal Reserve Board's H.10 daily foreign exchange rates, as CSV from its Data
+ * Download Program (DDP), into one USD-based table per day, newest first. These are the noon
+ * buying rates in New York, certified by the New York Fed for customs purposes, with `source:
+ * 'FRB'` and `type: 'noon buying'`, back to 1971.
+ *
+ * - **Direction.** H.10 quotes "currency units per U.S. dollar except as noted": AUD, EUR, NZD and
+ *   GBP (series `RXI$US_N.B.*`) are USD per unit. Those four are stored as exact inverses, so
+ *   every table is USD → currency, and the published quote stays on the rate:
+ *   `rate('USD', 'EUR').inverse().toString()` is '1.1750' again.
+ * - **Holidays** are rows of `ND` ("no data"); such a day is left out, so a lookback goes on to
+ *   the day before, and a file of holidays only gives []. A single `ND` cell is a missing value.
+ *   A file with no observation rows at all throws, as it is more likely cut short than empty.
+ * - **Strict:** each column's Unit, Multiplier and Currency must be "Currency", 1 and the code
+ *   its series ID stands for (EU is EUR), a currency can't have two columns, and two different
+ *   values for one day throw.
+ * - **Digits.** H.10 publishes four decimals and keeps trailing zeros; they are kept.
+ * - **Codes.** The Fed's column codes are used as they are, so the bolivar is `VEB`, as the Fed
+ *   labels it.
+ * - **Publication.** The release is weekly (Mondays, 4:15 p.m. ET) and covers the week before,
+ *   so a Tuesday's rate is known only up to six days later. The CSV doesn't say when each row was
+ *   released, so no `availableAt` is set; give each table one yourself if a backtest needs it.
+ *
+ * **Where the data comes from.** The DDP at federalreserve.gov/datadownload (release H10, CSV,
+ * "series in columns", with labels) serves these files today. The Board is retiring the DDP: the
+ * "Build Your Package" feature goes in November 2026 and the rest later, and it points users to
+ * FRED (fred.stlouisfed.org) instead. FRED needs an API key, and its terms forbid storing or
+ * caching its content and any commercial use without consent, which is why ducat has no H.10
+ * fetcher. Board data itself is public domain ("please cite to the Board as the source").
+ *
+ *     const tables = parseFedH10Csv(await readFile('FRB_H10.csv', 'utf8'));
+ */
+export function parseFedH10Csv(csv: string): RateTable[] {
+  const rows = csvRows(csv.charCodeAt(0) === 0xfeff ? csv.slice(1) : csv);
+  const series =
+    rows.find((cells) => cells[0]?.trim() === 'Time Period') ?? notH10('no "Time Period" row');
+  const labelled = (label: string): string[] => {
+    const row = rows.find((cells) => cells[0]?.trim() === label);
+    if (row === undefined || row.length !== series.length) {
+      notH10(`no "${label}" row matching the columns`);
+    }
+    return row;
+  };
+  const currencies = labelled('Currency:');
+  const multipliers = labelled('Multiplier:');
+  const units = labelled('Unit:');
+
+  // Each column: its currency, and whether it is quoted as USD per unit (to be inverted).
+  const columns: { currency: string; inverted: boolean }[] = [];
+  for (let i = 1; i < series.length; i++) {
+    const id = SERIES.exec(series[i]!.trim());
+    const currency = currencies[i]!.trim();
+    if (id === null || !/^[A-Z]{3}$/.test(currency) || currency === 'USD') {
+      notH10(`column ${i + 1} is ${series[i]} for ${currency}`);
+    }
+    // The series ID names the country; it must agree with the currency code beside it.
+    const expected = FED_COUNTRIES[id[2]!];
+    if (expected !== undefined && expected !== currency) {
+      notH10(`series ${series[i]} is ${expected}, not ${currency}`);
+    }
+    if (columns.some((column) => column.currency === currency)) {
+      notH10(`${currency} has two columns`);
+    }
+    // Other units or a multiplier other than 1 would make the published number mean something else.
+    if (units[i]!.trim() !== 'Currency' || multipliers[i]!.trim() !== '1') {
+      throw new SyntaxError(
+        `Unsupported H.10 unit ${units[i]} × ${multipliers[i]} for ${currency}`,
+      );
+    }
+    columns.push({ currency, inverted: id[1] !== undefined });
+  }
+
+  const observations = rows.slice(rows.indexOf(series) + 1);
+  if (observations.length === 0) {
+    notH10('no observations');
+  }
+  const days = new Map<string, Record<string, string | null>>();
+  for (const cells of observations) {
+    const day = cells[0]!.trim();
+    if (!isCalendarDay(day) || cells.length !== series.length) {
+      throw new SyntaxError(`Malformed H.10 row: ${cells.join(',')}`);
+    }
+    columns.forEach(({ currency }, i) => {
+      addDayRate(days, day, currency, readRateCell(cells[i + 1]!, `${currency} on ${day}`));
+    });
+  }
+
+  const tables: RateTable[] = [];
+  for (const [day, published] of days) {
+    const rates: Record<string, { rate: string; inverted: boolean } | null> = {};
+    let quoted = 0;
+    for (const { currency, inverted } of columns) {
+      const rate = published[currency] ?? null;
+      rates[currency] = rate === null ? null : { rate, inverted };
+      if (rate !== null) {
+        quoted++;
+      }
+    }
+    if (quoted > 0) {
+      tables.push(
+        quotedTable({ base: 'USD', source: 'FRB', type: 'noon buying', asOf: day, rates }),
+      );
+    }
+  }
+  return newestFirst(tables);
+}