@ducatjs/money 0.0.0-stage → 0.1.0

package/src/ecb.ts

@@ -0,0 +1,162 @@
+// 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';
+
+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>): 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;
+}
+
+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
+ * `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 skipped, 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 rates: Record<string, string> = {};
+    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;
+      }
+    }
+    const day = isoDay(cells[0]!);
+    if (Object.keys(rates).length > 0) {
+      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/fetch.ts

@@ -0,0 +1,127 @@
+// 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 type { RateTable } from './provider.js';
+
+/**
+ * The part of the platform AbortSignal used here. Declared structurally so the library needs no DOM
+ * or Node types; any real AbortSignal fits.
+ */
+export interface AbortSignalLike {
+  readonly aborted: boolean;
+  readonly reason?: unknown;
+  addEventListener(type: 'abort', listener: () => void, options?: { once?: boolean }): void;
+  removeEventListener(type: 'abort', listener: () => void): void;
+}
+
+/** The subset of the platform fetch used here (Node 24+, Deno, Bun, browsers, workers). */
+export type Fetch = (
+  url: string,
+  init?: { signal?: AbortSignalLike; headers?: Record<string, string> },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/** The platform's AbortSignal statics, where they exist. */
+type AbortSignalStatics = {
+  timeout?: (milliseconds: number) => AbortSignalLike;
+  any?: (signals: AbortSignalLike[]) => AbortSignalLike;
+};
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** The ECB's eurofxref files: the latest day, the last 90 days, and the full history since 1999. */
+export const ECB_URLS = {
+  daily: 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml',
+  '90d': 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml',
+  all: 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist.xml',
+} as const;
+
+/** Options for fetching ECB reference rates. */
+export interface FetchEcbOptions {
+  /** 'daily' (default): the latest day; '90d': the last 90 days; 'all': since 1999 (several MB). */
+  readonly history?: keyof typeof ECB_URLS;
+  /** An AbortSignal to cancel the request; it is combined with the timeout. */
+  readonly signal?: AbortSignalLike;
+  /**
+   * Milliseconds before the request is aborted (default 30 000; 0 for no timeout). It needs the
+   * platform's AbortSignal.timeout, which Node 24, Deno, Bun and current browsers all have.
+   */
+  readonly timeout?: number;
+  /** A fetch to use instead of the global one (for proxies, retries or tests). */
+  readonly fetch?: Fetch;
+}
+
+/** Thrown when the HTTP request completes without a 2xx status. */
+export class FetchRatesError extends Error {
+  readonly status: number;
+  readonly url: string;
+  constructor(url: string, status: number) {
+    super(`GET ${url} failed with HTTP ${status}`);
+    this.name = 'FetchRatesError';
+    this.status = status;
+    this.url = url;
+  }
+}
+
+/**
+ * Fetches the ECB euro reference rates and parses them with parseEcbXml: EUR-based tables,
+ * newest first. The ECB publishes once per TARGET working day at about 16:00 CET and states
+ * that its rates are for information purposes only.
+ *
+ *     const [latest] = await fetchEcb(); // the RateTable for the last published day
+ *     const hist = snapshotsFrom(await fetchEcb({ history: '90d' }));
+ */
+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;
+  }
+}
+
+/** The caller's signal, a timeout signal, or both combined. */
+function requestSignal(
+  signal: AbortSignalLike | undefined,
+  timeout: number,
+): AbortSignalLike | undefined {
+  if (!Number.isFinite(timeout) || timeout < 0) {
+    throw new RangeError(`timeout must be a non-negative number of milliseconds, got ${timeout}`);
+  }
+  const statics = (globalThis as unknown as { AbortSignal?: AbortSignalStatics }).AbortSignal;
+  if (timeout === 0 || statics?.timeout === undefined) {
+    return signal;
+  }
+
+  const timeoutSignal = statics.timeout(timeout);
+  if (signal === undefined) {
+    return timeoutSignal;
+  }
+  if (statics.any === undefined) {
+    // Without AbortSignal.any the caller's signal wins: it is the one they can control.
+    return signal;
+  }
+  return statics.any([signal, timeoutSignal]);
+}