@suaveplan/money - Universal precise currency/money arithmetic using integer minor-unit (bigint) representation: immutable Money class with full arithmetic + comparison + conversion surface, locale-aware Intl-backed formatting (formatMoney, formatMoneyCompact), fair allocators preserving the input total (allocateEvenly, allocateByRatios, allocateByPercentages), aggregators (sumMoney, minMoney, maxMoney), 30 ISO 4217 fiat + 5 cryptocurrency built-ins, custom and virtual currency registration, lossless JSON round-trip, typed MoneyError hierarchy with stable MONEY.* code registry.

Universal precise currency and money arithmetic using integer minor-unit representation. All operations use bigint so consumers never hit floating-point rounding drift; cross-currency mistakes raise typed errors; allocations preserve the input total to the minor unit.

Documentation tree

allocator — The allocator module solves two related problems: splitting a Money amount across N recipients (or N weights or N per…
- allocator — The allocator module solves two related problems: splitting a Money amount across N recipients (or N weights or N per…
currencies — This module owns the currency-metadata registry that every other part of @suaveplan/money consults to compute minor-u…
- currencies — This module owns the currency-metadata registry that every other part of @suaveplan/money consults to compute minor-u…
error-codes — @suaveplan/money raises only typed errors. This module owns the stable MONEY_CODES registry (built with `defineCode…
- error-codes — @suaveplan/money raises only typed errors. This module owns the stable MONEY_CODES registry (built with `defineCode…
formatter — The formatter renders MoneyLike values to human-readable strings using Intl.NumberFormat(locale)-derived separators…
- formatter — The formatter renders MoneyLike values to human-readable strings using Intl.NumberFormat(locale)-derived separators…
money — Money is the cornerstone of the package: an immutable value object that stores monetary amounts as bigint minor uni…
- money — Money is the cornerstone of the package: an immutable value object that stores monetary amounts as bigint minor uni…
types — @suaveplan/money exposes a small, stable set of types that downstream packages (@suaveplan/currency, `@suaveplan/pa…
- common — @suaveplan/money exposes a small, stable set of types that downstream packages (@suaveplan/currency, `@suaveplan/pa…

Install

bun add @suaveplan/money

Quick start

import { Money, formatMoney, allocateEvenly } from "@suaveplan/money";

const price = Money.fromMajor(29.99, "USD");
const tax = price.multiply(0.08);
const total = price.add(tax);

console.log(formatMoney(total));      // "$32.39"
console.log(total.toDecimalString()); // "32.39"

// Split a $32.39 bill among 3 — no penny lost
const { shares } = allocateEvenly(total, 3);
console.log(shares.map((s) => formatMoney(s))); // ["$10.80", "$10.80", "$10.79"]

Features

Immutable Money class with full arithmetic (add, subtract, multiply, divide, abs, negate), comparison (compareTo, equals, greaterThan, ...), and conversion (toMajor, toDecimalString, toJSON, toString).
30 ISO 4217 fiat currencies (USD, EUR, GBP, JPY, ...) plus 5 cryptocurrencies (BTC, ETH, SOL, USDT, USDC) with accurate exponents.
Custom and virtual currency registration via registerCurrency(info) with virtual / issuerId flags for game-currency use cases.
Locale-aware formatting through Intl.NumberFormat-derived separators; decimalSeparator / thousandsSeparator overrides for locked output.
Compact notation (formatMoneyCompact) with K / M / B suffixes.
Fair allocators (allocateEvenly, allocateByRatios, allocateByPercentages) that always preserve the input total.
Aggregators (sumMoney, minMoney, maxMoney) with typed empty-input and cross-currency guards.
Lossless JSON round-trip via Money.toJSON() / Money.fromJSON() (bigint encoded as decimal string).
Typed MoneyError hierarchy extending SuaveplanError<MoneyErrorCode> with stable MONEY.* code registry and currency / otherCurrency discriminants.
Subpath exports for every public module so consumers can tree-shake.
Universal — no node:*, bun:*, DOM, or fs imports; runs unchanged on Node ≥ 18, Bun, browsers, and Web Workers.

Modules

money/money.md — Money class + applyRounding
currencies/currencies.md — built-in registry, lookup, custom / virtual currency registration
formatter/formatter.md — formatMoney + formatMoneyCompact
allocator/allocator.md — allocators + aggregators (sumMoney, minMoney, maxMoney)
error-codes/error-codes.md — MONEY_CODES registry + MoneyError class
types/common.md — public type contracts

Subpath exports

import { Money }            from "@suaveplan/money/money/money";
import { formatMoney }      from "@suaveplan/money/formatter/formatter";
import { allocateEvenly }   from "@suaveplan/money/allocator/allocator";
import { registerCurrency } from "@suaveplan/money/currencies/currencies";
import { MoneyError }       from "@suaveplan/money/error-codes/error-codes";
import type { MoneyLike }   from "@suaveplan/money/types/common";

Error handling

Every failure path raises a typed MoneyError carrying a stable MONEY.* code. Six codes are declared: CURRENCY_MISMATCH, UNKNOWN_CURRENCY, DIVISION_BY_ZERO, INVALID_ALLOCATION, EMPTY_INPUT, PARSE_ERROR.

import { Money, MoneyError, MONEY_CODES } from "@suaveplan/money";

try {
    Money.fromMinor(100n, "USD").add(Money.fromMinor(50n, "EUR"));
} catch (err) {
    if (err instanceof MoneyError && err.code === MONEY_CODES.CURRENCY_MISMATCH) {
        console.error(`mismatch: ${err.currency} vs ${err.otherCurrency}`);
    }
}

6.5 KiB Raw Blame History