@ducatjs/money 0.2.1 → 0.3.0

package/src/ecb.ts

@@ -1,7 +1,14 @@
 // 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';
+import {
+  addDayRate,
+  checkAvailableAt,
+  csvRows,
+  newestFirst,
+  readRateCell,
+  withDecimals,
+} from './rate-text.js';
 
 const MONTHS = [
   'january',
@@ -24,13 +31,60 @@ const ATTRIBUTE = /([A-Za-z]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
 const RATE_TEXT = /^\d+(?:\.\d+)?$/;
 const ISO_DAY = /^(\d{4})-(\d\d)-(\d\d)$/;
 
+/** When each day's ECB rates became available: a publication time, for point-in-time lookups. */
+export type EcbAvailableAt = boolean | ((day: string) => string | Date);
+
+/** Options for parseEcbXml and parseEcbCsv. */
+export interface EcbOptions {
+  /**
+   * When each day's rates became available, so that a historical lookup (`asOf` a time) can't
+   * use a rate before it was published. `true` gives the ECB's documented publication time, 16:00
+   * CET on the day (Frankfurt time: 15:00 UTC in winter, 14:00 UTC in summer); a function gives
+   * your own, say from your own fetch log, since the ECB's time is approximate and a delay moves
+   * it. Default: none, so a query at any time on the day gets that day's rates.
+   */
+  readonly availableAt?: EcbAvailableAt;
+}
+
+// The ECB publishes its rates "at around 16:00 CET" on each TARGET working day. CET here is
+// Frankfurt's local time, summer time included; one formatter gives its offset on any day.
+let frankfurtFormatter: Intl.DateTimeFormat | undefined;
+
+/** 16:00 in Frankfurt on `day`, as a UTC instant. */
+function ecbPublicationTime(day: string): string {
+  frankfurtFormatter ??= new Intl.DateTimeFormat('en-US', {
+    timeZone: 'Europe/Berlin',
+    timeZoneName: 'shortOffset',
+  });
+  // Noon UTC is after any clock change that day (they happen at 01:00 UTC), and before 16:00 local.
+  const noon = new Date(`${day}T12:00:00Z`);
+  const zone = frankfurtFormatter.formatToParts(noon).find((part) => part.type === 'timeZoneName');
+  const offset = /^GMT([+-]\d+)$/.exec(zone?.value ?? '');
+  if (offset === null) {
+    throw new RangeError(`Can't tell Frankfurt's UTC offset on ${day} (${zone?.value})`);
+  }
+  const utcMs = Date.parse(`${day}T16:00:00Z`) - Number(offset[1]) * 3_600_000;
+  return new Date(utcMs).toISOString();
+}
+
 /**
  * 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 ecbTable(
+  asOf: string,
+  rates: Record<string, string | null>,
+  availableAt: EcbAvailableAt | undefined,
+): RateTable {
+  const info = { base: 'EUR', asOf, source: 'ECB', type: 'reference', rates };
+  if (availableAt === undefined || availableAt === false) {
+    return rateTable(info);
+  }
+  if (availableAt === true) {
+    return rateTable({ ...info, availableAt: ecbPublicationTime(asOf) });
+  }
+  return rateTable({ ...info, availableAt: availableAt(asOf) });
 }
 
 function notAnEcbFile(): never {
@@ -72,11 +126,13 @@ function ratesOfDay(body: string): Record<string, string> {
  * 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.
+ * before. A rate entry that can't be read throws SyntaxError. Pass `availableAt: true` to give each
+ * table the ECB's publication time, 16:00 CET (see `EcbOptions`).
  *
  *     const [latest] = parseEcbXml(await readFile('eurofxref-daily.xml', 'utf8'));
  */
-export function parseEcbXml(xml: string): RateTable[] {
+export function parseEcbXml(xml: string, options?: EcbOptions): RateTable[] {
+  checkAvailableAt(options?.availableAt);
   let days = 0;
   const tables: RateTable[] = [];
   for (const [, asOf, body] of withoutByteOrderMark(xml).matchAll(DAY_CUBE)) {
@@ -84,7 +140,7 @@ export function parseEcbXml(xml: string): RateTable[] {
     const day = isoDay(asOf!);
     const rates = ratesOfDay(body!);
     if (Object.keys(rates).length > 0) {
-      tables.push(ecbTable(day, rates));
+      tables.push(ecbTable(day, rates, options?.availableAt));
     }
   }
 
@@ -128,9 +184,11 @@ 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 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.
+ * day with no rates at all is left out, so a lookback goes on to the day before. `availableAt` works
+ * as in parseEcbXml.
  */
-export function parseEcbCsv(csv: string): RateTable[] {
+export function parseEcbCsv(csv: string, options?: EcbOptions): RateTable[] {
+  checkAvailableAt(options?.availableAt);
   const lines = withoutByteOrderMark(csv)
     .split(/\r?\n/)
     .filter((line) => line.trim() !== '');
@@ -157,7 +215,7 @@ export function parseEcbCsv(csv: string): RateTable[] {
       }
     }
     if (quoted > 0) {
-      tables.push(ecbTable(day, rates));
+      tables.push(ecbTable(day, rates, options?.availableAt));
     }
   }
   return newestFirst(tables);
@@ -171,7 +229,7 @@ export function parseEcbCsv(csv: string): RateTable[] {
 const PUBLISHED_DECIMALS: Readonly<Record<string, number>> = { THB: 3, LTL: 4 };
 
 /** Options for parseEcbSdmxCsv. */
-export interface EcbSdmxOptions {
+export interface EcbSdmxOptions extends EcbOptions {
   /**
    * 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.
@@ -262,14 +320,15 @@ function optionalCell(cells: readonly string[], columns: Map<string, number>, na
  * 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.
+ * The API gives no publication time, so no `availableAt` is set unless asked for, as with
+ * parseEcbXml: without it, a backtest that asks for 10:00 CET on a day still gets that day's rate.
+ * Pass `availableAt: true` for the ECB's documented 16:00 CET, or a function for your own.
  *
  *     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[] {
+  checkAvailableAt(options?.availableAt);
   const { header, rows } = sdmxRecords(csv);
   const columns = sdmxColumns(header, ['CURRENCY', 'CURRENCY_DENOM', 'TIME_PERIOD', 'OBS_VALUE']);
   const at = (cells: readonly string[], name: string): string =>
@@ -310,18 +369,18 @@ export function parseEcbSdmxCsv(csv: string, options?: EcbSdmxOptions): RateTabl
       }
     }
 
-    const isoDay = calendarDay(
+    const calendarDayOf = calendarDay(
       Number(day.slice(0, 4)),
       Number(day.slice(5, 7)),
       Number(day.slice(8)),
     );
-    addDayRate(days, isoDay, currency, rate);
+    addDayRate(days, calendarDayOf, currency, rate);
   }
 
   const tables: RateTable[] = [];
   for (const [day, rates] of days) {
     if (Object.values(rates).some((rate) => rate !== null)) {
-      tables.push(ecbTable(day, rates));
+      tables.push(ecbTable(day, rates, options?.availableAt));
     }
   }
   return newestFirst(tables);

package/src/entries/adyen-fx.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/adyen-fx`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../adyen-fx.js';

package/src/entries/boc.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/convert/boc`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../boc.js';

package/src/entries/boe.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/convert/boe`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../boe.js';

package/src/entries/crypto.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/crypto`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../crypto.js';

package/src/entries/currencies.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/currencies`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../currencies.js';

package/src/entries/drizzle-mysql.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/drizzle/mysql`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../drizzle/mysql.js';

package/src/entries/drizzle-pg.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/drizzle/pg`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../drizzle/pg.js';

package/src/entries/drizzle-sqlite.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/drizzle/sqlite`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../drizzle/sqlite.js';

package/src/entries/ecb.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/convert/ecb`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../ecb.js';

package/src/entries/fed.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/convert/fed`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../fed.js';

package/src/entries/fetch.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/convert/fetch`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../fetch.js';

package/src/entries/finance.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/finance`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../finance.js';

package/src/entries/historic.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/historic`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../historic.js';

package/src/entries/history.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/convert/history`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../history.js';

package/src/entries/hmrc.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/convert/hmrc`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../hmrc.js';

package/src/entries/kysely.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/kysely`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../kysely.js';

package/src/entries/parse.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/parse`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../parse.js';

package/src/entries/pg.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/pg`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../pg.js';

package/src/entries/policy.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/policy`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../policy.js';

package/src/entries/pricing.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/pricing`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../pricing.js';

package/src/entries/stripe-fx.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/stripe-fx`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../stripe-fx.js';

package/src/entries/testing-arbitraries.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/testing/arbitraries`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../testing/arbitraries.js';

package/src/entries/testing-index.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/testing`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../testing/index.js';

package/src/entries/testing-jest.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/testing/jest`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../testing/jest.js';

package/src/entries/testing-vitest.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/testing/vitest`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../testing/vitest.js';

package/src/entries/valibot.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/valibot`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../valibot.js';

package/src/entries/wire.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/wire`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../wire.js';

package/src/entries/zod.ts

@@ -0,0 +1,5 @@
+// `@ducatjs/money/zod`, as published: registers every ISO 4217 code first, as every entry
+// except /fn does, then the module itself.
+import '../plugins/iso.js';
+
+export * from '../zod.js';

package/src/exact.ts

@@ -2,7 +2,7 @@
 // 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 { checkScale, 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';
@@ -109,7 +109,7 @@ export class ExactMoney<C extends string = string> {
 
   /** 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;
+    return (this.num * pow10n(checkScale(scale))) % this.den === 0n;
   }
 
   /** Rounds once to `scale` (default: the currency's exponent). */
@@ -117,7 +117,7 @@ export class ExactMoney<C extends string = string> {
     rounding: RoundingMode = DEFAULT_ROUNDING,
     scale: number = currencyExponent(this.currency),
   ): Money<C> {
-    const minor = divideAndRoundBigint(this.num * pow10n(scale), this.den, rounding);
+    const minor = divideAndRoundBigint(this.num * pow10n(checkScale(scale)), this.den, rounding);
     return make(this.currency, minor, scale);
   }
 

package/src/fetch.ts

@@ -2,7 +2,8 @@
 // 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 { parseBankOfCanadaJson } from './boc.js';
-import { parseEcbSdmxCsv, parseEcbSdmxDecimals, parseEcbXml } from './ecb.js';
+import { parseEcbSdmxCsv, parseEcbSdmxDecimals, parseEcbXml, type EcbAvailableAt } from './ecb.js';
+import { checkAvailableAt } from './rate-text.js';
 import type { RateTable } from './provider.js';
 
 /**
@@ -50,6 +51,11 @@ export interface FetchEcbOptions {
   readonly timeout?: number;
   /** A fetch to use instead of the global one (for proxies, retries or tests). */
   readonly fetch?: Fetch;
+  /**
+   * ECB fetchers only: when each day's rates became available, passed to the parser (`true` for
+   * the ECB's documented 16:00 CET; see `EcbOptions` in `@ducatjs/money/convert/ecb`).
+   */
+  readonly availableAt?: EcbAvailableAt;
 }
 
 /** Thrown when the HTTP request completes without a 2xx status. */
@@ -73,9 +79,13 @@ export class FetchRatesError extends Error {
  *     const hist = snapshotsFrom(await fetchEcb({ history: '90d' }));
  */
 export async function fetchEcb(options?: FetchEcbOptions): Promise<RateTable[]> {
+  // before the request, not after it
+  checkAvailableAt(options?.availableAt);
   const url = ECB_URLS[options?.history ?? 'daily'];
   const body = await getText(url, 'application/xml', options);
-  return parsedFrom(url, () => parseEcbXml(body));
+  const parseOptions =
+    options?.availableAt === undefined ? undefined : { availableAt: options.availableAt };
+  return parsedFrom(url, () => parseEcbXml(body, parseOptions));
 }
 
 /** The caller's signal, a timeout signal, or both combined. */
@@ -202,6 +212,8 @@ async function getTextOrNotFound(
  *     const history = rateHistory(tables); // from @ducatjs/money/convert/history
  */
 export async function fetchEcbRange(options: FetchEcbRangeOptions): Promise<RateTable[]> {
+  // before the request, not after it
+  checkAvailableAt(options?.availableAt);
   const currencies = options.currencies ?? [];
   for (const currency of currencies) {
     if (!/^[A-Z]{3}$/.test(currency)) {
@@ -257,7 +269,11 @@ export async function fetchEcbRange(options: FetchEcbRangeOptions): Promise<Rate
     return [];
   }
   const decimals = parsedFrom(seriesUrl, () => parseEcbSdmxDecimals(series));
-  return parsedFrom(dataUrl, () => parseEcbSdmxCsv(data, { decimals }));
+  const parseOptions =
+    options.availableAt === undefined
+      ? { decimals }
+      : { decimals, availableAt: options.availableAt };
+  return parsedFrom(dataUrl, () => parseEcbSdmxCsv(data, parseOptions));
 }
 
 /** The Bank of Canada's Valet API for its daily exchange rates (no key; CORS-enabled). */
@@ -265,7 +281,7 @@ 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'> {
+export interface FetchBankOfCanadaOptions extends Omit<FetchEcbOptions, 'history' | 'availableAt'> {
   /** 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`. */