@ducatjs/money 0.1.0 → 0.2.0

package/dist/history.js

@@ -0,0 +1,213 @@
+import { rateTable, } from './provider.js';
+import { ratio } from './decimal.js';
+import { hasEnded, hasStarted, Rate, toIsoString } from './rate.js';
+import { withDecimals } from './rate-text.js';
+const DAY_MS = 86_400_000;
+const PLAIN_DECIMAL = /^\d+(?:\.\d+)?$/;
+/** The exact rate a quote stands for, in the Rate's own direction. */
+function quoteRatio(quote) {
+    if (!PLAIN_DECIMAL.test(quote.rate)) {
+        throw new RangeError(`A quote is a plain decimal string, got ${quote.rate}`);
+    }
+    const per = quote.per ?? 1;
+    if (!Number.isSafeInteger(per) || per < 1) {
+        throw new RangeError(`A quote's per is a positive integer, got ${per}`);
+    }
+    const published = ratio(quote.rate);
+    if (quote.inverted === true) {
+        return ratio(published.den * BigInt(per), published.num);
+    }
+    return ratio(published.num, published.den * BigInt(per));
+}
+/**
+ * A Rate from a published quote: `per` units and the direction are applied exactly, and the quote
+ * is kept on the Rate.
+ *
+ *     rateFromQuote('JPY', 'NOK', { rate: '6.50', per: 100 })        // JPY→NOK 0.065
+ *     rateFromQuote('USD', 'EUR', { rate: '1.1650', inverted: true }) // USD→EUR 200/233
+ */
+export function rateFromQuote(from, to, quote, info) {
+    const exact = quoteRatio(quote);
+    // Stored in one form: per 1 and inverted false are the same as leaving them out, and a quote
+    // without them prints its own digits.
+    const kept = { rate: quote.rate };
+    if (quote.per !== undefined && quote.per !== 1) {
+        kept.per = quote.per;
+    }
+    if (quote.inverted === true) {
+        kept.inverted = true;
+    }
+    return new Rate(from, to, exact, { ...info, quote: kept });
+}
+/**
+ * A rateTable from rates as a source published them: each is stored exactly in the table's
+ * direction, base → currency, and keeps its quote (`rate.quote`).
+ *
+ *     const boc = quotedTable({ base: 'CAD', inverted: true, asOf: '2026-11-06', rates: { USD: '1.3654' } });
+ *     boc.rate('CAD', 'USD')?.inverse().toString(); // '1.3654'
+ */
+export function quotedTable(spec) {
+    const rates = {};
+    for (const [currency, entry] of Object.entries(spec.rates)) {
+        if (entry === null) {
+            rates[currency] = null;
+            continue;
+        }
+        let quoted;
+        if (typeof entry === 'string') {
+            quoted = { rate: entry };
+        }
+        else {
+            quoted = entry;
+        }
+        let text = quoted.rate.trim();
+        const decimals = quoted.decimals ?? spec.decimals;
+        if (decimals !== undefined) {
+            text = withDecimals(text, decimals);
+        }
+        const quote = { rate: text };
+        if (quoted.per !== undefined) {
+            quote.per = quoted.per;
+        }
+        if (quoted.inverted ?? spec.inverted ?? false) {
+            quote.inverted = true;
+        }
+        rates[currency] = rateFromQuote(spec.base, currency, quote, spec);
+    }
+    return rateTable({ ...spec, rates });
+}
+/** 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);
+}
+/**
+ * Why a table can't answer the pair at the time asked for, or undefined when it can. The table's
+ * own dates are checked first; a table built from a list of Rates has none, so its rate's are.
+ */
+function passOver(table, from, to, query, periodEnded) {
+    const asOf = query?.asOf;
+    if (periodEnded) {
+        return 'expired';
+    }
+    if (asOf !== undefined &&
+        table.availableAt !== undefined &&
+        !hasStarted(table.availableAt, asOf)) {
+        return 'notYetAvailable';
+    }
+    if (table.rate(from, to, query) !== undefined) {
+        return undefined;
+    }
+    if (table.missing?.includes(from) === true || table.missing?.includes(to) === true) {
+        return 'missing';
+    }
+    const held = table.rates.find((rate) => rate.from === from && rate.to === to);
+    if (held !== undefined && asOf !== undefined) {
+        if (held.isExpired(asOf)) {
+            return 'expired';
+        }
+        if (!held.isAvailable(asOf)) {
+            return 'notYetAvailable';
+        }
+    }
+    return 'notQuoted';
+}
+/** The ISO date `count` days before `day`. */
+function daysBefore(day, count) {
+    return new Date(Date.parse(`${day}T00:00:00Z`) - count * DAY_MS).toISOString().slice(0, 10);
+}
+/**
+ * A provider over many dated tables, such as a date range loaded in one call: for each lookup it
+ * takes the latest table at or before `asOf` that has the pair, published by then and still
+ * valid, looking back up to `lookback` days. Each currency pair falls back on its own, so a
+ * currency missing on a holiday comes from the day before while the others stay current; the
+ * Rate's `asOf` says which day it is from. Without an `asOf`, the newest table with the pair
+ * answers. `lookup` reports why a lookup fell back.
+ *
+ *     const history = rateHistory(parseEcbXml(xml90Days));
+ *     history.rate('EUR', 'USD', { asOf: '2026-11-08' }); // Sunday: Friday's rate
+ *     history.lookup('EUR', 'USD', { asOf: '2026-11-08' }).skipped;
+ *     // [{ day: '2026-11-08', reason: 'noTable' }, { day: '2026-11-07', reason: 'noTable' }]
+ */
+export function rateHistory(tables, options) {
+    const lookback = options?.lookback ?? 4;
+    if (!Number.isSafeInteger(lookback) || lookback < 0) {
+        throw new RangeError(`lookback must be a non-negative integer, got ${lookback}`);
+    }
+    const dated = [];
+    for (const table of tables) {
+        if (table.asOf === undefined) {
+            throw new RangeError('rateHistory needs tables with an asOf');
+        }
+        dated.push({ day: dayOf(table.asOf), table });
+    }
+    // Newest first; a stable sort keeps the caller's order within a day.
+    dated.sort((entry, other) => (other.day < entry.day ? -1 : Number(other.day > entry.day)));
+    const hasPeriods = dated.some((entry) => entry.table.validUntil !== undefined);
+    function lookup(from, to, query) {
+        const asOf = query?.asOf;
+        const skipped = [];
+        let firstDay;
+        if (asOf !== undefined) {
+            firstDay = dayOf(asOf);
+        }
+        else {
+            firstDay = dated[0]?.day;
+        }
+        if (firstDay === undefined) {
+            return { rate: undefined, skipped };
+        }
+        const lastDay = daysBefore(firstDay, lookback);
+        // The newest day of the lookback window not yet accounted for by a daily table.
+        let expectedDay = firstDay;
+        for (const { day, table } of dated) {
+            if (day > firstDay) {
+                continue;
+            }
+            const periodEnded = asOf !== undefined && table.validUntil !== undefined && hasEnded(table.validUntil, asOf);
+            const coversPeriod = table.validUntil !== undefined && !periodEnded;
+            if (day < lastDay && !coversPeriod) {
+                // Older daily tables are out of the window; an older period table may still cover it.
+                if (!hasPeriods) {
+                    break;
+                }
+                continue;
+            }
+            // Days between the last table and this one had no table. A period table that answers
+            // covers them, so for one they count only once it turns out not to answer.
+            // An older period table comes after every day of the window, so all of them are gaps.
+            const inWindow = day >= lastDay;
+            const accountedTo = inWindow ? day : daysBefore(lastDay, 1);
+            const gaps = [];
+            for (let gap = expectedDay; gap > accountedTo; gap = daysBefore(gap, 1)) {
+                gaps.push({ day: gap, reason: 'noTable' });
+            }
+            if (!coversPeriod) {
+                skipped.push(...gaps);
+            }
+            const reason = passOver(table, from, to, query, periodEnded);
+            if (reason === undefined) {
+                return { rate: table.rate(from, to, query), skipped };
+            }
+            if (coversPeriod) {
+                skipped.push(...gaps);
+            }
+            skipped.push({ day, reason });
+            if (accountedTo <= expectedDay) {
+                expectedDay = inWindow ? daysBefore(day, 1) : accountedTo;
+            }
+        }
+        // Days left in the window without any table at all.
+        for (let gap = expectedDay; gap >= lastDay; gap = daysBefore(gap, 1)) {
+            skipped.push({ day: gap, reason: 'noTable' });
+        }
+        return { rate: undefined, skipped };
+    }
+    return {
+        tables: dated.map((entry) => entry.table),
+        rate(from, to, query) {
+            return lookup(from, to, query).rate;
+        },
+        lookup,
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

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

package/dist/hmrc.d.ts

@@ -0,0 +1,28 @@
+import { type RateTable } from './provider.js';
+/** Options for parseHmrcMonthlyCsv. */
+export interface HmrcOptions {
+    /**
+     * When each period's rates were published, or false for none. Default: the end (UTC) of the
+     * Wednesday before the penultimate Thursday of the month before, when HMRC publishes them.
+     */
+    readonly availableAt?: false | ((start: string) => string | Date);
+}
+/**
+ * Parses HMRC's monthly exchange rates CSV (trade-tariff.service.gov.uk, under the Open
+ * Government Licence) into one GBP-based table per period, newest first. Each is valid for its
+ * calendar month: `asOf` is the start date and `validUntil` the end date, so a `rateHistory` of
+ * them answers any day of the month (see @ducatjs/money/convert/history). Rates are currency units
+ * per £1, with `source: 'HMRC'` and `type: 'customs'`, four decimals as published. HMRC publishes
+ * each month's file in the month before, on the Wednesday before its penultimate Thursday (the
+ * `publication_date` that https://www.trade-tariff.service.gov.uk/api/v2/exchange_rates/
+ * period_lists/2026?filter[type]=monthly gives for each file); `availableAt` is the end of that
+ * UTC day. Several countries share a code (the CFA francs, AED, XCD): their rows must agree.
+ * HMRC never leaves a rate blank, so a blank or missing-value cell throws SyntaxError, as does any
+ * other row that can't be read. A file may hold several periods; they may overlap (a mid-month
+ * amendment, say), and `rateHistory` then uses the one that started last.
+ *
+ *     const [november] = parseHmrcMonthlyCsv(await readFile('monthly_csv_2026-11.csv', 'utf8'));
+ *     november.rate('GBP', 'EUR', { asOf: '2026-11-15' })?.toString(); // '1.1930'
+ */
+export declare function parseHmrcMonthlyCsv(csv: string, options?: HmrcOptions): RateTable[];
+//# sourceMappingURL=hmrc.d.ts.map

package/dist/hmrc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmrc.d.ts","sourceRoot":"","sources":["../src/hmrc.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAmC1D,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,EAAE,CA6DnF"}

package/dist/hmrc.js

@@ -0,0 +1,108 @@
+// `@ducatjs/money/convert/hmrc`: an offline parser for HMRC's monthly exchange rates, the UK's
+// rates for customs and VAT. No I/O: download the CSV yourself.
+import { rateTable } from './provider.js';
+import { addDayRate, csvRows, isCalendarDay, newestFirst, readRateCell } from './rate-text.js';
+const UK_DATE = /^(\d\d)\/(\d\d)\/(\d{4})$/;
+const COLUMNS = ['Currency Code', 'Currency Units per £1', 'Start date', 'End date'];
+function notHmrc(why) {
+    throw new SyntaxError(`Not an HMRC monthly exchange rates CSV file: ${why}`);
+}
+/** 'DD/MM/YYYY' as an ISO date, or SyntaxError. */
+function isoDate(text) {
+    const match = UK_DATE.exec(text.trim());
+    const day = match === null ? '' : `${match[3]}-${match[2]}-${match[1]}`;
+    if (!isCalendarDay(day)) {
+        notHmrc(`bad date ${JSON.stringify(text)}`);
+    }
+    return day;
+}
+/**
+ * When a month's rates are public: the end of the day HMRC publishes them, the Wednesday before the
+ * penultimate Thursday of the month before. The trade tariff service's API gives that Wednesday as
+ * the `publication_date` of every monthly file from January 2024 to November 2026; it gives no
+ * time of day, so the end of that UTC day is the earliest moment that is never too early. That
+ * instant is the start of the penultimate Thursday.
+ */
+function publishedBy(start) {
+    // The last day of the previous month, then back to its last Thursday, then a week before that.
+    const lastDay = new Date(Date.UTC(Number(start.slice(0, 4)), Number(start.slice(5, 7)) - 1, 0));
+    const backToThursday = (lastDay.getUTCDay() - 4 + 7) % 7;
+    lastDay.setUTCDate(lastDay.getUTCDate() - backToThursday - 7);
+    return lastDay.toISOString();
+}
+/**
+ * Parses HMRC's monthly exchange rates CSV (trade-tariff.service.gov.uk, under the Open
+ * Government Licence) into one GBP-based table per period, newest first. Each is valid for its
+ * calendar month: `asOf` is the start date and `validUntil` the end date, so a `rateHistory` of
+ * them answers any day of the month (see @ducatjs/money/convert/history). Rates are currency units
+ * per £1, with `source: 'HMRC'` and `type: 'customs'`, four decimals as published. HMRC publishes
+ * each month's file in the month before, on the Wednesday before its penultimate Thursday (the
+ * `publication_date` that https://www.trade-tariff.service.gov.uk/api/v2/exchange_rates/
+ * period_lists/2026?filter[type]=monthly gives for each file); `availableAt` is the end of that
+ * UTC day. Several countries share a code (the CFA francs, AED, XCD): their rows must agree.
+ * HMRC never leaves a rate blank, so a blank or missing-value cell throws SyntaxError, as does any
+ * other row that can't be read. A file may hold several periods; they may overlap (a mid-month
+ * amendment, say), and `rateHistory` then uses the one that started last.
+ *
+ *     const [november] = parseHmrcMonthlyCsv(await readFile('monthly_csv_2026-11.csv', 'utf8'));
+ *     november.rate('GBP', 'EUR', { asOf: '2026-11-15' })?.toString(); // '1.1930'
+ */
+export function parseHmrcMonthlyCsv(csv, options) {
+    const [header, ...rows] = csvRows(csv.charCodeAt(0) === 0xfeff ? csv.slice(1) : csv);
+    const names = (header ?? []).map((name) => name.trim());
+    const index = COLUMNS.map((name) => names.indexOf(name));
+    if (index.some((i) => i === -1)) {
+        notHmrc(`the columns are ${names.join(', ')}`);
+    }
+    const [codeAt, rateAt, startAt, endAt] = index;
+    if (rows.length === 0) {
+        notHmrc('no rates');
+    }
+    // Periods by their start and end; within one, rates by code.
+    const periods = new Map();
+    for (const cells of rows) {
+        if (cells.length !== names.length) {
+            notHmrc(`a row has ${cells.length} cells, the header ${names.length}`);
+        }
+        const code = cells[codeAt].trim();
+        if (!/^[A-Z]{3}$/.test(code) || code === 'GBP') {
+            notHmrc(`bad currency code ${JSON.stringify(code)}`);
+        }
+        const start = isoDate(cells[startAt]);
+        const end = isoDate(cells[endAt]);
+        if (end < start) {
+            notHmrc(`${code} ends on ${end}, before it starts on ${start}`);
+        }
+        const key = `${start}/${end}`;
+        let codes = periods.get(key);
+        if (codes === undefined) {
+            codes = new Map();
+            periods.set(key, codes);
+        }
+        const where = `${code} from ${start}`;
+        const rate = readRateCell(cells[rateAt], where);
+        if (rate === null) {
+            notHmrc(`no rate for ${where}`);
+        }
+        addDayRate(codes, start, code, rate);
+    }
+    const tables = [];
+    for (const [key, codes] of periods) {
+        const [start, end] = key.split('/');
+        const rates = codes.get(start);
+        if (!Object.values(rates).some((rate) => rate !== null)) {
+            continue;
+        }
+        let availableAt;
+        if (options?.availableAt === undefined) {
+            availableAt = publishedBy(start);
+        }
+        else if (options.availableAt !== false) {
+            availableAt = options.availableAt(start);
+        }
+        const info = { base: 'GBP', source: 'HMRC', type: 'customs', asOf: start, validUntil: end };
+        tables.push(rateTable({ ...info, ...(availableAt === undefined ? {} : { availableAt }), rates }));
+    }
+    return newestFirst(tables);
+}
+//# sourceMappingURL=hmrc.js.map

package/dist/hmrc.js.map

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

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * formatting, parsing and the processor and database views are opt-in modules
  * (`@ducatjs/money/allocate`, `@ducatjs/money/tax`, ...; `@ducatjs/money/all` for everything).
  */
-export { money, fromMinor, zero, fromJSON, isMoney, extendMoney, type ExtendMoneyOptions, sum, ratio, CurrencyMismatchError, type Money, type MoneyJSON, type MoneyOptions, type CurrencyInput, type Factor, type Ratio, } from './money.js';
+export { money, fromMinor, zero, fromJSON, isMoney, isMoneyIn, assertCurrency, extendMoney, type ExtendMoneyOptions, sum, ratio, CurrencyMismatchError, type RoundingPolicy, type RoundingInput, type Money, type MoneyJSON, type MoneyOptions, type CurrencyInput, type Factor, type Ratio, } from './money.js';
 export { DEFAULT_ROUNDING, Rounding, RoundingError, type RoundingMode } from './rounding.js';
 export { currencyExponent, defineCurrency, isCurrency, ISO_EXPONENTS, ISO_4217_PUBLISHED, ISO_NON_MONETARY, type CurrencyCode, type IsoCurrencyCode, type CustomCurrencies, } from './currency.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,EACL,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,WAAW,EACX,KAAK,kBAAkB,EACvB,GAAG,EACH,KAAK,EACL,qBAAqB,EACrB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,MAAM,EACX,KAAK,KAAK,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,EACL,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,SAAS,EACT,cAAc,EACd,WAAW,EACX,KAAK,kBAAkB,EACvB,GAAG,EACH,KAAK,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,MAAM,EACX,KAAK,KAAK,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -5,7 +5,7 @@
  * formatting, parsing and the processor and database views are opt-in modules
  * (`@ducatjs/money/allocate`, `@ducatjs/money/tax`, ...; `@ducatjs/money/all` for everything).
  */
-export { money, fromMinor, zero, fromJSON, isMoney, extendMoney, sum, ratio, CurrencyMismatchError, } from './money.js';
+export { money, fromMinor, zero, fromJSON, isMoney, isMoneyIn, assertCurrency, extendMoney, sum, ratio, CurrencyMismatchError, } from './money.js';
 export { DEFAULT_ROUNDING, Rounding, RoundingError } from './rounding.js';
 export { currencyExponent, defineCurrency, isCurrency, ISO_EXPONENTS, ISO_4217_PUBLISHED, ISO_NON_MONETARY, } from './currency.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,EACL,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,WAAW,EAEX,GAAG,EACH,KAAK,EACL,qBAAqB,GAOtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAqB,MAAM,eAAe,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,EACL,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,SAAS,EACT,cAAc,EACd,WAAW,EAEX,GAAG,EACH,KAAK,EACL,qBAAqB,GAStB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAqB,MAAM,eAAe,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,eAAe,CAAC"}

package/dist/kysely.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `@ducatjs/money/kysely`: Money in Kysely queries, without the plugin having to understand query
+ * shapes. A money value is selected as a self-describing JSON object built in SQL (marked, with the
+ * amount as exact text and the currency), and `MoneyResultPlugin` turns exactly those objects into
+ * Money, wherever they appear: unions, CTEs, subqueries, nested JSON, every `stream()` chunk, and
+ * under `CamelCasePlugin`. A raw column is never typed as Money.
+ *
+ *     const money = moneyHelpers('postgres');
+ *     const db = new Kysely<Database>({ dialect, plugins: [new MoneyResultPlugin()] });
+ *
+ *     await db.insertInto('payments').values({ id: 1, ...setMoney(fee, 'amount_minor', 'currency') });
+ *     await db
+ *       .selectFrom('payments')
+ *       .select((eb) => money.selectMoney(eb, 'amount_minor', 'currency').as('fee'))
+ *       .where((eb) => money.compareMoney(eb, 'amount_minor', 'currency', '>=', fee))
+ *       .execute();
+ */
+import { type ColumnType, type Expression, type ExpressionBuilder, type ExtractTypeFromReferenceExpression, type KyselyPlugin, type PluginTransformQueryArgs, type PluginTransformResultArgs, type QueryResult, type RawBuilder, type ReferenceExpression, type RootOperationNode, type SqlBool, type UnknownRow } from 'kysely';
+import { type CurrencyInput, type Money } from './money.js';
+import { type DecimalColumnSize } from './sql.js';
+export { DEFAULT_DECIMAL_SIZE, type DecimalColumnSize } from './sql.js';
+/** The SQL dialects the helpers can build JSON objects and exact casts for. */
+export type MoneyDialect = 'postgres' | 'mysql' | 'sqlite';
+/**
+ * A BIGINT (SQLite INTEGER) column of minor units. Drivers return it as a string, a number or a
+ * bigint; `setMoney` writes integer strings, which every driver binds exactly.
+ */
+export type MinorUnitsColumn = ColumnType<string | number | bigint, string | bigint, string | bigint>;
+/** A NUMERIC/DECIMAL (SQLite TEXT) column holding the exact decimal as a string. */
+export type DecimalAmountColumn = ColumnType<string, string, string>;
+/** A currency that is fixed for a column instead of stored in another column: `fixed('EUR')`. */
+export interface FixedCurrency<C extends string> {
+    readonly fixed: C;
+}
+/** Marks a column's currency as fixed: `selectMoney(eb, 'total_minor', fixed('EUR'))`. */
+export declare function fixed<const C extends CurrencyInput>(currency: C): FixedCurrency<C>;
+/** The comparison operators `compareMoney` supports. */
+export type MoneyComparison = '=' | '<>' | '<' | '<=' | '>' | '>=';
+/** `Money<C>`, or `Money<C> | null` when the amount column is nullable. */
+type MoneyFor<Amount, C extends string> = null extends Amount ? Money<C> | null : Money<C>;
+/**
+ * Column values for an insert or update: the minor units as an integer string, and the currency
+ * (unless it is fixed for the column, in which case the Money must be in it).
+ *
+ *     .values({ id: 1, ...setMoney(fee, 'amount_minor', 'currency') })
+ *     .set(setMoney(total, 'total_minor', fixed('EUR')))
+ */
+export declare function setMoney<const A extends string, const K extends string>(money: Money, amount: A, currency: K): {
+    [P in A | K]: string;
+};
+export declare function setMoney<const A extends string, const C extends string>(money: Money<NoInfer<C>>, amount: A, currency: FixedCurrency<C>): {
+    [P in A]: string;
+};
+/**
+ * Like `setMoney`, for a NUMERIC/DECIMAL amount column: the exact decimal. Pass the column's size
+ * (NUMERIC(19,4) by default) so that a value it would round or clamp throws instead. On SQLite,
+ * where decimals are TEXT, the size only limits what is written.
+ */
+export declare function setDecimalMoney<const A extends string, const K extends string>(money: Money, amount: A, currency: K, size?: DecimalColumnSize): {
+    [P in A | K]: string;
+};
+export declare function setDecimalMoney<const A extends string, const C extends string>(money: Money<NoInfer<C>>, amount: A, currency: FixedCurrency<C>, size?: DecimalColumnSize): {
+    [P in A]: string;
+};
+/** The money helpers for one dialect, from `moneyHelpers`. */
+export interface MoneyHelpers {
+    /**
+     * The Money in an amount column of minor units, with the currency from a column or `fixed()`.
+     * Typed `Money<C>`, or `Money<C> | null` for a nullable amount column; needs `MoneyResultPlugin`.
+     *
+     *     .select((eb) => money.selectMoney(eb, 'p.amount_minor', 'p.currency').as('paid'))
+     */
+    selectMoney<DB, TB extends keyof DB, RA extends ReferenceExpression<DB, TB>>(eb: ExpressionBuilder<DB, TB>, amount: RA, currency: ReferenceExpression<DB, TB>): RawBuilder<MoneyFor<ExtractTypeFromReferenceExpression<DB, TB, RA>, CurrencyInput>>;
+    selectMoney<DB, TB extends keyof DB, RA extends ReferenceExpression<DB, TB>, C extends string>(eb: ExpressionBuilder<DB, TB>, amount: RA, currency: FixedCurrency<C>): RawBuilder<MoneyFor<ExtractTypeFromReferenceExpression<DB, TB, RA>, C>>;
+    /** Like `selectMoney`, for a NUMERIC/DECIMAL (SQLite TEXT) amount column. */
+    selectDecimalMoney<DB, TB extends keyof DB, RA extends ReferenceExpression<DB, TB>>(eb: ExpressionBuilder<DB, TB>, amount: RA, currency: ReferenceExpression<DB, TB>): RawBuilder<MoneyFor<ExtractTypeFromReferenceExpression<DB, TB, RA>, CurrencyInput>>;
+    selectDecimalMoney<DB, TB extends keyof DB, RA extends ReferenceExpression<DB, TB>, C extends string>(eb: ExpressionBuilder<DB, TB>, amount: RA, currency: FixedCurrency<C>): RawBuilder<MoneyFor<ExtractTypeFromReferenceExpression<DB, TB, RA>, C>>;
+    /**
+     * A condition comparing a stored amount with Money, currency and amount together. With a
+     * currency column, `=` and the ordering comparisons also require the same currency, and `<>`
+     * holds when either differs. With `fixed()`, Money in another currency throws.
+     *
+     *     .where((eb) => money.compareMoney(eb, 'amount_minor', 'currency', '>=', limit))
+     */
+    compareMoney<DB, TB extends keyof DB>(eb: ExpressionBuilder<DB, TB>, amount: ReferenceExpression<DB, TB>, currency: ReferenceExpression<DB, TB> | FixedCurrency<string>, operator: MoneyComparison, money: Money): Expression<SqlBool>;
+    /**
+     * Like `compareMoney`, for a NUMERIC/DECIMAL amount column of the given size (NUMERIC(19,4) by
+     * default). SQLite allows only `=` and `<>`, which compare the text, so they match only values
+     * written with `setDecimalMoney`.
+     */
+    compareDecimalMoney<DB, TB extends keyof DB>(eb: ExpressionBuilder<DB, TB>, amount: ReferenceExpression<DB, TB>, currency: ReferenceExpression<DB, TB> | FixedCurrency<string>, operator: MoneyComparison, money: Money, size?: DecimalColumnSize): Expression<SqlBool>;
+    /**
+     * The sum of an amount column as Money, or null over no rows. With a currency column, rows in
+     * more than one currency (or an amount without a currency) make the result throw when read, so
+     * group by the currency column to sum per currency.
+     *
+     *     .select((eb) => [money.sumMoney(eb, 'amount_minor', 'currency').as('total'), 'currency'])
+     *     .groupBy('currency')
+     */
+    sumMoney<DB, TB extends keyof DB>(eb: ExpressionBuilder<DB, TB>, amount: ReferenceExpression<DB, TB>, currency: ReferenceExpression<DB, TB>): RawBuilder<Money | null>;
+    sumMoney<DB, TB extends keyof DB, C extends string>(eb: ExpressionBuilder<DB, TB>, amount: ReferenceExpression<DB, TB>, currency: FixedCurrency<C>): RawBuilder<Money<C> | null>;
+    /** Like `sumMoney`, for a NUMERIC/DECIMAL amount column. Not available on SQLite (TEXT). */
+    sumDecimalMoney<DB, TB extends keyof DB>(eb: ExpressionBuilder<DB, TB>, amount: ReferenceExpression<DB, TB>, currency: ReferenceExpression<DB, TB>): RawBuilder<Money | null>;
+    sumDecimalMoney<DB, TB extends keyof DB, C extends string>(eb: ExpressionBuilder<DB, TB>, amount: ReferenceExpression<DB, TB>, currency: FixedCurrency<C>): RawBuilder<Money<C> | null>;
+}
+/** The read, filter and sum helpers for one SQL dialect. */
+export declare function moneyHelpers(dialect: MoneyDialect): MoneyHelpers;
+/**
+ * A Kysely plugin that turns the values built by `moneyHelpers` into Money, in every row and in
+ * JSON nested inside rows. It keeps no state between queries and doesn't touch the query, so it
+ * works with streams, prepared and repeated queries, and other plugins. For nested JSON that
+ * SQLite returns as text (`jsonArrayFrom`), put `ParseJSONResultsPlugin` before it.
+ */
+export declare class MoneyResultPlugin implements KyselyPlugin {
+    /** Leaves the query as it is. */
+    transformQuery(args: PluginTransformQueryArgs): RootOperationNode;
+    /** Converts the money values in every row. */
+    transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+}
+//# sourceMappingURL=kysely.d.ts.map

package/dist/kysely.d.ts.map

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