@ducatjs/money 0.0.0-stage → 0.1.0

package/dist/provider.d.ts

@@ -0,0 +1,89 @@
+import type { Factor } from './decimal.js';
+import { type Rate, type RateInfo } from './rate.js';
+/** When a rate is wanted for. */
+export interface RateQuery {
+    /** An ISO-8601 date or instant, or a Date. */
+    readonly asOf?: string | Date;
+}
+/** Looks up a rate synchronously. `undefined` when it has none for the pair (or for `asOf`). */
+export interface RateProvider {
+    rate<From extends string, To extends string>(from: From, to: To, query?: RateQuery): Rate<From, To> | undefined;
+}
+/** A fixed set of rates, as built by rateTable() and returned by the ECB parsers and fetchers. */
+export interface RateTable extends RateProvider {
+    readonly rates: readonly Rate[];
+    /** The quoted currency, for a one-base table. */
+    readonly base?: string;
+    /** The table's date, when it has one. */
+    readonly asOf?: string;
+}
+/** Thrown when no provider has a rate for the pair. */
+export declare class RateUnavailableError extends Error {
+    readonly from: string;
+    readonly to: string;
+    readonly asOf: string | undefined;
+    constructor(from: string, to: string, asOf?: string | Date);
+}
+/** The rate for the pair, or RateUnavailableError: a lookup that must succeed. */
+export declare function rateOf<From extends string, To extends string>(provider: RateProvider, from: From, to: To, query?: RateQuery): Rate<From, To>;
+/** 1:1 for a currency to itself; nothing otherwise. */
+export declare function identity(): RateProvider;
+/** A one-base table: `rates.USD` is the number of USD per 1 `base`. */
+export interface RateTableSpec extends RateInfo {
+    readonly base: string;
+    readonly rates: Readonly<Record<string, Factor>>;
+}
+/**
+ * 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.
+ *
+ *     const ecb = rateTable({ base: 'EUR', source: 'ECB', asOf: '2026-11-06', rates: { USD: '1.1165' } });
+ */
+export declare function rateTable(spec: RateTableSpec | readonly Rate[]): RateTable;
+/** Asks each provider in turn; the first with an answer wins. */
+export declare function chain(...providers: readonly RateProvider[]): RateProvider;
+/** Answers to→from lookups with the exact inverse of the provider's from→to rate. */
+export declare function reversed(provider: RateProvider): RateProvider;
+/**
+ * Triangulates through `base`: from→base, then base→to, composed exactly (converting rounds once).
+ * Each leg is looked up directly or as an exact inverse, so an ECB table (EUR→X only) answers X→Y.
+ */
+export declare function via(base: string, provider: RateProvider): RateProvider;
+/** Options for snapshots(). */
+export interface SnapshotOptions {
+    /**
+     * How many earlier days to try when a day has no table (weekends, holidays). Default 4, which
+     * covers Good Friday to Easter Monday.
+     */
+    readonly lookback?: number;
+    /** How many loaded days to keep; the least recently used are dropped. Default 32. */
+    readonly max?: number;
+}
+/** Dated tables, loaded on demand. */
+export interface Snapshots {
+    /** The latest table at or before `asOf` (a date, an instant or a Date), within the lookback. */
+    at(asOf: string | Date): Promise<RateProvider>;
+}
+/**
+ * Dated tables from a loader you supply: `load('2026-11-06')` resolves to that day's table, or to
+ * 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.
+ *
+ *     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
+ */
+export declare function snapshots(load: (day: string) => Promise<RateProvider | undefined>, options?: SnapshotOptions): Snapshots;
+/**
+ * Snapshots over tables you already hold (e.g. an ECB 90-day history), keyed by their asOf day.
+ *
+ *     const history = snapshotsFrom(parseEcbXml(xml90d));
+ *     const fx = await history.at('2026-11-08');
+ */
+export declare function snapshotsFrom(tables: readonly RateTable[], options?: SnapshotOptions): Snapshots;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/provider.js

@@ -0,0 +1,240 @@
+import { CurrencyMismatchError } from './money.js';
+import { exchangeRate, isRate, toIsoString } from './rate.js';
+const DAY_MS = 86_400_000;
+/** Thrown when no provider has a rate for the pair. */
+export class RateUnavailableError extends Error {
+    from;
+    to;
+    asOf;
+    constructor(from, to, asOf) {
+        let when;
+        if (asOf !== undefined) {
+            when = toIsoString(asOf);
+        }
+        let message = `No exchange rate ${from}→${to}`;
+        if (when !== undefined) {
+            message += ` as of ${when}`;
+        }
+        super(message);
+        this.name = 'RateUnavailableError';
+        this.from = from;
+        this.to = to;
+        this.asOf = when;
+    }
+}
+/** The UTC date ('2026-11-06') of a date, an instant (any offset) or a Date. */
+function dayOf(time) {
+    return toIsoString(time).slice(0, 10);
+}
+/** The rate for the pair, or RateUnavailableError: a lookup that must succeed. */
+export function rateOf(provider, from, to, query) {
+    const rate = provider.rate(from, to, query);
+    if (rate === undefined) {
+        throw new RateUnavailableError(from, to, query?.asOf);
+    }
+    // A provider is user code: a wrong pair here would produce Money labelled with the wrong
+    // currency.
+    if (rate.from !== from) {
+        throw new CurrencyMismatchError(from, rate.from);
+    }
+    if (rate.to !== to) {
+        throw new CurrencyMismatchError(to, rate.to);
+    }
+    return rate;
+}
+/** 1:1 for a currency to itself; nothing otherwise. */
+export function identity() {
+    return {
+        rate(from, to) {
+            // Compared as strings: From and To are independent type parameters.
+            if (from !== to) {
+                return undefined;
+            }
+            return exchangeRate(from, to, 1n);
+        },
+    };
+}
+/**
+ * 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.
+ *
+ *     const ecb = rateTable({ base: 'EUR', source: 'ECB', asOf: '2026-11-06', rates: { USD: '1.1165' } });
+ */
+export function rateTable(spec) {
+    let rates;
+    const header = {};
+    if (isRateList(spec)) {
+        rates = [...spec];
+    }
+    else {
+        rates = Object.entries(spec.rates).map(([to, rate]) => exchangeRate(spec.base, to, rate, spec));
+        header.base = spec.base;
+        if (spec.asOf !== undefined) {
+            header.asOf = toIsoString(spec.asOf);
+        }
+    }
+    const byPair = new Map();
+    for (const rate of rates) {
+        byPair.set(`${rate.from}/${rate.to}`, rate);
+    }
+    return {
+        ...header,
+        rates,
+        rate(from, to, query) {
+            const rate = byPair.get(`${from}/${to}`);
+            if (rate === undefined) {
+                return undefined;
+            }
+            const askedBeforeRateExisted = query?.asOf !== undefined &&
+                rate.asOf !== undefined &&
+                dayOf(query.asOf) < dayOf(rate.asOf);
+            if (askedBeforeRateExisted) {
+                return undefined;
+            }
+            // The key matched, so the rate's currencies are exactly `from` and `to`.
+            return rate;
+        },
+    };
+}
+function isRateList(spec) {
+    return Array.isArray(spec) && spec.every(isRate);
+}
+/** Asks each provider in turn; the first with an answer wins. */
+export function chain(...providers) {
+    return {
+        rate(from, to, query) {
+            for (const provider of providers) {
+                const rate = provider.rate(from, to, query);
+                if (rate !== undefined) {
+                    return rate;
+                }
+            }
+            return undefined;
+        },
+    };
+}
+/** Answers to→from lookups with the exact inverse of the provider's from→to rate. */
+export function reversed(provider) {
+    return {
+        rate(from, to, query) {
+            return provider.rate(to, from, query)?.inverse();
+        },
+    };
+}
+/**
+ * Triangulates through `base`: from→base, then base→to, composed exactly (converting rounds once).
+ * Each leg is looked up directly or as an exact inverse, so an ECB table (EUR→X only) answers X→Y.
+ */
+export function via(base, provider) {
+    function leg(from, to, query) {
+        return provider.rate(from, to, query) ?? provider.rate(to, from, query)?.inverse();
+    }
+    return {
+        rate(from, to, query) {
+            if (from === to) {
+                return undefined;
+            }
+            if (from === base || to === base) {
+                return leg(from, to, query);
+            }
+            const toBase = leg(from, base, query);
+            if (toBase === undefined) {
+                return undefined;
+            }
+            const fromBase = leg(base, to, query);
+            if (fromBase === undefined) {
+                return undefined;
+            }
+            return toBase.andThen(fromBase);
+        },
+    };
+}
+/**
+ * Dated tables from a loader you supply: `load('2026-11-06')` resolves to that day's table, or to
+ * 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.
+ *
+ *     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
+ */
+export function snapshots(load, options) {
+    const lookback = options?.lookback ?? 4;
+    const max = options?.max ?? 32;
+    if (!Number.isSafeInteger(lookback) || lookback < 0) {
+        throw new RangeError(`lookback must be a non-negative integer, got ${lookback}`);
+    }
+    if (!Number.isSafeInteger(max) || max < 1) {
+        throw new RangeError(`max must be a positive integer, got ${max}`);
+    }
+    // Map iteration order is insertion order, so re-inserting on every use makes it an LRU.
+    const cache = new Map();
+    // Only drop the entry this load created: a newer load for the same day may have replaced it.
+    function forget(day, loading) {
+        if (cache.get(day) === loading) {
+            cache.delete(day);
+        }
+    }
+    function loadDay(day) {
+        let pending = cache.get(day);
+        if (pending === undefined) {
+            const loading = load(day).then((table) => {
+                if (table === undefined) {
+                    forget(day, loading);
+                }
+                return table;
+            });
+            loading.catch(() => forget(day, loading));
+            pending = loading;
+        }
+        else {
+            cache.delete(day);
+        }
+        cache.set(day, pending);
+        if (cache.size > max) {
+            const leastRecentlyUsed = cache.keys().next().value;
+            cache.delete(leastRecentlyUsed);
+        }
+        return pending;
+    }
+    return {
+        async at(asOf) {
+            const firstDay = dayOf(asOf);
+            const firstDayMs = Date.parse(`${firstDay}T00:00:00Z`);
+            if (Number.isNaN(firstDayMs)) {
+                throw new RangeError(`Invalid asOf ${String(asOf)}`);
+            }
+            for (let i = 0; i <= lookback; i++) {
+                const day = new Date(firstDayMs - i * DAY_MS).toISOString().slice(0, 10);
+                // 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) {
+                    return table;
+                }
+            }
+            throw new RateUnavailableError('*', '*', firstDay);
+        },
+    };
+}
+/**
+ * Snapshots over tables you already hold (e.g. an ECB 90-day history), keyed by their asOf day.
+ *
+ *     const history = snapshotsFrom(parseEcbXml(xml90d));
+ *     const fx = await history.at('2026-11-08');
+ */
+export function snapshotsFrom(tables, options) {
+    const byDay = new Map();
+    for (const table of tables) {
+        if (table.asOf !== undefined) {
+            byDay.set(dayOf(table.asOf), table);
+        }
+    }
+    return snapshots(async (day) => byDay.get(day), options);
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAA4B,MAAM,WAAW,CAAC;AAExF,MAAM,MAAM,GAAG,UAAU,CAAC;AA0B1B,uDAAuD;AACvD,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAAS;IACb,EAAE,CAAS;IACX,IAAI,CAAqB;IAElC,YAAY,IAAY,EAAE,EAAU,EAAE,IAAoB;QACxD,IAAI,IAAwB,CAAC;QAC7B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,OAAO,GAAG,oBAAoB,IAAI,IAAI,EAAE,EAAE,CAAC;QAC/C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,IAAI,UAAU,IAAI,EAAE,CAAC;QAC9B,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,gFAAgF;AAChF,SAAS,KAAK,CAAC,IAAmB;IAChC,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,MAAM,CACpB,QAAsB,EACtB,IAAU,EACV,EAAM,EACN,KAAiB;IAEjB,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,oBAAoB,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;IAED,yFAAyF;IACzF,YAAY;IACZ,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,qBAAqB,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,QAAQ;IACtB,OAAO;QACL,IAAI,CAAC,IAAI,EAAE,EAAE;YACX,oEAAoE;YACpE,IAAK,IAAe,KAAK,EAAE,EAAE,CAAC;gBAC5B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,IAAqC;IAC7D,IAAI,KAAa,CAAC;IAClB,MAAM,MAAM,GAAqC,EAAE,CAAC;IACpD,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACpB,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAChG,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,CAAC,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgB,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO;QACL,GAAG,MAAM;QACT,KAAK;QACL,IAAI,CAAyC,IAAU,EAAE,EAAM,EAAE,KAAiB;YAChF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,sBAAsB,GAC1B,KAAK,EAAE,IAAI,KAAK,SAAS;gBACzB,IAAI,CAAC,IAAI,KAAK,SAAS;gBACvB,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,sBAAsB,EAAE,CAAC;gBAC3B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,yEAAyE;YACzE,OAAO,IAAsB,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAqC;IACvD,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,KAAK,CAAC,GAAG,SAAkC;IACzD,OAAO;QACL,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK;YAClB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;gBAC5C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBACvB,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,QAAsB;IAC7C,OAAO;QACL,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK;YAClB,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,QAAsB;IACtD,SAAS,GAAG,CACV,IAAU,EACV,EAAM,EACN,KAAiB;QAEjB,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IACrF,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK;YAClB,IAAK,IAAe,KAAK,EAAE,EAAE,CAAC;gBAC5B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,IAAI,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBACjC,OAAO,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;YAC9B,CAAC;YAED,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;YACtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC;AAmBD;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CACvB,IAAwD,EACxD,OAAyB;IAEzB,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,UAAU,CAAC,gDAAgD,QAAQ,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAAC,uCAAuC,GAAG,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,wFAAwF;IACxF,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6C,CAAC;IAEnE,6FAA6F;IAC7F,SAAS,MAAM,CAAC,GAAW,EAAE,OAA0C;QACrE,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC;YAC/B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,SAAS,OAAO,CAAC,GAAW;QAC1B,IAAI,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAsC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC1E,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBACvB,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;YAC1C,OAAO,GAAG,OAAO,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,KAAK,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC;YACrB,MAAM,iBAAiB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC;YACrD,KAAK,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,EAAE,CAAC,IAAI;YACX,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;YAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,QAAQ,YAAY,CAAC,CAAC;YACvD,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,UAAU,CAAC,gBAAgB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACvD,CAAC;YAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;gBACnC,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACzE,uFAAuF;gBACvF,kDAAkD;gBAClD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;gBACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC;YACD,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAA4B,EAAE,OAAyB;IACnF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC"}

package/dist/rate.d.ts

@@ -0,0 +1,119 @@
+import { type Factor, type Ratio } from './decimal.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { type RoundingMode } from './rounding.js';
+/** How a rate was quoted. `inverse()` swaps 'bid' and 'ask'. */
+export type RateType = 'mid' | 'bid' | 'ask' | (string & {});
+/**
+ * Where a rate came from. `asOf` and `validUntil` are ISO-8601 dates ('2026-11-06') or instants.
+ */
+export interface RateInfo {
+    readonly source?: string;
+    readonly asOf?: string | Date;
+    readonly validUntil?: string | Date;
+    readonly type?: RateType;
+}
+/** Options for converting an amount. */
+export interface ConvertOptions {
+    /** Result scale (default: the target currency's exponent). */
+    readonly scale?: number;
+    /**
+     * Throw RateExpiredError when the rate has a `validUntil` that has passed (by the system clock).
+     * Off by default: ducat reads no clock unless asked to.
+     */
+    readonly strictValidity?: boolean;
+}
+/** Thrown by a strict-validity conversion with a rate past its `validUntil`. */
+export declare class RateExpiredError extends RangeError {
+    readonly validUntil: string;
+    constructor(from: string, to: string, validUntil: string);
+}
+/** The JSON form of a Rate: the exact decimal string, or "num/den" when it doesn't terminate. */
+export interface RateJSON {
+    from: string;
+    to: string;
+    rate: string;
+    source?: string;
+    asOf?: string;
+    validUntil?: string;
+    type?: string;
+    derivedFrom?: RateJSON[];
+}
+/**
+ * @internal
+ * A date stays as given ('2026-11-06'); an instant becomes UTC ISO ('2026-11-06T15:00:00.000Z'), so
+ * that times with different offsets compare correctly as strings.
+ */
+export declare function toIsoString(time: string | Date): string;
+/**
+ * minor × rate × 10^scaleShift, rounded once with `rounding`. This is the kernel of every
+ * conversion: `scaleShift` is the result scale minus the input scale. Pure, and `rate.den > 0` by
+ * construction.
+ */
+export declare function multiplyByRatioAtScale(minor: number | bigint, rate: Ratio, scaleShift: number, rounding: RoundingMode): number | bigint;
+/**
+ * An exact exchange rate: one unit of `from` is worth `ratio` units of `to`. Build it with
+ * `exchangeRate()`. Derived rates (`inverse`, `andThen`, `withMargin`, `round`) keep their inputs
+ * in `derivedFrom`, the audit chain. Their `asOf` is the oldest input's, so staleness can't hide,
+ * and their `validUntil` is the earliest.
+ */
+export declare class Rate<From extends string = string, To extends string = string> {
+    readonly from: From;
+    readonly to: To;
+    readonly ratio: Ratio;
+    readonly source?: string;
+    readonly asOf?: string;
+    readonly validUntil?: string;
+    readonly type?: RateType;
+    readonly derivedFrom?: readonly Rate[];
+    /** @internal use exchangeRate() */
+    constructor(from: From, to: To, rate: Ratio, info?: RateInfo, derivedFrom?: readonly Rate[]);
+    /** The exact reciprocal, `to` → `from`. A bid becomes an ask and vice versa. */
+    inverse(): Rate<To, From>;
+    /**
+     * The exact composite `from` → `next.to`. Nothing is rounded: converting with it rounds once.
+     * (Named `andThen`, not `then`, so that a Rate is never mistaken for a promise.)
+     */
+    andThen<Next extends string>(next: Rate<To, Next>): Rate<From, Next>;
+    /** This rate × (1 + margin), exactly: `withMargin('-0.02')` gives 2% less `to` per `from`. */
+    withMargin(margin: Factor): Rate<From, To>;
+    /**
+     * A new Rate rounded to `places` decimals, for businesses that quote rounded (e.g. inverse)
+     * rates.
+     */
+    round(places: number, rounding?: RoundingMode): Rate<From, To>;
+    /** The rate with exactly `places` decimals, for display. The Rate itself keeps every digit. */
+    toDecimal(places: number, rounding?: RoundingMode): string;
+    /** The exact rate: '1.1165', or '2000/2233' when its decimal expansion doesn't terminate. */
+    toString(): string;
+    /** The rate, its metadata and its audit chain as JSON. `rateFromJSON` reverses it. */
+    toJSON(): RateJSON;
+    /**
+     * Whether `validUntil` has passed at `now` (default: the system clock). A date is valid all day
+     * (UTC).
+     */
+    isExpired(now?: string | Date): boolean;
+    /** Converts `money`, rounding once to the target currency's exponent (or `options.scale`). */
+    convert(money: Money<From>, rounding?: RoundingMode, options?: ConvertOptions): Money<To>;
+}
+/**
+ * An exact rate pinned to a currency pair, so converting the wrong currency is a type error. Give
+ * the rate as a decimal string ('1.1165', every digit kept), a "num/den" string, a bigint or a
+ * Ratio. Numbers are read at their shortest decimal form (1.234 is exactly 1234/1000).
+ *
+ *     const eurUsd = exchangeRate('EUR', 'USD', '1.1165', { source: 'ECB', asOf: '2026-11-06' });
+ *     eurUsd.convert(money('100', 'EUR'), 'halfEven');   // 111.65 USD
+ *     eurUsd.inverse().ratio                             // 2000/2233, exactly
+ */
+export declare function exchangeRate<From extends CurrencyInput, To extends CurrencyInput>(from: From, to: To, rate: Factor, info?: RateInfo): Rate<From, To>;
+/** Rebuilds a Rate, with its audit chain, from `rate.toJSON()`. */
+export declare function rateFromJSON(json: RateJSON): Rate;
+/** Whether `value` is a Rate. */
+export declare function isRate(value: unknown): value is Rate;
+/**
+ * The exact rate a processor actually applied: settled ÷ presented. Use it to audit a quoted rate,
+ * which after the processor's own rounding often doesn't reproduce the settled amount.
+ *
+ *     impliedRate(money('10.00', 'EUR'), money('12.34', 'USD'))   // EUR→USD 1.234
+ */
+export declare function impliedRate<From extends string, To extends string>(presented: Money<From>, settled: Money<To>, info?: RateInfo): Rate<From, To>;
+//# sourceMappingURL=rate.d.ts.map

package/dist/rate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate.d.ts","sourceRoot":"","sources":["../src/rate.ts"],"names":[],"mappings":"AAIA,OAAO,EAOL,KAAK,MAAM,EACX,KAAK,KAAK,EACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAA+B,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAIvB,gEAAgE;AAChE,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1B;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,gFAAgF;AAChF,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAKzD;AAED,iGAAiG;AACjG,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;CAC1B;AAUD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASvD;AAgBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,IAAI,EAAE,KAAK,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,YAAY,GACrB,MAAM,GAAG,MAAM,CA8BjB;AAED;;;;;GAKG;AACH,qBAAa,IAAI,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM;IACxE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAGtB,SAAiB,MAAM,CAAC,EAAE,MAAM,CAAC;IACjC,SAAiB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAiB,UAAU,CAAC,EAAE,MAAM,CAAC;IACrC,SAAiB,IAAI,CAAC,EAAE,QAAQ,CAAC;IACjC,SAAiB,WAAW,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IAE/C,mCAAmC;gBACvB,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,SAAS,IAAI,EAAE;IA8B3F,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IASzB;;;OAGG;IACH,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;IAgBpE,8FAA8F;IAC9F,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;IAO1C;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,YAAyB,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;IAK1E,+FAA+F;IAC/F,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,YAAyB,GAAG,MAAM;IAKtE,6FAA6F;IAC7F,QAAQ,IAAI,MAAM;IAIlB,sFAAsF;IACtF,MAAM,IAAI,QAAQ;IAQlB;;;OAGG;IACH,SAAS,CAAC,GAAG,GAAE,MAAM,GAAG,IAAiB,GAAG,OAAO;IAcnD,8FAA8F;IAC9F,OAAO,CACL,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAClB,QAAQ,GAAE,YAA+B,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,KAAK,CAAC,EAAE,CAAC;CAWb;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,aAAa,EAAE,EAAE,SAAS,aAAa,EAC/E,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,QAAQ,GACd,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAEhB;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAGjD;AAED,iCAAiC;AACjC,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EAChE,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,EACtB,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,EAClB,IAAI,CAAC,EAAE,QAAQ,GACd,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAKhB"}