A lightweight, robust JavaScript library for currency operations with precision and reliability. Designed to handle monetary values safely, avoiding floating point issues common in financial calculations. Inspired by the lib of the same name currency.js.
- 1. 🚀 Why Currency.js?
- 2. 📦 Installation
- 3. 🔍 Quick Start
- 4. ✨ Key Features
- 5. 🔧 Core APIs
- 6. 📚 Documentation
- 7. 🧪 Testing
- 8. 🤝 Contributing
- 9. 📄 License
- 10. 🔗 Resources
- 11. 👥 Contributors
Financial operations demand precision. JavaScript's native floating-point math can lead to errors when handling currency values:
// Native JS floating-point issues
0.1 + 0.2 // 0.30000000000000004 ❌
19.99 * 0.07 // 1.3993000000000002 ❌
(10.25 * 3).toFixed(2) // "30.75" ❌ (close, but doesn't handle rounding properly)
// With Currency.js
Money(0.1).plus(0.2).value // 0.3 ✅
Money(19.99).percentage(7) // 1.40 ✅ (properly rounded)
Money(10.25).times(3).value // 30.75 ✅npm install @eriveltonsilva/currency.jsimport Money from '@eriveltonsilva/currency.js'
// Create money instances
const price = Money(19.99)
const discount = Money(5)
// Basic operations
const finalPrice = price.minus(discount)
console.log(finalPrice.format()) // $14.99
// Chain operations
const total = Money(100)
.applyDiscount(15) // Apply 15% discount
.plus(4.99) // Add shipping
.format({ currencyCode: 'EUR' }) // Format as euros
console.log(total) // 89.99 €
// Business calculations
const subtotal = Money(125.99)
const installments = subtotal.allocate(3) // [42.00, 42.00, 41.99]- ✅ Zero Dependencies: Lightweight implementation (< 5KB min+gzip)
- ✅ Type-Safe Operations: Full TypeScript support with comprehensive type definitions
- ✅ Immutable Values: All operations return new Money instances
- ✅ Precise Calculations: Uses integer-based math to eliminate floating-point errors
- ✅ Business Operations: Support for discounts, taxes, installments, and more
- ✅ Flexible Formatting: Internationalization support for 100+ currencies and locales
- ✅ Simple API: Intuitive method names and chainable operations
// Basic creation
const a = Money(10.50) // From number
const b = Money("10.50") // From string
const c = Money(a) // From another Money instance
// With format options
const price = Money(99.99, {
currencyCode: 'EUR',
locale: 'de-DE',
})
// Pre-configured currencies
import { Currency } from '@eriveltonsilva/currency.js'
const usd = Currency.USD(99.99) // $99.99
const eur = Currency.EUR(99.99) // 99.99 €
const brl = Currency.BRL(99.99) // R$ 99,99// Arithmetic
const sum = price.plus(20) // Addition
const diff = price.minus(5.99) // Subtraction
const doubled = price.times(2) // Multiplication
const half = price.dividedBy(2) // Division
// Comparison
price.equals(99.99) // true
price.greaterThan(50) // true
price.lessThan(100) // false
price.isBetween(50, 150) // true
// Business operations
const tenPercent = price.percentage(10) // 10% of price
const discounted = price.applyDiscount(20) // 20% discount
const total = price.applySurcharge(15) // 15% surchargeFor comprehensive guides and examples, explore our documentation:
- API Reference - Complete method and property listing
- Formatting Guide - Currency formatting options
- Best Practices - Recommended usage patterns
- Advanced Examples - Real-world implementations
- Important Warnings - Limitations to be aware of
# Run the test suite
npm test
# Run the test suite with coverage
npm run test:coverageContributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Thanks to all the people who have contributed to this project:
- Erivelton Silva - Creator
To become a contributor, please see the 🤝 Contributing section.