@ducatjs/money 0.0.0 → 0.2.0

package/dist/policy.js

@@ -0,0 +1,90 @@
+/**
+ * `@ducatjs/money/policy`: rounding policies, reusable values for a scale, an increment and a
+ * rounding mode ("CHF cash", "4 decimals, half even"), accepted wherever a rounding mode is. The
+ * core only hands the work to the policy, so none of this code is in a bundle that never imports
+ * this entry (or `cashPolicy` from `@ducatjs/money/cash`).
+ */
+import { currencyExponent, isCurrency } from './currency.js';
+import { MAX_DECIMAL_SCALE } from './decimal.js';
+import { CurrencyMismatchError, multiply, multiplyByRatio, ratio, ROUND_PRODUCT, } from './money.js';
+import { DEFAULT_ROUNDING, Rounding } from './rounding.js';
+const ONE = ratio(1);
+const MODES = new Set(Object.values(Rounding));
+/**
+ * Builds a reusable rounding policy (see `RoundingPolicy`). The options are checked here, once, so
+ * applying the policy needs no checks.
+ *
+ *     const unitPrice = roundingPolicy({ scale: 4, rounding: 'halfEven' })
+ *     const fiveCents = roundingPolicy({ increment: 5 })   // 0.05 in a 2-decimal currency
+ */
+export function roundingPolicy(options = {}) {
+    const scale = options.scale;
+    const increment = options.increment ?? 1;
+    const rounding = options.rounding ?? DEFAULT_ROUNDING;
+    const currency = options.currency;
+    if (scale !== undefined &&
+        !(Number.isInteger(scale) && scale >= 0 && scale <= MAX_DECIMAL_SCALE)) {
+        throw new RangeError(`Invalid scale ${scale}`);
+    }
+    if (!(Number.isSafeInteger(increment) && increment >= 1)) {
+        throw new RangeError(`Invalid increment ${increment}; it must be a positive integer`);
+    }
+    if (!MODES.has(rounding)) {
+        throw new RangeError(`Invalid rounding mode ${String(rounding)}`);
+    }
+    // A typo such as 'chf' would otherwise make a policy that rejects every amount.
+    if (currency !== undefined && !isCurrency(currency)) {
+        throw new RangeError(`Unknown currency ${currency}`);
+    }
+    const incrementAsBigint = BigInt(increment);
+    // money × factor rounded once to the policy: with an increment, count whole increments
+    // (money × factor / increment, rounded at the policy's scale) and multiply back, which is
+    // rounding to the nearest multiple of the increment. The count's ratio is left unreduced: the
+    // division rounds the same either way, and a gcd per call would cost more than it saves.
+    const roundProduct = (money, factor) => {
+        if (currency !== undefined && currency !== money.currency) {
+            throw new CurrencyMismatchError(currency, money.currency);
+        }
+        const resultScale = scale ?? currencyExponent(money.currency);
+        if (increment === 1) {
+            return multiplyByRatio(money, factor, rounding, resultScale);
+        }
+        const stepDenominator = factor.d * increment;
+        const perStep = {
+            num: factor.num,
+            den: factor.den * incrementAsBigint,
+            n: factor.n,
+            // NaN (not a safe integer) sends multiplyByRatio down its bigint path
+            d: Number.isSafeInteger(stepDenominator) ? stepDenominator : NaN,
+        };
+        return multiply(multiplyByRatio(money, perStep, rounding, resultScale), increment);
+    };
+    const policy = (money) => roundProduct(money, ONE);
+    return Object.freeze(Object.assign(policy, { scale, increment, rounding, currency, [ROUND_PRODUCT]: roundProduct }));
+}
+/**
+ * Rounding to the currency's ISO exponent, half up: the policy most amounts should end with.
+ * `assertScale(m, isoPolicy)` checks that an amount is already there.
+ */
+export const isoPolicy = /* @__PURE__ */ roundingPolicy();
+/**
+ * Throws a RangeError unless `money` is exactly what `policy` produces: at the policy's scale and a
+ * multiple of its increment (and in its currency, if it has one). Use it where an amount must
+ * already be rounded, such as before booking it or sending it to a processor.
+ */
+export function assertScale(money, policy) {
+    if (policy.currency !== undefined && policy.currency !== money.currency) {
+        throw new CurrencyMismatchError(policy.currency, money.currency);
+    }
+    const scale = policy.scale ?? currencyExponent(money.currency);
+    if (money.scale !== scale) {
+        throw new RangeError(`${money} has scale ${money.scale}, expected ${scale}`);
+    }
+    const minor = money.minor;
+    const increment = policy.increment;
+    const isMultiple = typeof minor === 'number' ? minor % increment === 0 : minor % BigInt(increment) === 0n;
+    if (!isMultiple) {
+        throw new RangeError(`${money} is not a multiple of ${increment} at scale ${scale}`);
+    }
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

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

package/dist/prisma.d.ts

@@ -0,0 +1,77 @@
+import { type CurrencyInput, type Money, type MoneyOptions } from './money.js';
+/** Structural type of Prisma.Decimal / decimal.js / big.js values. */
+export interface DecimalLike {
+    toFixed(): string;
+}
+/**
+ * Money from a Decimal (or decimal string) column. Exact; throws if it has more decimals than the
+ * currency.
+ */
+export declare function fromDecimal<C extends CurrencyInput>(value: DecimalLike | string, currency: C, options?: MoneyOptions): Money<C>;
+/** A Decimal for a NUMERIC column: toDecimalValue(m, Prisma.Decimal). */
+export declare function toDecimalValue<D>(money: Money, Decimal: new (value: string) => D): D;
+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 Prisma result-extension field that exposes a Money built from `amount_minor` + `currency`
+ * 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 declare 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 declare 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;
+};
+/**
+ * A Prisma result-extension field for a Decimal column, with the currency taken from another column
+ * (`{ currencyField: 'currency' }`) or fixed (`{ currency: 'EUR' }`).
+ */
+export declare function decimalMoneyField<const A extends string, const K extends string>(amount: A, currency: {
+    currencyField: K;
+}): {
+    needs: {
+        [P in A | K]: true;
+    };
+    compute: (row: Row<A, DecimalLike> & Row<K, string>) => Money;
+};
+export declare function decimalMoneyField<const A extends string, const C extends CurrencyInput>(amount: A, currency: {
+    currency: C;
+}): {
+    needs: {
+        [P in A]: true;
+    };
+    compute: (row: Row<A, DecimalLike>) => Money<C>;
+};
+/**
+ * Column values for writes: `data: { ...toMinorColumns(total, 'totalMinor', 'currency') }`.
+ * 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 declare function toMinorColumns<const A extends string, const K extends string>(money: Money, amount: A, currency: K): Row<A, bigint> & Row<K, string>;
+export declare 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 {};
+//# sourceMappingURL=prisma.d.ts.map

package/dist/prisma.d.ts.map

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

package/dist/prisma.js

@@ -0,0 +1,76 @@
+/**
+ * Prisma / SQL interop with no dependency on @prisma/client (works with any Decimal class that has
+ * toFixed(): Prisma.Decimal, decimal.js, big.js).
+ *
+ * Storage options (see README "Databases"):
+ *  1. two columns: amount_minor BIGINT + currency CHAR(3)
+ *     -> minorMoneyField / toMinorColumns
+ *  2. a DECIMAL/NUMERIC column (+ a currency column or constant)
+ *     -> decimalMoneyField / toDecimalValue
+ */
+import { MAX_DECIMAL_SCALE } from './decimal.js';
+import { fromMinor, money, toDecimal, toMinor, } from './money.js';
+/**
+ * Money from a Decimal (or decimal string) column. Exact; throws if it has more decimals than the
+ * currency.
+ */
+export function fromDecimal(value, currency, options) {
+    return money(typeof value === 'string' ? value : value.toFixed(), currency, options);
+}
+/** A Decimal for a NUMERIC column: toDecimalValue(m, Prisma.Decimal). */
+export function toDecimalValue(money, Decimal) {
+    return new Decimal(toDecimal(money));
+}
+/** A scale read from a row: a safe, non-negative integer (a SMALLINT or INT column). */
+function readScale(value, column) {
+    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;
+}
+export function minorMoneyField(amount, currency, options) {
+    if (options === undefined) {
+        return {
+            needs: { [amount]: true, [currency]: true },
+            compute: (row) => fromMinor(row[amount], row[currency]),
+        };
+    }
+    const scaleColumn = options.scale;
+    return {
+        needs: { [amount]: true, [currency]: true, [scaleColumn]: true },
+        compute: (row) => fromMinor(row[amount], row[currency], readScale(row[scaleColumn], scaleColumn)),
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function decimalMoneyField(amount, currencySource) {
+    if ('currencyField' in currencySource) {
+        return {
+            needs: { [amount]: true, [currencySource.currencyField]: true },
+            compute: (row) => fromDecimal(row[amount], row[currencySource.currencyField]),
+        };
+    }
+    return {
+        needs: { [amount]: true },
+        compute: (row) => fromDecimal(row[amount], currencySource.currency),
+    };
+}
+export function toMinorColumns(money, amount, currency, options) {
+    if (options === undefined) {
+        return { [amount]: toMinorAtIsoScale(money), [currency]: money.currency };
+    }
+    return { [amount]: toMinor(money), [currency]: money.currency, [options.scale]: money.scale };
+}
+function toMinorAtIsoScale(money) {
+    const iso = fromMinor(0, money.currency).scale;
+    if (money.scale !== iso) {
+        throw new RangeError(`${money} has scale ${money.scale}; round() it to ${iso} decimals before storing minor units`);
+    }
+    return toMinor(money);
+}
+//# sourceMappingURL=prisma.js.map

package/dist/prisma.js.map

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

package/dist/processor.d.ts

@@ -0,0 +1,28 @@
+import { type CurrencyInput, type Money } from './money.js';
+import { type RoundingMode } from './rounding.js';
+/**
+ * Which signs a processor field accepts, checked after rounding:
+ * - 'any': negative amounts are documented (Klarna's discount order lines);
+ * - 'nonNegative': zero is documented but negatives aren't (refunds are sent as positive amounts);
+ * - 'positive': the processor rejects zero too (Braintree's transaction amount).
+ */
+export type SignRule = 'any' | 'nonNegative' | 'positive';
+/**
+ * @internal Money -> a processor's integer amount at the processor's exponent.
+ * Throws a RangeError when the amount doesn't fit in a safe integer or has a sign `sign` rules out.
+ */
+export declare function toProcessorAmount(processor: string, money: Money, exponent: number, multiple: number, rounding: RoundingMode, sign?: SignRule): number;
+/**
+ * @internal Money -> a processor's decimal string with exactly `exponent` decimals
+ * ("10.00", or "1000" for JPY), built from the integer so it never goes through a float.
+ */
+export declare function toProcessorDecimal(processor: string, money: Money, exponent: number, rounding: RoundingMode, sign?: SignRule): string;
+/** @internal A processor's integer amount -> Money (see `toIsoScaleWhenExact` for the scale). */
+export declare function fromProcessorAmount<C extends CurrencyInput>(processor: string, amount: number | bigint, currency: C, exponent: number): Money<C>;
+/**
+ * @internal A processor's decimal string -> Money, exactly (never via a float). `pattern` is the
+ * processor's documented format and `maxLength` its length limit, if any. The scale follows
+ * `toIsoScaleWhenExact`.
+ */
+export declare function fromProcessorDecimal<C extends CurrencyInput>(processor: string, value: string, currency: C, pattern: RegExp, maxLength?: number): Money<C>;
+//# sourceMappingURL=processor.d.ts.map

package/dist/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../src/processor.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0C,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACpG,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,aAAa,GAAG,UAAU,CAAC;AAuE1D;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,IAAI,GAAE,QAAgB,GACrB,MAAM,CASR;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,IAAI,GAAE,QAAgB,GACrB,MAAM,CAMR;AAmBD,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,aAAa,EACzD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,QAAQ,EAAE,CAAC,EACX,QAAQ,EAAE,MAAM,GACf,KAAK,CAAC,CAAC,CAAC,CAMV;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,aAAa,EAC1D,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,MAAM,EACf,SAAS,SAAW,GACnB,KAAK,CAAC,CAAC,CAAC,CAWV"}

package/dist/processor.js

@@ -0,0 +1,118 @@
+import { currencyExponent } from './currency.js';
+import { formatScaled, parseDecimal, parsePlainDecimal, normalizeMinor } from './decimal.js';
+import { fromMinor, scaleDown, scaleUp, toScale } from './money.js';
+import { divideAndRound, divideAndRoundBigint, RoundingError, } from './rounding.js';
+/**
+ * Rescales Money's minor units to a processor's exponent, then to a multiple of `multiple` minor
+ * units (Checkout.com's CLP, Stripe's ISK). Throws a RoundingError naming the processor when
+ * precision would be lost and `rounding` is 'unnecessary'.
+ */
+function rescaleForProcessor(processor, money, exponent, multiple, rounding) {
+    // Going up in scale is always exact; going down (e.g. IDR on Adyen) may need rounding.
+    let minor;
+    try {
+        if (exponent >= money.scale) {
+            minor = scaleUp(money.minor, exponent - money.scale);
+        }
+        else {
+            minor = scaleDown(money.minor, money.scale - exponent, rounding);
+        }
+    }
+    catch (error) {
+        if (error instanceof RoundingError) {
+            throw new RoundingError(`${money} has more precision than ${processor} accepts for ${money.currency} ` +
+                `(${exponent} decimals); pass a rounding mode`);
+        }
+        throw error;
+    }
+    if (multiple === 1) {
+        return minor;
+    }
+    const isMultiple = typeof minor === 'number' ? minor % multiple === 0 : minor % BigInt(multiple) === 0n;
+    if (isMultiple) {
+        return minor;
+    }
+    if (rounding === 'unnecessary') {
+        throw new RoundingError(`${processor} requires ${money.currency} amounts to be a multiple of ${multiple} minor units; ` +
+            `${money} is not (pass a rounding mode)`);
+    }
+    if (typeof minor === 'number') {
+        return divideAndRound(minor, multiple, rounding) * multiple;
+    }
+    const bigMultiple = BigInt(multiple);
+    return normalizeMinor(divideAndRoundBigint(minor, bigMultiple, rounding) * bigMultiple);
+}
+/** Throws a RangeError when the rounded amount has a sign the processor doesn't accept. */
+function checkSign(processor, money, minor, sign) {
+    // Checked on the rounded amount, so -0.004 USD rounded to 0 counts as zero, not as negative.
+    if (sign === 'any') {
+        return;
+    }
+    if (minor < 0) {
+        throw new RangeError(`${processor} amounts can't be negative (${money}); send refunds as positive amounts`);
+    }
+    if (sign === 'positive' && (minor === 0 || minor === 0n)) {
+        throw new RangeError(`${processor} amounts must be greater than zero (${money})`);
+    }
+}
+/**
+ * @internal Money -> a processor's integer amount at the processor's exponent.
+ * Throws a RangeError when the amount doesn't fit in a safe integer or has a sign `sign` rules out.
+ */
+export function toProcessorAmount(processor, money, exponent, multiple, rounding, sign = 'any') {
+    const minor = rescaleForProcessor(processor, money, exponent, multiple, rounding);
+    if (typeof minor !== 'number') {
+        throw new RangeError(`${money} is too large for ${processor}`);
+    }
+    checkSign(processor, money, minor, sign);
+    // `+ 0` turns -0 into 0, so a zero amount never serialises as "-0".
+    return minor + 0;
+}
+/**
+ * @internal Money -> a processor's decimal string with exactly `exponent` decimals
+ * ("10.00", or "1000" for JPY), built from the integer so it never goes through a float.
+ */
+export function toProcessorDecimal(processor, money, exponent, rounding, sign = 'any') {
+    const minor = rescaleForProcessor(processor, money, exponent, 1, rounding);
+    checkSign(processor, money, minor, sign);
+    // `+ 0` turns -0 into 0, so a zero amount never serialises as "-0".
+    return formatScaled(typeof minor === 'number' ? minor + 0 : minor, exponent);
+}
+/**
+ * Returns Money at the currency's ISO scale when that is exact, and otherwise at the scale it
+ * came with, so a processor's extra precision (Stripe's ISK 12.34) is kept rather than lost.
+ */
+function toIsoScaleWhenExact(money, currency) {
+    const isoExponent = currencyExponent(currency);
+    if (isoExponent >= money.scale) {
+        return toScale(money, isoExponent);
+    }
+    try {
+        return toScale(money, isoExponent, 'unnecessary');
+    }
+    catch {
+        return money;
+    }
+}
+/** @internal A processor's integer amount -> Money (see `toIsoScaleWhenExact` for the scale). */
+export function fromProcessorAmount(processor, amount, currency, exponent) {
+    if (typeof amount === 'number' && !Number.isSafeInteger(amount)) {
+        throw new RangeError(`${processor} amount must be an integer, got ${amount}`);
+    }
+    return toIsoScaleWhenExact(fromMinor(amount, currency, exponent), currency);
+}
+/**
+ * @internal A processor's decimal string -> Money, exactly (never via a float). `pattern` is the
+ * processor's documented format and `maxLength` its length limit, if any. The scale follows
+ * `toIsoScaleWhenExact`.
+ */
+export function fromProcessorDecimal(processor, value, currency, pattern, maxLength = Infinity) {
+    if (typeof value !== 'string' || value.length > maxLength || !pattern.test(value)) {
+        throw new SyntaxError(`${processor} amount must be a decimal string, got ${JSON.stringify(value)}`);
+    }
+    // PayPal's pattern allows a bare fraction (".5"), which the decimal parsers don't.
+    const withLeadingZero = value.replace(/^(-?)\./, '$10.');
+    const parsed = parsePlainDecimal(withLeadingZero) ?? parseDecimal(withLeadingZero);
+    return toIsoScaleWhenExact(fromMinor(parsed.digits, currency, parsed.scale), currency);
+}
+//# sourceMappingURL=processor.js.map

package/dist/processor.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,103 @@
+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;
+    /** 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. */
+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` (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 | 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.
+ *
+ * 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 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. 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
+ */
+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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"}