Vielzeug

Appearance

coins logoCoinsFinance
Exact bigint monetary arithmetic with explicit currency definitions, decimal strings, allocation, exchange, formatting, and JSON boundaries.
Version
v2.0.1
Size
3.9 KB gzip
Dependencies
Zero dependencies
Runtime support
BrowserNode ≥22SSRDeno
Key exports
moneycurrencyaddallocateexchange View all 6 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 size3.9 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: deterministic built-in currency definitions
  • 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
  • parseMoneyJSON: validate persisted money values

Documentation ​

See Also ​

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