@eriveltonsilva/currency.js v0.1.4

💰 Currency.js — Currency Manipulation Library

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.

📖 Table of Contents

• 1. 🚀 Why Currency.js?
• 2. 📦 Installation
• 3. 🔍 Quick Start
• 4. ✨ Key Features
• 5. 🔧 Core APIs
  • 5.1. Creating Money Instances
  • 5.2. Essential Operations
• 6. 📚 Documentation
• 7. 🧪 Testing
• 8. 🤝 Contributing
• 9. 📄 License
• 10. 🔗 Resources
• 11. 👥 Contributors

1. 🚀 Why Currency.js?

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 ✅

2. 📦 Installation

npm install @eriveltonsilva/currency.js

3. 🔍 Quick Start

import 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]

4. ✨ Key Features

• ✅ 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

5. 🔧 Core APIs

5.1. Creating Money Instances

// 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

5.2. Essential Operations

// 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% surcharge

6. 📚 Documentation

For 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

7. 🧪 Testing

# Run the test suite
npm test

# Run the test suite with coverage
npm run test:coverage

8. 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

9. 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

10. 🔗 Resources

• GitHub Repository
• Report Issues
• NPM Package

11. 👥 Contributors

Thanks to all the people who have contributed to this project:

• Erivelton Silva - Creator

To become a contributor, please see the 🤝 Contributing section.