Hidden

Overview

The Amount is an immutable data type that represents a monetary value with confidence and precision. But why to not just work with regular floating-point numbers?

The fact is that they can quickly become problematic. Because numbers are stored in binary using the IEEE 754 standard, certain decimal values can’t be represented with perfect accuracy. This often leads to unexpected results when performing seemingly simple operations like addition or subtraction — for example, 0.1 + 0.2 resulting in 0.30000000000000004. These small inaccuracies can accumulate over time, causing bugs, rounding issues or inconsistencies in financial and scientific calculations.

Amount stores values as integers in the smallest currency units (e.g., cents) to ensure exactness and avoid floating-point pitfalls.

import { amount } from '@inpulse-ui/utils';

const price = amount(0.1, 'USD');
console.log(price.add(0.2)); // Precisely 0.3

The Amount was built to help you deal with monetary calculations when you’re in a context of ecommerce stores, SaaS apps ERPs, and simple reports. It offers an ever evolving elegant API that must suit most real life scenarios.

If you’re dealing with really large numbers, complex calculations, compound interest and crypto currency, you’ll be in better hands using libraries like Big.js or Dinero.js. Keep that in mind.

Features

• Immutability: Each operation returns a new instance
• Precise Calculations: Avoids floating-point errors
• Comprehensive API: Covers common operations.
• Currency Support: Supports 160+ ISO 4217 currencies
• Formatting: Formats values according to locale (Intl support)
• Conversion: Converts between currencies with rates
• Type Safety: Maintains full type safety
• Fewer Errors: Reduces the chance of accidentally mixing currencies
• Developer Experience: Autocomplete and IntelliSense in the IDE
• Production Ready: Tested even for edge cases with 92.85% coverage

Data Type

This object includes two primary properties with the following types:

• AmountType: An integer that stores the value in the smallest currency units (e.g., cents).
• CurrencyCode: A string containing one of the 160+ active ISO 4217 currency code.

Supported Currencies:

• Main Currencies: USD, EUR, JPY, GBP, BRL, etc.
• Regional Currencies: All active currencies per ISO 4217
• Special Codes: XAU (gold), XAG (silver), XTS (testing), XXX (no currency)

You can access the typing for AmountType and CurrencyCode as follows:

import type { AmountType, CurrencyCode } from '@inpulse-ui/utils';

The active currency code list was updated on January 2024.

Usage

Start importing the method as follows:

import { amount } from '@inpulse-ui/utils';

Then you can simply instantiate a new Amount immutable object as follows:

const price = amount(19.99);
// or
const price = amount(19.99, 'EUR');

If you do not define the currency, it will automacally inherits the default value (“USD”). If you don’t want to set the locale all the time, you can also define it globally.

After that, you can manipulate it using the diverse range of methods we export. All operations returns an Amount instance, so you can chain methods as you like:

price.add(2.99).multiply(2); // 45.96

You can also create a new “empty” instance, preparing it for post manipulations.

let cart = amount();
// And then, when a user adds an item to it
cart = cart.add(19.99);

Please explore all methods to explore the Amount in its full potential.