Vielzeug
coins logoCoinsFinance
Exact bigint monetary arithmetic with explicit currency definitions, decimal strings, allocation, exchange, formatting, and JSON boundaries.
Version
v3.0.0
Size
4.0 KB gzip
Dependencies
Zero dependencies
Runtime support
BrowserNode ≥22SSRDeno
Key exports
USDEURGBPJPYKRW View all 30 exports
Works well with
vault courier spell

Why Coins? ​

Coins keeps monetary values in bigint minor units, but makes units explicit at construction. Currency scale comes from deterministic definitions; Intl formats a known value without deciding its arithmetic representation.

ts
// Before
const total = (19.99 + 7.25) * 1.08;

// After
import { USD, add, money, multiply } from '@vielzeug/coins';

const total = multiply(add(money('19.99', USD), money('7.25', USD)), '1.08');
FeatureCoinsdecimal.jsDinero.js
Bundle size4.0 KBExternal dependencyExternal dependency
Bigint minor units
Explicit currency scaleApp-definedPartial
Exact allocationManual
Zero dependencies

Use Coins when application values represent real money and every rounding boundary must be visible.

Consider native numbers when values are estimates, analytics, or display-only approximations.

Installation ​

sh
pnpm add @vielzeug/coins
sh
npm install @vielzeug/coins
sh
yarn add @vielzeug/coins

Quick Start ​

ts
import { USD, add, format, money, multiply } from '@vielzeug/coins';

const subtotal = add(money('12.50', USD), money('7.25', USD));
const total = multiply(subtotal, '1.08', { rounding: 'halfEven' });

console.log(format(total));

Features ​

  • money: one constructor for decimal and explicit minor-unit values
  • currency: resolve seven canonical built-ins, or create a local custom definition
  • add: exact same-currency arithmetic
  • allocate: split every minor unit without loss
  • exchange: typed source and target currency conversion
  • format: locale presentation for bigint values
  • decodeMoney: validate and re-canonicalize persisted, transported, or cross-realm values

Documentation ​

See Also ​

  • Vault — persist validated money JSON.
  • Courier — retrieve exchange-rate data.
  • Spell — validate external monetary payloads.