@arki/money 0.0.0-stage → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARKI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# @arki/money
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Exact, fast money for every JavaScript runtime.
+
+- **Exact.** Amounts are whole numbers of units: `19.99 EUR` is `1999` units at 2 decimals. Nothing rounds unless you pass a rounding mode.
+- **Fast.** Units are a plain `number` up to 2^53 and a `bigint` only beyond that. Adding two amounts takes about 4 ns, against 350–550 ns in currency.js and dinero.js.
+- **Safe types.** `Money<'EUR'>` cannot be added to `Money<'USD'>`. The compiler stops it, and the runtime throws `CurrencyMismatchError` too.
+- **Same answer everywhere.** The ISO 4217 table ships with the package (178 currencies, published 2026-09-17). `Intl` is only used for display, so a value has the same decimals on every device.
+- **Runs everywhere.** Pure ESM with web-standard globals only. Tested on Node, Bun, Deno and Chromium; built for React Native (Hermes).
+
+```ts
+import { factor, money, sum } from '@arki/money';
+
+const price = money('19.99', 'EUR');
+const total = sum([price, money('5.01', 'EUR')]); // 25.00 EUR
+price.times(3); // 59.97 EUR
+price.times('1.19'); // throws RoundingNecessaryError: 23.7881 does not fit
+price.times('1.19', 'halfEven'); // 23.79 EUR
+money(100, 'EUR').allocate([1, 1, 1]); // [33.34, 33.33, 33.33] — adds back to 100.00
+money(1, 'EUR').plus(money(1, 'USD')); // compile error, and CurrencyMismatchError at run time
+```
+
+## Creating money
+
+| Call                                                | Result                                                                                |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `money('19.99', 'EUR')`                             | From major units. Strings are the safest input.                                       |
+| `money(19.99, 'EUR')`                               | A number is read as written. `0.1 + 0.2` arrives as `0.30000000000000004` and throws. |
+| `money('1.005', 'EUR', { rounding: 'halfEven' })`   | Extra digits need a rounding mode.                                                    |
+| `money('0.1234', 'EUR', { scale: 4 })`              | Keep more decimals, for unit prices.                                                  |
+| `Money.fromMinor(1999, 'EUR')`                      | From cents. Also takes a `bigint` or an integer string, as databases return `BIGINT`. |
+| `Money.zero('EUR')`                                 | Zero.                                                                                 |
+| `Money.parse('19.99 EUR')` / `Money.fromJSON(json)` | Reads what `toString()` / `toJSON()` write.                                           |
+| `Money.of(m, 'EUR')`                                | Checks a `Money<string>` is EUR and narrows its type to `Money<'EUR'>`.               |
+
+`money()` also accepts a `Decimal` or a `Rational` from `@arki/math`.
+
+## Rounding
+
+Rounding modes: `up`, `down`, `ceiling`, `floor`, `halfUp`, `halfDown`, `halfEven`, `unnecessary`.
+
+There is no default mode. `times`, `dividedBy`, `percentage`, `toScale` and `roundToStep` return the exact result when it fits, and throw `RoundingNecessaryError` when it does not and no mode was given. `plus`, `minus`, `allocate`, `split` and `sum` are always exact.
+
+Cash rounding is a step, because it is set by each country's law, not by the currency:
+
+```ts
+money('1.025', 'CHF', { scale: 3 }).roundToStep('0.05', 'halfUp'); // 1.050 CHF
+```
+
+For a calculation with several steps, round once at the end through `@arki/math`:
+
+```ts
+import { ratio } from '@arki/math/rational';
+import { toRational } from '@arki/money/exact';
+
+const share = toRational(price).times(ratio(1, 3)).plus(ratio(1, 7));
+money(share, 'EUR', { rounding: 'halfEven' });
+```
+
+## Splitting
+
+`allocate(ratios, { remainder })` and `split(parts, { remainder })` always add back to the whole. Leftover units go to the parts whose exact share lost the most (`'largest'`, the default), or from the start (`'first'`) or end (`'last'`). A zero ratio never receives a unit. Ratios may be decimals: `allocate(['0.5', '0.25', '0.25'])`.
+
+## Currencies
+
+```ts
+import { Currency } from '@arki/money';
+
+Currency.of('EUR'); // { code: 'EUR', numeric: '978', scale: 2, iso: true }
+Currency.fromNumeric('978'); // EUR
+Currency.of('ZZZ'); // throws UnknownCurrencyError (Intl would accept it)
+const btc = Currency.custom({ code: 'BTC', scale: 8 });
+money('0.00012', btc); // 0.00012000 BTC
+```
+
+Custom currencies are not registered globally. Keep the object and pass it where you would pass a code. Codes that ISO defines without decimals (gold `XAU`, test code `XTS`) use 0.
+
+## Output
+
+| Call                                                     | Result                                                  |
+| -------------------------------------------------------- | ------------------------------------------------------- |
+| `toString()`                                             | `'19.99 EUR'`, locale-free                              |
+| `toJSON()`                                               | `{ amount: '19.99', currency: 'EUR' }`                  |
+| `toDecimalString()`                                      | `'19.99'`, for `NUMERIC` columns                        |
+| `toMinorUnits()` / `toMinorBigInt()` / `toMinorNumber()` | `1999`, for `BIGINT` columns and payment APIs           |
+| `toNumber()`                                             | Nearest float, for charts only                          |
+| `+price`                                                 | Throws. A `Money` never turns into a float by accident. |
+
+```ts
+import { createMoneyFormatter, formatMoney } from '@arki/money/format';
+
+formatMoney(money('1234.5', 'EUR'), { locale: 'de-DE' }); // '1.234,50 €'
+formatMoney(money(-5, 'USD'), { accounting: true }); // '($5.00)'
+const de = createMoneyFormatter({ locale: 'de-DE' }); // binds options once, for loops
+```
+
+Formatting passes the amount to `Intl` as exact text, so digits past 2^53 survive. If the runtime lacks a feature you asked for (Hermes on iOS lacks some), it throws `UnsupportedFeatureError` instead of printing something else.
+
+## Reading what people type
+
+```ts
+import { createMoneyParser, parseMoney } from '@arki/money/parse';
+
+parseMoney('1.234,56 €', 'EUR', { locale: 'de-DE' }); // 1234.56 EUR
+parseMoney('₹1,23,456.78', 'INR', { locale: 'en-IN' }); // 123456.78 INR
+parseMoney('($1,234.56)', 'USD'); // -1234.56 USD
+parseMoney('$10', 'CAD'); // 10.00 CAD — you say which currency, so '$' is never guessed
+parseMoney('1,23,4', 'USD'); // throws NumberFormatError: grouping does not match the locale
+
+const form = createMoneyParser('EUR', { locale: 'de-DE' }); // reads the locale once
+form.tryParse('12,505 €'); // undefined — too many decimals, for form validation
+```
+
+Separators, digits, minus sign and currency symbols come from `Intl` for the locale. Parsing is strict: wrong grouping, the other locale's decimal separator, two signs, mixed digit scripts or a different currency's symbol throw instead of being guessed. Text without grouping (`'1234.5'`) is always accepted. On runtimes without `formatToParts` (Hermes on iOS), pass `symbols: { decimal: ',', group: '.' }` instead of a locale.
+
+## Converting currencies
+
+```ts
+import { convert, createConverter, exchangeRate, ratesFrom } from '@arki/money/exchange';
+
+const rates = ratesFrom({ base: 'EUR', rates: { USD: '1.0832', GBP: '0.8571' } });
+const fx = createConverter(rates, { inverse: true, via: 'EUR' });
+fx.convert(money('1234.56', 'USD'), 'GBP', { rounding: 'halfEven' }); // 976.87 GBP, USD → EUR → GBP rounded once
+fx.rate('USD', 'GBP').toString(); // 'USD/GBP 8571/10832'
+
+convert(money(100, 'EUR'), exchangeRate('EUR', 'USD', '1.0832')); // 108.32 USD
+```
+
+Rates are exact fractions, never floats, so inverse and cross rates add no error. A conversion rounds once, at the end; converting in two rounded steps above would give 976.86. Reversed rates (`inverse`) and routing through a base currency (`via`) are opt-in, because a bid rate reversed is not an ask rate. There is no network code: fetch rates from wherever you trust and pass them in.
+
+## Payment providers
+
+```ts
+import { fromStripeAmount, toStripe, toStripeAmount } from '@arki/money/stripe';
+
+toStripe(money('10.99', 'EUR')); // { amount: 1099, currency: 'eur' }
+toStripeAmount(money(5, 'ISK')); // 500 — Stripe sends ISK with two decimals that are always 00
+toStripeAmount(money('10.50', 'MGA')); // throws ProviderAmountError — MGA is zero-decimal at Stripe
+toStripeAmount(money('10.45', 'HUF'), 'payout'); // throws — HUF payouts must be whole forints
+fromStripeAmount(1099, 'usd'); // 10.99 USD
+```
+
+Rules come from docs.stripe.com/currencies, checked on 2026-10-12 (`STRIPE_RULES_VERSION`). Stripe documents no rule for currencies with 3 or 4 decimals, so those throw instead of being guessed. For other providers, describe their units with `toProviderUnits(money, { scale, step })` and `fromProviderUnits` from `@arki/money/provider`.
+
+## Exact steps and several currencies
+
+```ts
+import { MoneyBag } from '@arki/money/bag';
+import { RationalMoney } from '@arki/money/rational';
+
+const third = RationalMoney.of(100, 'EUR').dividedBy(3); // '100/3 EUR', no rounding yet
+third.plus(third).plus(third).toMoney(); // 100.00 EUR — three rounded thirds would give 99.99
+third.times('1.19').toMoney({ rounding: 'halfEven' }); // 39.67 EUR, rounded once
+
+const wallet = MoneyBag.of(money('1.07', 'USD'), money('1.06', 'GBP')); // two balances, never one fake total
+wallet.convert(fx, 'EUR', { rounding: 'halfEven' }); // 2.22 EUR; rounding each balance first gives 2.23
+```
+
+A `RationalMoney` is an exact fraction of major units that keeps its currency, so EUR and USD still cannot mix halfway through a calculation. A `MoneyBag` holds one exact balance per currency and drops zeros.
+
+## Validation and databases
+
+```ts
+import { anyMoneySchema, moneyInputSchema, moneySchema } from '@arki/money/zod';
+
+const order = z.object({ total: moneySchema('EUR', { min: money(0, 'EUR') }) });
+order.parse({ total: { amount: '19.99', currency: 'EUR' } }).total; // Money<'EUR'>
+moneyInputSchema('EUR', { locale: 'de-DE' }).parse('1.234,56 €'); // form field
+```
+
+```ts
+import { moneyDecimal, moneyJson, moneyMinor } from '@arki/money/drizzle/pg'; // or /drizzle/mysql, /drizzle/sqlite
+
+const prices = pgTable('prices', {
+  total: moneyMinor('total', { currency: 'EUR' }), // bigint of cents ↔ Money<'EUR'>
+  unit: moneyDecimal('unit', { currency: 'EUR', scale: 4 }), // numeric(19, 4)
+  price: moneyJson('price'), // jsonb { amount, currency } ↔ Money in any currency
+});
+```
+
+| Column         | Postgres        | MySQL / MariaDB | SQLite                               |
+| -------------- | --------------- | --------------- | ------------------------------------ |
+| `moneyMinor`   | `bigint`        | `bigint`        | `integer`                            |
+| `moneyDecimal` | `numeric(p, s)` | `decimal(p, s)` | `text` (SQLite has no exact decimal) |
+| `moneyJson`    | `jsonb`         | `json`          | `text`                               |
+
+SQLite drivers usually return numbers, which are exact up to 2^53 minor units. A bigger stored amount throws on read instead of turning into a wrong value; switch the driver to big integers to read it (libSQL `intMode: 'bigint'`, better-sqlite3 `safeIntegers()`).
+
+The schemas take the JSON shape as input, so tRPC and oRPC clients infer what to send. The columns read text from every driver, so no value passes through a float, and writing another currency or a value that needs rounding throws. `zod` (4.x) and `drizzle-orm` (1.x) are optional peer dependencies, used only by their subpaths.
+
+## Errors
+
+Every deliberate failure extends `MathError` from `@arki/math`, so one `instanceof` catches both libraries. Money-only errors extend `MoneyError`: `CurrencyMismatchError`, `UnknownCurrencyError`, `ExchangeRateError`, `ProviderAmountError`. Shared ones: `RoundingNecessaryError`, `DivisionByZeroError`, `InvalidArgumentError`, `NumberFormatError`, `NumericRangeError`, `ResourceLimitError`, `EmptyDataError`, `UnsupportedFeatureError`.
+
+## Entry points
+
+| Import                                        | Contents                                                                       |
+| --------------------------------------------- | ------------------------------------------------------------------------------ |
+| `@arki/money`                                 | `Money`, `money`, `Currency`, `factor`, `sum`, `average`, `min`, `max`, errors |
+| `@arki/money/currency`                        | `Currency` alone                                                               |
+| `@arki/money/format`                          | `formatMoney`, `formatMoneyToParts`, `createMoneyFormatter`                    |
+| `@arki/money/exact`                           | `toDecimal`, `toRational` bridges to `@arki/math`                              |
+| `@arki/money/errors`                          | Error classes                                                                  |
+| `@arki/money/parse`                           | `parseMoney`, `createMoneyParser`                                              |
+| `@arki/money/exchange`                        | `exchangeRate`, `ratesFrom`, `convert`, `createConverter`, `Converter`         |
+| `@arki/money/provider`                        | `toProviderUnits`, `fromProviderUnits`                                         |
+| `@arki/money/rational`                        | `RationalMoney`, `isRationalMoney`                                             |
+| `@arki/money/bag`                             | `MoneyBag`                                                                     |
+| `@arki/money/zod`                             | `moneySchema`, `anyMoneySchema`, `moneyInputSchema`, `currencyCodeSchema`      |
+| `@arki/money/drizzle/pg`, `/mysql`, `/sqlite` | `moneyMinor`, `moneyDecimal`, `moneyJson`                                      |
+| `@arki/money/stripe`                          | `toStripe`, `toStripeAmount`, `fromStripeAmount`, `stripeRule`                 |
+
+## Performance
+
+`bun run bench` compares against dinero.js v1, currency.js, big.js and the old `@arki/math/money`. Node 22, Apple Silicon, ns/op:
+
+| Operation                                   | @arki/money | dinero.js v1 | currency.js | big.js |
+| ------------------------------------------- | ----------: | -----------: | ----------: | -----: |
+| add                                         |         3.5 |          457 |         470 |     67 |
+| × 1.0825, round half-even (prepared factor) |          37 |          680 |         347 |    267 |
+| allocate into 3                             |         172 |         1244 |        1045 |      — |
+| compare                                     |         5.7 |         11.8 |           — |   13.6 |
+| format en-US                                |         557 |        20725 |         674 |      — |
+
+Amounts past 2^53 switch to `bigint` and stay exact; adding them costs about 29 ns. Converting with a cached rate takes about 170 ns, parsing German input about 1.1 µs, and `toStripeAmount` about 80 ns.
+
+## Size
+
+`bun run size` bundles each entry point as an app would (minified, gzipped, `@arki/math` included) and fails past its budget. The core (`Money`, `Currency` with the full ISO table, errors) is 6.3 KB. Parsing adds 0.9 KB, conversion 0.6 KB, Stripe 0.1 KB, and `RationalMoney` 3.2 KB (the exact `Rational` type from `@arki/math`).
+
+## Runtime support
+
+Node 20+, Bun, Deno, modern browsers and React Native on Hermes V1 (React Native 0.86). `bun run test:runtimes` runs the same checks on all five; the Hermes leg needs a `hermes` binary (`HERMES_BIN`, build steps in `scripts/smoke-hermes.mjs`) and says so loudly when it is missing.
+
+On Hermes for Apple platforms, `Intl.NumberFormat` has no `formatToParts` and formats number strings through a float. So `parseMoney` with a `locale` throws `UnsupportedFeatureError` (pass `symbols` instead), `formatMoneyToParts` throws, and `formatMoney` is exact up to 15 significant digits and throws beyond. Arithmetic, allocation, conversion, Stripe units and JSON work everywhere.
+
+## License
+
+MIT

package/dist/bag.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A wallet of several currencies: `10 EUR + 5 USD` stays two balances. It never
+ * pretends mixed amounts have one total until you convert it, and then it
+ * converts each balance exactly and rounds once.
+ *
+ * ```ts
+ * const cart = MoneyBag.of(money(10, 'EUR'), money(5, 'USD')).plus(money('2.50', 'EUR'));
+ * cart.get('EUR').toString();                                   // '25/2 EUR'
+ * cart.convert(fx, 'EUR', { rounding: 'halfEven' });            // one EUR total
+ * ```
+ */
+import type { Currency, CurrencyLike } from './currency.js';
+import type { Converter } from './exchange.js';
+import type { MoneyJSON, MoneyOptions } from './money.js';
+import type { ExactMoney } from './rational.js';
+import { Money } from './money.js';
+import { RationalMoney } from './rational.js';
+/** An immutable set of balances, at most one per currency. Zero balances are dropped. */
+export declare class MoneyBag {
+    private readonly balances;
+    private constructor();
+    static empty(): MoneyBag;
+    /** `MoneyBag.of(money(10, 'EUR'), money(5, 'USD'))`. */
+    static of(...items: (ExactMoney | MoneyBag)[]): MoneyBag;
+    /** Adds amounts or whole bags. Returns a new bag. */
+    plus(...items: (ExactMoney | MoneyBag)[]): MoneyBag;
+    /** Subtracts amounts or whole bags. Balances may go negative. Returns a new bag. */
+    minus(...items: (ExactMoney | MoneyBag)[]): MoneyBag;
+    /** The exact balance in one currency; zero when the bag holds none. */
+    get<const C extends string>(currency: CurrencyLike<C>): RationalMoney<C>;
+    /** The currencies with a non-zero balance, sorted by code. */
+    currencies(): Currency[];
+    /** The non-zero balances, sorted by currency code. */
+    entries(): RationalMoney[];
+    /** `true` when every balance is zero. */
+    isZero(): boolean;
+    /**
+     * One total in `currency`: each balance is converted exactly, the results are
+     * added, and the sum is rounded once. Missing rates throw `ExchangeRateError`.
+     */
+    convert<const C extends string>(converter: Converter, currency: CurrencyLike<C>, options?: MoneyOptions): Money<C>;
+    /** `[{ amount: '25/2', currency: 'EUR' }, ...]`, sorted by currency code. */
+    toJSON(): MoneyJSON[];
+    /** `'12.5 EUR + 5 USD'`-style text with exact fractions: `'25/2 EUR + 5 USD'`. Empty bag: `'0'`. */
+    toString(): string;
+    private combine;
+}
+//# sourceMappingURL=bag.d.ts.map

package/dist/bag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bag.d.ts","sourceRoot":"","sources":["../src/bag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAQ9C,yFAAyF;AACzF,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAE9D,OAAO,eAGN;IAED,MAAM,CAAC,KAAK,IAAI,QAAQ,CAEvB;IAED,wDAAwD;IACxD,MAAM,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,UAAU,GAAG,QAAQ,CAAC,EAAE,GAAG,QAAQ,CAEvD;IAED,qDAAqD;IACrD,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,UAAU,GAAG,QAAQ,CAAC,EAAE,GAAG,QAAQ,CAElD;IAED,oFAAoF;IACpF,KAAK,CAAC,GAAG,KAAK,EAAE,CAAC,UAAU,GAAG,QAAQ,CAAC,EAAE,GAAG,QAAQ,CAEnD;IAED,uEAAuE;IACvE,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAMvE;IAED,8DAA8D;IAC9D,UAAU,IAAI,QAAQ,EAAE,CAEvB;IAED,sDAAsD;IACtD,OAAO,IAAI,aAAa,EAAE,CAEzB;IAED,yCAAyC;IACzC,MAAM,IAAI,OAAO,CAEhB;IAED;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAQjH;IAED,6EAA6E;IAC7E,MAAM,IAAI,SAAS,EAAE,CAEpB;IAED,oGAAoG;IACpG,QAAQ,IAAI,MAAM,CAGjB;IAUD,OAAO,CAAC,OAAO;CAchB"}

package/dist/bag.js

@@ -0,0 +1,110 @@
+/**
+ * A wallet of several currencies: `10 EUR + 5 USD` stays two balances. It never
+ * pretends mixed amounts have one total until you convert it, and then it
+ * converts each balance exactly and rounds once.
+ *
+ * ```ts
+ * const cart = MoneyBag.of(money(10, 'EUR'), money(5, 'USD')).plus(money('2.50', 'EUR'));
+ * cart.get('EUR').toString();                                   // '25/2 EUR'
+ * cart.convert(fx, 'EUR', { rounding: 'halfEven' });            // one EUR total
+ * ```
+ */
+import { ratio } from '@arki/math/rational';
+import { assertSameCurrency, toCurrency } from './currency.js';
+import { Money } from './money.js';
+import { RationalMoney } from './rational.js';
+const BRAND = Symbol('MoneyBag');
+function exact(value) {
+    return value instanceof RationalMoney ? value : RationalMoney.from(value);
+}
+/** An immutable set of balances, at most one per currency. Zero balances are dropped. */
+export class MoneyBag {
+    balances;
+    constructor(balances, brand) {
+        if (brand !== BRAND)
+            throw new TypeError('Use MoneyBag.of() instead of new MoneyBag()');
+        this.balances = balances;
+    }
+    static empty() {
+        return new MoneyBag(new Map(), BRAND);
+    }
+    /** `MoneyBag.of(money(10, 'EUR'), money(5, 'USD'))`. */
+    static of(...items) {
+        return MoneyBag.empty().plus(...items);
+    }
+    /** Adds amounts or whole bags. Returns a new bag. */
+    plus(...items) {
+        return this.combine(items, false);
+    }
+    /** Subtracts amounts or whole bags. Balances may go negative. Returns a new bag. */
+    minus(...items) {
+        return this.combine(items, true);
+    }
+    /** The exact balance in one currency; zero when the bag holds none. */
+    get(currency) {
+        const target = toCurrency(currency);
+        const found = this.balances.get(target.code);
+        if (found === undefined)
+            return RationalMoney.zero(target);
+        assertSameCurrency(found.currency, target);
+        return RationalMoney.create(found.amount, target);
+    }
+    /** The currencies with a non-zero balance, sorted by code. */
+    currencies() {
+        return this.entries().map(entry => entry.currency);
+    }
+    /** The non-zero balances, sorted by currency code. */
+    entries() {
+        return [...this.balances.values()].sort((a, b) => (a.currency.code < b.currency.code ? -1 : 1));
+    }
+    /** `true` when every balance is zero. */
+    isZero() {
+        return this.balances.size === 0;
+    }
+    /**
+     * One total in `currency`: each balance is converted exactly, the results are
+     * added, and the sum is rounded once. Missing rates throw `ExchangeRateError`.
+     */
+    convert(converter, currency, options) {
+        const target = toCurrency(currency);
+        let total = ratio(0);
+        for (const balance of this.balances.values()) {
+            const rate = converter.rate(balance.currency, target);
+            total = total.plus(balance.amount.times(ratio(BigInt(rate.numerator), BigInt(rate.denominator))));
+        }
+        return Money.of(total, target, options);
+    }
+    /** `[{ amount: '25/2', currency: 'EUR' }, ...]`, sorted by currency code. */
+    toJSON() {
+        return this.entries().map(entry => entry.toJSON());
+    }
+    /** `'12.5 EUR + 5 USD'`-style text with exact fractions: `'25/2 EUR + 5 USD'`. Empty bag: `'0'`. */
+    toString() {
+        const entries = this.entries();
+        return entries.length === 0 ? '0' : entries.map(String).join(' + ');
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `MoneyBag(${this.toString()})`;
+    }
+    [Symbol.for('Deno.customInspect')]() {
+        return `MoneyBag(${this.toString()})`;
+    }
+    combine(items, subtract) {
+        const next = new Map(this.balances);
+        const add = (value) => {
+            const code = value.currency.code;
+            const current = next.get(code);
+            const delta = subtract ? value.negated() : value;
+            next.set(code, current === undefined ? delta : current.plus(delta));
+        };
+        for (const item of items) {
+            if (item instanceof MoneyBag)
+                for (const balance of item.balances.values())
+                    add(balance);
+            else
+                add(exact(item));
+        }
+        return new MoneyBag(new Map([...next].filter(([, balance]) => !balance.isZero())), BRAND);
+    }
+}
+//# sourceMappingURL=bag.js.map

package/dist/bag.js.map

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

package/dist/currency.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Currencies. The ISO 4217 list ships with the package, so a currency's number
+ * of decimals is the same on every runtime and device. `Intl` is only used for
+ * display (see `@arki/money/format`); it accepts made-up codes such as `ZZZ`
+ * and its decimals can differ from ISO, so it never decides arithmetic.
+ *
+ * `Currency.of('EUR')` returns the same object every time, so comparing two
+ * currencies is a pointer check on the hot path.
+ */
+export { ISO_4217_VERSION } from './data/iso4217.js';
+/** A currency, or the code of an ISO 4217 currency. */
+export type CurrencyLike<C extends string = string> = C | Currency<C>;
+/** What `Currency.custom` needs. */
+export type CurrencyDefinition<C extends string = string> = {
+    /** Letters, digits and `. _ : -`, up to 32 characters, not an ISO 4217 code: `'BTC'`, `'crypto:ETH'`, `'points'`. */
+    code: C;
+    /** Number of decimals, 0–100: 8 for BTC, 18 for ETH, 0 for loyalty points. */
+    scale: number;
+    /** Optional three-digit numeric code. */
+    numeric?: string;
+};
+/** An immutable currency: its code, its ISO numeric code and its number of decimals. */
+export declare class Currency<C extends string = string> {
+    /** `'EUR'`. */
+    readonly code: C;
+    /** Three-digit ISO numeric code as a string, so `'008'` keeps its zeros. `undefined` for most custom currencies. */
+    readonly numeric: string | undefined;
+    /** Number of decimals: 2 for EUR, 0 for JPY, 3 for KWD. ISO codes without minor units (XAU, XTS) use 0. */
+    readonly scale: number;
+    /** `true` for a currency from the shipped ISO 4217 table. */
+    readonly iso: boolean;
+    private constructor();
+    /**
+     * The ISO 4217 currency with this upper-case code: `Currency.of('EUR')`.
+     * Throws `UnknownCurrencyError` for anything not in the table, including `'eur'`.
+     */
+    static of<const C extends string>(code: C): Currency<C>;
+    /** The ISO 4217 currency with this numeric code: `Currency.fromNumeric('978')` or `(978)` → EUR. */
+    static fromNumeric(numeric: string | number): Currency;
+    /**
+     * A currency that is not in ISO 4217: crypto, loyalty points, a withdrawn
+     * currency you still hold data in. It is not registered anywhere; keep the
+     * object and pass it where you would pass a code. Two custom currencies with
+     * the same code and scale are treated as the same currency.
+     */
+    static custom<const C extends string>(definition: CurrencyDefinition<C>): Currency<C>;
+    /** `true` when `code` is in the shipped ISO 4217 table. */
+    static isKnown(code: string): boolean;
+    /** Every ISO 4217 code in the shipped table, sorted. */
+    static codes(): string[];
+    /** Same code and same scale. */
+    eq(other: Currency): boolean;
+    toString(): C;
+    toJSON(): C;
+    /** Decodes the packed table on first use. */
+    private static table;
+}
+/** Accepts a `Currency` or an ISO code. */
+export declare function toCurrency<C extends string>(currency: CurrencyLike<C>): Currency<C>;
+/** Finds a currency by code among `custom`, then in the ISO table. */
+export declare function resolveCurrency(code: string, custom: readonly Currency[] | undefined): Currency;
+/** Throws `CurrencyMismatchError` unless the two are the same currency. */
+export declare function assertSameCurrency(a: Currency, b: Currency): void;
+//# sourceMappingURL=currency.d.ts.map

package/dist/currency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../src/currency.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAQrD,uDAAuD;AACvD,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEtE,oCAAoC;AACpC,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC1D,qHAAqH;IACrH,IAAI,EAAE,CAAC,CAAC;IACR,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wFAAwF;AACxF,qBAAa,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC7C,eAAe;IACf,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,oHAAoH;IACpH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,2GAA2G;IAC3G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IAEtB,OAAO,eAON;IAED;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAItD;IAED,oGAAoG;IACpG,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAWrD;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAiBpF;IAED,2DAA2D;IAC3D,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpC;IAED,wDAAwD;IACxD,MAAM,CAAC,KAAK,IAAI,MAAM,EAAE,CAEvB;IAED,gCAAgC;IAChC,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAE3B;IAED,QAAQ,IAAI,CAAC,CAEZ;IAED,MAAM,IAAI,CAAC,CAEV;IAUD,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAAC,KAAK;CAWrB;AAMD,2CAA2C;AAC3C,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAInF;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,GAAG,QAAQ,CAK/F;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAEjE"}