Dinero

Returns the amount.

// returns 500
Dinero({ amount: 500 }).getAmount()

Returns the currency.

// returns 'EUR'
Dinero({ currency: 'EUR' }).getCurrency()

Returns the locale.

// returns 'fr-FR'
Dinero().setLocale('fr-FR').getLocale()

Returns a new Dinero object with an embedded locale.

// Returns a Dinero object with locale 'ja-JP'
Dinero().setLocale('ja-JP')

Returns the precision.

// returns 3
Dinero({ precision: 3 }).getPrecision()

Returns a new Dinero object with a new precision and a converted amount.

By default, fractional minor currency units are rounded using the half to even rule (banker's rounding). This can be necessary when you need to convert objects to a smaller precision.

Rounding can lead to accuracy issues as you chain many times. Consider a minimal amount of subsequent conversions for safer results. You can also specify a different roundingMode to better fit your needs.

// Returns a Dinero object with precision 3 and amount 1000
Dinero({ amount: 100, precision: 2 }).convertPrecision(3)

Returns a new Dinero object that represents the sum of this and an other Dinero object.

If Dinero objects have a different precision, they will be first converted to the highest.

// returns a Dinero object with amount 600
Dinero({ amount: 400 }).add(Dinero({ amount: 200 }))

// returns a Dinero object with amount 144545 and precision 4
Dinero({ amount: 400 }).add(Dinero({ amount: 104545, precision: 4 }))

Returns a new Dinero object that represents the difference of this and an other Dinero object.

If Dinero objects have a different precision, they will be first converted to the highest.

// returns a Dinero object with amount 200
Dinero({ amount: 400 }).subtract(Dinero({ amount: 200 }))

// returns a Dinero object with amount 64545 and precision 4
Dinero({ amount: 104545, precision: 4 }).subtract(Dinero({ amount: 400 }))

Returns a new Dinero object that represents the multiplied value by the given factor.

By default, fractional minor currency units are rounded using the half to even rule (banker's rounding).

Rounding can lead to accuracy issues as you chain many times. Consider a minimal amount of subsequent calculations for safer results. You can also specify a different roundingMode to better fit your needs.

// returns a Dinero object with amount 1600
Dinero({ amount: 400 }).multiply(4)

// returns a Dinero object with amount 800
Dinero({ amount: 400 }).multiply(2.001)

// returns a Dinero object with amount 801
Dinero({ amount: 400 }).multiply(2.00125, 'HALF_UP')

Returns a new Dinero object that represents the divided value by the given factor.

By default, fractional minor currency units are rounded using the half to even rule (banker's rounding).

Rounding can lead to accuracy issues as you chain many times. Consider a minimal amount of subsequent calculations for safer results. You can also specify a different roundingMode to better fit your needs.

As rounding is applied, precision may be lost in the process. If you want to accurately split a Dinero object, use allocate instead.

// returns a Dinero object with amount 100
Dinero({ amount: 400 }).divide(4)

// returns a Dinero object with amount 52
Dinero({ amount: 105 }).divide(2)

// returns a Dinero object with amount 53
Dinero({ amount: 105 }).divide(2, 'HALF_UP')

Returns a new Dinero object that represents a percentage of this.

As rounding is applied, precision may be lost in the process. If you want to accurately split a Dinero object, use allocate instead.

// returns a Dinero object with amount 5000
Dinero({ amount: 10000 }).percentage(50)

// returns a Dinero object with amount 29
Dinero({ amount: 57 }).percentage(50, "HALF_ODD")

Allocates the amount of a Dinero object according to a list of ratios.

Sometimes you need to split monetary values but percentages can't cut it without adding or losing pennies. A good example is invoicing: let's say you need to bill $1,000.03 and you want a 50% downpayment. If you use percentage, you'll get an accurate Dinero object but the amount won't be billable: you can't split a penny. If you round it, you'll bill a penny extra. With allocate, you can split a monetary amount then distribute the remainder as evenly as possible.

You can use percentage style or ratio style for ratios: [25, 75] and [1, 3] will do the same thing.

Since v1.8.0, you can use zero ratios (such as [0, 50, 50]). If there's a remainder to distribute, zero ratios are skipped and return a Dinero object with amount zero.

// returns an array of two Dinero objects
// the first one with an amount of 502
// the second one with an amount of 501
Dinero({ amount: 1003 }).allocate([50, 50])

// returns an array of two Dinero objects
// the first one with an amount of 25
// the second one with an amount of 75
Dinero({ amount: 100 }).allocate([1, 3])

// since version 1.8.0
// returns an array of three Dinero objects
// the first one with an amount of 0
// the second one with an amount of 502
// the third one with an amount of 501
Dinero({ amount: 1003 }).allocate([0, 50, 50])

Returns a Promise containing a new Dinero object converted to another currency.

You have two options to provide the exchange rates:

1. Use an exchange rate REST API, and let Dinero handle the fetching and conversion. This is a simple option if you have access to an exchange rate REST API and want Dinero to do the rest.
2. Fetch the exchange rates on your own and provide them directly. This is useful if you're fetching your rates from somewhere else (a file, a database), use a different protocol or query language than REST (SOAP, GraphQL) or want to fetch rates once and cache them instead of making new requests every time.

If you want to use a REST API, you must provide a third-party endpoint yourself. Dinero doesn't come bundled with an exchange rates endpoint.

Here are some exchange rate APIs you can use:

• Fixer
• Open Exchange Rates
• Coinbase
• More foreign and crypto exchange rate APIs.

If you want to fetch your own rates and provide them directly, you need to pass a promise that resolves to the exchanges rates.

In both cases, you need to specify at least:

• a destination currency: the currency in which you want to convert your Dinero object. You can specify it with currency.
• an endpoint: the API URL to query exchange rates, with parameters, or a promise that resolves to the exchange rates. You can specify it with options.endpoint.
• a property path: the path to access the wanted rate in your API's JSON response (or the custom promise's payload). For example, with a response of:

{
    "data": {
      "base": "USD",
      "destination": "EUR",
      "rate": "0.827728919"
    }
}

Then the property path is 'data.rate'. You can specify it with options.propertyPath.

The base currency (the one of your Dinero object) and the destination currency can be used as "merge tags" with the mustache syntax, respectively {{from}} and {{to}}. You can use these tags to refer to these values in options.endpoint and options.propertyPath.

For example, if you need to specify the base currency as a query parameter, you can do the following:

{
  endpoint: 'https://yourexchangerates.api/latest?base={{from}}'
}

// your global API parameters
Dinero.globalExchangeRatesApi = { ... }

// returns a Promise containing a Dinero object with the destination currency
// and the initial amount converted to the new currency.
Dinero({ amount: 500 }).convert('EUR')

// returns a Promise containing a Dinero object,
// with specific API parameters and rounding mode for this specific instance.
Dinero({ amount: 500 })
  .convert('XBT', {
    endpoint: 'https://yourexchangerates.api/latest?base={{from}}',
    propertyPath: 'data.rates.{{to}}',
    headers: {
      'user-key': 'xxxxxxxxx'
    },
    roundingMode: 'HALF_UP'
  })

// usage with exchange rates provided as a custom promise
// using the default `propertyPath` format (so it doesn't have to be specified)
const rates = {
  rates: {
    EUR: 0.81162
  }
}

Dinero({ amount: 500 })
  .convert('EUR', {
    endpoint: new Promise(resolve => resolve(rates))
  })

// usage with Promise.prototype.then and Promise.prototype.catch
Dinero({ amount: 500 })
  .convert('EUR')
  .then(dinero => {
    dinero.getCurrency() // returns 'EUR'
  })
  .catch(err => {
    // handle errors
  })

// usage with async/await
(async () => {
  const price = await Dinero({ amount: 500 }).convert('EUR')
  price.getCurrency() // returns 'EUR'
})()

Checks whether the value represented by this object equals to the other.

// returns true
Dinero({ amount: 500, currency: 'EUR' }).equalsTo(Dinero({ amount: 500, currency: 'EUR' }))

// returns false
Dinero({ amount: 500, currency: 'EUR' }).equalsTo(Dinero({ amount: 800, currency: 'EUR' }))

// returns false
Dinero({ amount: 500, currency: 'USD' }).equalsTo(Dinero({ amount: 500, currency: 'EUR' }))

// returns false
Dinero({ amount: 500, currency: 'USD' }).equalsTo(Dinero({ amount: 800, currency: 'EUR' }))

// returns true
Dinero({ amount: 1000, currency: 'EUR', precision: 2 }).equalsTo(Dinero({ amount: 10000, currency: 'EUR', precision: 3 }))

// returns false
Dinero({ amount: 10000, currency: 'EUR', precision: 2 }).equalsTo(Dinero({ amount: 10000, currency: 'EUR', precision: 3 }))

Checks whether the value represented by this object is less than the other.

// returns true
Dinero({ amount: 500 }).lessThan(Dinero({ amount: 800 }))

// returns false
Dinero({ amount: 800 }).lessThan(Dinero({ amount: 500 }))

// returns true
Dinero({ amount: 5000, precision: 3 }).lessThan(Dinero({ amount: 800 }))

// returns false
Dinero({ amount: 800 }).lessThan(Dinero({ amount: 5000, precision: 3 }))

Checks whether the value represented by this object is less than or equal to the other.

// returns true
Dinero({ amount: 500 }).lessThanOrEqual(Dinero({ amount: 800 }))

// returns true
Dinero({ amount: 500 }).lessThanOrEqual(Dinero({ amount: 500 }))

// returns false
Dinero({ amount: 500 }).lessThanOrEqual(Dinero({ amount: 300 }))

// returns true
Dinero({ amount: 5000, precision: 3 }).lessThanOrEqual(Dinero({ amount: 800 }))

// returns true
Dinero({ amount: 5000, precision: 3 }).lessThanOrEqual(Dinero({ amount: 500 }))

// returns false
Dinero({ amount: 800 }).lessThanOrEqual(Dinero({ amount: 5000, precision: 3 }))

Checks whether the value represented by this object is greater than the other.

// returns false
Dinero({ amount: 500 }).greaterThan(Dinero({ amount: 800 }))

// returns true
Dinero({ amount: 800 }).greaterThan(Dinero({ amount: 500 }))

// returns true
Dinero({ amount: 800 }).greaterThan(Dinero({ amount: 5000, precision: 3 }))

// returns false
Dinero({ amount: 5000, precision: 3 }).greaterThan(Dinero({ amount: 800 }))

Checks whether the value represented by this object is greater than or equal to the other.

// returns true
Dinero({ amount: 500 }).greaterThanOrEqual(Dinero({ amount: 300 }))

// returns true
Dinero({ amount: 500 }).greaterThanOrEqual(Dinero({ amount: 500 }))

// returns false
Dinero({ amount: 500 }).greaterThanOrEqual(Dinero({ amount: 800 }))

// returns true
Dinero({ amount: 800 }).greaterThanOrEqual(Dinero({ amount: 5000, precision: 3 }))

// returns true
Dinero({ amount: 500 }).greaterThanOrEqual(Dinero({ amount: 5000, precision: 3 }))

// returns false
Dinero({ amount: 5000, precision: 3 }).greaterThanOrEqual(Dinero({ amount: 800 }))

Checks if the value represented by this object is zero.

// returns true
Dinero({ amount: 0 }).isZero()

// returns false
Dinero({ amount: 100 }).isZero()

Checks if the value represented by this object is positive.

// returns false
Dinero({ amount: -10 }).isPositive()

// returns true
Dinero({ amount: 10 }).isPositive()

// returns true
Dinero({ amount: 0 }).isPositive()

Checks if the value represented by this object is negative.

// returns true
Dinero({ amount: -10 }).isNegative()

// returns false
Dinero({ amount: 10 }).isNegative()

// returns false
Dinero({ amount: 0 }).isNegative()

Checks if this has minor currency units. Deprecates hasCents.

// returns false
Dinero({ amount: 1100 }).hasSubUnits()

// returns true
Dinero({ amount: 1150 }).hasSubUnits()

Checks if this has minor currency units.

// returns false
Dinero({ amount: 1100 }).hasCents()

// returns true
Dinero({ amount: 1150 }).hasCents()

Checks whether the currency represented by this object equals to the other.

// returns true
Dinero({ amount: 2000, currency: 'EUR' }).hasSameCurrency(Dinero({ amount: 1000, currency: 'EUR' }))

// returns false
Dinero({ amount: 1000, currency: 'EUR' }).hasSameCurrency(Dinero({ amount: 1000, currency: 'USD' }))

Checks whether the amount represented by this object equals to the other.

// returns true
Dinero({ amount: 1000, currency: 'EUR' }).hasSameAmount(Dinero({ amount: 1000 }))

// returns false
Dinero({ amount: 2000, currency: 'EUR' }).hasSameAmount(Dinero({ amount: 1000, currency: 'EUR' }))

// returns true
Dinero({ amount: 1000, currency: 'EUR', precision: 2 }).hasSameAmount(Dinero({ amount: 10000, precision: 3 }))

// returns false
Dinero({ amount: 10000, currency: 'EUR', precision: 2 }).hasSameAmount(Dinero({ amount: 10000, precision: 3 }))

Returns this object formatted as a string.

The format is a mask which defines how the output string will be formatted. It defines whether to display a currency, in what format, how many fraction digits to display and whether to use grouping separators. The output is formatted according to the applying locale.

Object	Format	String
Dinero({ amount: 500050 })	'$0,0.00'	$5,000.50
Dinero({ amount: 500050 })	'$0,0'	$5,001
Dinero({ amount: 500050 })	'$0'	$5001
Dinero({ amount: 500050 })	'$0.0'	$5000.5
Dinero({ amount: 500050 })	'USD0,0.0'	USD5,000.5
Dinero({ amount: 500050 })	'0,0.0 dollar'	5,000.5 dollars

Don't try to substitute the $ sign or the USD code with your target currency, nor adapt the format string to the exact format you want. The format is a mask which defines a pattern and returns a valid, localized currency string. If you want to display the object in a custom way, either use getAmount, toUnit or toRoundedUnit and manipulate the output string as you wish.

toFormat wraps around Number.prototype.toLocaleString. For that reason, format will vary depending on how it's implemented in the end user's environment.

You can also use toLocaleString directly: Dinero().toRoundedUnit(digits, roundingMode).toLocaleString(locale, options).

By default, amounts are rounded using the half away from zero rule (commercial rounding). You can also specify a different roundingMode to better fit your needs.

// returns $2,000
Dinero({ amount: 200000 }).toFormat('$0,0')

// returns €50.5
Dinero({ amount: 5050, currency: 'EUR' }).toFormat('$0,0.0')

// returns 100 euros
Dinero({ amount: 10000, currency: 'EUR' }).setLocale('fr-FR').toFormat('0,0 dollar')

// returns 2000
Dinero({ amount: 200000, currency: 'EUR' }).toFormat()

// returns $10
Dinero({ amount: 1050 }).toFormat('$0', 'HALF_EVEN')

Returns the amount represented by this object in units.

// returns 10.5
Dinero({ amount: 1050 }).toUnit()

// returns 10.545
Dinero({ amount: 10545, precision: 3 }).toUnit()

Returns the amount represented by this object in rounded units.

By default, the method uses the half away from zero rule (commercial rounding). You can also specify a different roundingMode to better fit your needs.

// returns 10.6
Dinero({ amount: 1055 }).toRoundedUnit(1)

// returns 10
Dinero({ amount: 1050 }).toRoundedUnit(0, 'HALF_EVEN')

Returns the object's data as an object literal.

// returns { amount: 500, currency: 'EUR', precision: 2 }
Dinero({ amount: 500, currency: 'EUR', precision: 2 }).toObject()

Returns the object's data as an object literal.

Alias of toObject. It is defined so that calling JSON.stringify on a Dinero object will automatically extract the relevant data.

// returns '{"amount":500,"currency":"EUR","precision":2}'
JSON.stringify(Dinero({ amount: 500, currency: 'EUR', precision: 2 }))

Returns an array of Dinero objects, normalized to the same precision (the highest).

// returns an array of Dinero objects
// both with a precision of 3
// and an amount of 1000
Dinero.normalizePrecision([
  Dinero({ amount: 100, precision: 2 }),
  Dinero({ amount: 1000, precision: 3 })
])

Returns the smallest Dinero object from an array of Dinero objects

// returns the smallest Dinero object with amount of 500 from an array of Dinero objects with different precisions
Dinero.minimum([
  Dinero({ amount: 500, precision: 3 }),
  Dinero({ amount: 100, precision: 2 })
])

// returns the smallest Dinero object with amount of 50 from an array of Dinero objects
Dinero.minimum([
  Dinero({ amount: 50 }),
  Dinero({ amount: 100 })
])

Returns the biggest Dinero object from an array of Dinero objects

// returns the biggest Dinero object with amount of 20, from an array of Dinero objects with different precisions
Dinero.maximum([
  Dinero({ amount: 20, precision: 2 }),
  Dinero({ amount: 150, precision: 3 })
])

// returns the biggest Dinero object with amount of 100, from an array of Dinero objects
Dinero.maximum([
  Dinero({ amount: 100 }),
  Dinero({ amount: 50 })
])