@arki/money 0.0.0-stage → 0.0.4

package/dist/drizzle.js

@@ -0,0 +1,77 @@
+/**
+ * Drizzle columns for Postgres that read and write `Money`. Optional: needs
+ * `drizzle-orm` 1.x installed.
+ *
+ * - `moneyMinor(name, { currency })` — a `bigint` column of minor units for one
+ *   fixed currency ↔ `Money<C>`. Best for sums in SQL.
+ * - `moneyDecimal(name, { currency, precision, scale })` — a `numeric` column ↔
+ *   `Money<C>`. Readable in SQL tools; holds more decimals than the currency.
+ * - `moneyJson(name)` — a `jsonb` column of `{ amount, currency }` ↔ `Money`
+ *   in any currency. For prices that vary by row.
+ *
+ * Every column declares a `:string`-style codec where Drizzle has one, so each
+ * driver (node-postgres, postgres.js, PGlite, Bun SQL) hands back text and no
+ * value ever passes through a float. Writing a `Money` in another currency, or
+ * with more decimals than the column holds, throws instead of storing a wrong
+ * value.
+ */
+import { customType } from 'drizzle-orm/pg-core';
+import { assertSameCurrency, resolveCurrency, toCurrency } from './currency.js';
+import { InvalidArgumentError } from './errors.js';
+import { quantize } from './internal/units.js';
+import { Money as MoneyClass } from './money.js';
+function requireConfig(config, column) {
+    if (config === undefined)
+        throw new InvalidArgumentError(`${column} needs a config with a currency`);
+    return config;
+}
+/** Minor units as text, at the column's scale. Throws if the value needs rounding. */
+export function moneyToMinorText(value, currency, scale) {
+    assertSameCurrency(value.currency, currency);
+    return String(quantize(value.units, value.scale, scale));
+}
+/** `bigint` column ↔ `Money<C>` in one fixed currency. */
+export function moneyMinor(name, config) {
+    const currency = toCurrency(config.currency);
+    const scale = config.scale ?? currency.scale;
+    return customType({
+        dataType: () => 'bigint',
+        codec: 'bigint:string',
+        toDriver: value => moneyToMinorText(value, currency, scale),
+        fromDriver: text => MoneyClass.fromMinor(String(text), currency, scale),
+    })(name, requireConfig(config, 'moneyMinor'));
+}
+/** `numeric(precision, scale)` column ↔ `Money<C>` in one fixed currency. */
+export function moneyDecimal(name, config) {
+    const currency = toCurrency(config.currency);
+    const scale = config.scale ?? currency.scale;
+    const precision = config.precision ?? 19;
+    return customType({
+        dataType: () => `numeric(${precision}, ${scale})`,
+        codec: 'numeric',
+        toDriver: value => {
+            assertSameCurrency(value.currency, currency);
+            return value.toScale(scale).toDecimalString();
+        },
+        fromDriver: text => MoneyClass.of(String(text), currency, { scale }),
+    })(name, requireConfig(config, 'moneyDecimal'));
+}
+/** `jsonb` column of `{ amount, currency }` ↔ `Money` in any currency. */
+export function moneyJson(name, config = {}) {
+    return customType({
+        dataType: () => 'jsonb',
+        toDriver: value => JSON.stringify(value.toJSON()),
+        fromDriver: stored => {
+            const parsed = typeof stored === 'string' ? JSON.parse(stored) : stored;
+            if (typeof parsed !== 'object' ||
+                parsed === null ||
+                !('currency' in parsed) ||
+                typeof parsed.currency !== 'string') {
+                throw new InvalidArgumentError('A moneyJson column holds { amount, currency }');
+            }
+            resolveCurrency(parsed.currency, config.currencies);
+            return MoneyClass.fromJSON(parsed, config.currencies);
+        },
+    })(name, config);
+}
+//# sourceMappingURL=drizzle.js.map

package/dist/drizzle.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Every failure this package raises on purpose extends `MathError` from
+ * `@arki/math`, so one `instanceof MathError` catches both libraries. The
+ * money-only failures also extend `MoneyError`. Wrong runtime types (a number
+ * where a `Money` was required, or `money + 1`) throw the built-in `TypeError`.
+ * Nothing here returns `NaN` or `null` as a hidden failure channel.
+ */
+import { MathError } from '@arki/math/errors';
+export { DivisionByZeroError, EmptyDataError, InvalidArgumentError, MathError, NumberFormatError, NumericRangeError, ResourceLimitError, RoundingNecessaryError, UnsupportedFeatureError, } from '@arki/math/errors';
+/** Base class of the failures that only money can have. */
+export declare class MoneyError extends MathError {
+}
+/** Two amounts in different currencies were combined or compared. */
+export declare class CurrencyMismatchError extends MoneyError {
+    /** Code of the currency on the left-hand side. */
+    readonly left: string;
+    /** Code of the currency on the right-hand side. */
+    readonly right: string;
+    constructor(left: string, right: string);
+}
+/** The code is not in the shipped ISO 4217 table and no custom currency was supplied for it. */
+export declare class UnknownCurrencyError extends MoneyError {
+    readonly code: string;
+    constructor(code: string);
+}
+/** No exchange rate is known for the pair, or a rate is invalid (zero, negative, conflicting). */
+export declare class ExchangeRateError extends MoneyError {
+}
+/** An amount cannot be expressed in a payment provider's units (fraction it does not accept, wrong step, unsupported currency). */
+export declare class ProviderAmountError extends MoneyError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,2DAA2D;AAC3D,qBAAa,UAAW,SAAQ,SAAS;CAAG;AAE5C,qEAAqE;AACrE,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAQtC;CACF;AAED,gGAAgG;AAChG,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAMvB;CACF;AAED,kGAAkG;AAClG,qBAAa,iBAAkB,SAAQ,UAAU;CAAG;AAEpD,mIAAmI;AACnI,qBAAa,mBAAoB,SAAQ,UAAU;CAAG"}

package/dist/errors.js

@@ -0,0 +1,42 @@
+/**
+ * Every failure this package raises on purpose extends `MathError` from
+ * `@arki/math`, so one `instanceof MathError` catches both libraries. The
+ * money-only failures also extend `MoneyError`. Wrong runtime types (a number
+ * where a `Money` was required, or `money + 1`) throw the built-in `TypeError`.
+ * Nothing here returns `NaN` or `null` as a hidden failure channel.
+ */
+import { MathError } from '@arki/math/errors';
+export { DivisionByZeroError, EmptyDataError, InvalidArgumentError, MathError, NumberFormatError, NumericRangeError, ResourceLimitError, RoundingNecessaryError, UnsupportedFeatureError, } from '@arki/math/errors';
+/** Base class of the failures that only money can have. */
+export class MoneyError extends MathError {
+}
+/** Two amounts in different currencies were combined or compared. */
+export class CurrencyMismatchError extends MoneyError {
+    /** Code of the currency on the left-hand side. */
+    left;
+    /** Code of the currency on the right-hand side. */
+    right;
+    constructor(left, right) {
+        super(left === right
+            ? `Cannot combine two different definitions of ${left}; they disagree on the number of decimals`
+            : `Cannot combine ${left} with ${right}`);
+        this.left = left;
+        this.right = right;
+    }
+}
+/** The code is not in the shipped ISO 4217 table and no custom currency was supplied for it. */
+export class UnknownCurrencyError extends MoneyError {
+    code;
+    constructor(code) {
+        super(`Unknown currency ${JSON.stringify(code)}. ISO 4217 codes are three upper-case letters; ` +
+            'for anything else create one with Currency.custom()');
+        this.code = code;
+    }
+}
+/** No exchange rate is known for the pair, or a rate is invalid (zero, negative, conflicting). */
+export class ExchangeRateError extends MoneyError {
+}
+/** An amount cannot be expressed in a payment provider's units (fraction it does not accept, wrong step, unsupported currency). */
+export class ProviderAmountError extends MoneyError {
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,2DAA2D;AAC3D,MAAM,OAAO,UAAW,SAAQ,SAAS;CAAG;AAE5C,qEAAqE;AACrE,MAAM,OAAO,qBAAsB,SAAQ,UAAU;IACnD,kDAAkD;IACzC,IAAI,CAAS;IACtB,mDAAmD;IAC1C,KAAK,CAAS;IAEvB,YAAY,IAAY,EAAE,KAAa;QACrC,KAAK,CACH,IAAI,KAAK,KAAK;YACZ,CAAC,CAAC,+CAA+C,IAAI,2CAA2C;YAChG,CAAC,CAAC,kBAAkB,IAAI,SAAS,KAAK,EAAE,CAC3C,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,gGAAgG;AAChG,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IACzC,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,KAAK,CACH,oBAAoB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,iDAAiD;YACvF,qDAAqD,CACxD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,kGAAkG;AAClG,MAAM,OAAO,iBAAkB,SAAQ,UAAU;CAAG;AAEpD,mIAAmI;AACnI,MAAM,OAAO,mBAAoB,SAAQ,UAAU;CAAG"}

package/dist/exact.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bridges to `@arki/math`'s exact types, for multi-step math that should
+ * round only once at the end:
+ *
+ * ```ts
+ * const share = toRational(price).times(ratio(1, 3)).plus(ratio(1, 7));
+ * Money.of(share, 'EUR', { rounding: 'halfEven' }); // Money.of reads Decimal and Rational directly
+ * ```
+ *
+ * Kept in its own entry point so the core never loads the `Decimal` and
+ * `Rational` classes.
+ */
+import type { Decimal } from '@arki/math/decimal';
+import type { Rational } from '@arki/math/rational';
+import type { Money } from './money.js';
+/** `19.99 EUR` → `Decimal('19.99')`, keeping the scale. */
+export declare function toDecimal(money: Money): Decimal;
+/** `19.99 EUR` → `1999/100`, reduced. */
+export declare function toRational(money: Money): Rational;
+//# sourceMappingURL=exact.d.ts.map

package/dist/exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact.d.ts","sourceRoot":"","sources":["../src/exact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE/C;AAED,yCAAyC;AACzC,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAEjD"}

package/dist/exact.js

@@ -0,0 +1,23 @@
+/**
+ * Bridges to `@arki/math`'s exact types, for multi-step math that should
+ * round only once at the end:
+ *
+ * ```ts
+ * const share = toRational(price).times(ratio(1, 3)).plus(ratio(1, 7));
+ * Money.of(share, 'EUR', { rounding: 'halfEven' }); // Money.of reads Decimal and Rational directly
+ * ```
+ *
+ * Kept in its own entry point so the core never loads the `Decimal` and
+ * `Rational` classes.
+ */
+import { decimal } from '@arki/math/decimal';
+import { ratio } from '@arki/math/rational';
+/** `19.99 EUR` → `Decimal('19.99')`, keeping the scale. */
+export function toDecimal(money) {
+    return decimal(money.toDecimalString());
+}
+/** `19.99 EUR` → `1999/100`, reduced. */
+export function toRational(money) {
+    return ratio(BigInt(money.units), 10n ** BigInt(money.scale));
+}
+//# sourceMappingURL=exact.js.map

package/dist/exact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact.js","sourceRoot":"","sources":["../src/exact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAI5C,2DAA2D;AAC3D,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,OAAO,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/dist/exchange.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Currency conversion with exact rates. A rate is a fraction, never a float:
+ * `1 EUR = 1.0832 USD` is stored as `677/625`. Inverse and cross
+ * rates stay exact, and a conversion rounds once, at the end.
+ *
+ * There is no network code. Fetch rates however you like (ECB, a bank, your
+ * own table), then build rates from them here.
+ *
+ * ```ts
+ * const converter = createConverter(ratesFrom({ base: 'EUR', rates: { USD: '1.0832', GBP: '0.8571' } }), {
+ *   inverse: true,
+ *   via: 'EUR',
+ * });
+ * converter.convert(money(100, 'USD'), 'GBP', { rounding: 'halfEven' }); // USD → EUR → GBP, rounded once
+ * ```
+ */
+import type { CurrencyLike } from './currency.js';
+import type { Units } from './internal/units.js';
+import type { Amount, MoneyOptions } from './money.js';
+import { Currency } from './currency.js';
+import { Money } from './money.js';
+/** An exact, directed rate: one unit of `base` buys `numerator / denominator` units of `quote`. */
+export declare class ExchangeRate<B extends string = string, Q extends string = string> {
+    readonly base: Currency<B>;
+    readonly quote: Currency<Q>;
+    /** Positive, in lowest terms with `denominator`. */
+    readonly numerator: Units;
+    /** Positive. */
+    readonly denominator: Units;
+    private constructor();
+    /** The reverse rate, exact: `EUR/USD 1.0832` → `USD/EUR 625/677`. */
+    inverse(): ExchangeRate<Q, B>;
+    /** Chains two rates, exact: `EUR→USD` then `USD→JPY` gives `EUR→JPY`. */
+    chain<R extends string>(next: ExchangeRate<Q, R>): ExchangeRate<B, R>;
+    /** `true` for the same pair and the same exact value. */
+    eq(other: ExchangeRate): boolean;
+    /** `'EUR/USD 1.0832'`, or `'USD/EUR 625/677'` when the rate has no finite decimal form. */
+    toString(): string;
+}
+/** `exchangeRate('EUR', 'USD', '1.0832')`: one euro buys 1.0832 dollars. The value must be positive. */
+export declare function exchangeRate<const B extends string, const Q extends string>(base: CurrencyLike<B>, quote: CurrencyLike<Q>, value: Amount): ExchangeRate<B, Q>;
+/** A table of rates from one base currency, as central banks publish them. */
+export type RateTable = {
+    base: CurrencyLike;
+    /** Quote code → units of that currency one unit of `base` buys. */
+    rates: Readonly<Record<string, Amount>>;
+    /** Custom currencies used as quote codes. */
+    currencies?: readonly Currency[];
+};
+/** `ratesFrom({ base: 'EUR', rates: { USD: '1.0832' } })` → `[EUR/USD 1.0832]`. */
+export declare function ratesFrom(table: RateTable): ExchangeRate[];
+/**
+ * Converts with one rate. The rate's base must be the amount's currency. The
+ * exact result is rounded once to the target scale (the quote currency's,
+ * or `options.scale`); an inexact result needs `options.rounding`.
+ */
+export declare function convert<B extends string, Q extends string>(amount: Money<B>, rate: ExchangeRate<NoInfer<B>, Q>, options?: MoneyOptions): Money<Q>;
+export type ConverterOptions = {
+    /** Also use `B→A` reversed when only `A→B` is known. Off by default: a bid rate reversed is not an ask rate. */
+    inverse?: boolean;
+    /** Route through this currency when no direct rate exists: `USD→GBP` as `USD→EUR→GBP`. */
+    via?: CurrencyLike;
+};
+/** A fixed set of rates with lookups. Build it with `createConverter`. Immutable. */
+export declare class Converter {
+    private readonly rates;
+    private readonly inverse;
+    private readonly via;
+    /** Resolved lookups, including misses. Rates never change, so the cache never goes stale. */
+    private readonly resolved;
+    constructor(rates: Iterable<ExchangeRate>, options?: ConverterOptions);
+    /** The exact rate used for `from → to`. Throws `ExchangeRateError` when none can be found. */
+    rate<const F extends string, const T extends string>(from: CurrencyLike<F>, to: CurrencyLike<T>): ExchangeRate<F, T>;
+    /** `true` when `rate(from, to)` would succeed. */
+    has(from: CurrencyLike, to: CurrencyLike): boolean;
+    /** Converts and rounds once. Same-currency conversion needs no rate and only changes the scale. */
+    convert<const T extends string>(amount: Money, to: CurrencyLike<T>, options?: MoneyOptions): Money<T>;
+    private resolve;
+    private lookup;
+    private lookupVia;
+}
+/** `createConverter(rates, { inverse: true, via: 'EUR' })`. */
+export declare function createConverter(rates: Iterable<ExchangeRate>, options?: ConverterOptions): Converter;
+//# sourceMappingURL=exchange.d.ts.map

package/dist/exchange.d.ts.map

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

package/dist/exchange.js

@@ -0,0 +1,215 @@
+/**
+ * Currency conversion with exact rates. A rate is a fraction, never a float:
+ * `1 EUR = 1.0832 USD` is stored as `677/625`. Inverse and cross
+ * rates stay exact, and a conversion rounds once, at the end.
+ *
+ * There is no network code. Fetch rates however you like (ECB, a bank, your
+ * own table), then build rates from them here.
+ *
+ * ```ts
+ * const converter = createConverter(ratesFrom({ base: 'EUR', rates: { USD: '1.0832', GBP: '0.8571' } }), {
+ *   inverse: true,
+ *   via: 'EUR',
+ * });
+ * converter.convert(money(100, 'USD'), 'GBP', { rounding: 'halfEven' }); // USD → EUR → GBP, rounded once
+ * ```
+ */
+import { assertSameCurrency, Currency, toCurrency } from './currency.js';
+import { ExchangeRateError } from './errors.js';
+import { divExact, gcdUnits, mulDiv, mulUnits, pow10, quantize } from './internal/units.js';
+import { Money, toFraction } from './money.js';
+const BRAND = Symbol('ExchangeRate');
+/** An exact, directed rate: one unit of `base` buys `numerator / denominator` units of `quote`. */
+export class ExchangeRate {
+    base;
+    quote;
+    /** Positive, in lowest terms with `denominator`. */
+    numerator;
+    /** Positive. */
+    denominator;
+    constructor(base, quote, numerator, denominator, brand) {
+        if (brand !== BRAND)
+            throw new TypeError('Use exchangeRate(base, quote, value) instead of new ExchangeRate()');
+        this.base = base;
+        this.quote = quote;
+        const divisor = gcdUnits(numerator, denominator);
+        this.numerator = divExact(numerator, divisor);
+        this.denominator = divExact(denominator, divisor);
+        Object.freeze(this);
+    }
+    /** @internal */
+    static create(base, quote, numerator, denominator) {
+        return new ExchangeRate(base, quote, numerator, denominator, BRAND);
+    }
+    /** The reverse rate, exact: `EUR/USD 1.0832` → `USD/EUR 625/677`. */
+    inverse() {
+        return new ExchangeRate(this.quote, this.base, this.denominator, this.numerator, BRAND);
+    }
+    /** Chains two rates, exact: `EUR→USD` then `USD→JPY` gives `EUR→JPY`. */
+    chain(next) {
+        assertSameCurrency(this.quote, next.base);
+        return new ExchangeRate(this.base, next.quote, mulUnits(this.numerator, next.numerator), mulUnits(this.denominator, next.denominator), BRAND);
+    }
+    /** `true` for the same pair and the same exact value. */
+    eq(other) {
+        return (this.base.eq(other.base) &&
+            this.quote.eq(other.quote) &&
+            this.numerator === other.numerator &&
+            this.denominator === other.denominator);
+    }
+    /** `'EUR/USD 1.0832'`, or `'USD/EUR 625/677'` when the rate has no finite decimal form. */
+    toString() {
+        return `${this.base.code}/${this.quote.code} ${rateText(this.numerator, this.denominator)}`;
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `ExchangeRate(${this.toString()})`;
+    }
+    [Symbol.for('Deno.customInspect')]() {
+        return `ExchangeRate(${this.toString()})`;
+    }
+}
+function rateText(numerator, denominator) {
+    // A fraction has a finite decimal form when its denominator has no prime factors other than 2 and 5.
+    let rest = BigInt(denominator);
+    let twos = 0;
+    let fives = 0;
+    while (rest % 2n === 0n) {
+        rest /= 2n;
+        twos++;
+    }
+    while (rest % 5n === 0n) {
+        rest /= 5n;
+        fives++;
+    }
+    if (rest !== 1n)
+        return `${String(numerator)}/${String(denominator)}`;
+    const scale = Math.max(twos, fives);
+    const digits = String(mulDiv(numerator, pow10(scale), denominator)).padStart(scale + 1, '0');
+    return scale === 0 ? digits : `${digits.slice(0, -scale)}.${digits.slice(-scale)}`;
+}
+/** `exchangeRate('EUR', 'USD', '1.0832')`: one euro buys 1.0832 dollars. The value must be positive. */
+export function exchangeRate(base, quote, value) {
+    const from = toCurrency(base);
+    const to = toCurrency(quote);
+    const [numerator, denominator] = toFraction(value);
+    if (!(numerator > 0))
+        throw new ExchangeRateError(`An exchange rate must be positive (${from.code}/${to.code})`);
+    if (from.eq(to) && numerator !== denominator) {
+        throw new ExchangeRateError(`A rate from ${from.code} to itself must be 1`);
+    }
+    return ExchangeRate.create(from, to, numerator, denominator);
+}
+/** `ratesFrom({ base: 'EUR', rates: { USD: '1.0832' } })` → `[EUR/USD 1.0832]`. */
+export function ratesFrom(table) {
+    const base = toCurrency(table.base);
+    return Object.entries(table.rates).map(([code, value]) => {
+        const quote = table.currencies?.find(currency => currency.code === code) ?? Currency.of(code);
+        return exchangeRate(base, quote, value);
+    });
+}
+/**
+ * Converts with one rate. The rate's base must be the amount's currency. The
+ * exact result is rounded once to the target scale (the quote currency's,
+ * or `options.scale`); an inexact result needs `options.rounding`.
+ */
+export function convert(amount, rate, options) {
+    assertSameCurrency(amount.currency, rate.base);
+    const scale = options?.scale ?? rate.quote.scale;
+    return Money.fromMinor(convertUnits(amount, rate, scale, options), rate.quote, scale);
+}
+/** The one rounding of a conversion: `units × rate × 10^(target − source scale)`. */
+function convertUnits(amount, rate, scale, options) {
+    return mulDiv(amount.units, mulUnits(rate.numerator, pow10(scale)), mulUnits(rate.denominator, pow10(amount.scale)), options?.rounding);
+}
+/** A fixed set of rates with lookups. Build it with `createConverter`. Immutable. */
+export class Converter {
+    rates;
+    inverse;
+    via;
+    /** Resolved lookups, including misses. Rates never change, so the cache never goes stale. */
+    resolved = new Map();
+    constructor(rates, options = {}) {
+        const map = new Map();
+        for (const rate of rates) {
+            if (!(rate instanceof ExchangeRate))
+                throw new TypeError('Expected ExchangeRate values');
+            const key = pairKey(rate.base, rate.quote);
+            const existing = map.get(key);
+            if (existing !== undefined && !existing.eq(rate)) {
+                throw new ExchangeRateError(`Two different rates for ${rate.base.code}/${rate.quote.code}`);
+            }
+            map.set(key, rate);
+        }
+        this.rates = map;
+        this.inverse = options.inverse === true;
+        this.via = options.via === undefined ? undefined : toCurrency(options.via);
+    }
+    /** The exact rate used for `from → to`. Throws `ExchangeRateError` when none can be found. */
+    rate(from, to) {
+        const a = toCurrency(from);
+        const b = toCurrency(to);
+        const found = this.resolve(a, b);
+        return ExchangeRate.create(a, b, found.numerator, found.denominator);
+    }
+    /** `true` when `rate(from, to)` would succeed. */
+    has(from, to) {
+        const a = toCurrency(from);
+        const b = toCurrency(to);
+        try {
+            this.resolve(a, b);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof ExchangeRateError)
+                return false;
+            throw error;
+        }
+    }
+    /** Converts and rounds once. Same-currency conversion needs no rate and only changes the scale. */
+    convert(amount, to, options) {
+        const target = toCurrency(to);
+        if (amount.currency.eq(target)) {
+            const scale = options?.scale ?? target.scale;
+            return Money.fromMinor(quantize(amount.units, amount.scale, scale, options?.rounding), target, scale);
+        }
+        const scale = options?.scale ?? target.scale;
+        return Money.fromMinor(convertUnits(amount, this.resolve(amount.currency, target), scale, options), target, scale);
+    }
+    resolve(from, to) {
+        const key = pairKey(from, to);
+        let found = this.resolved.get(key);
+        if (found === undefined) {
+            found = this.lookup(from, to) ?? this.lookupVia(from, to) ?? null;
+            this.resolved.set(key, found);
+        }
+        if (found === null)
+            throw new ExchangeRateError(`No exchange rate from ${from.code} to ${to.code}`);
+        return found;
+    }
+    lookup(from, to) {
+        if (from.eq(to))
+            return ExchangeRate.create(from, to, 1, 1);
+        const direct = this.rates.get(pairKey(from, to));
+        if (direct !== undefined)
+            return direct;
+        if (this.inverse)
+            return this.rates.get(pairKey(to, from))?.inverse();
+        return undefined;
+    }
+    lookupVia(from, to) {
+        const via = this.via;
+        if (via === undefined || via.eq(from) || via.eq(to))
+            return undefined;
+        const first = this.lookup(from, via);
+        const second = this.lookup(via, to);
+        return first === undefined || second === undefined ? undefined : first.chain(second);
+    }
+}
+function pairKey(from, to) {
+    return `${from.code}>${to.code}`;
+}
+/** `createConverter(rates, { inverse: true, via: 'EUR' })`. */
+export function createConverter(rates, options) {
+    return new Converter(rates, options);
+}
+//# sourceMappingURL=exchange.js.map

package/dist/exchange.js.map

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

package/dist/format.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Localized display through `Intl.NumberFormat`. The amount reaches `Intl` as
+ * exact decimal text, never as a float, so digits past 2^53 survive on runtimes
+ * that support string input (ES2023). Where a runtime lacks a feature you asked
+ * for (React Native's Hermes on iOS lacks some), the call throws
+ * `UnsupportedFeatureError` instead of quietly printing something else.
+ *
+ * Rounding for display is done exactly by this package, not by `Intl`, so it
+ * matches arithmetic rounding everywhere.
+ */
+import type { RoundingMode } from '@arki/math/rounding';
+import type { Money } from './money.js';
+export type FormatOptions = {
+    /** BCP 47 locale. Defaults to `'en-US'`; there is no global locale. */
+    locale?: string;
+    /** How to show the currency. Defaults to `'symbol'` for ISO currencies and `'code'` for custom ones. */
+    display?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+    /** `($5.00)` instead of `-$5.00` where the locale has an accounting style. */
+    accounting?: boolean;
+    signDisplay?: 'auto' | 'always' | 'exceptZero' | 'negative' | 'never';
+    /** Defaults to `true`. */
+    useGrouping?: boolean;
+    /** Decimals to show. Defaults to the amount's scale, so nothing is hidden. */
+    fractionDigits?: number;
+    /** Needed when `fractionDigits` drops non-zero digits. */
+    rounding?: RoundingMode;
+};
+export type MoneyFormatter = {
+    format(money: Money): string;
+    formatToParts(money: Money): Intl.NumberFormatPart[];
+};
+/**
+ * `formatMoney(money('1234.5', 'EUR'), { locale: 'de-DE' })` → `'1.234,50 €'`.
+ * Custom currencies print the number and the code: `'0.00012000 BTC'`.
+ */
+export declare function formatMoney(money: Money, options?: FormatOptions): string;
+/** The parts `Intl` produces (currency, integer, group, decimal, fraction, ...), for custom rendering. */
+export declare function formatMoneyToParts(money: Money, options?: FormatOptions): Intl.NumberFormatPart[];
+/** Binds options once for loops: `const eur = createMoneyFormatter({ locale: 'de-DE' }); eur.format(price)`. */
+export declare function createMoneyFormatter(options?: FormatOptions): MoneyFormatter;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,MAAM,aAAa,GAAG;IAC1B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,OAAO,CAAC,EAAE,QAAQ,GAAG,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;IACtD,8EAA8E;IAC9E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;IACtE,0BAA0B;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IAC7B,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;CACtD,CAAC;AAmFF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAI7E;AAED,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI,CAAC,gBAAgB,EAAE,CASrG;AAED,gHAAgH;AAChH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,cAAc,CAMhF"}