@ducatjs/money 0.0.0 → 0.2.0

package/dist/fetch.js

@@ -0,0 +1,222 @@
+// Network fetchers for published reference rates, using the platform fetch. Opt-in: nothing else in
+// the library imports this module, so core and @ducatjs/money/convert never touch the
+// network. You decide when to call it and how to cache.
+import { parseBankOfCanadaJson } from './boc.js';
+import { parseEcbSdmxCsv, parseEcbSdmxDecimals, parseEcbXml } from './ecb.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** The ECB's eurofxref files: the latest day, the last 90 days, and the full history since 1999. */
+export const ECB_URLS = {
+    daily: 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml',
+    '90d': 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml',
+    all: 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist.xml',
+};
+/** Thrown when the HTTP request completes without a 2xx status. */
+export class FetchRatesError extends Error {
+    status;
+    url;
+    constructor(url, status) {
+        super(`GET ${url} failed with HTTP ${status}`);
+        this.name = 'FetchRatesError';
+        this.status = status;
+        this.url = url;
+    }
+}
+/**
+ * Fetches the ECB euro reference rates and parses them with parseEcbXml: EUR-based tables,
+ * newest first. The ECB publishes once per TARGET working day at about 16:00 CET and states
+ * that its rates are for information purposes only.
+ *
+ *     const [latest] = await fetchEcb(); // the RateTable for the last published day
+ *     const hist = snapshotsFrom(await fetchEcb({ history: '90d' }));
+ */
+export async function fetchEcb(options) {
+    const url = ECB_URLS[options?.history ?? 'daily'];
+    const body = await getText(url, 'application/xml', options);
+    return parsedFrom(url, () => parseEcbXml(body));
+}
+/** The caller's signal, a timeout signal, or both combined. */
+function requestSignal(signal, timeout) {
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        throw new RangeError(`timeout must be a non-negative number of milliseconds, got ${timeout}`);
+    }
+    const statics = globalThis.AbortSignal;
+    if (timeout === 0 || statics?.timeout === undefined) {
+        return signal;
+    }
+    const timeoutSignal = statics.timeout(timeout);
+    if (signal === undefined) {
+        return timeoutSignal;
+    }
+    if (statics.any === undefined) {
+        // Without AbortSignal.any the caller's signal wins: it is the one they can control.
+        return signal;
+    }
+    return statics.any([signal, timeoutSignal]);
+}
+/** The ECB Data Portal's SDMX REST API (no key, and CORS-enabled, so it works in browsers). */
+export const ECB_DATA_API = 'https://data-api.ecb.europa.eu/service/data/EXR';
+/**
+ * A request's UTC day: a 'YYYY-MM-DD' string that is a real calendar day, or a Date (any
+ * offset) as its UTC day. Anything else is a RangeError, before any request is made.
+ */
+function requestDay(time, name) {
+    let day;
+    if (typeof time === 'string') {
+        day = time;
+    }
+    else {
+        day = Number.isNaN(time.getTime()) ? '' : time.toISOString().slice(0, 10);
+    }
+    const match = /^(\d{4})-(\d\d)-(\d\d)$/.exec(day);
+    const date = match === null ? undefined : new Date(Date.UTC(+match[1], +match[2] - 1, +match[3]));
+    // Date.UTC rolls 30 February over into March, so a real day must come back unchanged.
+    if (date === undefined || date.toISOString().slice(0, 10) !== day) {
+        throw new RangeError(`${name} must be a date, got ${String(time)}`);
+    }
+    return day;
+}
+/** Wraps a parser's SyntaxError with the URL the bad file came from (an error page, usually). */
+function parsedFrom(url, parse) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new SyntaxError(`${error.message} (from ${url})`, { cause: error });
+        }
+        throw error;
+    }
+}
+/** GETs `url` as text, with the timeout and signal handling every fetcher here shares. */
+async function getText(url, accept, options) {
+    return (await getTextOrNotFound(url, accept, options, false));
+}
+/** getText, or undefined for HTTP 404 when `notFoundIsEmpty` (an API's "no results"). */
+async function getTextOrNotFound(url, accept, options, notFoundIsEmpty) {
+    const fetchFunction = options?.fetch ?? globalThis.fetch;
+    if (fetchFunction === undefined) {
+        throw new TypeError('No fetch available: pass options.fetch');
+    }
+    const init = {
+        headers: { accept },
+    };
+    const signal = requestSignal(options?.signal, options?.timeout ?? DEFAULT_TIMEOUT_MS);
+    if (signal !== undefined) {
+        init.signal = signal;
+    }
+    const response = await fetchFunction(url, init);
+    if (notFoundIsEmpty && response.status === 404) {
+        return undefined;
+    }
+    if (!response.ok) {
+        throw new FetchRatesError(url, response.status);
+    }
+    return response.text();
+}
+/**
+ * Fetches a date range of ECB euro reference rates from the ECB Data Portal and parses them with
+ * parseEcbSdmxCsv: EUR-based tables, one per TARGET working day, newest first, with the published
+ * digits. It makes two requests: the series' DECIMALS (small) and the observations without
+ * attributes, which keeps the full history since 1999 to about 15 MB. Give a few days before the
+ * first day you need, so that a lookback from it has a table to fall back on. A range with no
+ * rates (a weekend, or after the latest day) gives []. Both requests share one timeout and are
+ * cancelled together: if one fails, the other is aborted. The ECB states that its rates are for
+ * information purposes only.
+ *
+ *     const tables = await fetchEcbRange({ start: '2026-01-01', currencies: ['USD', 'JPY'] });
+ *     const history = rateHistory(tables); // from @ducatjs/money/convert/history
+ */
+export async function fetchEcbRange(options) {
+    const currencies = options.currencies ?? [];
+    for (const currency of currencies) {
+        if (!/^[A-Z]{3}$/.test(currency)) {
+            throw new RangeError(`Not an ISO currency code: ${currency}`);
+        }
+    }
+    const start = requestDay(options.start, 'start');
+    if (start < '1999-01-04') {
+        throw new RangeError(`The ECB's rates start on 1999-01-04, not ${start}`);
+    }
+    let query = `?format=csvdata&startPeriod=${start}`;
+    if (options.end !== undefined) {
+        const end = requestDay(options.end, 'end');
+        if (end < start) {
+            throw new RangeError(`end ${end} is before start ${start}`);
+        }
+        query += `&endPeriod=${end}`;
+    }
+    const url = `${ECB_DATA_API}/D.${currencies.join('+')}.EUR.SP00.A`;
+    const seriesUrl = `${url}?format=csvdata&detail=nodata`;
+    const dataUrl = `${url}${query}&detail=dataonly`;
+    // One controller for both requests, tied to the caller's signal and the timeout, so that a
+    // failure of either cancels the other (the data can be ~15 MB) instead of letting it run on.
+    let shared = options;
+    let controller;
+    const Controller = globalThis
+        .AbortController;
+    if (Controller !== undefined) {
+        const own = new Controller();
+        controller = own;
+        const outer = requestSignal(options.signal, options.timeout ?? DEFAULT_TIMEOUT_MS);
+        if (outer?.aborted === true) {
+            own.abort(outer.reason);
+        }
+        else {
+            outer?.addEventListener('abort', () => own.abort(outer.reason), { once: true });
+        }
+        shared = { ...options, signal: own.signal, timeout: 0 };
+    }
+    let series;
+    let data;
+    try {
+        [series, data] = await Promise.all([
+            getText(seriesUrl, 'text/csv', shared),
+            getTextOrNotFound(dataUrl, 'text/csv', shared, true),
+        ]);
+    }
+    catch (error) {
+        controller?.abort(error);
+        throw error;
+    }
+    if (data === undefined) {
+        return [];
+    }
+    const decimals = parsedFrom(seriesUrl, () => parseEcbSdmxDecimals(series));
+    return parsedFrom(dataUrl, () => parseEcbSdmxCsv(data, { decimals }));
+}
+/** The Bank of Canada's Valet API for its daily exchange rates (no key; CORS-enabled). */
+export const BANK_OF_CANADA_URL = 'https://www.bankofcanada.ca/valet/observations/group/FX_RATES_DAILY/json';
+/**
+ * Fetches the Bank of Canada's daily exchange rates from its Valet API and parses them with
+ * parseBankOfCanadaJson: CAD-based tables, newest first. Without `start`, only the latest day;
+ * without `end`, up to the latest. A range with no business days in it gives [].
+ * The Bank asks users to keep within its request limits, which it doesn't publish, and its rates
+ * are "released for statistical and analytical purposes only", not for transactions.
+ *
+ *     const [latest] = await fetchBankOfCanada();
+ *     const year = await fetchBankOfCanada({ start: '2026-01-01' });
+ */
+export async function fetchBankOfCanada(options) {
+    let query = '?recent=1';
+    if (options?.start !== undefined) {
+        const start = requestDay(options.start, 'start');
+        if (start < '2017-01-03') {
+            throw new RangeError(`Valet's daily rates start on 2017-01-03, not ${start}`);
+        }
+        query = `?start_date=${start}`;
+        if (options.end !== undefined) {
+            const end = requestDay(options.end, 'end');
+            if (end < start) {
+                throw new RangeError(`end ${end} is before start ${start}`);
+            }
+            query += `&end_date=${end}`;
+        }
+    }
+    else if (options?.end !== undefined) {
+        throw new RangeError('end needs a start');
+    }
+    const url = `${BANK_OF_CANADA_URL}${query}`;
+    const body = await getText(url, 'application/json', options);
+    return parsedFrom(url, () => parseBankOfCanadaJson(body));
+}
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,sFAAsF;AACtF,wDAAwD;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AA0B9E,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,oGAAoG;AACpG,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,KAAK,EAAE,+DAA+D;IACtE,KAAK,EAAE,kEAAkE;IACzE,GAAG,EAAE,8DAA8D;CAC3D,CAAC;AAiBX,mEAAmE;AACnE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,MAAM,CAAS;IACf,GAAG,CAAS;IACrB,YAAY,GAAW,EAAE,MAAc;QACrC,KAAK,CAAC,OAAO,GAAG,qBAAqB,MAAM,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAyB;IACtD,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,IAAI,OAAO,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,+DAA+D;AAC/D,SAAS,aAAa,CACpB,MAAmC,EACnC,OAAe;IAEf,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,UAAU,CAAC,8DAA8D,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,OAAO,GAAI,UAA8D,CAAC,WAAW,CAAC;IAC5F,IAAI,OAAO,KAAK,CAAC,IAAI,OAAO,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;QACpD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,oFAAoF;QACpF,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,MAAM,YAAY,GAAG,iDAAiD,CAAC;AAY9E;;;GAGG;AACH,SAAS,UAAU,CAAC,IAAmB,EAAE,IAAY;IACnD,IAAI,GAAW,CAAC;IAChB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,GAAG,GAAG,IAAI,CAAC;IACb,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,KAAK,GAAG,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,IAAI,GACR,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;IAC1F,sFAAsF;IACtF,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC;QAClE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,wBAAwB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iGAAiG;AACjG,SAAS,UAAU,CAAI,GAAW,EAAE,KAAc;IAChD,IAAI,CAAC;QACH,OAAO,KAAK,EAAE,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,WAAW,CAAC,GAAG,KAAK,CAAC,OAAO,UAAU,GAAG,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAKD,0FAA0F;AAC1F,KAAK,UAAU,OAAO,CACpB,GAAW,EACX,MAAc,EACd,OAAqD;IAErD,OAAO,CAAC,MAAM,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAE,CAAC;AACjE,CAAC;AAED,yFAAyF;AACzF,KAAK,UAAU,iBAAiB,CAC9B,GAAW,EACX,MAAc,EACd,OAAqD,EACrD,eAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,EAAE,KAAK,IAAK,UAAgC,CAAC,KAAK,CAAC;IAChF,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,IAAI,GAAkE;QAC1E,OAAO,EAAE,EAAE,MAAM,EAAE;KACpB,CAAC;IACF,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,IAAI,kBAAkB,CAAC,CAAC;IACtF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAChD,IAAI,eAAe,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC/C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA6B;IAC/D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;IAC5C,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,UAAU,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;QACzB,MAAM,IAAI,UAAU,CAAC,4CAA4C,KAAK,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,KAAK,GAAG,+BAA+B,KAAK,EAAE,CAAC;IACnD,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3C,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,UAAU,CAAC,OAAO,GAAG,oBAAoB,KAAK,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,KAAK,IAAI,cAAc,GAAG,EAAE,CAAC;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,YAAY,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC;IACnE,MAAM,SAAS,GAAG,GAAG,GAAG,+BAA+B,CAAC;IACxD,MAAM,OAAO,GAAG,GAAG,GAAG,GAAG,KAAK,kBAAkB,CAAC;IAEjD,2FAA2F;IAC3F,6FAA6F;IAC7F,IAAI,MAAM,GAAqC,OAAO,CAAC;IACvD,IAAI,UAA2C,CAAC;IAChD,MAAM,UAAU,GAAI,UAAkE;SACnF,eAAe,CAAC;IACnB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,UAAU,GAAG,GAAG,CAAC;QACjB,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,IAAI,kBAAkB,CAAC,CAAC;QACnF,IAAI,KAAK,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC5B,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,KAAK,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,GAAG,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC1D,CAAC;IAED,IAAI,MAAc,CAAC;IACnB,IAAI,IAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACjC,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC;YACtC,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC;SACrD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACzB,MAAM,KAAK,CAAC;IACd,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E,OAAO,UAAU,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,MAAM,kBAAkB,GAC7B,0EAA0E,CAAC;AAU7E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAkC;IACxE,IAAI,KAAK,GAAG,WAAW,CAAC;IACxB,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;YACzB,MAAM,IAAI,UAAU,CAAC,gDAAgD,KAAK,EAAE,CAAC,CAAC;QAChF,CAAC;QACD,KAAK,GAAG,eAAe,KAAK,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC3C,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;gBAChB,MAAM,IAAI,UAAU,CAAC,OAAO,GAAG,oBAAoB,KAAK,EAAE,CAAC,CAAC;YAC9D,CAAC;YACD,KAAK,IAAI,aAAa,GAAG,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,EAAE,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,kBAAkB,GAAG,KAAK,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;IAC7D,OAAO,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/fixed.d.ts

@@ -0,0 +1,121 @@
+import { type Factor } from './decimal.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { type RoundingMode } from './rounding.js';
+declare const INTERNAL: unique symbol;
+/** What `fixed()` accepts: a decimal string, a number, a bigint or a Fixed. */
+export type FixedInput = string | number | bigint | Fixed;
+/** Options for `fixed()`. */
+export interface FixedOptions {
+    /** Decimal places to keep (default: as many as the input has; 0 for integers). */
+    readonly scale?: number;
+    /** How to round input with more decimals than `scale` (default 'unnecessary': throw). */
+    readonly rounding?: RoundingMode;
+}
+/** Options for multiply and divide. */
+export interface ArithmeticOptions {
+    /** The result's scale (default: the scale of the value being multiplied or divided). */
+    readonly scale?: number;
+}
+/** The integer-and-scale form of a Fixed: `value / 10^scale`. */
+export interface ScaledInteger {
+    readonly value: number | bigint;
+    readonly scale: number;
+}
+/**
+ * An exact fixed-point decimal: `value / 10^scale`. Immutable. Create one with `fixed()` or
+ * `fromScaled()`. Mixed scales work as for Money: add, subtract and compare align to the larger
+ * scale exactly, and multiply and divide keep this value's scale.
+ */
+export declare class Fixed {
+    /** The scaled integer: a number while it is a safe integer, a bigint beyond. */
+    readonly value: number | bigint;
+    /** Decimal places. */
+    readonly scale: number;
+    /** @internal use fixed() or fromScaled() */
+    constructor(token: typeof INTERNAL, value: number | bigint, scale: number);
+    /** this + other, exactly, at the larger of the two scales. */
+    add(other: FixedInput): Fixed;
+    /** this − other, exactly, at the larger of the two scales. */
+    subtract(other: FixedInput): Fixed;
+    /**
+     * this × factor, rounded once to this value's scale or `options.scale` (default 'halfExpand').
+     * The factor is exact: an integer, a decimal string ('1.075'), a bigint, a `ratio()` or another
+     * Fixed. Give `scale` rather than calling toScale afterwards, which would round twice.
+     */
+    multiply(factor: Factor | Fixed, rounding?: RoundingMode, options?: ArithmeticOptions): Fixed;
+    /**
+     * this ÷ divisor, rounded once to this value's scale or `options.scale` (default 'halfExpand'):
+     * `fixed('9.990').divide('1.2', 'halfEven', { scale: 2 })` is 8.32.
+     */
+    divide(divisor: Factor | Fixed, rounding?: RoundingMode, options?: ArithmeticOptions): Fixed;
+    /** −this */
+    negate(): Fixed;
+    /** |this| */
+    abs(): Fixed;
+    /**
+     * Rounds to `scale` decimal places (default 0, an integer): `fixed('2.5').round('halfEven')` is
+     * 2. Money's round() defaults to the currency's exponent; a Fixed has none, so the default is 0.
+     */
+    round(rounding: RoundingMode, scale?: number): Fixed;
+    /**
+     * Changes the scale: increasing it is always exact, decreasing it rounds (default 'halfExpand').
+     */
+    toScale(scale: number, rounding?: RoundingMode): Fixed;
+    /** −1, 0 or 1, exactly, across scales and number/bigint. */
+    compare(other: FixedInput): -1 | 0 | 1;
+    /** The same value, at any scale: 1.0 equals 1.00. */
+    equals(other: FixedInput): boolean;
+    /** this < other */
+    lessThan(other: FixedInput): boolean;
+    /** this ≤ other */
+    lessThanOrEqual(other: FixedInput): boolean;
+    /** this > other */
+    greaterThan(other: FixedInput): boolean;
+    /** this ≥ other */
+    greaterThanOrEqual(other: FixedInput): boolean;
+    /** this = 0 */
+    isZero(): boolean;
+    /** this > 0 */
+    isPositive(): boolean;
+    /** this < 0 */
+    isNegative(): boolean;
+    /** −1, 0 or 1 */
+    sign(): -1 | 0 | 1;
+    /** The plain decimal string, with every decimal place of the scale: '12.340'. */
+    toString(): string;
+    /** The decimal string, as toString(), so JSON round-trips exactly through `fixed()`. */
+    toJSON(): string;
+    /** `{ value, scale }`, the exact integer form: value / 10^scale. */
+    toScaled(): ScaledInteger;
+    /**
+     * Money in `currency`, at its exponent. Throws RoundingError when that would drop digits, unless
+     * `rounding` is given: `fixed('1.005').toMoney('EUR', 'halfEven')` is 1.00 EUR.
+     */
+    toMoney<C extends CurrencyInput>(currency: C, rounding?: RoundingMode): Money<C>;
+    /** Blocks `a + b`, `a > b` and `+a`: arithmetic and comparison go through the methods. */
+    [Symbol.toPrimitive](hint: string): string;
+}
+/**
+ * Creates an exact fixed-point decimal.
+ *
+ *     fixed('12.340')                 // 12.340: a string keeps its scale (3)
+ *     fixed('1.005', { scale: 2, rounding: 'halfEven' })   // 1.00
+ *     fixed(12)                       // 12, scale 0
+ *     fixed(0.25)                     // 0.25: read at its shortest decimal form
+ *     fixed(10n ** 30n)
+ *
+ * Numbers are taken at their shortest decimal form, and only when that has at most 15 significant
+ * digits, which a double always holds faithfully. So `fixed(0.1 + 0.2)` throws rather than becoming
+ * 0.30000000000000004; pass the decimal as a string, or give `scale` and `rounding`. Input with
+ * more decimals than `scale` throws unless `rounding` is given, and `rounding` needs a `scale`.
+ * Scales run from 0 to 1000.
+ */
+export declare function fixed(value: FixedInput, options?: FixedOptions): Fixed;
+/** The Fixed `value / 10^scale`: `fromScaled(12345, 3)` is 12.345. `value` must be an integer. */
+export declare function fromScaled(value: number | bigint, scale: number): Fixed;
+/** Whether `value` is a Fixed. */
+export declare function isFixed(value: unknown): value is Fixed;
+/** The exact Fixed of a Money amount, at the money's scale: `money('12.34', 'EUR')` → 12.34. */
+export declare function moneyToFixed(money: Money): Fixed;
+export {};
+//# sourceMappingURL=fixed.d.ts.map

package/dist/fixed.d.ts.map

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