soff-money
v0.2.7~2KB CoreImmutable money class with precise arithmetic for LATAM currencies.
Formatted
$ 1.500.000,00
Tax Amount (19%)
$ 285.000,00
Total with Tax
$ 1.785.000,00
Person 1
$ 500.000,00
Person 2
$ 500.000,00
Person 3
$ 500.000,00
Total: $ 1.500.000,00 (no cents lost!)
Cents (internal)
150000000
Decimal
1500000
Currency
COP
COP (Colombian Peso)
$ 1.500.000,00
USD (US Dollar)
$100.50
MXN (Mexican Peso)
$25,000.00
CLP (Chilean Peso)
$ 150.000
EUR (Euro)
1.500,00 €
19% Tax on $100.50
$119.60
Addition (COP)
$ 2.000.000,00
$100 USD ÷ 3 (fair distribution)
$33.34 + $33.33 + $33.33
Installation
npm install soff-moneyQuick Start
import { Money, COP, USD, MXN } from 'soff-money';
// Create money from decimal
const price = Money.fromDecimal(1500000, COP);
price.format(); // '$ 1.500.000'
// Create from cents (smallest unit)
const cents = Money.fromCents(10050, USD);
cents.format(); // '$100.50'
// Arithmetic (immutable - returns new instance)
const total = price.add(Money.fromDecimal(500000, COP));
total.format(); // '$ 2.000.000'
// Distribution without losing cents
const shares = Money.fromDecimal(100, USD).distribute(3);
// [$33.34, $33.33, $33.33] - no cents lost!Key Features
Immutable
All operations return new Money instances. Safe for React state.
Integer Arithmetic
Uses cents internally to avoid floating-point precision issues.
9 Currencies
COP, MXN, BRL, ARS, USD, CLP, PEN, UYU, EUR with correct formatting.
Fair Distribution
Split money without losing cents. Perfect for bill splitting.
Percentage Ops
Calculate, add, or subtract percentages. Perfect for tax/discounts.
Static Helpers
Money.sum(), Money.average(), Money.minimum(), Money.maximum()
Available Currencies
| Currency | Code | Symbol | Example |
|---|---|---|---|
| 🇨🇴 Colombian Peso | COP | $ | $ 1.500.000 |
| 🇲🇽 Mexican Peso | MXN | $ | $25,000.00 |
| 🇧🇷 Brazilian Real | BRL | R$ | R$ 1.500,00 |
| 🇦🇷 Argentine Peso | ARS | $ | $ 150.000,00 |
| 🇺🇸 US Dollar | USD | $ | $1,500.00 |
| 🇨🇱 Chilean Peso | CLP | $ | $ 150.000 |
| 🇵🇪 Peruvian Sol | PEN | S/ | S/ 1,500.00 |
| 🇺🇾 Uruguayan Peso | UYU | $ | $ 1.500,00 |
| 🇪🇺 Euro | EUR | € | 1.500,00 € |
API Reference
// From decimal amount
Money.fromDecimal(100.50, USD) // $100.50
// From cents (smallest unit)
Money.fromCents(10050, USD) // $100.50
// Zero money
Money.zero(USD) // $0.00Common Patterns
// Shopping cart total
const items = [
Money.fromDecimal(29.99, USD),
Money.fromDecimal(49.99, USD),
Money.fromDecimal(19.99, USD),
];
const total = Money.sum(items); // $99.97
// Apply discount (10% off)
const discounted = total.subtractPercentage(10); // $89.97
// Tax calculation (19% IVA)
const withTax = discounted.addPercentage(19); // $107.07
// Split bill (4 people)
const perPerson = withTax.distribute(4);
// [$26.77, $26.77, $26.77, $26.76]
// Price validation
const minOrder = Money.fromDecimal(50, USD);
const maxOrder = Money.fromDecimal(500, USD);
if (!total.isBetween(minOrder, maxOrder)) {
throw new Error('Order must be between $50 and $500');
}
// Find cheapest/most expensive item
const cheapest = Money.minimum(items); // $19.99
const mostExpensive = Money.maximum(items); // $49.99
const average = Money.average(items); // $33.32