@ducatjs/money 0.1.0 → 0.2.0

package/src/fetch.ts

@@ -1,7 +1,8 @@
 // Network fetchers for published reference rates, using the platform fetch. Opt-in: nothing else in
 // the library imports this module, so core and @ducatjs/money/convert never touch the
 // network. You decide when to call it and how to cache.
-import { parseEcbXml } from './ecb.js';
+import { parseBankOfCanadaJson } from './boc.js';
+import { parseEcbSdmxCsv, parseEcbSdmxDecimals, parseEcbXml } from './ecb.js';
 import type { RateTable } from './provider.js';
 
 /**
@@ -73,33 +74,8 @@ export class FetchRatesError extends Error {
  */
 export async function fetchEcb(options?: FetchEcbOptions): Promise<RateTable[]> {
   const url = ECB_URLS[options?.history ?? 'daily'];
-  const fetchFunction = options?.fetch ?? (globalThis as { fetch?: Fetch }).fetch;
-  if (fetchFunction === undefined) {
-    throw new TypeError('No fetch available: pass options.fetch');
-  }
-
-  const init: { signal?: AbortSignalLike; headers: Record<string, string> } = {
-    headers: { accept: 'application/xml' },
-  };
-  const signal = requestSignal(options?.signal, options?.timeout ?? DEFAULT_TIMEOUT_MS);
-  if (signal !== undefined) {
-    init.signal = signal;
-  }
-  const response = await fetchFunction(url, init);
-  if (!response.ok) {
-    throw new FetchRatesError(url, response.status);
-  }
-
-  const body = await response.text();
-  try {
-    return parseEcbXml(body);
-  } catch (error) {
-    // An error page or a captive portal is the usual cause, so say where the bad file came from.
-    if (error instanceof SyntaxError) {
-      throw new SyntaxError(`${error.message} (from ${url})`, { cause: error });
-    }
-    throw error;
-  }
+  const body = await getText(url, 'application/xml', options);
+  return parsedFrom(url, () => parseEcbXml(body));
 }
 
 /** The caller's signal, a timeout signal, or both combined. */
@@ -125,3 +101,206 @@ function requestSignal(
   }
   return statics.any([signal, timeoutSignal]);
 }
+
+/** The ECB Data Portal's SDMX REST API (no key, and CORS-enabled, so it works in browsers). */
+export const ECB_DATA_API = 'https://data-api.ecb.europa.eu/service/data/EXR';
+
+/** Options for fetching a date range of ECB reference rates. */
+export interface FetchEcbRangeOptions extends Omit<FetchEcbOptions, 'history'> {
+  /** The first day ('1999-01-04' at the earliest). */
+  readonly start: string | Date;
+  /** The last day (default: the latest published). */
+  readonly end?: string | Date;
+  /** ISO codes to fetch (default: every currency, including discontinued series). */
+  readonly currencies?: readonly string[];
+}
+
+/**
+ * A request's UTC day: a 'YYYY-MM-DD' string that is a real calendar day, or a Date (any
+ * offset) as its UTC day. Anything else is a RangeError, before any request is made.
+ */
+function requestDay(time: string | Date, name: string): string {
+  let day: string;
+  if (typeof time === 'string') {
+    day = time;
+  } else {
+    day = Number.isNaN(time.getTime()) ? '' : time.toISOString().slice(0, 10);
+  }
+  const match = /^(\d{4})-(\d\d)-(\d\d)$/.exec(day);
+  const date =
+    match === null ? undefined : new Date(Date.UTC(+match[1]!, +match[2]! - 1, +match[3]!));
+  // Date.UTC rolls 30 February over into March, so a real day must come back unchanged.
+  if (date === undefined || date.toISOString().slice(0, 10) !== day) {
+    throw new RangeError(`${name} must be a date, got ${String(time)}`);
+  }
+  return day;
+}
+
+/** Wraps a parser's SyntaxError with the URL the bad file came from (an error page, usually). */
+function parsedFrom<T>(url: string, parse: () => T): T {
+  try {
+    return parse();
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new SyntaxError(`${error.message} (from ${url})`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+/** The platform's AbortController, where it exists. */
+type AbortControllerLike = { readonly signal: AbortSignalLike; abort(reason?: unknown): void };
+
+/** GETs `url` as text, with the timeout and signal handling every fetcher here shares. */
+async function getText(
+  url: string,
+  accept: string,
+  options: Omit<FetchEcbOptions, 'history'> | undefined,
+): Promise<string> {
+  return (await getTextOrNotFound(url, accept, options, false))!;
+}
+
+/** getText, or undefined for HTTP 404 when `notFoundIsEmpty` (an API's "no results"). */
+async function getTextOrNotFound(
+  url: string,
+  accept: string,
+  options: Omit<FetchEcbOptions, 'history'> | undefined,
+  notFoundIsEmpty: boolean,
+): Promise<string | undefined> {
+  const fetchFunction = options?.fetch ?? (globalThis as { fetch?: Fetch }).fetch;
+  if (fetchFunction === undefined) {
+    throw new TypeError('No fetch available: pass options.fetch');
+  }
+  const init: { signal?: AbortSignalLike; headers: Record<string, string> } = {
+    headers: { accept },
+  };
+  const signal = requestSignal(options?.signal, options?.timeout ?? DEFAULT_TIMEOUT_MS);
+  if (signal !== undefined) {
+    init.signal = signal;
+  }
+  const response = await fetchFunction(url, init);
+  if (notFoundIsEmpty && response.status === 404) {
+    return undefined;
+  }
+  if (!response.ok) {
+    throw new FetchRatesError(url, response.status);
+  }
+  return response.text();
+}
+
+/**
+ * Fetches a date range of ECB euro reference rates from the ECB Data Portal and parses them with
+ * parseEcbSdmxCsv: EUR-based tables, one per TARGET working day, newest first, with the published
+ * digits. It makes two requests: the series' DECIMALS (small) and the observations without
+ * attributes, which keeps the full history since 1999 to about 15 MB. Give a few days before the
+ * first day you need, so that a lookback from it has a table to fall back on. A range with no
+ * rates (a weekend, or after the latest day) gives []. Both requests share one timeout and are
+ * cancelled together: if one fails, the other is aborted. The ECB states that its rates are for
+ * information purposes only.
+ *
+ *     const tables = await fetchEcbRange({ start: '2026-01-01', currencies: ['USD', 'JPY'] });
+ *     const history = rateHistory(tables); // from @ducatjs/money/convert/history
+ */
+export async function fetchEcbRange(options: FetchEcbRangeOptions): Promise<RateTable[]> {
+  const currencies = options.currencies ?? [];
+  for (const currency of currencies) {
+    if (!/^[A-Z]{3}$/.test(currency)) {
+      throw new RangeError(`Not an ISO currency code: ${currency}`);
+    }
+  }
+  const start = requestDay(options.start, 'start');
+  if (start < '1999-01-04') {
+    throw new RangeError(`The ECB's rates start on 1999-01-04, not ${start}`);
+  }
+  let query = `?format=csvdata&startPeriod=${start}`;
+  if (options.end !== undefined) {
+    const end = requestDay(options.end, 'end');
+    if (end < start) {
+      throw new RangeError(`end ${end} is before start ${start}`);
+    }
+    query += `&endPeriod=${end}`;
+  }
+  const url = `${ECB_DATA_API}/D.${currencies.join('+')}.EUR.SP00.A`;
+  const seriesUrl = `${url}?format=csvdata&detail=nodata`;
+  const dataUrl = `${url}${query}&detail=dataonly`;
+
+  // One controller for both requests, tied to the caller's signal and the timeout, so that a
+  // failure of either cancels the other (the data can be ~15 MB) instead of letting it run on.
+  let shared: Omit<FetchEcbOptions, 'history'> = options;
+  let controller: AbortControllerLike | undefined;
+  const Controller = (globalThis as { AbortController?: new () => AbortControllerLike })
+    .AbortController;
+  if (Controller !== undefined) {
+    const own = new Controller();
+    controller = own;
+    const outer = requestSignal(options.signal, options.timeout ?? DEFAULT_TIMEOUT_MS);
+    if (outer?.aborted === true) {
+      own.abort(outer.reason);
+    } else {
+      outer?.addEventListener('abort', () => own.abort(outer.reason), { once: true });
+    }
+    shared = { ...options, signal: own.signal, timeout: 0 };
+  }
+
+  let series: string;
+  let data: string | undefined;
+  try {
+    [series, data] = await Promise.all([
+      getText(seriesUrl, 'text/csv', shared),
+      getTextOrNotFound(dataUrl, 'text/csv', shared, true),
+    ]);
+  } catch (error) {
+    controller?.abort(error);
+    throw error;
+  }
+  if (data === undefined) {
+    return [];
+  }
+  const decimals = parsedFrom(seriesUrl, () => parseEcbSdmxDecimals(series));
+  return parsedFrom(dataUrl, () => parseEcbSdmxCsv(data, { decimals }));
+}
+
+/** The Bank of Canada's Valet API for its daily exchange rates (no key; CORS-enabled). */
+export const BANK_OF_CANADA_URL =
+  'https://www.bankofcanada.ca/valet/observations/group/FX_RATES_DAILY/json';
+
+/** Options for fetching Bank of Canada rates. */
+export interface FetchBankOfCanadaOptions extends Omit<FetchEcbOptions, 'history'> {
+  /** The first day (2017-01-03 at the earliest). Default: only the latest published day. */
+  readonly start?: string | Date;
+  /** The last day (default: the latest published). Needs a `start`. */
+  readonly end?: string | Date;
+}
+
+/**
+ * Fetches the Bank of Canada's daily exchange rates from its Valet API and parses them with
+ * parseBankOfCanadaJson: CAD-based tables, newest first. Without `start`, only the latest day;
+ * without `end`, up to the latest. A range with no business days in it gives [].
+ * The Bank asks users to keep within its request limits, which it doesn't publish, and its rates
+ * are "released for statistical and analytical purposes only", not for transactions.
+ *
+ *     const [latest] = await fetchBankOfCanada();
+ *     const year = await fetchBankOfCanada({ start: '2026-01-01' });
+ */
+export async function fetchBankOfCanada(options?: FetchBankOfCanadaOptions): Promise<RateTable[]> {
+  let query = '?recent=1';
+  if (options?.start !== undefined) {
+    const start = requestDay(options.start, 'start');
+    if (start < '2017-01-03') {
+      throw new RangeError(`Valet's daily rates start on 2017-01-03, not ${start}`);
+    }
+    query = `?start_date=${start}`;
+    if (options.end !== undefined) {
+      const end = requestDay(options.end, 'end');
+      if (end < start) {
+        throw new RangeError(`end ${end} is before start ${start}`);
+      }
+      query += `&end_date=${end}`;
+    }
+  } else if (options?.end !== undefined) {
+    throw new RangeError('end needs a start');
+  }
+  const url = `${BANK_OF_CANADA_URL}${query}`;
+  const body = await getText(url, 'application/json', options);
+  return parsedFrom(url, () => parseBankOfCanadaJson(body));
+}

package/src/fn.ts

@@ -12,6 +12,8 @@ export {
   zero,
   fromJSON,
   isMoney,
+  isMoneyIn,
+  assertCurrency,
   extendMoney,
   type ExtendMoneyOptions,
   sum,
@@ -26,6 +28,7 @@ export {
   toScale,
   compare,
   equals,
+  identical,
   lessThan,
   lessThanOrEqual,
   greaterThan,
@@ -37,10 +40,14 @@ export {
   min,
   max,
   clamp,
+  majorPart,
+  minorPart,
   toDecimal,
   toMinor,
   toMinorNumber,
   CurrencyMismatchError,
+  type RoundingPolicy,
+  type RoundingInput,
   type Money,
   type MoneyJSON,
   type MoneyOptions,
@@ -65,9 +72,16 @@ export * from './tax.js';
 export * from './convert.js';
 export * from './exact.js';
 export * from './ecb.js';
+export * from './boc.js';
+export * from './boe.js';
+export * from './hmrc.js';
+export * from './fed.js';
+export * from './history.js';
 export * from './stripe-fx.js';
 export * from './adyen-fx.js';
 export * from './cash.js';
+export * from './historic.js';
+export { roundingPolicy, isoPolicy, assertScale, type RoundingPolicyOptions } from './policy.js';
 export * from './format.js';
 export * from './parse.js';
 export * from './stripe.js';

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