@vielzeug/coins 1.0.5 → 2.0.0

package/README.md

@@ -1,262 +1,90 @@
 # @vielzeug/coins
 
-> Zero-dependency TypeScript utilities for precise monetary arithmetic
+Exact monetary arithmetic for TypeScript. Coins stores bigint minor units, uses explicit currency definitions, and accepts decimal strings at every exact-input boundary.
 
-Bigint-based money creation, arithmetic, allocation, formatting, exchange rate conversion, and serialization — with no floating-point rounding errors.
-
-## Why Coins?
-
-Float arithmetic silently loses precision:
-
-```ts
-// number (float)
-10.1 + 10.2; // 20.299999999999997
-
-// @vielzeug/coins (bigint)
-import { add, money } from '@vielzeug/coins';
-add(money('10.10', 'USD'), money('10.20', 'USD')); // { amount: 2030n, currency: 'USD' }  — exact
-```
-
-Coins stores every value as bigint **minor units** (cents for USD, whole units for JPY, fils for KWD), so arithmetic and allocation are always lossless.
-
-## Installation
+## Install
 
 ```sh
 pnpm add @vielzeug/coins
 ```
 
-## Quick Start
-
-```ts
-import { add, allocate, exchange, format, money, multiply } from '@vielzeug/coins';
-import type { ExchangeRate, Money } from '@vielzeug/coins';
-
-// Create money from a decimal string (lossless) or bigint minor units
-const price: Money = money('19.99', 'USD'); // { amount: 1999n, currency: 'USD' }
-const tax: Money = money('1.60', 'USD');
-const total: Money = add(price, tax); // { amount: 3559n, currency: 'USD' }
-
-// Arithmetic with explicit rounding mode
-multiply(total, '1.1'); // $39.15  (half-away-from-zero, default)
-multiply(total, '1.1', 'floor'); // $39.14  (explicit mode)
-
-// Lossless allocation — no minor unit is ever lost or gained
-allocate(money('10.00', 'USD'), [1, 1, 1]); // [$3.34, $3.33, $3.33]
-
-// Locale-aware formatting
-format(total); // '$35.59'
-format(total, { locale: 'de-DE' }); // '35,59 $'
-format(total, { style: 'code' }); // 'USD 35.59'
-
-// Currency exchange — ExchangeRate.from/to are plain strings; rate is a decimal string or number
-const rate: ExchangeRate = { from: 'USD', rate: '0.92', to: 'EUR' };
-exchange(total, rate); // { amount: 3274n, currency: 'EUR' }
-```
-
-## API
-
-### `money(amount, currency)`
-
-Creates a `Money` value. Validates the currency code against `Intl.NumberFormat`; throws `InvalidCurrencyError` for unrecognised ISO 4217 codes.
-
-| `amount` type        | Behaviour                                                              |
-| -------------------- | ---------------------------------------------------------------------- |
-| `string` `'1234.56'` | Parsed losslessly; excess digits rounded half-away-from-zero           |
-| `number` `1234.56`   | Converted via `String()` first — IEEE-754 limits apply; prefer strings |
-| `bigint` `123456n`   | Used as-is (already in minor units)                                    |
+## Start Here
 
 ```ts
-money('1234.56', 'USD'); // { amount: 123456n, currency: 'USD' }
-money(0n, 'USD'); // { amount: 0n, currency: 'USD' }  — zero accumulator
-money('1.00', 'FAKE'); // throws InvalidCurrencyError
-```
-
-### Arithmetic
+import { USD, add, money, toDecimal } from '@vielzeug/coins';
 
-All binary functions (`add`, `subtract`) throw `CurrencyMismatchError` on currency mismatch.
+const subtotal = add(money('12.50', USD), money('7.25', USD));
 
-```ts
-add(a, b); // → Money
-subtract(a, b); // → Money
-multiply(money, factor, mode?); // → Money  (factor: number | string)
-divide(money, divisor, mode?); // → Money  (throws RangeError on division by zero)
-abs(money); // → Money  (absolute value)
-negate(money); // → Money  (sign flip)
+console.log(toDecimal(subtotal)); // '19.75'
 ```
 
-### Allocation
-
-Uses the **Largest Remainder Method** — every output sums exactly to the input, no minor unit is ever lost or gained.
-
-```ts
-allocate(money, ratios); // → [Money, ...Money[]]  (weighted; use strings for lossless decimal ratios)
-splitEvenly(money, parts); // → [Money, ...Money[]]  (equal shares; sugar over allocate)
-```
-
-Both throw `RangeError` on empty ratios, negative ratios, or non-positive parts.
-
-### Aggregates
-
-```ts
-sum(moneys); // → Money  (throws RangeError if empty; CurrencyMismatchError on mismatch)
-min(moneys); // → Money  (non-empty array; CurrencyMismatchError on mismatch)
-max(moneys); // → Money  (non-empty array; CurrencyMismatchError on mismatch)
-clamp(m, lower, upper); // → Money  (CurrencyMismatchError on mismatch; RangeError if lower > upper)
-```
-
-### Comparison
-
-`isEqual` returns `false` on currency mismatch (safe for `.filter()`). All other comparison functions throw `CurrencyMismatchError` on mismatch.
+`money()` has one common path and one explicit low-level path:
 
 ```ts
-compare(a, b); // → -1 | 0 | 1
-isEqual(a, b); // → boolean  (false on currency mismatch — no throw)
-greaterThan(a, b); // → boolean
-greaterThanOrEqual(a, b); // → boolean
-lessThan(a, b); // → boolean
-lessThanOrEqual(a, b); // → boolean
-isZero(m); // → boolean
-isPositive(m); // → boolean
-isNegative(m); // → boolean
-isNonNegative(m); // → boolean  (>= 0)
-isNonPositive(m); // → boolean  (<= 0)
+money('19.99', USD);                    // exact decimal major units
+money('19.999', USD, { rounding: 'halfEven' });
+money(1999n, USD, { unit: 'minor' });   // stored minor units
 ```
 
-### Serialization
+## Core API
 
 ```ts
-toDecimal(money); // → string   e.g. '1234.56'  (round-trips losslessly with money())
-toNumber(money); // → number   e.g. 1234.56    (lossy — display/charting only)
-toJSON(money); // → MoneyJSON  { amount: '123456', currency: 'USD' }
-fromJSON(json); // → Money     (validates currency; throws on invalid input)
+import {
+  EUR,
+  USD,
+  allocate,
+  decimal,
+  exchange,
+  exchangeRate,
+  format,
+  money,
+  multiply,
+  sum,
+  toDecimal,
+} from '@vielzeug/coins';
+
+const items = [money('12.50', USD), money('7.25', USD)];
+const subtotal = sum(items, { currency: USD });
+const total = multiply(subtotal, '1.08', { rounding: 'halfEven' });
+const shares = allocate(total, 3);
+
+const usdToEur = exchangeRate({ from: USD, to: EUR, value: '0.9234' });
+const eurTotal = exchange(total, usdToEur, { rounding: 'halfEven' });
+
+console.log(format(eurTotal, { locale: 'de-DE' }));
+console.log(shares.map(toDecimal));
+console.log(decimal('1.075'));
 ```
 
-`bigint` cannot be serialized by `JSON.stringify`. Use `JSON.stringify(toJSON(price))` and `fromJSON(JSON.parse(raw))`.
+## Currency Definitions
 
-### `roundTo(money, places, mode?)`
+Built-in definitions: `USD`, `EUR`, `GBP`, `JPY`, `KRW`, `BHD`, `KWD`.
 
-Rounds a `Money` value to fewer decimal places than the currency default — useful for display (whole dollars, chart axes). `places` must be in `0..currencyDecimals`.
+Define a business currency explicitly when required:
 
 ```ts
-roundTo(money('1234.56', 'USD'), 0); // { amount: 1235n, currency: 'USD' }  ($1,235)
-roundTo(money('1234.56', 'USD'), 1, 'floor'); // { amount: 12345n, currency: 'USD' } ($1,234.5)
-```
-
-### `format(money, options?)`
-
-Formats a `Money` value as a locale-aware currency string. Uses bigint arithmetic throughout — no floating-point precision loss.
+import { defineCurrency, money } from '@vielzeug/coins';
 
-| Option                  | Type                                              | Default          | Description                  |
-| ----------------------- | ------------------------------------------------- | ---------------- | ---------------------------- |
-| `locale`                | `string`                                          | `'en-US'`        | BCP 47 language tag          |
-| `style`                 | `'symbol' \| 'code' \| 'name' \| 'narrowSymbol'` | `'symbol'`       | Display style                |
-| `minimumFractionDigits` | `number`                                          | currency default | Minimum decimal places shown |
-| `maximumFractionDigits` | `number`                                          | currency default | Maximum decimal places shown |
-
-```ts
-format(money('1234.56', 'USD')); // '$1,234.56'
-format(money('1234.56', 'USD'), { locale: 'de-DE' }); // '1.234,56 $'
-format(money('1234.56', 'USD'), { style: 'code' }); // 'USD 1,234.56'
+const POINTS = defineCurrency({ code: 'PTS', minorUnit: 0 });
+const balance = money('250', POINTS);
 ```
 
-### `formatParts(money, options?)`
+## Errors
 
-Same options as `format()`. Returns a `MoneyFormatPart[]` array of semantic segments — useful for applying separate styles to symbol, integer, decimal, and fraction parts.
-
-Joining all `value` fields produces the same string as `format()`.
-
-### `exchange(money, rate, mode?)`
-
-Converts a `Money` value using an `ExchangeRate`. `ExchangeRate.from` and `.to` are plain strings; `rate.rate` is a decimal string or number (`number | string`, for symmetry with `multiply()`/`divide()` — prefer a string for lossless bigint arithmetic). Throws `CurrencyMismatchError` if `money.currency !== rate.from`.
+All failures extend `CoinsError` and expose `code`.
 
 ```ts
-import type { ExchangeRate } from '@vielzeug/coins';
-
-const rate: ExchangeRate = { from: 'USD', rate: '0.92', to: 'EUR' };
-exchange(money('100.00', 'USD'), rate); // { amount: 9200n, currency: 'EUR' }
-exchange(money('100.00', 'USD'), rate, 'floor'); // explicit rounding mode
-```
-
-### Typed Errors
-
-```ts
-import { CurrencyMismatchError, InvalidCurrencyError } from '@vielzeug/coins';
-
-try {
-  add(money('1.00', 'USD'), money('1.00', 'EUR'));
-} catch (e) {
-  if (e instanceof CurrencyMismatchError) {
-    console.log(e.expected, e.received); // 'USD' 'EUR'
-  }
-}
+import { CoinsError, money, USD } from '@vielzeug/coins';
 
 try {
-  money('1.00', 'FAKE');
-} catch (e) {
-  if (e instanceof InvalidCurrencyError) {
-    console.log(e.code); // 'FAKE'
+  money(100n, USD);
+} catch (error) {
+  if (error instanceof CoinsError && error.code === 'INVALID_MONEY') {
+    // Bigint construction requires { unit: 'minor' }.
   }
 }
 ```
 
-- `CurrencyMismatchError` extends `TypeError` — existing `instanceof TypeError` catch blocks still work.
-- `InvalidCurrencyError` extends `RangeError` — existing `instanceof RangeError` catch blocks still work.
-
-### Rounding Modes
-
-Used by `multiply`, `divide`, `exchange`, and `roundTo`.
-
-| Mode                    | Description                                    |
-| ----------------------- | ---------------------------------------------- |
-| `'half-away-from-zero'` | Round half away from zero **(default)**        |
-| `'half-even'`           | Banker's rounding — minimises cumulative error |
-| `'down'`                | Truncate toward zero                           |
-| `'up'`                  | Away from zero                                 |
-| `'floor'`               | Toward −∞                                      |
-| `'ceiling'`             | Toward +∞                                      |
-
-### Key Types
-
-```ts
-type Money = {
-  readonly amount: bigint; // minor units (cents for USD, whole units for JPY)
-  readonly currency: string; // validated ISO 4217 code
-};
-
-type ExchangeRate = {
-  readonly from: string; // source currency code
-  readonly rate: number | string; // decimal multiplier, e.g. '0.92' or 0.92
-  readonly to: string; // target currency code
-};
-
-type RoundingMode = 'ceiling' | 'down' | 'floor' | 'half-away-from-zero' | 'half-even' | 'up';
-
-type FormatOptions = {
-  locale?: string;
-  maximumFractionDigits?: number;
-  minimumFractionDigits?: number;
-  style?: 'code' | 'name' | 'narrowSymbol' | 'symbol';
-};
-
-type MoneyFormatPart = {
-  type: 'currency' | 'decimal' | 'fraction' | 'integer' | 'literal' | 'minusSign';
-  value: string;
-};
-
-type MoneyJSON = { amount: string; currency: string };
-```
-
-## Documentation
-
-- **[Full Guide](https://vielzeug.dev/coins/)** — Overview, concepts, quick start
-- **[Usage Guide](https://vielzeug.dev/coins/usage/)** — Common patterns and best practices
-- **[API Reference](https://vielzeug.dev/coins/api/)** — All types and function signatures
-- **[Examples](https://vielzeug.dev/coins/examples/)** — Real-world integration examples
-
-## TypeScript
-
-Requires TypeScript 5.0+ with `strict: true`.
-
 ## License
 
-MIT
+MIT © Helmuth Saatkamp

package/dist/aggregate.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs"),t=require("./decimal.cjs"),n=require("./money.cjs");function r(t,r){let i=0n;for(let a of t){if(!n.isMoney(a))throw new e.CoinsError(`INVALID_MONEY`,`sum() requires canonical money values`);if(a.currency!==r.currency)throw new e.CurrencyMismatchError(r.currency.code,a.currency.code);i+=a.amount}return n.withMinor(i,r.currency)}function i(r,i){if(!n.isMoney(r))throw new e.CoinsError(`INVALID_MONEY`,`allocate() requires canonical money`);if(typeof i==`number`)return o(r,i);if(i.length===0)throw new e.CoinsError(`INVALID_ALLOCATION`,`Allocation weights cannot be empty`);let a=i.map(t.decimal);if(a.some(e=>e.numerator<0n))throw new e.CoinsError(`INVALID_ALLOCATION`,`Allocation weights cannot be negative`);let s=a.reduce((e,n)=>t.lcm(e,n.denominator),1n),c=a.map(e=>e.numerator*(s/e.denominator)),l=c.reduce((e,t)=>e+t,0n);if(l===0n)throw new e.CoinsError(`INVALID_ALLOCATION`,`Allocation weights must include a positive value`);let u=r.amount<0n?-1n:1n,d=r.amount<0n?-r.amount:r.amount,f=c.map(e=>d*e/l),p=d-f.reduce((e,t)=>e+t,0n),m=c.map((e,t)=>({index:t,remainder:d*e%l})).sort((e,t)=>e.remainder===t.remainder?e.index-t.index:e.remainder>t.remainder?-1:1);for(let e of m){if(p===0n)break;f[e.index]+=1n,p-=1n}return f.map(e=>n.withMinor(e*u,r.currency))}function a(t,r){if(n.compare(r.min,r.max)===1)throw new e.CoinsError(`INVALID_ALLOCATION`,`Clamp minimum cannot exceed maximum`);return n.compare(t,r.min)===-1?r.min:n.compare(t,r.max)===1?r.max:t}function o(t,r){if(!Number.isInteger(r)||r<1)throw new e.CoinsError(`INVALID_ALLOCATION`,`Allocation count must be a positive integer`);let i=BigInt(r),a=t.amount<0n?-1n:1n,o=t.amount<0n?-t.amount:t.amount,s=o/i,c=o%i;return Array.from({length:r},(e,r)=>n.withMinor((s+(BigInt(r)<c?1n:0n))*a,t.currency))}exports.allocate=i,exports.clamp=a,exports.sum=r;
+//# sourceMappingURL=aggregate.cjs.map

package/dist/aggregate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.cjs","names":[],"sources":["../src/aggregate.ts"],"sourcesContent":["import type { Currency, Money } from './types';\n\nimport { decimal, lcm } from './decimal';\nimport { CoinsError, CurrencyMismatchError } from './errors';\nimport { compare, isMoney, withMinor } from './money';\n\nexport function sum<C extends Currency>(values: Iterable<Money<C>>, options: { currency: C }): Money<C> {\n  let amount = 0n;\n\n  for (const value of values) {\n    if (!isMoney(value)) throw new CoinsError('INVALID_MONEY', 'sum() requires canonical money values');\n\n    if (value.currency !== options.currency)\n      throw new CurrencyMismatchError(options.currency.code, value.currency.code);\n\n    amount += value.amount;\n  }\n\n  return withMinor(amount, options.currency);\n}\n\nexport function allocate<C extends Currency>(value: Money<C>, count: number): Money<C>[];\nexport function allocate<C extends Currency>(value: Money<C>, weights: readonly string[]): Money<C>[];\nexport function allocate<C extends Currency>(value: Money<C>, weightsOrCount: number | readonly string[]): Money<C>[] {\n  if (!isMoney(value)) throw new CoinsError('INVALID_MONEY', 'allocate() requires canonical money');\n\n  if (typeof weightsOrCount === 'number') return allocateEvenly(value, weightsOrCount);\n\n  if (weightsOrCount.length === 0) throw new CoinsError('INVALID_ALLOCATION', 'Allocation weights cannot be empty');\n\n  const weights = weightsOrCount.map(decimal);\n\n  if (weights.some((weight) => weight.numerator < 0n)) {\n    throw new CoinsError('INVALID_ALLOCATION', 'Allocation weights cannot be negative');\n  }\n\n  const commonDenominator = weights.reduce((result, weight) => lcm(result, weight.denominator), 1n);\n  const scaledWeights = weights.map((weight) => weight.numerator * (commonDenominator / weight.denominator));\n  const totalWeight = scaledWeights.reduce((result, weight) => result + weight, 0n);\n\n  if (totalWeight === 0n)\n    throw new CoinsError('INVALID_ALLOCATION', 'Allocation weights must include a positive value');\n\n  const sign = value.amount < 0n ? -1n : 1n;\n  const absolute = value.amount < 0n ? -value.amount : value.amount;\n  const shares = scaledWeights.map((weight) => (absolute * weight) / totalWeight);\n  let remainder = absolute - shares.reduce((result, amount) => result + amount, 0n);\n  const ranked = scaledWeights\n    .map((weight, index) => ({ index, remainder: (absolute * weight) % totalWeight }))\n    .sort((left, right) =>\n      left.remainder === right.remainder ? left.index - right.index : left.remainder > right.remainder ? -1 : 1,\n    );\n\n  for (const entry of ranked) {\n    if (remainder === 0n) break;\n\n    shares[entry.index]! += 1n;\n    remainder -= 1n;\n  }\n\n  return shares.map((amount) => withMinor(amount * sign, value.currency));\n}\n\nexport function clamp<C extends Currency>(\n  value: Money<C>,\n  options: { max: Money<NoInfer<C>>; min: Money<NoInfer<C>> },\n): Money<C> {\n  if (compare(options.min, options.max) === 1) {\n    throw new CoinsError('INVALID_ALLOCATION', 'Clamp minimum cannot exceed maximum');\n  }\n\n  return compare(value, options.min) === -1 ? options.min : compare(value, options.max) === 1 ? options.max : value;\n}\n\nfunction allocateEvenly<C extends Currency>(value: Money<C>, countValue: number): Money<C>[] {\n  if (!Number.isInteger(countValue) || countValue < 1) {\n    throw new CoinsError('INVALID_ALLOCATION', 'Allocation count must be a positive integer');\n  }\n\n  const count = BigInt(countValue);\n  const sign = value.amount < 0n ? -1n : 1n;\n  const absolute = value.amount < 0n ? -value.amount : value.amount;\n  const base = absolute / count;\n  const remainder = absolute % count;\n\n  return Array.from({ length: countValue }, (_, index) =>\n    withMinor((base + (BigInt(index) < remainder ? 1n : 0n)) * sign, value.currency),\n  );\n}\n"],"mappings":"oFAMA,SAAgB,EAAwB,EAA4B,EAAoC,CACtG,IAAI,EAAS,GAEb,IAAK,IAAM,KAAS,EAAQ,CAC1B,GAAI,CAAC,EAAA,QAAQ,CAAK,EAAG,MAAM,IAAI,EAAA,WAAW,gBAAiB,uCAAuC,EAElG,GAAI,EAAM,WAAa,EAAQ,SAC7B,MAAM,IAAI,EAAA,sBAAsB,EAAQ,SAAS,KAAM,EAAM,SAAS,IAAI,EAE5E,GAAU,EAAM,MAClB,CAEA,OAAO,EAAA,UAAU,EAAQ,EAAQ,QAAQ,CAC3C,CAIA,SAAgB,EAA6B,EAAiB,EAAwD,CACpH,GAAI,CAAC,EAAA,QAAQ,CAAK,EAAG,MAAM,IAAI,EAAA,WAAW,gBAAiB,qCAAqC,EAEhG,GAAI,OAAO,GAAmB,SAAU,OAAO,EAAe,EAAO,CAAc,EAEnF,GAAI,EAAe,SAAW,EAAG,MAAM,IAAI,EAAA,WAAW,qBAAsB,oCAAoC,EAEhH,IAAM,EAAU,EAAe,IAAI,EAAA,OAAO,EAE1C,GAAI,EAAQ,KAAM,GAAW,EAAO,UAAY,EAAE,EAChD,MAAM,IAAI,EAAA,WAAW,qBAAsB,uCAAuC,EAGpF,IAAM,EAAoB,EAAQ,QAAQ,EAAQ,IAAW,EAAA,IAAI,EAAQ,EAAO,WAAW,EAAG,EAAE,EAC1F,EAAgB,EAAQ,IAAK,GAAW,EAAO,WAAa,EAAoB,EAAO,YAAY,EACnG,EAAc,EAAc,QAAQ,EAAQ,IAAW,EAAS,EAAQ,EAAE,EAEhF,GAAI,IAAgB,GAClB,MAAM,IAAI,EAAA,WAAW,qBAAsB,kDAAkD,EAE/F,IAAM,EAAO,EAAM,OAAS,GAAK,CAAC,GAAK,GACjC,EAAW,EAAM,OAAS,GAAK,CAAC,EAAM,OAAS,EAAM,OACrD,EAAS,EAAc,IAAK,GAAY,EAAW,EAAU,CAAW,EAC1E,EAAY,EAAW,EAAO,QAAQ,EAAQ,IAAW,EAAS,EAAQ,EAAE,EAC1E,EAAS,EACZ,KAAK,EAAQ,KAAW,CAAE,QAAO,UAAY,EAAW,EAAU,CAAY,EAAE,CAAC,CACjF,MAAM,EAAM,IACX,EAAK,YAAc,EAAM,UAAY,EAAK,MAAQ,EAAM,MAAQ,EAAK,UAAY,EAAM,UAAY,GAAK,CAC1G,EAEF,IAAK,IAAM,KAAS,EAAQ,CAC1B,GAAI,IAAc,GAAI,MAEtB,EAAO,EAAM,QAAW,GACxB,GAAa,EACf,CAEA,OAAO,EAAO,IAAK,GAAW,EAAA,UAAU,EAAS,EAAM,EAAM,QAAQ,CAAC,CACxE,CAEA,SAAgB,EACd,EACA,EACU,CACV,GAAI,EAAA,QAAQ,EAAQ,IAAK,EAAQ,GAAG,IAAM,EACxC,MAAM,IAAI,EAAA,WAAW,qBAAsB,qCAAqC,EAGlF,OAAO,EAAA,QAAQ,EAAO,EAAQ,GAAG,IAAM,GAAK,EAAQ,IAAM,EAAA,QAAQ,EAAO,EAAQ,GAAG,IAAM,EAAI,EAAQ,IAAM,CAC9G,CAEA,SAAS,EAAmC,EAAiB,EAAgC,CAC3F,GAAI,CAAC,OAAO,UAAU,CAAU,GAAK,EAAa,EAChD,MAAM,IAAI,EAAA,WAAW,qBAAsB,6CAA6C,EAG1F,IAAM,EAAQ,OAAO,CAAU,EACzB,EAAO,EAAM,OAAS,GAAK,CAAC,GAAK,GACjC,EAAW,EAAM,OAAS,GAAK,CAAC,EAAM,OAAS,EAAM,OACrD,EAAO,EAAW,EAClB,EAAY,EAAW,EAE7B,OAAO,MAAM,KAAK,CAAE,OAAQ,CAAW,GAAI,EAAG,IAC5C,EAAA,WAAW,GAAQ,OAAO,CAAK,EAAI,EAAY,GAAK,KAAO,EAAM,EAAM,QAAQ,CACjF,CACF"}

package/dist/aggregate.d.ts

@@ -0,0 +1,11 @@
+import type { Currency, Money } from './types';
+export declare function sum<C extends Currency>(values: Iterable<Money<C>>, options: {
+    currency: C;
+}): Money<C>;
+export declare function allocate<C extends Currency>(value: Money<C>, count: number): Money<C>[];
+export declare function allocate<C extends Currency>(value: Money<C>, weights: readonly string[]): Money<C>[];
+export declare function clamp<C extends Currency>(value: Money<C>, options: {
+    max: Money<NoInfer<C>>;
+    min: Money<NoInfer<C>>;
+}): Money<C>;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAM/C,wBAAgB,GAAG,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE;IAAE,QAAQ,EAAE,CAAC,CAAA;CAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAatG;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACzF,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAyCtG,wBAAgB,KAAK,CAAC,CAAC,SAAS,QAAQ,EACtC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,EAAE;IAAE,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;CAAE,GAC1D,KAAK,CAAC,CAAC,CAAC,CAMV"}

package/dist/aggregate.js

@@ -0,0 +1,44 @@
+import { CoinsError as e, CurrencyMismatchError as t } from "./errors.js";
+import { decimal as n, lcm as r } from "./decimal.js";
+import { compare as i, isMoney as a, withMinor as o } from "./money.js";
+//#region src/aggregate.ts
+function s(n, r) {
+	let i = 0n;
+	for (let o of n) {
+		if (!a(o)) throw new e("INVALID_MONEY", "sum() requires canonical money values");
+		if (o.currency !== r.currency) throw new t(r.currency.code, o.currency.code);
+		i += o.amount;
+	}
+	return o(i, r.currency);
+}
+function c(t, i) {
+	if (!a(t)) throw new e("INVALID_MONEY", "allocate() requires canonical money");
+	if (typeof i == "number") return u(t, i);
+	if (i.length === 0) throw new e("INVALID_ALLOCATION", "Allocation weights cannot be empty");
+	let s = i.map(n);
+	if (s.some((e) => e.numerator < 0n)) throw new e("INVALID_ALLOCATION", "Allocation weights cannot be negative");
+	let c = s.reduce((e, t) => r(e, t.denominator), 1n), l = s.map((e) => e.numerator * (c / e.denominator)), d = l.reduce((e, t) => e + t, 0n);
+	if (d === 0n) throw new e("INVALID_ALLOCATION", "Allocation weights must include a positive value");
+	let f = t.amount < 0n ? -1n : 1n, p = t.amount < 0n ? -t.amount : t.amount, m = l.map((e) => p * e / d), h = p - m.reduce((e, t) => e + t, 0n), g = l.map((e, t) => ({
+		index: t,
+		remainder: p * e % d
+	})).sort((e, t) => e.remainder === t.remainder ? e.index - t.index : e.remainder > t.remainder ? -1 : 1);
+	for (let e of g) {
+		if (h === 0n) break;
+		m[e.index] += 1n, h -= 1n;
+	}
+	return m.map((e) => o(e * f, t.currency));
+}
+function l(t, n) {
+	if (i(n.min, n.max) === 1) throw new e("INVALID_ALLOCATION", "Clamp minimum cannot exceed maximum");
+	return i(t, n.min) === -1 ? n.min : i(t, n.max) === 1 ? n.max : t;
+}
+function u(t, n) {
+	if (!Number.isInteger(n) || n < 1) throw new e("INVALID_ALLOCATION", "Allocation count must be a positive integer");
+	let r = BigInt(n), i = t.amount < 0n ? -1n : 1n, a = t.amount < 0n ? -t.amount : t.amount, s = a / r, c = a % r;
+	return Array.from({ length: n }, (e, n) => o((s + (BigInt(n) < c ? 1n : 0n)) * i, t.currency));
+}
+//#endregion
+export { c as allocate, l as clamp, s as sum };
+
+//# sourceMappingURL=aggregate.js.map

package/dist/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","names":[],"sources":["../src/aggregate.ts"],"sourcesContent":["import type { Currency, Money } from './types';\n\nimport { decimal, lcm } from './decimal';\nimport { CoinsError, CurrencyMismatchError } from './errors';\nimport { compare, isMoney, withMinor } from './money';\n\nexport function sum<C extends Currency>(values: Iterable<Money<C>>, options: { currency: C }): Money<C> {\n  let amount = 0n;\n\n  for (const value of values) {\n    if (!isMoney(value)) throw new CoinsError('INVALID_MONEY', 'sum() requires canonical money values');\n\n    if (value.currency !== options.currency)\n      throw new CurrencyMismatchError(options.currency.code, value.currency.code);\n\n    amount += value.amount;\n  }\n\n  return withMinor(amount, options.currency);\n}\n\nexport function allocate<C extends Currency>(value: Money<C>, count: number): Money<C>[];\nexport function allocate<C extends Currency>(value: Money<C>, weights: readonly string[]): Money<C>[];\nexport function allocate<C extends Currency>(value: Money<C>, weightsOrCount: number | readonly string[]): Money<C>[] {\n  if (!isMoney(value)) throw new CoinsError('INVALID_MONEY', 'allocate() requires canonical money');\n\n  if (typeof weightsOrCount === 'number') return allocateEvenly(value, weightsOrCount);\n\n  if (weightsOrCount.length === 0) throw new CoinsError('INVALID_ALLOCATION', 'Allocation weights cannot be empty');\n\n  const weights = weightsOrCount.map(decimal);\n\n  if (weights.some((weight) => weight.numerator < 0n)) {\n    throw new CoinsError('INVALID_ALLOCATION', 'Allocation weights cannot be negative');\n  }\n\n  const commonDenominator = weights.reduce((result, weight) => lcm(result, weight.denominator), 1n);\n  const scaledWeights = weights.map((weight) => weight.numerator * (commonDenominator / weight.denominator));\n  const totalWeight = scaledWeights.reduce((result, weight) => result + weight, 0n);\n\n  if (totalWeight === 0n)\n    throw new CoinsError('INVALID_ALLOCATION', 'Allocation weights must include a positive value');\n\n  const sign = value.amount < 0n ? -1n : 1n;\n  const absolute = value.amount < 0n ? -value.amount : value.amount;\n  const shares = scaledWeights.map((weight) => (absolute * weight) / totalWeight);\n  let remainder = absolute - shares.reduce((result, amount) => result + amount, 0n);\n  const ranked = scaledWeights\n    .map((weight, index) => ({ index, remainder: (absolute * weight) % totalWeight }))\n    .sort((left, right) =>\n      left.remainder === right.remainder ? left.index - right.index : left.remainder > right.remainder ? -1 : 1,\n    );\n\n  for (const entry of ranked) {\n    if (remainder === 0n) break;\n\n    shares[entry.index]! += 1n;\n    remainder -= 1n;\n  }\n\n  return shares.map((amount) => withMinor(amount * sign, value.currency));\n}\n\nexport function clamp<C extends Currency>(\n  value: Money<C>,\n  options: { max: Money<NoInfer<C>>; min: Money<NoInfer<C>> },\n): Money<C> {\n  if (compare(options.min, options.max) === 1) {\n    throw new CoinsError('INVALID_ALLOCATION', 'Clamp minimum cannot exceed maximum');\n  }\n\n  return compare(value, options.min) === -1 ? options.min : compare(value, options.max) === 1 ? options.max : value;\n}\n\nfunction allocateEvenly<C extends Currency>(value: Money<C>, countValue: number): Money<C>[] {\n  if (!Number.isInteger(countValue) || countValue < 1) {\n    throw new CoinsError('INVALID_ALLOCATION', 'Allocation count must be a positive integer');\n  }\n\n  const count = BigInt(countValue);\n  const sign = value.amount < 0n ? -1n : 1n;\n  const absolute = value.amount < 0n ? -value.amount : value.amount;\n  const base = absolute / count;\n  const remainder = absolute % count;\n\n  return Array.from({ length: countValue }, (_, index) =>\n    withMinor((base + (BigInt(index) < remainder ? 1n : 0n)) * sign, value.currency),\n  );\n}\n"],"mappings":";;;;AAMA,SAAgB,EAAwB,GAA4B,GAAoC;CACtG,IAAI,IAAS;CAEb,KAAK,IAAM,KAAS,GAAQ;EAC1B,IAAI,CAAC,EAAQ,CAAK,GAAG,MAAM,IAAI,EAAW,iBAAiB,uCAAuC;EAElG,IAAI,EAAM,aAAa,EAAQ,UAC7B,MAAM,IAAI,EAAsB,EAAQ,SAAS,MAAM,EAAM,SAAS,IAAI;EAE5E,KAAU,EAAM;CAClB;CAEA,OAAO,EAAU,GAAQ,EAAQ,QAAQ;AAC3C;AAIA,SAAgB,EAA6B,GAAiB,GAAwD;CACpH,IAAI,CAAC,EAAQ,CAAK,GAAG,MAAM,IAAI,EAAW,iBAAiB,qCAAqC;CAEhG,IAAI,OAAO,KAAmB,UAAU,OAAO,EAAe,GAAO,CAAc;CAEnF,IAAI,EAAe,WAAW,GAAG,MAAM,IAAI,EAAW,sBAAsB,oCAAoC;CAEhH,IAAM,IAAU,EAAe,IAAI,CAAO;CAE1C,IAAI,EAAQ,MAAM,MAAW,EAAO,YAAY,EAAE,GAChD,MAAM,IAAI,EAAW,sBAAsB,uCAAuC;CAGpF,IAAM,IAAoB,EAAQ,QAAQ,GAAQ,MAAW,EAAI,GAAQ,EAAO,WAAW,GAAG,EAAE,GAC1F,IAAgB,EAAQ,KAAK,MAAW,EAAO,aAAa,IAAoB,EAAO,YAAY,GACnG,IAAc,EAAc,QAAQ,GAAQ,MAAW,IAAS,GAAQ,EAAE;CAEhF,IAAI,MAAgB,IAClB,MAAM,IAAI,EAAW,sBAAsB,kDAAkD;CAE/F,IAAM,IAAO,EAAM,SAAS,KAAK,CAAC,KAAK,IACjC,IAAW,EAAM,SAAS,KAAK,CAAC,EAAM,SAAS,EAAM,QACrD,IAAS,EAAc,KAAK,MAAY,IAAW,IAAU,CAAW,GAC1E,IAAY,IAAW,EAAO,QAAQ,GAAQ,MAAW,IAAS,GAAQ,EAAE,GAC1E,IAAS,EACZ,KAAK,GAAQ,OAAW;EAAE;EAAO,WAAY,IAAW,IAAU;CAAY,EAAE,CAAC,CACjF,MAAM,GAAM,MACX,EAAK,cAAc,EAAM,YAAY,EAAK,QAAQ,EAAM,QAAQ,EAAK,YAAY,EAAM,YAAY,KAAK,CAC1G;CAEF,KAAK,IAAM,KAAS,GAAQ;EAC1B,IAAI,MAAc,IAAI;EAGtB,AADA,EAAO,EAAM,UAAW,IACxB,KAAa;CACf;CAEA,OAAO,EAAO,KAAK,MAAW,EAAU,IAAS,GAAM,EAAM,QAAQ,CAAC;AACxE;AAEA,SAAgB,EACd,GACA,GACU;CACV,IAAI,EAAQ,EAAQ,KAAK,EAAQ,GAAG,MAAM,GACxC,MAAM,IAAI,EAAW,sBAAsB,qCAAqC;CAGlF,OAAO,EAAQ,GAAO,EAAQ,GAAG,MAAM,KAAK,EAAQ,MAAM,EAAQ,GAAO,EAAQ,GAAG,MAAM,IAAI,EAAQ,MAAM;AAC9G;AAEA,SAAS,EAAmC,GAAiB,GAAgC;CAC3F,IAAI,CAAC,OAAO,UAAU,CAAU,KAAK,IAAa,GAChD,MAAM,IAAI,EAAW,sBAAsB,6CAA6C;CAG1F,IAAM,IAAQ,OAAO,CAAU,GACzB,IAAO,EAAM,SAAS,KAAK,CAAC,KAAK,IACjC,IAAW,EAAM,SAAS,KAAK,CAAC,EAAM,SAAS,EAAM,QACrD,IAAO,IAAW,GAClB,IAAY,IAAW;CAE7B,OAAO,MAAM,KAAK,EAAE,QAAQ,EAAW,IAAI,GAAG,MAC5C,GAAW,KAAQ,OAAO,CAAK,IAAI,IAAY,KAAK,OAAO,GAAM,EAAM,QAAQ,CACjF;AACF"}

package/dist/coins.cjs

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class e extends Error{constructor(e,t){super(e,t),this.name=new.target.name,Object.setPrototypeOf(this,new.target.prototype)}static is(t){return t instanceof e}},t=class extends e{expected;received;constructor(e,t){super(`Currency mismatch: ${e} and ${t}`),this.expected=e,this.received=t}},n=class extends e{code;constructor(e){super(`Invalid ISO 4217 currency code: "${e}"`),this.code=e}};function r(e){let t=new Map;return{get:e=>t.get(e),set(n,r){t.size>=e&&t.delete(t.keys().next().value),t.set(n,r)}}}var i=r(512);function a(e){let t=i.get(e);if(t!==void 0)return t;let r;try{r=new Intl.NumberFormat(`en`,{currency:e,style:`currency`}).resolvedOptions().maximumFractionDigits}catch{throw new n(e)}if(r===void 0)throw new n(e);return i.set(e,r),r}function o(e){return a(e),e}function s(e){return 10n**BigInt(e)}var c=/^-?\d+(\.\d+)?$/,l=/^(-?\d+\.?\d*)[eE]([+-]?\d+)$/,u=1e3;function d(t){let n=l.exec(t),r=n[1],i=parseInt(n[2],10);if(Math.abs(i)>u)throw new e(`Scientific notation exponent too large: "${t}" (max ±${u})`);let a=r.startsWith(`-`),o=a?r.slice(1):r,s=o.indexOf(`.`),c=s===-1?o:o.replace(`.`,``),d=i-(s===-1?0:o.length-s-1),f;if(d>=0)f=c+`0`.repeat(d);else{let e=c.length+d;f=e<=0?`0.`+`0`.repeat(-e)+c:c.slice(0,e)+`.`+c.slice(e)}return a?`-${f}`:f}function f(t){let n=l.test(t)?d(t):t;if(!c.test(n))throw new e(`Invalid decimal string: "${t}"`);let r=n.startsWith(`-`),i=r?n.slice(1):n,a=i.indexOf(`.`),o=a===-1?i:i.slice(0,a),u=a===-1?``:i.slice(a+1),f=s(u.length);return{denominator:f,negative:r,numerator:BigInt(o||`0`)*f+BigInt(u||`0`)}}function p(t,n,r,i,a=!1){if(n===0n)return t;switch(i){case`ceiling`:return a?t:t+1n;case`down`:return t;case`floor`:return a?t+1n:t;case`half-away-from-zero`:return n*2n>=r?t+1n:t;case`half-even`:{let e=n*2n;return e<r?t:e>r?t+1n:t%2n==0n?t:t+1n}case`up`:return t+1n;default:throw new e(`Unknown rounding mode: ${String(i)}`)}}function m(n,r,i=`half-away-from-zero`){if(n.currency!==r.from)throw new t(n.currency,r.from);if(r.rate===``)throw new e(`Exchange rate must be a non-empty decimal string`);let{denominator:a,negative:s,numerator:c}=f(String(r.rate));if(s)throw new e(`Exchange rate must be non-negative`);let l=n.amount<0n,u=(n.amount<0n?-n.amount:n.amount)*c,d=p(u/a,u%a,a,i,l);return{amount:l?-d:d,currency:o(r.to)}}var h=r(512),g=r(32);function _(t,n){let{locale:r=`en-US`,maximumFractionDigits:i,minimumFractionDigits:o,style:c=`symbol`}=n,l=a(t.currency),u=b(`maximumFractionDigits`,i,l),d=b(`minimumFractionDigits`,o,Math.min(l,u));if(d>u)throw new e(`minimumFractionDigits must be less than or equal to maximumFractionDigits`);let f=ee(t.amount,l,u),p=f<0n,m=p?-f:f,h=s(u),g=m/h,_=x(u===0?``:(m%h).toString().padStart(u,`0`),d),v=S(r,t.currency,c,p);return{frac:_,intStr:C(r).format(g),negative:p,template:v}}function v(e,t={}){return y(e,t).map(e=>e.value).join(``)}function y(e,t={}){let{frac:n,intStr:r,template:i}=_(e,t),a=n.length>0,o=[],s=!1;for(let e of i)if(e.type!==`group`){if(e.type===`integer`){s||=(o.push({type:`integer`,value:r}),!0);continue}if(e.type===`decimal`){a&&o.push({type:`decimal`,value:e.value});continue}if(e.type===`fraction`){a&&o.push({type:`fraction`,value:n});continue}e.type===`currency`?o.push({type:`currency`,value:e.value}):e.type===`minusSign`?o.push({type:`minusSign`,value:e.value}):o.push({type:`literal`,value:e.value})}return o}function b(t,n,r){if(n==null)return r;if(!Number.isInteger(n)||n<0)throw new e(`${t} must be a non-negative integer`);return n}function ee(e,t,n){if(t===n)return e;if(n>t)return e*s(n-t);let r=e<0n,i=r?-e:e,a=s(t-n),o=p(i/a,i%a,a,`half-away-from-zero`);return r?-o:o}function x(e,t){if(e.length===0)return``;let n=e.length;for(;n>t&&e[n-1]===`0`;)n--;return e.slice(0,n)}function S(e,t,n,r){let i=[e,t,n,r?`neg`:`pos`].join(`\0`),a=h.get(i);if(a!==void 0)return a;let o=new Intl.NumberFormat(e,{currency:t,currencyDisplay:n,maximumFractionDigits:1,minimumFractionDigits:1,style:`currency`}).formatToParts(r?-1.1:1.1);return h.set(i,o),o}function C(e){let t=g.get(e);if(t!==void 0)return t;let n=new Intl.NumberFormat(e,{maximumFractionDigits:0,minimumFractionDigits:0,useGrouping:!0});return g.set(e,n),n}var w=!globalThis.__COINS_PROD__;function T(e){w&&console.warn(`[@vielzeug/coins] ${e}`)}function E(e,t){let n=o(t);if(typeof e==`bigint`)return{amount:e,currency:n};if(typeof e==`number`){let t=a(n),r=String(e),i=l.test(r)?d(r):r,o=i.indexOf(`.`),s=o===-1?0:i.length-o-1;return s>t&&T(`money(): number input "${e}" has more decimal places (${s}) than ${n} supports (${t}). Use a decimal string to avoid IEEE-754 precision loss.`),{amount:O(r,t),currency:n}}return{amount:O(String(e),a(n)),currency:n}}function D(e,n){if(e.currency!==n.currency)throw new t(e.currency,n.currency)}function O(e,t){let{denominator:n,negative:r,numerator:i}=f(e),a=i*s(t),o=p(a/n,a%n,n,`half-away-from-zero`);return r?-o:o}function k(e,t){return{amount:t,currency:e.currency}}function A(e){if(typeof e!=`object`||!e)return!1;let t=e;return Object.hasOwn(t,`amount`)&&typeof t.amount==`bigint`&&Object.hasOwn(t,`currency`)&&typeof t.currency==`string`}function j(e,t){return D(e,t),{amount:e.amount+t.amount,currency:e.currency}}function M(e,t){return D(e,t),{amount:e.amount-t.amount,currency:e.currency}}function N(e,t,n=`half-away-from-zero`){let{denominator:r,negative:i,numerator:a}=f(String(t)),o=e.amount<0n!==i,s=(e.amount<0n?-e.amount:e.amount)*a,c=p(s/r,s%r,r,n,o);return{amount:o?-c:c,currency:e.currency}}function P(t,n,r=`half-away-from-zero`){let{denominator:i,negative:a,numerator:o}=f(String(n));if(o===0n)throw new e(`Division by zero`);let s=t.amount<0n!==a,c=(t.amount<0n?-t.amount:t.amount)*i,l=p(c/o,c%o,o,r,s);return{amount:s?-l:l,currency:t.currency}}function F(t,n){if(n.length===0)throw new e(`allocate requires at least one ratio`);let r=n.map(e=>f(String(e)));if(r.some(e=>e.negative))throw new e(`All ratios must be non-negative`);if(!r.some(e=>e.numerator>0n))throw new e(`At least one ratio must be positive`);let i=t.amount<0n,a=i?-t.amount:t.amount,o=r.reduce((e,t)=>t.denominator>e?t.denominator:e,1n),s=r.map(e=>e.numerator*(o/e.denominator)),c=s.reduce((e,t)=>e+t,0n),l=[],u=[];for(let e of s){let t=a*e;l.push(t/c),u.push(t%c)}let d=n.map((e,t)=>t).sort((e,t)=>{let n=u[t]-u[e];return n>0n?1:n<0n?-1:0}),p=[...l],m=a-l.reduce((e,t)=>e+t,0n);for(let e=0;m>0n;e++,m--)p[d[e]]+=1n;return p.map(e=>({amount:i?-e:e,currency:t.currency}))}function I(n){if(n.length===0)throw new e(`sum requires at least one Money value`);let r=n[0].currency;for(let e=1;e<n.length;e++)if(n[e].currency!==r)throw new t(r,n[e].currency);return{amount:n.reduce((e,t)=>e+t.amount,0n),currency:r}}function L(t){if(t.length===0)throw new e(`min requires at least one Money value`);let n=t[0];for(let e=1;e<t.length;e++)n=U(n,t[e])<=0?n:t[e];return n}function R(t){if(t.length===0)throw new e(`max requires at least one Money value`);let n=t[0];for(let e=1;e<t.length;e++)n=U(n,t[e])>=0?n:t[e];return n}function z(t,n){if(!Number.isInteger(n)||n<=0)throw new e(`splitEvenly requires a positive integer number of parts`);return F(t,Array.from({length:n},()=>1))}function B(n,r,i){if(n.currency!==r.currency||n.currency!==i.currency)throw new t(n.currency,n.currency===r.currency?i.currency:r.currency);if(U(r,i)>0)throw new e(`clamp: lower (${$(r)} ${r.currency}) must be <= upper (${$(i)} ${i.currency})`);return R([r,L([n,i])])}function V(e){return{amount:e.amount<0n?-e.amount:e.amount,currency:e.currency}}function H(e){return{amount:-e.amount,currency:e.currency}}function U(e,t){return D(e,t),e.amount<t.amount?-1:+(e.amount>t.amount)}function W(e,t){return e.currency===t.currency&&e.amount===t.amount}function G(e,t){return U(e,t)>0}function K(e,t){return U(e,t)>=0}function q(e,t){return U(e,t)<0}function J(e,t){return U(e,t)<=0}function Y(e){return e.amount===0n}function X(e){return e.amount>0n}function Z(e){return e.amount<0n}function Q(e){return e.amount>=0n}function te(e){return e.amount<=0n}function ne(e){return{amount:String(e.amount),currency:e.currency}}function re(t){let n=o(t.currency);if(typeof t.amount!=`string`)throw new e(`Invalid money amount in JSON: ${String(t.amount)} (expected an integer string, e.g. '123456')`);let r;try{r=BigInt(t.amount)}catch{throw new e(`Invalid money amount in JSON: "${t.amount}" (expected an integer string, e.g. '123456')`)}return{amount:r,currency:n}}function $(e){let t=a(e.currency);if(t===0)return String(e.amount);let n=e.amount<0n,r=n?-e.amount:e.amount,i=s(t),o=r/i,c=(r%i).toString().padStart(t,`0`);return`${n?`-`:``}${o}.${c}`}function ie(e){let t=a(e.currency);return Number(e.amount)/Number(s(t))}function ae(t,n,r=`half-away-from-zero`){if(!Number.isInteger(n)||n<0)throw new e(`roundTo: places must be a non-negative integer, got ${n}`);let i=a(t.currency);if(n>i)throw new e(`roundTo: places (${n}) exceeds the decimal places for ${t.currency} (${i})`);if(n===i)return t;let o=s(i-n),c=t.amount<0n,l=c?-t.amount:t.amount,u=p(l/o,l%o,o,r,c);return{amount:c?-u:u,currency:t.currency}}exports.CoinsError=e,exports.CurrencyMismatchError=t,exports.InvalidCurrencyError=n,exports.abs=V,exports.add=j,exports.allocate=F,exports.clamp=B,exports.compare=U,exports.divide=P,exports.exchange=m,exports.format=v,exports.formatParts=y,exports.fromJSON=re,exports.getCurrencyDecimals=a,exports.greaterThan=G,exports.greaterThanOrEqual=K,exports.isEqual=W,exports.isMoney=A,exports.isNegative=Z,exports.isNonNegative=Q,exports.isNonPositive=te,exports.isPositive=X,exports.isZero=Y,exports.lessThan=q,exports.lessThanOrEqual=J,exports.max=R,exports.min=L,exports.money=E,exports.multiply=N,exports.negate=H,exports.roundTo=ae,exports.splitEvenly=z,exports.subtract=M,exports.sum=I,exports.toDecimal=$,exports.toJSON=ne,exports.toNumber=ie,exports.validateCurrencyCode=o,exports.withAmount=k;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class e extends Error{code;static is(t){return t instanceof e}constructor(e,t,n){super(t,n),this.code=e,this.name=new.target.name,Object.setPrototypeOf(this,new.target.prototype)}},t=class extends e{expected;received;constructor(e,t){super(`CURRENCY_MISMATCH`,`Currency mismatch: ${e} and ${t}`),this.expected=e,this.received=t}},n=class extends e{value;constructor(e){super(`INVALID_CURRENCY`,`Unsupported currency: "${String(e)}"`),this.value=e}},r=/^(-?)(\d+)(?:\.(\d+))?$/,i=1e3,a=100;function o(t){if(t.length>i)throw new e(`INVALID_DECIMAL`,`Decimal input is too long`);let n=r.exec(t);if(!n)throw new e(`INVALID_DECIMAL`,`Invalid decimal: "${t}"`);let o=(n[3]??``).replace(/0+$/,``);if(o.length>a)throw new e(`INVALID_DECIMAL`,`Decimal precision cannot exceed ${a} places`);let s=10n**BigInt(o.length),c=BigInt(n[2])*s+BigInt(o||`0`),u=n[1]===`-`&&c!==0n?-c:c,d=l(u<0n?-u:u,s);return Object.freeze({denominator:s/d,numerator:u/d})}function s(t,n,r){if(n<=0n)throw new e(`INVALID_DECIMAL`,`Decimal denominator must be positive`);let i=t<0n,a=i?-t:t,o=a/n,s=a%n;if(s===0n)return i?-o:o;let c=(()=>{switch(r){case`awayFromZero`:return!0;case`ceil`:return!i;case`floor`:return i;case`halfAwayFromZero`:return s*2n>=n;case`halfEven`:{let e=s*2n;return e>n||e===n&&o%2n!=0n}case`towardZero`:return!1}})()?o+1n:o;return i?-c:c}function c(e,t){let n=e<0n,r=n?-e:e,i=10n**BigInt(t),a=r/i;if(t===0)return`${n?`-`:``}${a}`;let o=(r%i).toString().padStart(t,`0`);return`${n?`-`:``}${a}.${o}`}function l(e,t){let n=e,r=t;for(;r!==0n;)[n,r]=[r,n%r];return n===0n?1n:n}function u(e,t){return e/l(e,t)*t}var d=new Map,f=new Map;function p(e,t){let n=w(e,t);return d.set(e,n),n}var m=p(`USD`,2),h=p(`EUR`,2),g=p(`GBP`,2),_=p(`JPY`,0),ee=p(`KRW`,0),v=p(`BHD`,3),y=p(`KWD`,3);function b({code:e,minorUnit:t}){T(e,t);let n=d.get(e);if(n){if(n.minorUnit!==t)throw E(e,n.minorUnit);return n}let r=f.get(e);if(r){if(r.minorUnit!==t)throw E(e,r.minorUnit);return r}let i=w(e,t);return f.set(e,i),i}function x(e){let t=d.get(e)??f.get(e);if(!t)throw new n(e);return t}function S(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.code==`string`&&(d.get(t.code)===e||f.get(t.code)===e)}function C(e){let t=d.get(e);if(!t)throw new n(e);return t}function w(e,t){return T(e,t),Object.freeze({code:e,minorUnit:t})}function T(t,n){if(!/^[A-Z]{3}$/.test(t))throw new e(`INVALID_CURRENCY`,`Currency code must be three uppercase letters: "${t}"`);if(!Number.isInteger(n)||n<0||n>6)throw new e(`INVALID_CURRENCY`,`Currency "${t}" must have 0–6 minor-unit digits`)}function E(t,n){return new e(`INVALID_CURRENCY`,`Currency "${t}" already has ${n} minor-unit digits`)}var D=`halfAwayFromZero`;function O(t,n,r){if(z(n),typeof t==`bigint`){if(!r||!(`unit`in r)||r.unit!==`minor`)throw new e(`INVALID_MONEY`,`Bigint amounts require { unit: 'minor' }`);return I(t,n)}if(r&&`unit`in r)throw new e(`INVALID_MONEY`,`Decimal strings do not accept a unit option`);let i=o(t),a=i.numerator*10n**BigInt(n.minorUnit);if(a%i.denominator!==0n&&!r)throw new e(`INVALID_MONEY`,`Amount "${t}" exceeds ${n.code} precision; provide rounding`);return I(s(a,i.denominator,r?.rounding??D),n)}function k(t){if(!B(t))throw new e(`INVALID_MONEY`,`Money must be a plain data object`);let n=Object.getOwnPropertyDescriptors(t),r=n.amount,i=n.currency;if(!V(r)||!V(i))throw new e(`INVALID_MONEY`,`Money properties must be plain data values`);if(typeof r.value!=`bigint`||!S(i.value))throw new e(`INVALID_MONEY`,`Money must contain bigint amount and a registered currency`);return I(r.value,i.value)}function A(e){try{return k(e),!0}catch{return!1}}function te(e,t){return R(e,t),I(e.amount+t.amount,e.currency)}function ne(e,t){return R(e,t),I(e.amount-t.amount,e.currency)}function re(e,t,n={}){L(e);let r=o(t);return I(s(e.amount*r.numerator,r.denominator,n.rounding??D),e.currency)}function ie(t,n,r={}){L(t);let i=o(n);if(i.numerator===0n)throw new e(`DIVISION_BY_ZERO`,`Cannot divide money by zero`);return I(s(t.amount*i.denominator,i.numerator<0n?-i.numerator:i.numerator,r.rounding??D)*(i.numerator<0n?-1n:1n),t.currency)}function j(e,t){return R(e,t),e.amount===t.amount?0:e.amount<t.amount?-1:1}function ae(e){return L(e),I(e.amount<0n?-e.amount:e.amount,e.currency)}function M(e){return L(e),I(-e.amount,e.currency)}function N(t,n){L(t);let{fractionDigits:r,rounding:i=D}=n;if(!Number.isInteger(r)||r<0||r>t.currency.minorUnit)throw new e(`INVALID_ROUNDING`,`fractionDigits must be an integer from 0 to ${t.currency.minorUnit}`);let a=10n**BigInt(t.currency.minorUnit-r);return I(s(t.amount,a,i)*a,t.currency)}function P(e){return L(e),c(e.amount,e.currency.minorUnit)}function F(e,t){return z(t),I(e,t)}function I(e,t){return Object.freeze({amount:e,currency:t})}function L(t){if(!Object.isFrozen(t)||!S(t.currency))throw new e(`INVALID_MONEY`,`Money must be a canonical Coins value`)}function R(e,n){if(L(e),L(n),e.currency!==n.currency)throw new t(e.currency.code,n.currency.code)}function z(t){if(!S(t))throw new e(`INVALID_CURRENCY`,`Money requires a registered currency`)}function B(e){if(typeof e!=`object`||!e)return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function V(e){return e!==void 0&&`value`in e&&e.get===void 0&&e.set===void 0}function H(n,r){let i=0n;for(let a of n){if(!A(a))throw new e(`INVALID_MONEY`,`sum() requires canonical money values`);if(a.currency!==r.currency)throw new t(r.currency.code,a.currency.code);i+=a.amount}return F(i,r.currency)}function U(t,n){if(!A(t))throw new e(`INVALID_MONEY`,`allocate() requires canonical money`);if(typeof n==`number`)return G(t,n);if(n.length===0)throw new e(`INVALID_ALLOCATION`,`Allocation weights cannot be empty`);let r=n.map(o);if(r.some(e=>e.numerator<0n))throw new e(`INVALID_ALLOCATION`,`Allocation weights cannot be negative`);let i=r.reduce((e,t)=>u(e,t.denominator),1n),a=r.map(e=>e.numerator*(i/e.denominator)),s=a.reduce((e,t)=>e+t,0n);if(s===0n)throw new e(`INVALID_ALLOCATION`,`Allocation weights must include a positive value`);let c=t.amount<0n?-1n:1n,l=t.amount<0n?-t.amount:t.amount,d=a.map(e=>l*e/s),f=l-d.reduce((e,t)=>e+t,0n),p=a.map((e,t)=>({index:t,remainder:l*e%s})).sort((e,t)=>e.remainder===t.remainder?e.index-t.index:e.remainder>t.remainder?-1:1);for(let e of p){if(f===0n)break;d[e.index]+=1n,f-=1n}return d.map(e=>F(e*c,t.currency))}function W(t,n){if(j(n.min,n.max)===1)throw new e(`INVALID_ALLOCATION`,`Clamp minimum cannot exceed maximum`);return j(t,n.min)===-1?n.min:j(t,n.max)===1?n.max:t}function G(t,n){if(!Number.isInteger(n)||n<1)throw new e(`INVALID_ALLOCATION`,`Allocation count must be a positive integer`);let r=BigInt(n),i=t.amount<0n?-1n:1n,a=t.amount<0n?-t.amount:t.amount,o=a/r,s=a%r;return Array.from({length:n},(e,n)=>F((o+(BigInt(n)<s?1n:0n))*i,t.currency))}function K({from:t,to:n,value:r}){if(!S(t)||!S(n))throw new e(`INVALID_CURRENCY`,`Exchange rate requires registered currencies`);let i=o(r);if(i.numerator<0n)throw new e(`INVALID_DECIMAL`,`Exchange rates cannot be negative`);return Object.freeze({from:t,to:n,value:i})}function q(n,r,i={}){if(!A(n)||!oe(r))throw new e(`INVALID_MONEY`,`Exchange requires canonical money and rate values`);if(n.currency!==r.from)throw new t(n.currency.code,r.from.code);return F(s(n.amount*r.value.numerator*10n**BigInt(r.to.minorUnit),r.value.denominator*10n**BigInt(r.from.minorUnit),i.rounding??`halfAwayFromZero`),r.to)}function oe(e){if(typeof e!=`object`||!e||!Object.isFrozen(e))return!1;let t=e;return S(t.from)&&S(t.to)&&typeof t.value==`object`&&t.value!==null&&Object.isFrozen(t.value)&&typeof t.value.numerator==`bigint`&&t.value.numerator>=0n&&typeof t.value.denominator==`bigint`&&t.value.denominator>0n}var J=20,Y=new Map,X=new Map;function se(e,t={}){return Z(e,t).map(e=>e.value).join(``)}function Z(t,n={}){if(!A(t))throw new e(`INVALID_MONEY`,`format() requires canonical money`);let{locale:r=`en-US`,maximumFractionDigits:i=t.currency.minorUnit,minimumFractionDigits:a=t.currency.minorUnit,style:o=`symbol`}=n;ce(a,i);let c=10n**BigInt(i),l=i>=t.currency.minorUnit?t.amount*10n**BigInt(i-t.currency.minorUnit):s(t.amount,10n**BigInt(t.currency.minorUnit-i),`halfAwayFromZero`),u=l<0n,d=u?-l:l,f=d/c,p=(i===0?``:(d%c).toString().padStart(i,`0`)).replace(RegExp(`0{0,${Math.max(0,i-a)}}$`),``),m=le(r,t.currency.code,o,u),h=[],g=!1;for(let e of m)e.type!==`group`&&(e.type===`integer`?g||=(h.push({type:`integer`,value:ue(r).format(f)}),!0):e.type===`decimal`?p&&h.push({type:`decimal`,value:e.value}):e.type===`fraction`?p&&h.push({type:`fraction`,value:p}):e.type===`currency`||e.type===`minusSign`||e.type===`plusSign`?h.push({type:e.type,value:e.value}):h.push({type:`literal`,value:e.value}));return h}function ce(t,n){if(!Number.isInteger(n)||!Number.isInteger(t)||t<0||n<t||n>J)throw new e(`INVALID_ROUNDING`,`Fraction digits must be integers satisfying 0 ≤ minimum ≤ maximum ≤ ${J}`)}function le(t,n,r,i){let a=`${t}\0${n}\0${r}\0${i}`,o=X.get(a);if(o)return o;try{let e=new Intl.NumberFormat(t,{currency:n,currencyDisplay:r,maximumFractionDigits:1,minimumFractionDigits:1,style:`currency`}).formatToParts(i?-1.1:1.1);return X.set(a,e),e}catch(r){throw new e(`INVALID_CURRENCY`,`Cannot format currency "${n}" for locale "${t}"`,{cause:r})}}function ue(t){let n=Y.get(t);if(n)return n;try{let e=new Intl.NumberFormat(t,{maximumFractionDigits:0,useGrouping:!0});return Y.set(t,e),e}catch(n){throw new e(`INVALID_ROUNDING`,`Cannot create number formatter for locale "${t}"`,{cause:n})}}var Q=/^(?:0|-[1-9]\d*|[1-9]\d*)$/,$=[`amount`,`currency`,`unit`];function de(e){return{amount:e.amount.toString(),currency:e.currency.code,unit:`minor`}}function fe(t,n={}){try{let e=pe(t),r=n.currency??C;return O(BigInt(e.amount),r(e.currency),{unit:`minor`})}catch(t){throw new e(`INVALID_MONEY`,`Invalid Money JSON`,{cause:t})}}function pe(e){if(typeof e!=`object`||!e||Object.getPrototypeOf(e)!==Object.prototype)throw TypeError(`Money JSON must be a plain object`);let t=Object.getOwnPropertyDescriptors(e),n=Reflect.ownKeys(e);if(n.length!==$.length||!$.every(e=>n.includes(e)))throw TypeError(`Money JSON must contain only amount, currency, and unit`);for(let e of $){let n=t[e];if(!n||!(`value`in n)||n.get||n.set)throw TypeError(`Money JSON property "${e}" must be a data value`)}let r=t.amount.value,i=t.currency.value,a=t.unit.value;if(typeof r!=`string`||!Q.test(r))throw TypeError(`Money JSON amount must be a canonical integer string`);if(typeof i!=`string`||a!==`minor`)throw TypeError(`Money JSON currency/unit are invalid`);return{amount:r,currency:i,unit:a}}exports.BHD=v,exports.CoinsError=e,exports.CurrencyMismatchError=t,exports.EUR=h,exports.GBP=g,exports.InvalidCurrencyError=n,exports.JPY=_,exports.KRW=ee,exports.KWD=y,exports.USD=m,exports.abs=ae,exports.add=te,exports.allocate=U,exports.clamp=W,exports.compare=j,exports.currency=x,exports.decimal=o,exports.defineCurrency=b,exports.divide=ie,exports.exchange=q,exports.exchangeRate=K,exports.format=se,exports.formatParts=Z,exports.isCurrency=S,exports.isMoney=A,exports.money=O,exports.multiply=re,exports.negate=M,exports.parseMoney=k,exports.parseMoneyJSON=fe,exports.round=N,exports.subtract=ne,exports.sum=H,exports.toDecimal=P,exports.toJSON=de;
 //# sourceMappingURL=coins.cjs.map