• API Overview
• Package Entry Point
• Construction
  • currency / defineCurrency
  • money
  • decimal
• Arithmetic
• Aggregation
• Exchange
• Formatting
• Serialization
• Types
• Errors

API Overview

Symbol	Purpose	Execution	Common gotcha
money	Construct validated money	Sync	Bigint requires { unit: 'minor' }
currency	Resolve supported definition	Sync	Unknown codes throw
defineCurrency	Define an explicit scale	Sync	Code must be three uppercase letters
add / subtract	Combine matching currencies	Sync	Mismatches throw
multiply / divide	Exact decimal scaling	Sync	Use decimal strings
sum	Aggregate with identity currency	Sync	Pass { currency }
allocate	Split without losing minor units	Sync	Weights must be non-negative
exchange	Convert through an exact rate	Sync	Rate source must match value currency
format	Present money with Intl	Sync	Formatting does not define currency scale
toJSON / parseMoneyJSON	Cross JSON boundary	Sync	Persisted amount uses minor units

Package Entry Point

Import	Purpose
@vielzeug/coins	Complete public Coins API

Construction

currency / defineCurrency

currency(code: string): Currency
defineCurrency({ code, minorUnit }): Currency

Built-ins: USD, EUR, GBP, JPY, KRW, BHD, KWD.

money

money(amount: string, currency: Currency): Money
money(amount: string, currency: Currency, options: { rounding: RoundingMode }): Money
money(amount: bigint, currency: Currency, options: { unit: 'minor' }): Money

money('19.99', USD);
money(1999n, USD, { unit: 'minor' });

decimal

decimal(value: string): Decimal

Creates an exact rational value for multiplication, division, or exchange rates.

Arithmetic

add(left, right)
subtract(left, right)
multiply(value, factor, { rounding? })
divide(value, divisor, { rounding? })
compare(left, right)
abs(value)
negate(value)
round(value, { fractionDigits, rounding? })

factor and divisor are decimal strings. Matching currency is required for binary money operations.

Aggregation

sum(values, { currency })
allocate(value, count)
allocate(value, weights)
clamp(value, { min, max })

sum([], { currency: USD }) returns zero USD. allocate returns values whose minor-unit total exactly equals input.

Exchange

exchangeRate({ from, to, value }): ExchangeRate
exchange(value, rate, { rounding? }): Money

const rate = exchangeRate({ from: USD, to: EUR, value: '0.9234' });
exchange(money('100.00', USD), rate);

Formatting

format(value, options?): string
formatParts(value, options?): MoneyFormatPart[]

FormatOptions uses locale, style, minimumFractionDigits, and maximumFractionDigits.

Serialization

toDecimal(value): string
toJSON(value): MoneyJSON
parseMoneyJSON(value: unknown, options?: { currency?: (code: string) => Currency }): Money
parseMoney(value: unknown): Money
isMoney(value: unknown): value is Money

Types

type Currency = { code: CurrencyCode; minorUnit: number };
type Money = { amount: bigint; currency: Currency };
type Decimal = { numerator: bigint; denominator: bigint };
type ExchangeRate = { from: Currency; to: Currency; value: Decimal };
type MoneyJSON = { amount: string; currency: string; unit: 'minor' };
type RoundingMode = 'awayFromZero' | 'ceil' | 'floor' | 'halfAwayFromZero' | 'halfEven' | 'towardZero';

Errors

Every Coins failure extends CoinsError and exposes code.

• INVALID_CURRENCY
• INVALID_DECIMAL
• INVALID_MONEY
• INVALID_ALLOCATION
• INVALID_ROUNDING
• DIVISION_BY_ZERO
• CURRENCY_MISMATCH

CurrencyMismatchError and InvalidCurrencyError are specialized CoinsError subclasses.