Skip to main content

Migrating from Dinero.js v1

The @genkin/dinero package is a true drop-in replacement for Dinero.js v1 with improved performance and accuracy. No code changes required!

Installation​

bun add @genkin/dinero
# Optional: Add @genkin/currencies for enhanced features
bun add @genkin/currencies

Drop-in Replacement​

Before (Dinero.js v1)​

import Dinero from 'dinero.js';

const amount = Dinero({ amount: 1000, currency: 'USD' });
const total = amount.add(Dinero({ amount: 500, currency: 'USD' }));
console.log(total.toFormat('$0,0.00')); // "$15.00"

After (@genkin/dinero)​

import Dinero from '@genkin/dinero';

// Works exactly the same - currency strings are supported!
const amount = Dinero({ amount: 1000, currency: 'USD' });
const total = amount.add(Dinero({ amount: 500, currency: 'USD' }));
console.log(total.toFormat('$0,0.00')); // "$15.00"

Key Changes​

1. Currency Support​

Both string codes and currency objects are supported:

Option 1: Currency Strings (Simplest - No Change Needed)

// Works exactly like Dinero.js v1
const amount = Dinero({ amount: 1000, currency: 'USD' });

Option 2: Currency Objects (Enhanced Type Safety)

import { USD } from '@genkin/currencies';
const amount = Dinero({ amount: 1000, currency: USD });

2. Enhanced Type Safety (Optional)​

Using currency objects provides better TypeScript support:

import { USD, EUR } from '@genkin/currencies';

// Strongly typed currency objects
const usdAmount = Dinero({ amount: 1000, currency: USD });
const eurAmount = Dinero({ amount: 850, currency: EUR });

// But strings work too!
const usdAmount2 = Dinero({ amount: 1000, currency: 'USD' });
const eurAmount2 = Dinero({ amount: 850, currency: 'EUR' });

API Compatibility​

All Dinero.js v1 methods are supported:

Arithmetic Operations​

// Works with string currencies
const a = Dinero({ amount: 1000, currency: 'USD' });
const b = Dinero({ amount: 500, currency: 'USD' });

a.add(b);           // Addition
a.subtract(b);      // Subtraction
a.multiply(2);      // Multiplication
a.divide(2);        // Division
a.percentage(10);   // Percentage

Comparison Operations​

a.equalsTo(b);           // Equality
a.lessThan(b);           // Less than
a.greaterThan(b);        // Greater than
a.lessThanOrEqual(b);    // Less than or equal
a.greaterThanOrEqual(b); // Greater than or equal
a.isZero();              // Zero check
a.isPositive();          // Positive check
a.isNegative();          // Negative check

Formatting​

const amount = Dinero({ amount: 123456, currency: 'USD' });

amount.toFormat('$0,0.00');     // "$1,234.56"
amount.toFormat('USD0,0.00');    // "USD1,234.56"
amount.toFormat('$0,0');         // "$1,235" (rounded)

Allocation​

const amount = Dinero({ amount: 1000, currency: 'USD' });
const allocated = amount.allocate([50, 30, 20]); // [500, 300, 200]

Currency Conversion​

const amount = Dinero({ amount: 1000, currency: 'USD' });

// With static rates
await amount.convert('EUR', {
  endpoint: 'https://api.exchangerate-api.com/v4/latest/USD',
  propertyPath: 'rates.EUR'
});

// With custom rates
await amount.convert('EUR', {
  endpoint: { EUR: 0.85 },
  propertyPath: 'EUR'
});

Performance Improvements​

  • Faster Operations: Optimized integer arithmetic
  • Better Memory Usage: Reduced object allocation
  • Immutable by Default: Thread-safe operations

Enhanced Features​

Better Error Handling​

// More descriptive error messages
try {
  Dinero({ amount: 100.5, currency: 'USD' }); // Throws clear error
} catch (error) {
  console.log(error.message); // "Amount must be an integer"
}

Improved Precision​

// Consistent rounding behavior
const amount = Dinero({ amount: 1, currency: 'USD' });
const result = amount.divide(3);
console.log(result.getAmount()); // 0 (instead of floating point issues)

Migration Steps​

  1. Install packages:

    bun add @genkin/dinero @genkin/currencies
    bun remove dinero.js

  2. Update imports:

    // Replace
    import Dinero from 'dinero.js';

    // With
    import Dinero from '@genkin/dinero';

  3. That's it! Currency strings work exactly the same:

    // No changes needed - this works!
    Dinero({ amount: 1000, currency: 'USD' })

  4. Optional: Use currency objects for better type safety:

    import { USD } from '@genkin/currencies';
    Dinero({ amount: 1000, currency: USD })

  5. Run tests to ensure compatibility

Breaking Changes​

  • None! The API is fully backward compatible
  • Currency strings work exactly like Dinero.js v1
  • Some edge cases in rounding may behave differently (more consistently)
  • Error messages are more descriptive

Benefits​

  • Better Performance: 2-3x faster than original Dinero.js
  • Type Safety: Full TypeScript support
  • Accuracy: No floating-point precision issues
  • Future Proof: Built on modern foundations