@ducatjs/money 0.0.0 → 0.2.0

package/dist/provider.js

@@ -0,0 +1,280 @@
+import { CurrencyMismatchError } from './money.js';
+import { exchangeRate, hasEnded, hasStarted, 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.
+ *
+ * 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) {
+    let rates;
+    const header = {};
+    if (isRateList(spec)) {
+        rates = [...spec];
+    }
+    else {
+        rates = [];
+        const missing = [];
+        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();
+    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;
+            }
+            // 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`.
+            return rate;
+        },
+    };
+}
+/** Whether a rate (or a table) applies at `at`: dated, published and still valid then. */
+function appliesAt(rate, at) {
+    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) {
+    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. 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 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);
+                // A table not yet published at the instant asked for is passed over like a missing one.
+                const availableAt = table?.availableAt;
+                if (table !== undefined && (availableAt === undefined || hasStarted(availableAt, asOf))) {
+                    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":"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"}

package/dist/rate-text.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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 declare function readRateCell(cell: string, where: string): string | null;
+/**
+ * @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 declare function withDecimals(text: string, decimals: number): string;
+/**
+ * @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 declare function csvRows(text: string): string[][];
+/**
+ * @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 declare function isCalendarDay(text: string): boolean;
+/**
+ * @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 declare function addDayRate(days: Map<string, Record<string, string | null>>, day: string, currency: string, rate: string | null): void;
+/** @internal Dated tables, newest first (ISO dates sort as strings). */
+export declare function newestFirst<T extends {
+    readonly asOf?: string;
+}>(tables: T[]): T[];
+//# sourceMappingURL=rate-text.d.ts.map

package/dist/rate-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-text.d.ts","sourceRoot":"","sources":["../src/rate-text.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASvE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYnE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAuDhD;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,EAChD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,IAAI,CAWN;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAElF"}

package/dist/rate-text.js

@@ -0,0 +1,143 @@
+// 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, where) {
+    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, decimals) {
+    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) {
+    const rows = [];
+    let row = [];
+    let cell = '';
+    // 'start' of a cell, inside an unquoted one, inside quotes, or just after the closing quote
+    let state = '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) {
+    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, day, currency, rate) {
+    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(tables) {
+    return tables.sort((table, other) => other.asOf.localeCompare(table.asOf));
+}
+//# sourceMappingURL=rate-text.js.map

package/dist/rate-text.js.map

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

package/dist/rate.d.ts

@@ -0,0 +1,175 @@
+import { type Factor, type Ratio } from './decimal.js';
+import { type CurrencyInput, type Money, type RoundingInput, type RoundingPolicy } 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 & {});
+/**
+ * How a source published a rate, kept with the Rate for audit and display. The published direction
+ * is `from` → `to`, or `to` → `from` when `inverted`.
+ */
+export interface RateQuote {
+    /** The number exactly as published, trailing zeros included ('136.80'). */
+    readonly rate: string;
+    /**
+     * How many units of the published direction's first currency the number is for: 100 for "NOK
+     * per 100 JPY". Omitted for 1.
+     */
+    readonly per?: number;
+    /** The source quoted `to` → `from`; this Rate is its exact inverse. */
+    readonly inverted?: boolean;
+}
+/**
+ * Where a rate came from. `asOf`, `availableAt` and `validUntil` are ISO-8601 dates ('2026-11-06')
+ * or instants.
+ */
+export interface RateInfo {
+    readonly source?: string;
+    /** The date or time the rate applies to. */
+    readonly asOf?: string | Date;
+    /**
+     * When the rate was published. A lookup for an earlier time doesn't get it, so a historical
+     * lookup sees only what was known then. A date means from the start of that UTC day.
+     */
+    readonly availableAt?: string | Date;
+    /** The last date or time the rate applies to. A date is valid all day (UTC). */
+    readonly validUntil?: string | Date;
+    readonly type?: RateType;
+    /** The rate as the source published it. */
+    readonly quote?: RateQuote;
+}
+/** 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;
+    availableAt?: string;
+    validUntil?: string;
+    type?: string;
+    /** Present only when it says more than `rate` does: a `per` or an inverted quote. */
+    quote?: RateQuote;
+    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;
+/**
+ * @internal
+ * Whether `time` has come by `at`. A date `at` means the whole of that UTC day, so anything on or
+ * before that day counts; a date `time` means the start of its day.
+ */
+export declare function hasStarted(time: string, at: string | Date): boolean;
+/** @internal Whether `validUntil` (a date: valid all day, UTC) has passed at `at`. */
+export declare function hasEnded(validUntil: string, at: string | Date): boolean;
+/**
+ * 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 availableAt?: string;
+    readonly validUntil?: string;
+    readonly type?: RateType;
+    readonly quote?: RateQuote;
+    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. A rate
+     * published one unit for one unit keeps the published digits ('136.80').
+     */
+    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;
+    /**
+     * Whether the rate had been published by `at`: always, without an `availableAt`. A date `at`
+     * means by the end of that UTC day.
+     */
+    isAvailable(at: string | Date): boolean;
+    /**
+     * Converts `money`, rounding once: with a mode, to the target currency's exponent (or
+     * `options.scale`); with a rounding policy, to the policy's scale and increment.
+     */
+    convert(money: Money<From>, rounding?: RoundingInput, options?: ConvertOptions): Money<To>;
+}
+/**
+ * @internal
+ * money × rate in `to`, rounded once by a policy. The amount is relabelled `to` at its own scale,
+ * so the policy rounds the product exactly as it would a multiplication in `to`: to its scale
+ * (default `to`'s exponent) and increment, checking its currency against `to`.
+ */
+export declare function convertWithPolicy<To extends string>(money: Money, to: To, rate: Ratio, policy: RoundingPolicy, 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