@ducatjs/money 0.1.0 → 0.2.0

package/src/drizzle/sqlite.ts

@@ -0,0 +1,70 @@
+/**
+ * `@ducatjs/money/drizzle/sqlite`: Drizzle ORM column types for SQLite (better-sqlite3, libSQL,
+ * Bun). Selects return `Money`, inserts and updates accept it, and the currency is part of the
+ * column's type.
+ *
+ *     import { sqliteTable } from 'drizzle-orm/sqlite-core';
+ *     import { moneyMinor } from '@ducatjs/money/drizzle/sqlite';
+ *
+ *     const orders = sqliteTable('orders', { total: moneyMinor('EUR')('total_minor').notNull() });
+ */
+import { customType } from 'drizzle-orm/sqlite-core';
+import { currencyExponent } from '../currency.js';
+import type { CurrencyInput, Money } from '../money.js';
+import {
+  decimalFromDriver,
+  decimalToDriver,
+  jsonFromDriver,
+  jsonToDriver,
+  minorFromDriver,
+  minorToDriver,
+} from '../sql.js';
+
+/**
+ * An INTEGER column of minor units in a fixed currency (`1234` is 12.34 EUR), read back as
+ * `Money<C>`. Exact up to SQLite's limit of ±9.2·10^18 minor units. better-sqlite3 returns integers
+ * as numbers by default, which are exact only below 2^53; beyond that reading throws, so call
+ * `defaultSafeIntegers(true)` on the database for larger amounts. Writing another currency, or a
+ * value at a scale other than the currency's, throws.
+ *
+ *     total: moneyMinor('EUR')('total_minor').notNull()
+ */
+export function moneyMinor<const C extends CurrencyInput>(currency: C) {
+  return customType<{ data: Money<C>; driverData: number | bigint }>({
+    dataType: () => 'integer',
+    toDriver: (money) => minorToDriver(money, currency),
+    fromDriver: (value) => minorFromDriver(value, currency),
+  });
+}
+
+/**
+ * A TEXT column holding the exact decimal string (`12.34`), read back as `Money<C>`. SQLite's
+ * NUMERIC affinity would store some decimals as REAL and lose digits, so they are kept as text.
+ * Writing another currency, or a value at a scale other than the currency's, throws.
+ *
+ *     price: moneyDecimal('EUR')('price').notNull()
+ */
+export function moneyDecimal<const C extends CurrencyInput>(currency: C) {
+  // fail at the schema definition, not on the first query, for an unknown currency
+  currencyExponent(currency);
+
+  return customType<{ data: Money<C>; driverData: string }>({
+    dataType: () => 'text',
+    toDriver: (money) => decimalToDriver(money, currency, undefined),
+    fromDriver: (value) => decimalFromDriver(value, currency),
+  });
+}
+
+/**
+ * A TEXT column holding `{"amount":"12.34","currency":"EUR"}`, with the currency in each value.
+ * Pass a currency to fix it: then a value in another currency throws, on write and on read.
+ *
+ *     refund: moneyJson()('refund')
+ */
+export function moneyJson<const C extends CurrencyInput = CurrencyInput>(currency?: C) {
+  return customType<{ data: Money<C>; driverData: string }>({
+    dataType: () => 'text',
+    toDriver: (money) => jsonToDriver(money, currency),
+    fromDriver: (value) => jsonFromDriver(value, currency),
+  });
+}

package/src/ecb.ts

@@ -1,6 +1,7 @@
 // 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',
@@ -28,7 +29,7 @@ const ISO_DAY = /^(\d{4})-(\d\d)-(\d\d)$/;
  * 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>): RateTable {
+function ecbTable(asOf: string, rates: Record<string, string | null>): RateTable {
   return rateTable({ base: 'EUR', asOf, source: 'ECB', type: 'reference', rates });
 }
 
@@ -67,10 +68,6 @@ function ratesOfDay(body: string): Record<string, string> {
   return rates;
 }
 
-function newestFirst(tables: RateTable[]): RateTable[] {
-  return tables.sort((table, other) => other.asOf!.localeCompare(table.asOf!));
-}
-
 /**
  * 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
@@ -130,8 +127,8 @@ function isoDay(text: string): string {
 
 /**
  * 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 skipped, and a day with no rates at
- * all is left out, so a lookback goes on to the day before.
+ * '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)
@@ -145,16 +142,185 @@ export function parseEcbCsv(csv: string): RateTable[] {
   const tables: RateTable[] = [];
   for (const line of lines.slice(1)) {
     const cells = line.split(',').map((cell) => cell.trim());
-    const rates: Record<string, string> = {};
+    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];
-      const rate = cells[i];
-      if (currency && rate && rate !== 'N/A') {
-        rates[currency] = rate;
+      if (!currency) {
+        continue;
+      }
+      const rate = readRateCell(cells[i] ?? '', `${currency} on ${day}`);
+      rates[currency] = rate;
+      if (rate !== null) {
+        quoted++;
       }
     }
-    const day = isoDay(cells[0]!);
-    if (Object.keys(rates).length > 0) {
+    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));
     }
   }

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);
+}