@vielzeug/coins 1.0.2

package/dist/money.js

@@ -0,0 +1,208 @@
+import { CoinsError as e, CurrencyMismatchError as t } from "./errors.js";
+import { SCIENTIFIC_RE as n, applyRounding as r, expandScientific as i, getCurrencyDecimals as a, parseRational as o, pow10 as s, validateCurrencyCode as c } from "./utils.js";
+import { warn as l } from "./_dev.js";
+//#region src/money.ts
+function u(e, t) {
+	let r = c(t);
+	if (typeof e == "bigint") return {
+		amount: e,
+		currency: r
+	};
+	if (typeof e == "number") {
+		let t = a(r), o = String(e), s = n.test(o) ? i(o) : o, c = s.indexOf("."), u = c === -1 ? 0 : s.length - c - 1;
+		return u > t && l(`money(): number input "${e}" has more decimal places (${u}) than ${r} supports (${t}). Use a decimal string to avoid IEEE-754 precision loss.`), {
+			amount: f(o, t),
+			currency: r
+		};
+	}
+	return {
+		amount: f(String(e), a(r)),
+		currency: r
+	};
+}
+function d(e, n) {
+	if (e.currency !== n.currency) throw new t(e.currency, n.currency);
+}
+function f(e, t) {
+	let { denominator: n, negative: i, numerator: a } = o(e), c = a * s(t), l = r(c / n, c % n, n, "half-away-from-zero");
+	return i ? -l : l;
+}
+function p(e, t) {
+	return {
+		amount: t,
+		currency: e.currency
+	};
+}
+function m(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 h(e, t) {
+	return d(e, t), {
+		amount: e.amount + t.amount,
+		currency: e.currency
+	};
+}
+function g(e, t) {
+	return d(e, t), {
+		amount: e.amount - t.amount,
+		currency: e.currency
+	};
+}
+function _(e, t, n = "half-away-from-zero") {
+	let { denominator: i, negative: a, numerator: s } = o(String(t)), c = e.amount < 0n !== a, l = (e.amount < 0n ? -e.amount : e.amount) * s, u = r(l / i, l % i, i, n, c);
+	return {
+		amount: c ? -u : u,
+		currency: e.currency
+	};
+}
+function v(t, n, i = "half-away-from-zero") {
+	let { denominator: a, negative: s, numerator: c } = o(String(n));
+	if (c === 0n) throw new e("Division by zero");
+	let l = t.amount < 0n !== s, u = (t.amount < 0n ? -t.amount : t.amount) * a, d = r(u / c, u % c, c, i, l);
+	return {
+		amount: l ? -d : d,
+		currency: t.currency
+	};
+}
+function y(t, n) {
+	if (n.length === 0) throw new e("allocate requires at least one ratio");
+	let r = n.map((e) => o(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, s = r.reduce((e, t) => t.denominator > e ? t.denominator : e, 1n), c = r.map((e) => e.numerator * (s / e.denominator)), l = c.reduce((e, t) => e + t, 0n), u = [], d = [];
+	for (let e of c) {
+		let t = a * e;
+		u.push(t / l), d.push(t % l);
+	}
+	let f = n.map((e, t) => t).sort((e, t) => {
+		let n = d[t] - d[e];
+		return n > 0n ? 1 : n < 0n ? -1 : 0;
+	}), p = [...u], m = a - u.reduce((e, t) => e + t, 0n);
+	for (let e = 0; m > 0n; e++, m--) p[f[e]] += 1n;
+	return p.map((e) => ({
+		amount: i ? -e : e,
+		currency: t.currency
+	}));
+}
+function b(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 x(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 = D(n, t[e]) <= 0 ? n : t[e];
+	return n;
+}
+function S(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 = D(n, t[e]) >= 0 ? n : t[e];
+	return n;
+}
+function C(t, n) {
+	if (!Number.isInteger(n) || n <= 0) throw new e("splitEvenly requires a positive integer number of parts");
+	return y(t, Array.from({ length: n }, () => 1));
+}
+function w(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 (D(r, i) > 0) throw new e(`clamp: lower (${B(r)} ${r.currency}) must be <= upper (${B(i)} ${i.currency})`);
+	return S([r, x([n, i])]);
+}
+function T(e) {
+	return {
+		amount: e.amount < 0n ? -e.amount : e.amount,
+		currency: e.currency
+	};
+}
+function E(e) {
+	return {
+		amount: -e.amount,
+		currency: e.currency
+	};
+}
+function D(e, t) {
+	return d(e, t), e.amount < t.amount ? -1 : +(e.amount > t.amount);
+}
+function O(e, t) {
+	return e.currency === t.currency && e.amount === t.amount;
+}
+function k(e, t) {
+	return D(e, t) > 0;
+}
+function A(e, t) {
+	return D(e, t) >= 0;
+}
+function j(e, t) {
+	return D(e, t) < 0;
+}
+function M(e, t) {
+	return D(e, t) <= 0;
+}
+function N(e) {
+	return e.amount === 0n;
+}
+function P(e) {
+	return e.amount > 0n;
+}
+function F(e) {
+	return e.amount < 0n;
+}
+function I(e) {
+	return e.amount >= 0n;
+}
+function L(e) {
+	return e.amount <= 0n;
+}
+function R(e) {
+	return {
+		amount: String(e.amount),
+		currency: e.currency
+	};
+}
+function z(t) {
+	let n = c(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 B(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 V(e) {
+	let t = a(e.currency);
+	return Number(e.amount) / Number(s(t));
+}
+function H(t, n, i = "half-away-from-zero") {
+	if (!Number.isInteger(n) || n < 0) throw new e(`roundTo: places must be a non-negative integer, got ${n}`);
+	let o = a(t.currency);
+	if (n > o) throw new e(`roundTo: places (${n}) exceeds the decimal places for ${t.currency} (${o})`);
+	if (n === o) return t;
+	let c = s(o - n), l = t.amount < 0n, u = l ? -t.amount : t.amount, d = r(u / c, u % c, c, i, l);
+	return {
+		amount: l ? -d : d,
+		currency: t.currency
+	};
+}
+//#endregion
+export { T as abs, h as add, y as allocate, w as clamp, D as compare, v as divide, z as fromJSON, k as greaterThan, A as greaterThanOrEqual, O as isEqual, m as isMoney, F as isNegative, I as isNonNegative, L as isNonPositive, P as isPositive, N as isZero, j as lessThan, M as lessThanOrEqual, S as max, x as min, u as money, _ as multiply, E as negate, H as roundTo, C as splitEvenly, g as subtract, b as sum, B as toDecimal, R as toJSON, V as toNumber, p as withAmount };
+
+//# sourceMappingURL=money.js.map

package/dist/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","names":[],"sources":["../src/money.ts"],"sourcesContent":["import type { CurrencyCode, Money, MoneyJSON, RoundingMode } from './types';\n\nimport { warn } from './_dev';\nimport { CoinsError, CurrencyMismatchError } from './errors';\nimport {\n  applyRounding,\n  expandScientific,\n  getCurrencyDecimals,\n  parseRational,\n  pow10,\n  SCIENTIFIC_RE,\n  validateCurrencyCode,\n} from './utils';\n\nexport { CoinsError, CurrencyMismatchError, InvalidCurrencyError } from './errors';\n\n// ─── Factories ───────────────────────────────────────────────────────────────\n\n/**\n * Creates a `Money` value from a decimal string, number, or raw bigint minor units.\n * Validates the currency code — throws `InvalidCurrencyError` for unrecognised ISO 4217 codes.\n *\n * - **string** `'1234.56'` → parsed losslessly; respects the currency's decimal places.\n * - **number** `1234.56` → converted via `String()` first; inherits IEEE-754 limits.\n *   Prefer strings when precision matters.\n * - **bigint** `123456n` → used as-is (already in minor units).\n *\n * @example\n * ```ts\n * money('1234.56', 'USD') // { amount: 123456n, currency: 'USD' }\n * money(1234,      'JPY') // { amount: 1234n,   currency: 'JPY' }\n * money(123456n,   'USD') // { amount: 123456n, currency: 'USD' }\n * ```\n */\nexport function money(amount: bigint | number | string, currency: CurrencyCode): Money {\n  const validCurrency = validateCurrencyCode(currency);\n\n  if (typeof amount === 'bigint') {\n    return { amount, currency: validCurrency };\n  }\n\n  if (typeof amount === 'number') {\n    const decimals = getCurrencyDecimals(validCurrency);\n    const str = String(amount);\n    // Expand scientific notation (e.g. String(1e-7) === '1e-7') before measuring fraction\n    // length — otherwise inputs like 1e-7 report 0 fractional digits and skip the warning\n    // below despite having far more precision than the currency supports.\n    const normalized = SCIENTIFIC_RE.test(str) ? expandScientific(str) : str;\n    const dotIndex = normalized.indexOf('.');\n    const fracLen = dotIndex === -1 ? 0 : normalized.length - dotIndex - 1;\n\n    if (fracLen > decimals) {\n      warn(\n        `money(): number input \"${amount}\" has more decimal places (${fracLen}) than ${validCurrency} supports (${decimals}). ` +\n          `Use a decimal string to avoid IEEE-754 precision loss.`,\n      );\n    }\n\n    // getCurrencyDecimals is cached from the validateCurrencyCode call above.\n    return { amount: parseToMinorUnits(str, decimals), currency: validCurrency };\n  }\n\n  // getCurrencyDecimals is cached from the validateCurrencyCode call above.\n  return { amount: parseToMinorUnits(String(amount), getCurrencyDecimals(validCurrency)), currency: validCurrency };\n}\n\n// ─── Internal ─────────────────────────────────────────────────────────────────\n\nfunction assertSameCurrency(a: Money, b: Money): void {\n  if (a.currency !== b.currency) {\n    throw new CurrencyMismatchError(a.currency, b.currency);\n  }\n}\n\n/**\n * Converts a decimal string to minor units for the given decimal precision.\n * Uses parseRational + applyRounding to share the single rounding implementation.\n */\nfunction parseToMinorUnits(str: string, decimals: number): bigint {\n  const { denominator, negative, numerator } = parseRational(str);\n  // numerator/denominator × 10^decimals = numerator × 10^decimals / denominator\n  const scale = pow10(decimals);\n  const raw = numerator * scale;\n  const quotient = raw / denominator;\n  const result = applyRounding(quotient, raw % denominator, denominator, 'half-away-from-zero');\n\n  return negative ? -result : result;\n}\n\n/**\n * Creates a new `Money` value with the given `amount` and the same currency as `m`.\n * Useful when you compute a raw `bigint` amount externally and need to wrap it\n * back into a `Money` value without re-validating the currency.\n *\n * @example\n * ```ts\n * const price = money('9.99', 'USD');\n * withAmount(price, 1999n)  // { amount: 1999n, currency: 'USD' }\n * ```\n */\nexport function withAmount(m: Money, amount: bigint): Money {\n  return { amount, currency: m.currency };\n}\n\n/**\n * Type guard that returns `true` if `value` is a `Money`-shaped object\n * (has a `bigint` `amount` and a `string` `currency`).\n * Useful for narrowing unknown payloads from APIs or deserialized storage.\n *\n * Note: does **not** validate the currency code — use `money(0n, currency)` or\n * `validateCurrencyCode()` if you also need to confirm it is a recognized ISO 4217 code.\n *\n * @example\n * ```ts\n * isMoney({ amount: 100n, currency: 'USD' })  // true\n * isMoney({ amount: 1.5, currency: 'USD' })   // false\n * isMoney(null)                               // false\n * ```\n */\nexport function isMoney(value: unknown): value is Money {\n  if (typeof value !== 'object' || value === null) return false;\n\n  const v = value as Record<string, unknown>;\n\n  return (\n    Object.hasOwn(v, 'amount') &&\n    typeof v.amount === 'bigint' &&\n    Object.hasOwn(v, 'currency') &&\n    typeof v.currency === 'string'\n  );\n}\n\n// ─── Arithmetic ──────────────────────────────────────────────────────────────\n\n/** Adds two `Money` values. Throws if their currencies differ. */\nexport function add(a: Money, b: Money): Money {\n  assertSameCurrency(a, b);\n\n  return { amount: a.amount + b.amount, currency: a.currency };\n}\n\n/** Subtracts `b` from `a`. Throws if their currencies differ. */\nexport function subtract(a: Money, b: Money): Money {\n  assertSameCurrency(a, b);\n\n  return { amount: a.amount - b.amount, currency: a.currency };\n}\n\n/**\n * Multiplies a `Money` value by a scalar factor.\n * The factor can be a decimal string (lossless) or a number.\n *\n * @param mode Rounding mode for fractional minor units. Defaults to `'half-away-from-zero'`.\n *\n * @example\n * ```ts\n * multiply(money('100.00', 'USD'), '1.5')              // $150.00\n * multiply(money('1.00', 'USD'), '0.339', 'floor')     // $0.33\n * multiply(money('1.00', 'USD'), '0.339', 'ceiling')   // $0.34\n * ```\n */\nexport function multiply(m: Money, factor: number | string, mode: RoundingMode = 'half-away-from-zero'): Money {\n  const { denominator, negative: factorNegative, numerator } = parseRational(String(factor));\n  const negative = m.amount < 0n !== factorNegative;\n  const absAmount = m.amount < 0n ? -m.amount : m.amount;\n  const raw = absAmount * numerator;\n  const quotient = raw / denominator;\n  const result = applyRounding(quotient, raw % denominator, denominator, mode, negative);\n\n  return { amount: negative ? -result : result, currency: m.currency };\n}\n\n/**\n * Divides a `Money` value by a scalar divisor.\n * The divisor can be a decimal string (lossless) or a number.\n *\n * @param mode Rounding mode for fractional minor units. Defaults to `'half-away-from-zero'`.\n * @throws {CoinsError} On division by zero.\n *\n * @example\n * ```ts\n * divide(money('100.00', 'USD'), 3)              // $33.33\n * divide(money('100.00', 'USD'), 3, 'ceiling')   // $33.34\n * ```\n */\nexport function divide(m: Money, divisor: number | string, mode: RoundingMode = 'half-away-from-zero'): Money {\n  const { denominator: parsedDenom, negative: divisorNegative, numerator } = parseRational(String(divisor));\n\n  if (numerator === 0n) throw new CoinsError('Division by zero');\n\n  const negative = m.amount < 0n !== divisorNegative;\n  const absAmount = m.amount < 0n ? -m.amount : m.amount;\n  // Dividing by (numerator/parsedDenom) = multiplying by (parsedDenom/numerator).\n  const raw = absAmount * parsedDenom;\n  const quotient = raw / numerator;\n  const result = applyRounding(quotient, raw % numerator, numerator, mode, negative);\n\n  return { amount: negative ? -result : result, currency: m.currency };\n}\n\n/**\n * Distributes `money` across `ratios` without losing or gaining a single minor unit.\n * Accepts both number and string ratios — use strings for lossless decimal weights.\n *\n * Uses the Largest Remainder Method: each share gets its floor allocation first,\n * then any remainder units are assigned one-by-one to the shares with the largest\n * fractional parts, breaking ties by original index (stable, left-to-right).\n *\n * Throws if `ratios` is empty, contains negative values (including negative strings like `'-0.5'`), or sums to zero.\n *\n * @example\n * ```ts\n * allocate(money('10.00', 'USD'), [1, 1, 1])\n * // → [$3.34, $3.33, $3.33]   (not three × $3.33 — that loses a penny)\n *\n * allocate(money('10.00', 'USD'), ['0.3', '0.7'])\n * // → [$3.00, $7.00]\n * ```\n */\nexport function allocate(m: Money, ratios: readonly (number | string)[]): [Money, ...Money[]] {\n  if (ratios.length === 0) throw new CoinsError('allocate requires at least one ratio');\n\n  const parsedRatios = ratios.map((r) => parseRational(String(r)));\n\n  if (parsedRatios.some((p) => p.negative)) throw new CoinsError('All ratios must be non-negative');\n\n  if (!parsedRatios.some((p) => p.numerator > 0n)) throw new CoinsError('At least one ratio must be positive');\n\n  const negative = m.amount < 0n;\n  const absAmount = negative ? -m.amount : m.amount;\n\n  // All denominators are powers of 10; the max is their LCM — use it to normalise weights to integers.\n  const maxDenominator = parsedRatios.reduce((max, p) => (p.denominator > max ? p.denominator : max), 1n);\n  const bigWeights = parsedRatios.map((p) => p.numerator * (maxDenominator / p.denominator));\n  const bigTotal = bigWeights.reduce((a, b) => a + b, 0n);\n\n  // Floor allocation + fractional remainders.\n  const floors: bigint[] = [];\n  const fracRemainders: bigint[] = [];\n\n  for (const w of bigWeights) {\n    const ideal = absAmount * w;\n\n    floors.push(ideal / bigTotal);\n    fracRemainders.push(ideal % bigTotal);\n  }\n\n  // Distribute leftover units to the shares with the largest fractional remainders.\n  // Relies on V8/SpiderMonkey's stable sort (ECMAScript 2019+ spec-mandated): ties\n  // in fractional remainders are broken by original index (left-to-right), ensuring\n  // deterministic output for equal-weight ratios (e.g. [1, 1, 1]).\n  const indices = ratios\n    .map((_, i) => i)\n    .sort((a, b) => {\n      const diff = fracRemainders[b]! - fracRemainders[a]!;\n\n      return diff > 0n ? 1 : diff < 0n ? -1 : 0;\n    });\n\n  const result = [...floors];\n  // `remaining` is always < ratios.length (at most one unit per share), safe for this loop.\n  let remaining = absAmount - floors.reduce((a, b) => a + b, 0n);\n\n  for (let i = 0; remaining > 0n; i++, remaining--) {\n    result[indices[i]!]! += 1n;\n  }\n\n  return result.map((amount) => ({ amount: negative ? -amount : amount, currency: m.currency })) as [Money, ...Money[]];\n}\n\n// ─── Aggregates ──────────────────────────────────────────────────────────────\n\n/**\n * Sums an array of `Money` values. Throws if the array is empty or currencies differ.\n *\n * @example\n * ```ts\n * sum([money('1.00', 'USD'), money('2.50', 'USD')]) // $3.50\n * ```\n */\nexport function sum(moneys: readonly Money[]): Money {\n  if (moneys.length === 0) throw new CoinsError('sum requires at least one Money value');\n\n  const currency = moneys[0]!.currency;\n\n  for (let i = 1; i < moneys.length; i++) {\n    if (moneys[i]!.currency !== currency) {\n      throw new CurrencyMismatchError(currency, moneys[i]!.currency);\n    }\n  }\n\n  return { amount: moneys.reduce((acc, m) => acc + m.amount, 0n), currency };\n}\n\n/**\n * Returns the smallest `Money` value from a non-empty array. Throws if currencies differ.\n *\n * @example\n * ```ts\n * min([money('3.00', 'USD'), money('1.00', 'USD'), money('2.00', 'USD')]) // $1.00\n * ```\n */\nexport function min(moneys: readonly Money[]): Money {\n  if (moneys.length === 0) throw new CoinsError('min requires at least one Money value');\n\n  let result = moneys[0]!;\n\n  for (let i = 1; i < moneys.length; i++) result = compare(result, moneys[i]!) <= 0 ? result : moneys[i]!;\n\n  return result;\n}\n\n/**\n * Returns the largest `Money` value from a non-empty array. Throws if currencies differ.\n *\n * @example\n * ```ts\n * max([money('1.00', 'USD'), money('3.00', 'USD'), money('2.00', 'USD')]) // $3.00\n * ```\n */\nexport function max(moneys: readonly Money[]): Money {\n  if (moneys.length === 0) throw new CoinsError('max requires at least one Money value');\n\n  let result = moneys[0]!;\n\n  for (let i = 1; i < moneys.length; i++) result = compare(result, moneys[i]!) >= 0 ? result : moneys[i]!;\n\n  return result;\n}\n\n/**\n * Splits `money` into `parts` equal shares without losing or gaining a single minor unit.\n * Equivalent to `allocate(money, Array.from({ length: parts }, () => 1))`.\n *\n * @throws {CoinsError} If `parts` is not a positive integer (≥ 1).\n *\n * @example\n * ```ts\n * splitEvenly(money('10.00', 'USD'), 3)\n * // → [$3.34, $3.33, $3.33]\n * ```\n */\nexport function splitEvenly(m: Money, parts: number): [Money, ...Money[]] {\n  if (!Number.isInteger(parts) || parts <= 0) {\n    throw new CoinsError('splitEvenly requires a positive integer number of parts');\n  }\n\n  return allocate(\n    m,\n    Array.from({ length: parts }, () => 1),\n  );\n}\n\n/**\n * Clamps `m` to the inclusive range `[lower, upper]`.\n *\n * @throws {CurrencyMismatchError} If `m`, `lower`, or `upper` have different currencies.\n * @throws {CoinsError}            If `lower > upper`.\n *\n * @example\n * ```ts\n * clamp(money('5.00', 'USD'), money('1.00', 'USD'), money('10.00', 'USD'))  // $5.00\n * clamp(money('0.00', 'USD'), money('1.00', 'USD'), money('10.00', 'USD'))  // $1.00\n * clamp(money('15.00', 'USD'), money('1.00', 'USD'), money('10.00', 'USD')) // $10.00\n * ```\n */\nexport function clamp(m: Money, lower: Money, upper: Money): Money {\n  // Validate currency consistency upfront so the error always names the mismatch,\n  // rather than surfacing mid-computation from min() or max().\n  if (m.currency !== lower.currency || m.currency !== upper.currency) {\n    throw new CurrencyMismatchError(m.currency, m.currency !== lower.currency ? lower.currency : upper.currency);\n  }\n\n  if (compare(lower, upper) > 0) {\n    throw new CoinsError(\n      `clamp: lower (${toDecimal(lower)} ${lower.currency}) must be <= upper (${toDecimal(upper)} ${upper.currency})`,\n    );\n  }\n\n  return max([lower, min([m, upper])]);\n}\n\n// ─── Unary ───────────────────────────────────────────────────────────────────\n\n/** Returns the absolute value of `money`. Negative amounts become positive. */\nexport function abs(m: Money): Money {\n  return { amount: m.amount < 0n ? -m.amount : m.amount, currency: m.currency };\n}\n\n/** Returns `money` with its sign flipped. */\nexport function negate(m: Money): Money {\n  return { amount: -m.amount, currency: m.currency };\n}\n\n// ─── Comparison ──────────────────────────────────────────────────────────────\n\n/**\n * Compares two `Money` values. Returns `-1`, `0`, or `1`.\n * Throws if their currencies differ.\n */\nexport function compare(a: Money, b: Money): -1 | 0 | 1 {\n  assertSameCurrency(a, b);\n\n  if (a.amount < b.amount) return -1;\n\n  if (a.amount > b.amount) return 1;\n\n  return 0;\n}\n\n/**\n * Returns `true` if both `Money` values have the same currency and amount.\n * Returns `false` if currencies differ — safe to use in `.filter()` and conditional chains.\n */\nexport function isEqual(a: Money, b: Money): boolean {\n  return a.currency === b.currency && a.amount === b.amount;\n}\n\n/** Returns `true` if `a` is strictly greater than `b`. Throws on currency mismatch. */\nexport function greaterThan(a: Money, b: Money): boolean {\n  return compare(a, b) > 0;\n}\n\n/** Returns `true` if `a` is greater than or equal to `b`. Throws on currency mismatch. */\nexport function greaterThanOrEqual(a: Money, b: Money): boolean {\n  return compare(a, b) >= 0;\n}\n\n/** Returns `true` if `a` is strictly less than `b`. Throws on currency mismatch. */\nexport function lessThan(a: Money, b: Money): boolean {\n  return compare(a, b) < 0;\n}\n\n/** Returns `true` if `a` is less than or equal to `b`. Throws on currency mismatch. */\nexport function lessThanOrEqual(a: Money, b: Money): boolean {\n  return compare(a, b) <= 0;\n}\n\n// ─── Predicates ──────────────────────────────────────────────────────────────\n\n/** Returns `true` if the amount is exactly zero. */\nexport function isZero(m: Money): boolean {\n  return m.amount === 0n;\n}\n\n/** Returns `true` if the amount is strictly positive (> 0). */\nexport function isPositive(m: Money): boolean {\n  return m.amount > 0n;\n}\n\n/** Returns `true` if the amount is strictly negative (< 0). */\nexport function isNegative(m: Money): boolean {\n  return m.amount < 0n;\n}\n\n/** Returns `true` if the amount is zero or positive (>= 0). */\nexport function isNonNegative(m: Money): boolean {\n  return m.amount >= 0n;\n}\n\n/** Returns `true` if the amount is zero or negative (<= 0). */\nexport function isNonPositive(m: Money): boolean {\n  return m.amount <= 0n;\n}\n\n// ─── Serialization ───────────────────────────────────────────────────────────\n\n/**\n * Serializes a `Money` value to a plain-object JSON-safe form.\n * `amount` is a bigint string (e.g. `'123456'`) to avoid `JSON.stringify` throwing.\n *\n * @example\n * ```ts\n * toJSON(money('1234.56', 'USD')) // { amount: '123456', currency: 'USD' }\n * JSON.stringify(toJSON(price))   // '{\"amount\":\"123456\",\"currency\":\"USD\"}'\n * ```\n */\nexport function toJSON(m: Money): MoneyJSON {\n  return { amount: String(m.amount), currency: m.currency };\n}\n\n/**\n * Deserializes a `MoneyJSON` object back into a `Money` value.\n * Validates the currency code and the amount string.\n *\n * @example\n * ```ts\n * fromJSON({ amount: '123456', currency: 'USD' }) // { amount: 123456n, currency: 'USD' }\n * ```\n */\nexport function fromJSON(json: MoneyJSON): Money {\n  const validCurrency = validateCurrencyCode(json.currency);\n\n  if (typeof json.amount !== 'string') {\n    throw new CoinsError(\n      `Invalid money amount in JSON: ${String(json.amount)} (expected an integer string, e.g. '123456')`,\n    );\n  }\n\n  let amount: bigint;\n\n  try {\n    amount = BigInt(json.amount);\n  } catch {\n    throw new CoinsError(`Invalid money amount in JSON: \"${json.amount}\" (expected an integer string, e.g. '123456')`);\n  }\n\n  return { amount, currency: validCurrency };\n}\n\n/**\n * Serializes a `Money` value to a decimal string (e.g. `'1234.56'`).\n * Round-trips losslessly with `money()`.\n *\n * @example\n * ```ts\n * toDecimal(money('1234.56', 'USD')) // '1234.56'\n * toDecimal(money(5n, 'USD'))        // '0.05'\n * toDecimal(money(1234n, 'JPY'))     // '1234'\n * ```\n */\nexport function toDecimal(m: Money): string {\n  const decimals = getCurrencyDecimals(m.currency);\n\n  if (decimals === 0) return String(m.amount);\n\n  const negative = m.amount < 0n;\n  const abs = negative ? -m.amount : m.amount;\n  const scale = pow10(decimals);\n  const whole = abs / scale;\n  const frac = (abs % scale).toString().padStart(decimals, '0');\n\n  return `${negative ? '-' : ''}${whole}.${frac}`;\n}\n\n/**\n * Converts a `Money` value to a floating-point number.\n * Useful for charting and display; **not** for arithmetic (lossy).\n *\n * @example\n * ```ts\n * toNumber(money('1234.56', 'USD')) // 1234.56\n * ```\n */\nexport function toNumber(m: Money): number {\n  const decimals = getCurrencyDecimals(m.currency);\n\n  return Number(m.amount) / Number(pow10(decimals));\n}\n\n// ─── Rounding ─────────────────────────────────────────────────────────────────\n\n/**\n * Rounds a `Money` value to fewer decimal places than the currency's default.\n * `places` must be a non-negative integer in the range `0..currencyDecimals`.\n *\n * Useful for display purposes (e.g. rounding USD to whole dollars).\n * @throws {CoinsError} If `places` is out of the allowed range.\n *\n * @param mode Rounding mode. Defaults to `'half-away-from-zero'`.\n *\n * @example\n * ```ts\n * roundTo(money('1234.56', 'USD'), 0)          // $1235   (whole dollars)\n * roundTo(money('1234.56', 'USD'), 1)          // $1234.6\n * roundTo(money('1234.56', 'USD'), 1, 'floor') // $1234.5\n * roundTo(money('1234', 'JPY'), 0)             // ¥1234   (no-op: JPY is already 0-decimal)\n * ```\n */\nexport function roundTo(m: Money, places: number, mode: RoundingMode = 'half-away-from-zero'): Money {\n  if (!Number.isInteger(places) || places < 0) {\n    throw new CoinsError(`roundTo: places must be a non-negative integer, got ${places}`);\n  }\n\n  const currencyDecimals = getCurrencyDecimals(m.currency);\n\n  if (places > currencyDecimals) {\n    throw new CoinsError(\n      `roundTo: places (${places}) exceeds the decimal places for ${m.currency} (${currencyDecimals})`,\n    );\n  }\n\n  if (places === currencyDecimals) return m;\n\n  const drop = currencyDecimals - places;\n  const divisor = pow10(drop);\n  const negative = m.amount < 0n;\n  const absAmount = negative ? -m.amount : m.amount;\n  const quotient = absAmount / divisor;\n  const remainder = absAmount % divisor;\n  const rounded = applyRounding(quotient, remainder, divisor, mode, negative);\n\n  return { amount: negative ? -rounded : rounded, currency: m.currency };\n}\n"],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A validated ISO 4217 currency code string (e.g. `'USD'`, `'EUR'`, `'JPY'`).
+ * Plain string alias — runtime validation is performed by every function that
+ * accepts a currency, and violations throw `InvalidCurrencyError`.
+ */
+export type CurrencyCode = string;
+/** A monetary value. `amount` is stored as bigint minor units (e.g. cents for USD). */
+export type Money = {
+    readonly amount: bigint;
+    readonly currency: CurrencyCode;
+};
+/**
+ * An exchange rate between two currencies.
+ * - `from` must match the `currency` of the `Money` passed to `exchange()`.
+ *   Since every `Money.currency` is already a validated ISO 4217 code, a matching
+ *   `from` is implicitly valid.
+ * - `to` is validated as a recognised ISO 4217 code by `exchange()` before returning.
+ * - `rate` is a decimal string (e.g. `'0.847532'`) or number, for symmetry with
+ *   `multiply()`/`divide()`. Prefer a string when precision matters — a number is
+ *   converted via `String()` first and inherits IEEE-754 limits.
+ */
+export type ExchangeRate = {
+    readonly from: CurrencyCode;
+    readonly rate: number | string;
+    readonly to: CurrencyCode;
+};
+/** Options for `format()`. */
+export type FormatOptions = {
+    locale?: string;
+    maximumFractionDigits?: number;
+    minimumFractionDigits?: number;
+    style?: 'code' | 'name' | 'narrowSymbol' | 'symbol';
+};
+/**
+ * Rounding mode for operations that produce fractional minor units.
+ *
+ * | Mode | Description |
+ * |---|---|
+ * | `'ceiling'` | Toward +∞ (up for positives, truncate for negatives) |
+ * | `'down'` | Toward zero (truncate, regardless of sign) |
+ * | `'floor'` | Toward −∞ (truncate for positives, down for negatives) |
+ * | `'half-away-from-zero'` | Round half away from zero (default, common in finance) |
+ * | `'half-even'` | Round half to even (banker's rounding, minimises cumulative error) |
+ * | `'up'` | Away from zero (regardless of sign) |
+ */
+export type RoundingMode = 'ceiling' | 'down' | 'floor' | 'half-away-from-zero' | 'half-even' | 'up';
+/** JSON-safe representation of `Money`. `amount` is a decimal integer string to avoid bigint serialization issues. */
+export type MoneyJSON = {
+    amount: string;
+    currency: string;
+};
+/**
+ * A single semantic part of a formatted money string, as returned by `formatParts()`.
+ * Useful for custom rendering (e.g. applying different CSS to symbol, integer, fraction).
+ */
+export type MoneyFormatPart = {
+    type: 'currency' | 'decimal' | 'fraction' | 'integer' | 'literal' | 'minusSign';
+    value: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,uFAAuF;AACvF,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;CAC3B,CAAC;AAEF,8BAA8B;AAC9B,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,GAAG,QAAQ,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,qBAAqB,GAAG,WAAW,GAAG,IAAI,CAAC;AAErG,sHAAsH;AACtH,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAChF,KAAK,EAAE,MAAM,CAAC;CACf,CAAC"}

package/dist/utils.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs");var t=require("./_cache.cjs").boundedCache(512);function n(n){let r=t.get(n);if(r!==void 0)return r;let i;try{i=new Intl.NumberFormat(`en`,{currency:n,style:`currency`}).resolvedOptions().maximumFractionDigits}catch{throw new e.InvalidCurrencyError(n)}if(i===void 0)throw new e.InvalidCurrencyError(n);return t.set(n,i),i}function r(e){return n(e),e}function i(e){return 10n**BigInt(e)}var a=/^-?\d+(\.\d+)?$/,o=/^(-?\d+\.?\d*)[eE]([+-]?\d+)$/,s=1e3;function c(t){let n=o.exec(t),r=n[1],i=parseInt(n[2],10);if(Math.abs(i)>s)throw new e.CoinsError(`Scientific notation exponent too large: "${t}" (max ±${s})`);let a=r.startsWith(`-`),c=a?r.slice(1):r,l=c.indexOf(`.`),u=l===-1?c:c.replace(`.`,``),d=i-(l===-1?0:c.length-l-1),f;if(d>=0)f=u+`0`.repeat(d);else{let e=u.length+d;f=e<=0?`0.`+`0`.repeat(-e)+u:u.slice(0,e)+`.`+u.slice(e)}return a?`-${f}`:f}function l(t){let n=o.test(t)?c(t):t;if(!a.test(n))throw new e.CoinsError(`Invalid decimal string: "${t}"`);let r=n.startsWith(`-`),s=r?n.slice(1):n,l=s.indexOf(`.`),u=l===-1?s:s.slice(0,l),d=l===-1?``:s.slice(l+1),f=i(d.length);return{denominator:f,negative:r,numerator:BigInt(u||`0`)*f+BigInt(d||`0`)}}function u(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.CoinsError(`Unknown rounding mode: ${String(i)}`)}}exports.SCIENTIFIC_RE=o,exports.applyRounding=u,exports.expandScientific=c,exports.getCurrencyDecimals=n,exports.parseRational=l,exports.pow10=i,exports.validateCurrencyCode=r;
+//# sourceMappingURL=utils.cjs.map

package/dist/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.cjs","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import type { CurrencyCode, RoundingMode } from './types';\n\nimport { boundedCache } from './_cache';\nimport { CoinsError, InvalidCurrencyError } from './errors';\n\nconst currencyDecimalsCache = boundedCache<string, number>(512);\n\n/**\n * Returns the number of minor-unit decimal places for a given ISO 4217 currency code.\n * Uses `Intl.NumberFormat` to resolve the canonical value (e.g. USD→2, JPY→0, KWD→3).\n * Throws `InvalidCurrencyError` for unrecognized codes or when the runtime cannot determine decimals.\n */\nexport function getCurrencyDecimals(currencyCode: CurrencyCode): number {\n  const cached = currencyDecimalsCache.get(currencyCode);\n\n  if (cached !== undefined) return cached;\n\n  let resolved: number | undefined;\n\n  try {\n    resolved = new Intl.NumberFormat('en', { currency: currencyCode, style: 'currency' }).resolvedOptions()\n      .maximumFractionDigits;\n  } catch {\n    throw new InvalidCurrencyError(currencyCode);\n  }\n\n  if (resolved === undefined) {\n    throw new InvalidCurrencyError(currencyCode);\n  }\n\n  currencyDecimalsCache.set(currencyCode, resolved);\n\n  return resolved;\n}\n\n/**\n * Validates an ISO 4217 currency code and returns it.\n * Throws `InvalidCurrencyError` if unrecognized. Uses `getCurrencyDecimals` internally so\n * the result is cached for subsequent decimal lookups.\n */\nexport function validateCurrencyCode(code: CurrencyCode): CurrencyCode {\n  getCurrencyDecimals(code);\n\n  return code;\n}\n\n/** Returns `10n ** BigInt(exponent)`. */\nexport function pow10(exponent: number): bigint {\n  return 10n ** BigInt(exponent);\n}\n\n/** Regex for valid decimal strings accepted by `parseRational`. */\nconst DECIMAL_RE = /^-?\\d+(\\.\\d+)?$/;\n\n/** Regex matching JavaScript scientific-notation strings, e.g. `'1e-7'`, `'-3.14E+5'`. */\nexport const SCIENTIFIC_RE = /^(-?\\d+\\.?\\d*)[eE]([+-]?\\d+)$/;\n\n/** Maximum absolute exponent allowed in scientific notation. Prevents '0'.repeat(N) allocation attacks. */\nconst MAX_SCIENTIFIC_EXP = 1000;\n\n/**\n * Expands a scientific-notation decimal string into a plain decimal string.\n * `'1e-7'` → `'0.0000001'`, `'1.23e+5'` → `'123000'`.\n * Only called when `SCIENTIFIC_RE` already matched — no extra validation.\n * @throws {CoinsError} If the absolute exponent exceeds `MAX_SCIENTIFIC_EXP` (1000).\n */\nexport function expandScientific(s: string): string {\n  const match = SCIENTIFIC_RE.exec(s)!;\n  const coeff = match[1]!;\n  const exp = parseInt(match[2]!, 10);\n\n  if (Math.abs(exp) > MAX_SCIENTIFIC_EXP) {\n    throw new CoinsError(`Scientific notation exponent too large: \"${s}\" (max ±${MAX_SCIENTIFIC_EXP})`);\n  }\n\n  const isNeg = coeff.startsWith('-');\n  const absCoeff = isNeg ? coeff.slice(1) : coeff;\n  const dotIndex = absCoeff.indexOf('.');\n  const digits = dotIndex === -1 ? absCoeff : absCoeff.replace('.', '');\n  const fracLen = dotIndex === -1 ? 0 : absCoeff.length - dotIndex - 1;\n  const newExp = exp - fracLen; // where the decimal point sits relative to end of digits\n\n  let result: string;\n\n  if (newExp >= 0) {\n    // All digits are to the left of the decimal — append trailing zeros\n    result = digits + '0'.repeat(newExp);\n  } else {\n    const intLen = digits.length + newExp; // digits before the decimal point\n\n    if (intLen <= 0) {\n      // Pure fraction: '0.' + leading zeros + digits\n      result = '0.' + '0'.repeat(-intLen) + digits;\n    } else {\n      result = digits.slice(0, intLen) + '.' + digits.slice(intLen);\n    }\n  }\n\n  return isNeg ? `-${result}` : result;\n}\n\n/**\n * Parses a decimal string into a rational `{ numerator, denominator, negative }`.\n * The denominator is always a power of 10 and the numerator is always non-negative.\n * @throws {CoinsError} For non-numeric input.\n *\n * Accepts standard decimal strings and JavaScript scientific notation\n * (e.g. `'1e-7'`, `'1.23E+5'`) — the latter is automatically expanded before parsing.\n *\n * @example\n * parseRational('1.5')   → { numerator: 15n, denominator: 10n, negative: false }\n * parseRational('-0.5')  → { numerator: 5n,  denominator: 10n, negative: true  }\n * parseRational('3')     → { numerator: 3n,  denominator: 1n,  negative: false }\n * parseRational('1e-7')  → { numerator: 1n,  denominator: 10000000n, negative: false }\n *\n * Note: `'-0'` and `'-0.0'` produce `{ negative: true, numerator: 0n, ... }`.\n * Callers that compute `negative ? -result : result` on `0n` remain correct\n * because `-0n === 0n` in bigint arithmetic.\n */\nexport function parseRational(str: string): { denominator: bigint; negative: boolean; numerator: bigint } {\n  // Expand scientific notation (e.g. from String(1e-7) = '1e-7') before validation.\n  const normalized = SCIENTIFIC_RE.test(str) ? expandScientific(str) : str;\n\n  if (!DECIMAL_RE.test(normalized)) {\n    throw new CoinsError(`Invalid decimal string: \"${str}\"`);\n  }\n\n  const negative = normalized.startsWith('-');\n  const absStr = negative ? normalized.slice(1) : normalized;\n  const dotIndex = absStr.indexOf('.');\n  const intStr = dotIndex === -1 ? absStr : absStr.slice(0, dotIndex);\n  const fracStr = dotIndex === -1 ? '' : absStr.slice(dotIndex + 1);\n  const denominator = pow10(fracStr.length);\n  const numerator = BigInt(intStr || '0') * denominator + BigInt(fracStr || '0');\n\n  return { denominator, negative, numerator };\n}\n\n/**\n * Applies a rounding mode to a truncated division result.\n *\n * **Contract**: `quotient` and `absRemainder` must be non-negative (absolute values).\n * The caller is responsible for:\n *   1. Computing everything in terms of absolute values.\n *   2. Passing `negative = true` when the true mathematical result is negative.\n *   3. Applying the sign after: `negative ? -result : result`.\n *\n * Returns the absolute value of the rounded result.\n *\n * @param quotient     Non-negative integer part of the division (`|dividend| / divisor`).\n * @param absRemainder Non-negative remainder (`|dividend| % divisor`).\n * @param denominator  The divisor used to produce quotient/remainder.\n * @param mode         The desired rounding mode.\n * @param negative     Whether the true mathematical result is negative. Defaults to `false`.\n */\nexport function applyRounding(\n  quotient: bigint,\n  absRemainder: bigint,\n  denominator: bigint,\n  mode: RoundingMode,\n  negative = false,\n): bigint {\n  if (absRemainder === 0n) return quotient;\n\n  switch (mode) {\n    case 'ceiling':\n      // Toward +∞: round up for positive results, truncate for negative results.\n      return negative ? quotient : quotient + 1n;\n\n    case 'down':\n      // Toward zero: always truncate.\n      return quotient;\n\n    case 'floor':\n      // Toward −∞: truncate for positive results, one step more for negative results.\n      return negative ? quotient + 1n : quotient;\n\n    case 'half-away-from-zero':\n      return absRemainder * 2n >= denominator ? quotient + 1n : quotient;\n\n    case 'half-even': {\n      const twice = absRemainder * 2n;\n\n      if (twice < denominator) return quotient;\n\n      if (twice > denominator) return quotient + 1n;\n\n      // Exactly half — round to the nearest even integer.\n      return quotient % 2n === 0n ? quotient : quotient + 1n;\n    }\n\n    case 'up':\n      // Away from zero: always round away.\n      return quotient + 1n;\n\n    default:\n      throw new CoinsError(`Unknown rounding mode: ${String(mode)}`);\n  }\n}\n"],"mappings":"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"}

package/dist/utils.d.ts

@@ -0,0 +1,66 @@
+import type { CurrencyCode, RoundingMode } from './types';
+/**
+ * Returns the number of minor-unit decimal places for a given ISO 4217 currency code.
+ * Uses `Intl.NumberFormat` to resolve the canonical value (e.g. USD→2, JPY→0, KWD→3).
+ * Throws `InvalidCurrencyError` for unrecognized codes or when the runtime cannot determine decimals.
+ */
+export declare function getCurrencyDecimals(currencyCode: CurrencyCode): number;
+/**
+ * Validates an ISO 4217 currency code and returns it.
+ * Throws `InvalidCurrencyError` if unrecognized. Uses `getCurrencyDecimals` internally so
+ * the result is cached for subsequent decimal lookups.
+ */
+export declare function validateCurrencyCode(code: CurrencyCode): CurrencyCode;
+/** Returns `10n ** BigInt(exponent)`. */
+export declare function pow10(exponent: number): bigint;
+/** Regex matching JavaScript scientific-notation strings, e.g. `'1e-7'`, `'-3.14E+5'`. */
+export declare const SCIENTIFIC_RE: RegExp;
+/**
+ * Expands a scientific-notation decimal string into a plain decimal string.
+ * `'1e-7'` → `'0.0000001'`, `'1.23e+5'` → `'123000'`.
+ * Only called when `SCIENTIFIC_RE` already matched — no extra validation.
+ * @throws {CoinsError} If the absolute exponent exceeds `MAX_SCIENTIFIC_EXP` (1000).
+ */
+export declare function expandScientific(s: string): string;
+/**
+ * Parses a decimal string into a rational `{ numerator, denominator, negative }`.
+ * The denominator is always a power of 10 and the numerator is always non-negative.
+ * @throws {CoinsError} For non-numeric input.
+ *
+ * Accepts standard decimal strings and JavaScript scientific notation
+ * (e.g. `'1e-7'`, `'1.23E+5'`) — the latter is automatically expanded before parsing.
+ *
+ * @example
+ * parseRational('1.5')   → { numerator: 15n, denominator: 10n, negative: false }
+ * parseRational('-0.5')  → { numerator: 5n,  denominator: 10n, negative: true  }
+ * parseRational('3')     → { numerator: 3n,  denominator: 1n,  negative: false }
+ * parseRational('1e-7')  → { numerator: 1n,  denominator: 10000000n, negative: false }
+ *
+ * Note: `'-0'` and `'-0.0'` produce `{ negative: true, numerator: 0n, ... }`.
+ * Callers that compute `negative ? -result : result` on `0n` remain correct
+ * because `-0n === 0n` in bigint arithmetic.
+ */
+export declare function parseRational(str: string): {
+    denominator: bigint;
+    negative: boolean;
+    numerator: bigint;
+};
+/**
+ * Applies a rounding mode to a truncated division result.
+ *
+ * **Contract**: `quotient` and `absRemainder` must be non-negative (absolute values).
+ * The caller is responsible for:
+ *   1. Computing everything in terms of absolute values.
+ *   2. Passing `negative = true` when the true mathematical result is negative.
+ *   3. Applying the sign after: `negative ? -result : result`.
+ *
+ * Returns the absolute value of the rounded result.
+ *
+ * @param quotient     Non-negative integer part of the division (`|dividend| / divisor`).
+ * @param absRemainder Non-negative remainder (`|dividend| % divisor`).
+ * @param denominator  The divisor used to produce quotient/remainder.
+ * @param mode         The desired rounding mode.
+ * @param negative     Whether the true mathematical result is negative. Defaults to `false`.
+ */
+export declare function applyRounding(quotient: bigint, absRemainder: bigint, denominator: bigint, mode: RoundingMode, negative?: boolean): bigint;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAO1D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAqBtE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAIrE;AAED,yCAAyC;AACzC,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9C;AAKD,0FAA0F;AAC1F,eAAO,MAAM,aAAa,QAAkC,CAAC;AAK7D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAiClD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAiBxG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,YAAY,EAClB,QAAQ,UAAQ,GACf,MAAM,CAqCR"}

package/dist/utils.js

@@ -0,0 +1,66 @@
+import { CoinsError as e, InvalidCurrencyError as t } from "./errors.js";
+import { boundedCache as n } from "./_cache.js";
+//#region src/utils.ts
+var r = n(512);
+function i(e) {
+	let n = r.get(e);
+	if (n !== void 0) return n;
+	let i;
+	try {
+		i = new Intl.NumberFormat("en", {
+			currency: e,
+			style: "currency"
+		}).resolvedOptions().maximumFractionDigits;
+	} catch {
+		throw new t(e);
+	}
+	if (i === void 0) throw new t(e);
+	return r.set(e, i), i;
+}
+function a(e) {
+	return i(e), e;
+}
+function o(e) {
+	return 10n ** BigInt(e);
+}
+var s = /^-?\d+(\.\d+)?$/, c = /^(-?\d+\.?\d*)[eE]([+-]?\d+)$/, l = 1e3;
+function u(t) {
+	let n = c.exec(t), r = n[1], i = parseInt(n[2], 10);
+	if (Math.abs(i) > l) throw new e(`Scientific notation exponent too large: "${t}" (max ±${l})`);
+	let a = r.startsWith("-"), o = a ? r.slice(1) : r, s = o.indexOf("."), u = s === -1 ? o : o.replace(".", ""), d = i - (s === -1 ? 0 : o.length - s - 1), f;
+	if (d >= 0) f = u + "0".repeat(d);
+	else {
+		let e = u.length + d;
+		f = e <= 0 ? "0." + "0".repeat(-e) + u : u.slice(0, e) + "." + u.slice(e);
+	}
+	return a ? `-${f}` : f;
+}
+function d(t) {
+	let n = c.test(t) ? u(t) : t;
+	if (!s.test(n)) throw new e(`Invalid decimal string: "${t}"`);
+	let r = n.startsWith("-"), i = r ? n.slice(1) : n, a = i.indexOf("."), l = a === -1 ? i : i.slice(0, a), d = a === -1 ? "" : i.slice(a + 1), f = o(d.length);
+	return {
+		denominator: f,
+		negative: r,
+		numerator: BigInt(l || "0") * f + BigInt(d || "0")
+	};
+}
+function f(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)}`);
+	}
+}
+//#endregion
+export { c as SCIENTIFIC_RE, f as applyRounding, u as expandScientific, i as getCurrencyDecimals, d as parseRational, o as pow10, a as validateCurrencyCode };
+
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import type { CurrencyCode, RoundingMode } from './types';\n\nimport { boundedCache } from './_cache';\nimport { CoinsError, InvalidCurrencyError } from './errors';\n\nconst currencyDecimalsCache = boundedCache<string, number>(512);\n\n/**\n * Returns the number of minor-unit decimal places for a given ISO 4217 currency code.\n * Uses `Intl.NumberFormat` to resolve the canonical value (e.g. USD→2, JPY→0, KWD→3).\n * Throws `InvalidCurrencyError` for unrecognized codes or when the runtime cannot determine decimals.\n */\nexport function getCurrencyDecimals(currencyCode: CurrencyCode): number {\n  const cached = currencyDecimalsCache.get(currencyCode);\n\n  if (cached !== undefined) return cached;\n\n  let resolved: number | undefined;\n\n  try {\n    resolved = new Intl.NumberFormat('en', { currency: currencyCode, style: 'currency' }).resolvedOptions()\n      .maximumFractionDigits;\n  } catch {\n    throw new InvalidCurrencyError(currencyCode);\n  }\n\n  if (resolved === undefined) {\n    throw new InvalidCurrencyError(currencyCode);\n  }\n\n  currencyDecimalsCache.set(currencyCode, resolved);\n\n  return resolved;\n}\n\n/**\n * Validates an ISO 4217 currency code and returns it.\n * Throws `InvalidCurrencyError` if unrecognized. Uses `getCurrencyDecimals` internally so\n * the result is cached for subsequent decimal lookups.\n */\nexport function validateCurrencyCode(code: CurrencyCode): CurrencyCode {\n  getCurrencyDecimals(code);\n\n  return code;\n}\n\n/** Returns `10n ** BigInt(exponent)`. */\nexport function pow10(exponent: number): bigint {\n  return 10n ** BigInt(exponent);\n}\n\n/** Regex for valid decimal strings accepted by `parseRational`. */\nconst DECIMAL_RE = /^-?\\d+(\\.\\d+)?$/;\n\n/** Regex matching JavaScript scientific-notation strings, e.g. `'1e-7'`, `'-3.14E+5'`. */\nexport const SCIENTIFIC_RE = /^(-?\\d+\\.?\\d*)[eE]([+-]?\\d+)$/;\n\n/** Maximum absolute exponent allowed in scientific notation. Prevents '0'.repeat(N) allocation attacks. */\nconst MAX_SCIENTIFIC_EXP = 1000;\n\n/**\n * Expands a scientific-notation decimal string into a plain decimal string.\n * `'1e-7'` → `'0.0000001'`, `'1.23e+5'` → `'123000'`.\n * Only called when `SCIENTIFIC_RE` already matched — no extra validation.\n * @throws {CoinsError} If the absolute exponent exceeds `MAX_SCIENTIFIC_EXP` (1000).\n */\nexport function expandScientific(s: string): string {\n  const match = SCIENTIFIC_RE.exec(s)!;\n  const coeff = match[1]!;\n  const exp = parseInt(match[2]!, 10);\n\n  if (Math.abs(exp) > MAX_SCIENTIFIC_EXP) {\n    throw new CoinsError(`Scientific notation exponent too large: \"${s}\" (max ±${MAX_SCIENTIFIC_EXP})`);\n  }\n\n  const isNeg = coeff.startsWith('-');\n  const absCoeff = isNeg ? coeff.slice(1) : coeff;\n  const dotIndex = absCoeff.indexOf('.');\n  const digits = dotIndex === -1 ? absCoeff : absCoeff.replace('.', '');\n  const fracLen = dotIndex === -1 ? 0 : absCoeff.length - dotIndex - 1;\n  const newExp = exp - fracLen; // where the decimal point sits relative to end of digits\n\n  let result: string;\n\n  if (newExp >= 0) {\n    // All digits are to the left of the decimal — append trailing zeros\n    result = digits + '0'.repeat(newExp);\n  } else {\n    const intLen = digits.length + newExp; // digits before the decimal point\n\n    if (intLen <= 0) {\n      // Pure fraction: '0.' + leading zeros + digits\n      result = '0.' + '0'.repeat(-intLen) + digits;\n    } else {\n      result = digits.slice(0, intLen) + '.' + digits.slice(intLen);\n    }\n  }\n\n  return isNeg ? `-${result}` : result;\n}\n\n/**\n * Parses a decimal string into a rational `{ numerator, denominator, negative }`.\n * The denominator is always a power of 10 and the numerator is always non-negative.\n * @throws {CoinsError} For non-numeric input.\n *\n * Accepts standard decimal strings and JavaScript scientific notation\n * (e.g. `'1e-7'`, `'1.23E+5'`) — the latter is automatically expanded before parsing.\n *\n * @example\n * parseRational('1.5')   → { numerator: 15n, denominator: 10n, negative: false }\n * parseRational('-0.5')  → { numerator: 5n,  denominator: 10n, negative: true  }\n * parseRational('3')     → { numerator: 3n,  denominator: 1n,  negative: false }\n * parseRational('1e-7')  → { numerator: 1n,  denominator: 10000000n, negative: false }\n *\n * Note: `'-0'` and `'-0.0'` produce `{ negative: true, numerator: 0n, ... }`.\n * Callers that compute `negative ? -result : result` on `0n` remain correct\n * because `-0n === 0n` in bigint arithmetic.\n */\nexport function parseRational(str: string): { denominator: bigint; negative: boolean; numerator: bigint } {\n  // Expand scientific notation (e.g. from String(1e-7) = '1e-7') before validation.\n  const normalized = SCIENTIFIC_RE.test(str) ? expandScientific(str) : str;\n\n  if (!DECIMAL_RE.test(normalized)) {\n    throw new CoinsError(`Invalid decimal string: \"${str}\"`);\n  }\n\n  const negative = normalized.startsWith('-');\n  const absStr = negative ? normalized.slice(1) : normalized;\n  const dotIndex = absStr.indexOf('.');\n  const intStr = dotIndex === -1 ? absStr : absStr.slice(0, dotIndex);\n  const fracStr = dotIndex === -1 ? '' : absStr.slice(dotIndex + 1);\n  const denominator = pow10(fracStr.length);\n  const numerator = BigInt(intStr || '0') * denominator + BigInt(fracStr || '0');\n\n  return { denominator, negative, numerator };\n}\n\n/**\n * Applies a rounding mode to a truncated division result.\n *\n * **Contract**: `quotient` and `absRemainder` must be non-negative (absolute values).\n * The caller is responsible for:\n *   1. Computing everything in terms of absolute values.\n *   2. Passing `negative = true` when the true mathematical result is negative.\n *   3. Applying the sign after: `negative ? -result : result`.\n *\n * Returns the absolute value of the rounded result.\n *\n * @param quotient     Non-negative integer part of the division (`|dividend| / divisor`).\n * @param absRemainder Non-negative remainder (`|dividend| % divisor`).\n * @param denominator  The divisor used to produce quotient/remainder.\n * @param mode         The desired rounding mode.\n * @param negative     Whether the true mathematical result is negative. Defaults to `false`.\n */\nexport function applyRounding(\n  quotient: bigint,\n  absRemainder: bigint,\n  denominator: bigint,\n  mode: RoundingMode,\n  negative = false,\n): bigint {\n  if (absRemainder === 0n) return quotient;\n\n  switch (mode) {\n    case 'ceiling':\n      // Toward +∞: round up for positive results, truncate for negative results.\n      return negative ? quotient : quotient + 1n;\n\n    case 'down':\n      // Toward zero: always truncate.\n      return quotient;\n\n    case 'floor':\n      // Toward −∞: truncate for positive results, one step more for negative results.\n      return negative ? quotient + 1n : quotient;\n\n    case 'half-away-from-zero':\n      return absRemainder * 2n >= denominator ? quotient + 1n : quotient;\n\n    case 'half-even': {\n      const twice = absRemainder * 2n;\n\n      if (twice < denominator) return quotient;\n\n      if (twice > denominator) return quotient + 1n;\n\n      // Exactly half — round to the nearest even integer.\n      return quotient % 2n === 0n ? quotient : quotient + 1n;\n    }\n\n    case 'up':\n      // Away from zero: always round away.\n      return quotient + 1n;\n\n    default:\n      throw new CoinsError(`Unknown rounding mode: ${String(mode)}`);\n  }\n}\n"],"mappings":";;;AAKA,IAAM,IAAwB,EAA6B,GAAG;AAO9D,SAAgB,EAAoB,GAAoC;CACtE,IAAM,IAAS,EAAsB,IAAI,CAAY;CAErD,IAAI,MAAW,KAAA,GAAW,OAAO;CAEjC,IAAI;CAEJ,IAAI;EACF,IAAW,IAAI,KAAK,aAAa,MAAM;GAAE,UAAU;GAAc,OAAO;EAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC,CACpG;CACL,QAAQ;EACN,MAAM,IAAI,EAAqB,CAAY;CAC7C;CAEA,IAAI,MAAa,KAAA,GACf,MAAM,IAAI,EAAqB,CAAY;CAK7C,OAFA,EAAsB,IAAI,GAAc,CAAQ,GAEzC;AACT;AAOA,SAAgB,EAAqB,GAAkC;CAGrE,OAFA,EAAoB,CAAI,GAEjB;AACT;AAGA,SAAgB,EAAM,GAA0B;CAC9C,OAAO,OAAO,OAAO,CAAQ;AAC/B;AAGA,IAAM,IAAa,mBAGN,IAAgB,iCAGvB,IAAqB;AAQ3B,SAAgB,EAAiB,GAAmB;CAClD,IAAM,IAAQ,EAAc,KAAK,CAAC,GAC5B,IAAQ,EAAM,IACd,IAAM,SAAS,EAAM,IAAK,EAAE;CAElC,IAAI,KAAK,IAAI,CAAG,IAAI,GAClB,MAAM,IAAI,EAAW,4CAA4C,EAAE,UAAU,EAAmB,EAAE;CAGpG,IAAM,IAAQ,EAAM,WAAW,GAAG,GAC5B,IAAW,IAAQ,EAAM,MAAM,CAAC,IAAI,GACpC,IAAW,EAAS,QAAQ,GAAG,GAC/B,IAAS,MAAa,KAAK,IAAW,EAAS,QAAQ,KAAK,EAAE,GAE9D,IAAS,KADC,MAAa,KAAK,IAAI,EAAS,SAAS,IAAW,IAG/D;CAEJ,IAAI,KAAU,GAEZ,IAAS,IAAS,IAAI,OAAO,CAAM;MAC9B;EACL,IAAM,IAAS,EAAO,SAAS;EAE/B,AAIE,IAJE,KAAU,IAEH,OAAO,IAAI,OAAO,CAAC,CAAM,IAAI,IAE7B,EAAO,MAAM,GAAG,CAAM,IAAI,MAAM,EAAO,MAAM,CAAM;CAEhE;CAEA,OAAO,IAAQ,IAAI,MAAW;AAChC;AAoBA,SAAgB,EAAc,GAA4E;CAExG,IAAM,IAAa,EAAc,KAAK,CAAG,IAAI,EAAiB,CAAG,IAAI;CAErE,IAAI,CAAC,EAAW,KAAK,CAAU,GAC7B,MAAM,IAAI,EAAW,4BAA4B,EAAI,EAAE;CAGzD,IAAM,IAAW,EAAW,WAAW,GAAG,GACpC,IAAS,IAAW,EAAW,MAAM,CAAC,IAAI,GAC1C,IAAW,EAAO,QAAQ,GAAG,GAC7B,IAAS,MAAa,KAAK,IAAS,EAAO,MAAM,GAAG,CAAQ,GAC5D,IAAU,MAAa,KAAK,KAAK,EAAO,MAAM,IAAW,CAAC,GAC1D,IAAc,EAAM,EAAQ,MAAM;CAGxC,OAAO;EAAE;EAAa;EAAU,WAFd,OAAO,KAAU,GAAG,IAAI,IAAc,OAAO,KAAW,GAAG;CAEnC;AAC5C;AAmBA,SAAgB,EACd,GACA,GACA,GACA,GACA,IAAW,IACH;CACR,IAAI,MAAiB,IAAI,OAAO;CAEhC,QAAQ,GAAR;EACE,KAAK,WAEH,OAAO,IAAW,IAAW,IAAW;EAE1C,KAAK,QAEH,OAAO;EAET,KAAK,SAEH,OAAO,IAAW,IAAW,KAAK;EAEpC,KAAK,uBACH,OAAO,IAAe,MAAM,IAAc,IAAW,KAAK;EAE5D,KAAK,aAAa;GAChB,IAAM,IAAQ,IAAe;GAO7B,OALI,IAAQ,IAAoB,IAE5B,IAAQ,IAAoB,IAAW,KAGpC,IAAW,MAAO,KAAK,IAAW,IAAW;EACtD;EAEA,KAAK,MAEH,OAAO,IAAW;EAEpB,SACE,MAAM,IAAI,EAAW,0BAA0B,OAAO,CAAI,GAAG;CACjE;AACF"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@vielzeug/coins",
+  "version": "1.0.2",
+  "description": "Bigint-based monetary arithmetic with currency formatting, exchange rates, and rounding policies",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest",
+    "build:bundle": "vite build --config vite.bundle.config.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}