@ducatjs/money 0.1.0 → 0.2.0

package/src/prisma.ts

@@ -8,6 +8,7 @@
  *  2. a DECIMAL/NUMERIC column (+ a currency column or constant)
  *     -> decimalMoneyField / toDecimalValue
  */
+import { MAX_DECIMAL_SCALE } from './decimal.js';
 import {
   fromMinor,
   money,
@@ -42,23 +43,84 @@ export function toDecimalValue<D>(money: Money, Decimal: new (value: string) =>
 
 type Row<A extends string, V> = { [P in A]: V };
 
+/** Options for `minorMoneyField` and `toMinorColumns`: a column that records each amount's scale. */
+export interface ScaleColumnOption<S extends string> {
+  /**
+   * The integer column holding the number of decimals the minor units are counted in (2 for
+   * cents). With it, any scale round-trips, and stored amounts keep their meaning even if a
+   * currency's exponent changes.
+   */
+  readonly scale: S;
+}
+
+/** A scale read from a row: a safe, non-negative integer (a SMALLINT or INT column). */
+function readScale(value: unknown, column: string): number {
+  const scale = typeof value === 'bigint' ? Number(value) : value;
+  // capped like parsed decimals: a corrupt row must not make toDecimal build a huge power of ten
+  const isValid =
+    typeof scale === 'number' &&
+    Number.isInteger(scale) &&
+    scale >= 0 &&
+    scale <= MAX_DECIMAL_SCALE;
+  if (!isValid) {
+    throw new RangeError(
+      `Expected an integer scale from 0 to ${MAX_DECIMAL_SCALE} in "${column}", got ${String(value)}`,
+    );
+  }
+  return scale;
+}
+
 /**
  * A Prisma result-extension field that exposes a Money built from `amount_minor` + `currency`
- * columns:
+ * columns, and optionally a scale column:
  *
  *     const db = new PrismaClient().$extends({
  *       result: { order: { total: minorMoneyField('totalMinor', 'currency') } },
  *     });
  *     (await db.order.findFirstOrThrow()).total   // Money
+ *
+ * Without a scale column the minor units are read at the currency's current exponent.
  */
 export function minorMoneyField<const A extends string, const K extends string>(
   amount: A,
   currency: K,
-) {
+): {
+  needs: { [P in A | K]: true };
+  compute: (row: Row<A, bigint | number> & Row<K, string>) => Money;
+};
+export function minorMoneyField<
+  const A extends string,
+  const K extends string,
+  const S extends string,
+>(
+  amount: A,
+  currency: K,
+  options: ScaleColumnOption<S>,
+): {
+  needs: { [P in A | K | S]: true };
+  compute: (row: Row<A, bigint | number> & Row<K, string> & Row<S, bigint | number>) => Money;
+};
+export function minorMoneyField(
+  amount: string,
+  currency: string,
+  options?: ScaleColumnOption<string>,
+): { needs: Record<string, true>; compute: (row: Record<string, unknown>) => Money } {
+  if (options === undefined) {
+    return {
+      needs: { [amount]: true, [currency]: true },
+      compute: (row) => fromMinor(row[amount] as bigint | number, row[currency] as string),
+    };
+  }
+
+  const scaleColumn = options.scale;
   return {
-    needs: { [amount]: true, [currency]: true } as { [P in A | K]: true },
-    compute: (row: Row<A, bigint | number> & Row<K, string>): Money =>
-      fromMinor(row[amount], row[currency]),
+    needs: { [amount]: true, [currency]: true, [scaleColumn]: true },
+    compute: (row) =>
+      fromMinor(
+        row[amount] as bigint | number,
+        row[currency] as string,
+        readScale(row[scaleColumn], scaleColumn),
+      ),
   };
 }
 
@@ -95,16 +157,35 @@ export function decimalMoneyField(
 
 /**
  * Column values for writes: `data: { ...toMinorColumns(total, 'totalMinor', 'currency') }`.
- * Minor units are a bigint (Prisma BigInt). Throws if the value has a non-standard scale, because
- * the column cannot record it.
+ * Minor units are a bigint (Prisma BigInt). Without a scale column, throws if the value has a
+ * non-standard scale, because the columns cannot record it. With `{ scale: 'amountScale' }`, any
+ * scale is stored, next to the minor units it counts.
  */
 export function toMinorColumns<const A extends string, const K extends string>(
   money: Money,
   amount: A,
   currency: K,
-): Row<A, bigint> & Row<K, string> {
-  return { [amount]: toMinorAtIsoScale(money), [currency]: money.currency } as Row<A, bigint> &
-    Row<K, string>;
+): Row<A, bigint> & Row<K, string>;
+export function toMinorColumns<
+  const A extends string,
+  const K extends string,
+  const S extends string,
+>(
+  money: Money,
+  amount: A,
+  currency: K,
+  options: ScaleColumnOption<S>,
+): Row<A, bigint> & Row<K, string> & Row<S, number>;
+export function toMinorColumns(
+  money: Money,
+  amount: string,
+  currency: string,
+  options?: ScaleColumnOption<string>,
+): Record<string, unknown> {
+  if (options === undefined) {
+    return { [amount]: toMinorAtIsoScale(money), [currency]: money.currency };
+  }
+  return { [amount]: toMinor(money), [currency]: money.currency, [options.scale]: money.scale };
 }
 
 function toMinorAtIsoScale(money: Money): bigint {

package/src/provider.ts

@@ -3,7 +3,15 @@
 // async boundary.
 import type { Factor } from './decimal.js';
 import { CurrencyMismatchError } from './money.js';
-import { exchangeRate, isRate, toIsoString, type Rate, type RateInfo } from './rate.js';
+import {
+  exchangeRate,
+  hasEnded,
+  hasStarted,
+  isRate,
+  toIsoString,
+  type Rate,
+  type RateInfo,
+} from './rate.js';
 
 const DAY_MS = 86_400_000;
 
@@ -29,6 +37,12 @@ export interface RateTable extends RateProvider {
   readonly base?: string;
   /** The table's date, when it has one. */
   readonly asOf?: string;
+  /** When the table was published, when that is known. */
+  readonly availableAt?: string;
+  /** The last day (or instant) the table applies to, for a table valid for a period. */
+  readonly validUntil?: string;
+  /** Currencies the source listed without a value (holidays, `ND`, `N/A`). */
+  readonly missing?: readonly string[];
 }
 
 /** Thrown when no provider has a rate for the pair. */
@@ -95,33 +109,68 @@ export function identity(): RateProvider {
   };
 }
 
-/** A one-base table: `rates.USD` is the number of USD per 1 `base`. */
-export interface RateTableSpec extends RateInfo {
+/**
+ * A one-base table: `rates.USD` is the number of USD per 1 `base` (or a base → USD Rate), or null
+ * when the source has no value for the day. For rates published the other way round or per 100
+ * units, see `quotedTable` in `@ducatjs/money/convert/history`.
+ */
+export interface RateTableSpec extends Omit<RateInfo, 'quote'> {
   readonly base: string;
-  readonly rates: Readonly<Record<string, Factor>>;
+  readonly rates: Readonly<Record<string, Factor | Rate | null>>;
 }
 
 /**
  * A fixed table of rates: one base currency against many (ECB style), or a list of Rates. Only the
  * pairs given are answered; wrap it in `reversed()` or `via()` for the others.
  *
- * Lookups are by whole UTC day: a query for a day before a rate's asOf gets nothing, and a query at
- * any time on the rate's own day gets the rate, even before its publication time (the ECB publishes
- * at about 15:00 UTC). If that matters, query with the previous day until the table is published.
+ * A query with an `asOf` gets nothing from a rate that doesn't apply then: one dated after it, one
+ * published (`availableAt`) after it, or one whose `validUntil` has passed. Days are UTC days, and
+ * a date query covers the whole day: without an `availableAt`, a query at any time on the rate's
+ * own day gets the rate, even before the source published it (the ECB publishes at about 15:00
+ * UTC). Give `availableAt` to rule that out.
  *
  *     const ecb = rateTable({ base: 'EUR', source: 'ECB', asOf: '2026-11-06', rates: { USD: '1.1165' } });
  */
 export function rateTable(spec: RateTableSpec | readonly Rate[]): RateTable {
   let rates: Rate[];
-  const header: { base?: string; asOf?: string } = {};
+  const header: {
+    base?: string;
+    asOf?: string;
+    availableAt?: string;
+    validUntil?: string;
+    missing?: string[];
+  } = {};
   if (isRateList(spec)) {
     rates = [...spec];
   } else {
-    rates = Object.entries(spec.rates).map(([to, rate]) => exchangeRate(spec.base, to, rate, spec));
+    rates = [];
+    const missing: string[] = [];
+    for (const [currency, entry] of Object.entries(spec.rates)) {
+      if (entry === null) {
+        missing.push(currency);
+      } else if (isRate(entry)) {
+        // A ready-made Rate is looked up under its own pair, so it must be the one its key says.
+        if (entry.from !== spec.base || entry.to !== currency) {
+          throw new CurrencyMismatchError(`${spec.base}→${currency}`, `${entry.from}→${entry.to}`);
+        }
+        rates.push(entry);
+      } else {
+        rates.push(exchangeRate(spec.base, currency, entry, spec));
+      }
+    }
     header.base = spec.base;
     if (spec.asOf !== undefined) {
       header.asOf = toIsoString(spec.asOf);
     }
+    if (spec.availableAt !== undefined) {
+      header.availableAt = toIsoString(spec.availableAt);
+    }
+    if (spec.validUntil !== undefined) {
+      header.validUntil = toIsoString(spec.validUntil);
+    }
+    if (missing.length > 0) {
+      header.missing = missing;
+    }
   }
 
   const byPair = new Map<string, Rate>();
@@ -137,11 +186,9 @@ export function rateTable(spec: RateTableSpec | readonly Rate[]): RateTable {
       if (rate === undefined) {
         return undefined;
       }
-      const askedBeforeRateExisted =
-        query?.asOf !== undefined &&
-        rate.asOf !== undefined &&
-        dayOf(query.asOf) < dayOf(rate.asOf);
-      if (askedBeforeRateExisted) {
+      // The table's own dates count too: a ready-made Rate entry doesn't carry them.
+      const asOf = query?.asOf;
+      if (asOf !== undefined && (!appliesAt(rate, asOf) || !appliesAt(header, asOf))) {
         return undefined;
       }
       // The key matched, so the rate's currencies are exactly `from` and `to`.
@@ -150,6 +197,20 @@ export function rateTable(spec: RateTableSpec | readonly Rate[]): RateTable {
   };
 }
 
+/** Whether a rate (or a table) applies at `at`: dated, published and still valid then. */
+function appliesAt(
+  rate: { readonly asOf?: string; readonly availableAt?: string; readonly validUntil?: string },
+  at: string | Date,
+): boolean {
+  if (rate.asOf !== undefined && dayOf(at) < dayOf(rate.asOf)) {
+    return false;
+  }
+  if (rate.availableAt !== undefined && !hasStarted(rate.availableAt, at)) {
+    return false;
+  }
+  return rate.validUntil === undefined || !hasEnded(rate.validUntil, at);
+}
+
 function isRateList(spec: RateTableSpec | readonly Rate[]): spec is readonly Rate[] {
   return Array.isArray(spec) && spec.every(isRate);
 }
@@ -235,7 +296,9 @@ export interface Snapshots {
  * undefined when there is none. Days are UTC days. Loaded tables are cached by day. Misses and
  * failures are not cached, so a table that isn't published yet is tried again next time. A loader
  * that throws fails the lookup rather than falling back to an older day, so an outage doesn't
- * silently become a stale rate. The rates carry the day they're from.
+ * silently become a stale rate. The rates carry the day they're from. A table with an
+ * `availableAt` after an instant asked for is passed over, so a lookup at 09:00 on a publication
+ * day gets the day before.
  *
  *     const history = snapshots(async (day) => parseEcbXml(await readFile(`ecb/${day}.xml`, 'utf8'))[0]);
  *     const fx = await history.at('2026-11-08');   // a Sunday: Friday 2026-11-06's table
@@ -298,7 +361,9 @@ export function snapshots(
         // Sequential on purpose: stop at the first day that has a table, without loading older
         // days. oxlint-disable-next-line no-await-in-loop
         const table = await loadDay(day);
-        if (table !== undefined) {
+        // A table not yet published at the instant asked for is passed over like a missing one.
+        const availableAt = (table as Partial<RateTable> | undefined)?.availableAt;
+        if (table !== undefined && (availableAt === undefined || hasStarted(availableAt, asOf))) {
           return table;
         }
       }

package/src/rate-text.ts

@@ -0,0 +1,151 @@
+// Reading rate cells from published files, shared by the source parsers so that every source
+// handles missing values and stripped digits the same way.
+
+// What sources write for "no value this day": blank (ECB CSV, BoE), ND (Fed H.10), N/A (ECB CSV),
+// NA (IMF), and dashes and NaN in other files. Compared upper-cased.
+const MISSING_MARKERS = new Set(['', 'ND', 'N/A', 'NA', 'N.A.', '-', '–', '—', 'NAN', 'NULL']);
+const PLAIN_DECIMAL = /^\d+(?:\.\d+)?$/;
+
+/**
+ * @internal
+ * A published rate cell: the decimal text, or null when the source marks the value as missing
+ * (holidays, `ND`, `N/A`). Anything else throws SyntaxError: a cell that can't be read must not
+ * look like "not quoted".
+ */
+export function readRateCell(cell: string, where: string): string | null {
+  const text = cell.trim();
+  if (MISSING_MARKERS.has(text.toUpperCase())) {
+    return null;
+  }
+  if (!PLAIN_DECIMAL.test(text)) {
+    throw new SyntaxError(`Not a rate: ${JSON.stringify(cell)} (${where})`);
+  }
+  return text;
+}
+
+/**
+ * @internal
+ * The published digits of a rate from a feed that strips trailing zeros, given the number of
+ * decimals the publisher states: '1.175' with 4 decimals is '1.1750'. Text with more decimals than
+ * stated is kept as it is, since dropping digits would change the rate.
+ */
+export function withDecimals(text: string, decimals: number): string {
+  if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 30) {
+    throw new RangeError(`decimals must be an integer from 0 to 30, got ${decimals}`);
+  }
+  const point = text.indexOf('.');
+  const present = point === -1 ? 0 : text.length - point - 1;
+  if (present >= decimals) {
+    return text;
+  }
+  const integerPart = point === -1 ? text : text.slice(0, point);
+  const fraction = point === -1 ? '' : text.slice(point + 1);
+  return `${integerPart}.${fraction.padEnd(decimals, '0')}`;
+}
+
+/**
+ * @internal
+ * The records of a CSV file, RFC 4180 style: a cell may be quoted ("a, b", with "" for a quote),
+ * and a quote anywhere else, or one left open, is a SyntaxError, so a stray quote can't swallow
+ * the lines after it. Blank lines are skipped.
+ */
+export function csvRows(text: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let cell = '';
+  // 'start' of a cell, inside an unquoted one, inside quotes, or just after the closing quote
+  let state: 'start' | 'plain' | 'quoted' | 'closed' = 'start';
+  const endRow = () => {
+    row.push(cell);
+    if (row.length > 1 || row[0]!.trim() !== '') {
+      rows.push(row);
+    }
+    row = [];
+    cell = '';
+    state = 'start';
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i]!;
+    if (state === 'quoted') {
+      if (char !== '"') {
+        cell += char;
+      } else if (text[i + 1] === '"') {
+        cell += '"';
+        i++;
+      } else {
+        state = 'closed';
+      }
+      continue;
+    }
+    if (char === ',') {
+      row.push(cell);
+      cell = '';
+      state = 'start';
+    } else if (char === '\n') {
+      endRow();
+    } else if (char === '\r' && text[i + 1] === '\n') {
+      continue;
+    } else if (char === '"' && state === 'start') {
+      state = 'quoted';
+    } else if (char === '"' || state === 'closed') {
+      throw new SyntaxError(
+        `Malformed CSV: unexpected ${JSON.stringify(char)} on line ${rows.length + 1}`,
+      );
+    } else {
+      cell += char;
+      state = 'plain';
+    }
+  }
+  if (state === 'quoted') {
+    throw new SyntaxError('Malformed CSV: a quoted cell is never closed');
+  }
+  if (cell !== '' || row.length > 0) {
+    endRow();
+  }
+  return rows;
+}
+
+const ISO_DAY = /^(\d{4})-(\d\d)-(\d\d)$/;
+
+/**
+ * @internal
+ * Whether `text` is a real calendar day in ISO form. '2026-02-30' is not, although Date.parse rolls
+ * it over to 2 March.
+ */
+export function isCalendarDay(text: string): boolean {
+  const match = ISO_DAY.exec(text);
+  if (match === null) {
+    return false;
+  }
+  const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+  return date.toISOString().slice(0, 10) === text;
+}
+
+/**
+ * @internal
+ * Records a currency's rate (or null, missing) for a day. The same currency twice on one day is
+ * either a repeat, which is fine, or a contradiction, which throws: a parser never picks one.
+ */
+export function addDayRate(
+  days: Map<string, Record<string, string | null>>,
+  day: string,
+  currency: string,
+  rate: string | null,
+): void {
+  let rates = days.get(day);
+  if (rates === undefined) {
+    rates = {};
+    days.set(day, rates);
+  }
+  const earlier = rates[currency];
+  if (earlier !== undefined && earlier !== rate) {
+    throw new SyntaxError(`Two different values for ${currency} on ${day}: ${earlier} and ${rate}`);
+  }
+  rates[currency] = rate;
+}
+
+/** @internal Dated tables, newest first (ISO dates sort as strings). */
+export function newestFirst<T extends { readonly asOf?: string }>(tables: T[]): T[] {
+  return tables.sort((table, other) => other.asOf!.localeCompare(table.asOf!));
+}