### Installation with npm and yarn
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Instructions for installing currency.js using package managers npm and yarn.
```sh
npm install --save currency.js
```
```sh
yarn add currency.js
```
--------------------------------
### Install with yarn
Source: https://github.com/scurker/currency.js/blob/main/docs/01-installation.md
Use this command to install the library if you are using yarn.
```sh
yarn add currency.js
```
--------------------------------
### Install with npm
Source: https://github.com/scurker/currency.js/blob/main/docs/01-installation.md
Use this command to install the library if you are using npm.
```sh
npm install --save currency.js
```
--------------------------------
### Installing Latest Cutting Edge Version
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Install the latest development version of currency.js tagged as 'next' on npm.
```sh
npm install --save currency.js@next
```
--------------------------------
### Installation via CDN
Source: https://github.com/scurker/currency.js/blob/main/readme.md
How to include currency.js in your project using a Content Delivery Network (CDN).
```html
```
--------------------------------
### Arithmetic Operations
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Examples of addition, subtraction, multiplication, and distribution using currency.js methods.
```javascript
currency(123.50).add(0.23); // 123.73
currency(5.00).subtract(0.50); // 4.50
currency(45.25).multiply(3); // 135.75
currency(1.12).distribute(5); // [0.23, 0.23, 0.22, 0.22, 0.22]
```
--------------------------------
### Import currency.js in JavaScript
Source: https://context7.com/scurker/currency.js/llms.txt
Import the library using ES module or CommonJS syntax depending on your project setup.
```js
// ES module
import currency from 'currency.js';
// CommonJS
const currency = require('currency.js');
```
--------------------------------
### Get Decimal Value of Currency
Source: https://github.com/scurker/currency.js/blob/main/docs/04-api.md
Access the decimal value of a currency instance. Useful for calculations or display.
```javascript
currency("123.45").add(.01).value; // => 123.46
```
--------------------------------
### Get Cent Value of Currency
Source: https://github.com/scurker/currency.js/blob/main/docs/04-api.md
Extracts the cent value from a currency instance, discarding the dollar amount. Useful for specific financial calculations or representations.
```javascript
currency(123.45).cents(); // => 45
```
```javascript
currency("0.99").cents(); // => 99
```
--------------------------------
### Get Fractional Cent Amount
Source: https://context7.com/scurker/currency.js/llms.txt
Returns the fractional cent portion of the currency value as an integer. Useful for payment processing APIs that expect cents as an integer.
```javascript
currency(123.45).cents(); // => 45
currency(0.99).cents(); // => 99
currency(1.00).cents(); // => 0
currency(1.5).cents(); // => 50
// Useful for payment processing (pass cents as integer to APIs like Stripe)
const charge = currency(29.99);
const stripeAmount = charge.intValue; // => 2999 (Stripe expects cents as integer)
```
--------------------------------
### Get Whole Dollar Amount
Source: https://context7.com/scurker/currency.js/llms.txt
Returns the whole-number dollar portion of the currency value, truncating any decimal part. Useful for separating dollars and cents.
```javascript
currency(123.45).dollars(); // => 123
currency(0.99).dollars(); // => 0
currency(-5.75).dollars(); // => -5
// Display dollars and cents separately
const price = currency(19.99);
`${price.dollars()} dollars and ${price.cents()} cents`; // => "19 dollars and 99 cents"
```
--------------------------------
### Get Integer Value of Currency
Source: https://github.com/scurker/currency.js/blob/main/docs/04-api.md
Retrieve the integer representation of the currency, effectively removing decimal places. Useful for internal storage or specific calculations.
```javascript
currency("123.45").add(.01).intValue; // => 12346
```
--------------------------------
### Get Dollar Value of Currency
Source: https://github.com/scurker/currency.js/blob/main/docs/04-api.md
Extracts the whole dollar amount from a currency instance, discarding any cents. Useful when only the main currency unit is needed.
```javascript
currency(123.45).dollars(); // => 123
```
```javascript
currency("0.99").dollars(); // => 0
```
--------------------------------
### Initialize Currency Values
Source: https://github.com/scurker/currency.js/blob/main/docs/02-usage.md
Demonstrates initializing currency values from different input types including numbers, decimals, and strings. Handles various string formats with currency symbols and commas.
```javascript
// Numbers
currency(1); // => "1.00"
currency(123); // => "123.00"
// Decimals
currency(1.00); // => "1.00"
currency(1.23); // => "1.23"
// Strings
currency("1.23"); // => "1.23"
currency("$12.30"); // => "12.30"
currency("£1,234,567.89"); // => "1,234,567.89"
// Currency
let c1 = currency(1.23);
let c2 = currency(4.56);
currency(7.89).add(c1).add(c2); // => "13.68"
```
--------------------------------
### Setting Up Factory Functions for Currencies
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Create factory functions to easily set up currency instances with specific settings like symbol and precision. This simplifies working with multiple currencies.
```javascript
const USD = value => currency(value, { symbol: "$", precision: 2 });
const JPY = value => currency(value, { symbol: "¥", precision: 0 });
const GAS = value => currency(value, { precision: 3 });
USD(1234.56).format(); // "$1,234.56"
JPY(1234.56).format(); // "¥1,235"
GAS(1234.56).format(); // "$1,234.560"
```
--------------------------------
### Basic Arithmetic with currency.js
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Demonstrates how currency.js resolves floating-point inaccuracies in addition and subtraction compared to standard JavaScript.
```javascript
2.51 + .01; // 2.5199999999999996
currency(2.51).add(.01); // 2.52
2.52 - .01; // 2.5100000000000002
currency(2.52).subtract(.01); // 2.51
```
--------------------------------
### Create currency instances
Source: https://context7.com/scurker/currency.js/llms.txt
Instantiate currency objects from numbers, numeric strings, or other currency instances. Handles symbols and separators automatically. Invalid input defaults to 0.
```js
// Numbers
currency(123); // value: 123.00, intValue: 12300
currency(1.23); // value: 1.23, intValue: 123
// Strings — symbols, separators, and negative notations are all stripped
currency("$12.30"); // value: 12.30
currency("£1,234,567.89"); // value: 1234567.89
currency("-$5,000"); // value: -5000.00
currency("($5,000)"); // value: -5000.00 (parenthesis = negative)
// Another currency instance
const a = currency(4.56);
currency(a); // value: 4.56
// From minor units (cents)
currency(123456, { fromCents: true }); // value: 1234.56
currency(123456, { fromCents: true, precision: 3 }); // value: 123.456
// Invalid input
currency(null); // value: 0.00 (silent)
currency(undefined, { errorOnInvalid: true }); // throws Error('Invalid Input')
// Access raw internal values
currency(123.45).value; // => 123.45 (float)
currency(123.45).intValue; // => 12345 (integer, scaled by precision)
```
--------------------------------
### Customized Formatting with Locale Options
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Illustrates how to customize currency formatting for different locales by specifying symbols, decimal separators, and group separators.
```javascript
var euro = value => currency(value, { symbol: "€", separator: ".", decimal: "," });
euro("2.573.693,75").add("100.275,50").format(); // "€2.673.969,25"
euro("1.237,72").subtract(300).format(); // "€937,72"
```
--------------------------------
### Parsing Various Input Types
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Shows how currency.js can parse numbers, strings, and existing currency instances.
```javascript
currency(123); // 123.00
currency(1.23); // 1.23
currency("1.23") // 1.23
currency("$12.30") // 12.30
var value = currency("123.45");
currency(value); // 123.45
```
--------------------------------
### Constructor: currency(value, [options])
Source: https://context7.com/scurker/currency.js/llms.txt
Creates a new immutable currency instance. Accepts numbers, numeric strings, or another currency instance. Invalid input defaults to 0 unless errorOnInvalid is enabled.
```APIDOC
## Constructor: `currency(value, [options])`
### Description
Creates a new immutable currency instance. Accepts numbers, numeric strings (with or without symbols/separators), or another `currency` instance. Invalid input defaults to `0` unless `errorOnInvalid` is enabled.
### Parameters
#### Path Parameters
- **value** (number | string | currency) - Required - The initial value for the currency instance.
- **options** (object) - Optional - Configuration options.
- **fromCents** (boolean) - Optional - If true, interprets the value as minor units (e.g., cents).
- **precision** (number) - Optional - The number of decimal places to use. Defaults to 2.
- **errorOnInvalid** (boolean) - Optional - If true, throws an error for invalid input.
### Request Example
```javascript
// Numbers
currency(123); // value: 123.00, intValue: 12300
currency(1.23); // value: 1.23, intValue: 123
// Strings
currency("$12.30"); // value: 12.30
currency("£1,234,567.89"); // value: 1234567.89
currency("-$5,000"); // value: -5000.00
currency("($5,000)"); // value: -5000.00
// Another currency instance
const a = currency(4.56);
currency(a); // value: 4.56
// From minor units
currency(123456, { fromCents: true }); // value: 1234.56
currency(123456, { fromCents: true, precision: 3 }); // value: 123.456
// Invalid input
currency(null); // value: 0.00 (silent)
currency(undefined, { errorOnInvalid: true }); // throws Error('Invalid Input')
// Access raw internal values
currency(123.45).value; // => 123.45 (float)
currency(123.45).intValue; // => 12345 (integer, scaled by precision)
```
```
--------------------------------
### Default Formatting
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Shows the default currency formatting, including comma delimiters and symbol placement.
```javascript
currency("2,573,693.75").add("100,275.50").format(); // "$2,673,969.25"
currency("1,237.72").subtract(300).format(); // "$937.72"
```
--------------------------------
### Custom Currency Formatting with Options
Source: https://context7.com/scurker/currency.js/llms.txt
Configure currency symbol, separators, decimal places, patterns, rounding, and error handling. Use `errorOnInvalid: true` to enforce valid inputs.
```javascript
const EUR = value => currency(value, {
symbol: '€',
separator: '.',
decimal: ',',
precision: 2,
pattern: '# !',
negativePattern: '-# !',
errorOnInvalid: true,
increment: 0.05,
fromCents: false,
useVedic: false,
});
EUR(1234567.89).format(); // => "1.234.567,89 €"
EUR(1.09).format(); // => "1,10 €" (rounded to 0.05)
```
```javascript
// Japanese Yen — zero decimal precision
const JPY = value => currency(value, { symbol: '¥', precision: 0 });
JPY(1234.567).format(); // => "¥1,235"
```
```javascript
// Indian Rupee — Vedic numbering
const INR = value => currency(value, { symbol: '₹', useVedic: true });
INR(1234567.89).format(); // => "₹12,34,567.89"
```
--------------------------------
### Parsing with fromCents Option
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Demonstrates parsing values that represent minor currency units (like cents) using the `fromCents` option and adjusting precision.
```javascript
currency(123, { fromCents: true }); // 1.23
currency('123', { fromCents: true }); // 1.23
currency(123, { fromCents: true, precision: 0 }); // 123
currency(123, { fromCents: true, precision: 3 }); // 0.123
```
--------------------------------
### Methods
Source: https://github.com/scurker/currency.js/blob/main/docs/04-api.md
Functions for performing operations on currency values.
```APIDOC
## Methods
### add
`currency.add( value )`
Adds a `string`, `number`, or `currency` value to the current currency instance.
```js
currency(123.45).add(.01); // => "123.46"
```
### subtract
`currency.subtract( value )`
Subtracts a `string`, `number`, or `currency` value to the current currency instance.
```js
currency(123.45).subtract(.01); // => "123.44"
```
### multiply
`currency.multiply( number )`
Multiplies the current currency instance by `number`.
```js
currency(123.45).multiply(2); // => "246.90"
```
### divide
`currency.divide( number )`
Divides the current currency instance by `number`.
```js
currency(123.45).divide(2); // => "61.73"
```
### distribute
`currency.distribute( number )`
Distribute takes the currency value, and tries to distribute the amount evenly. Any extra cents left over from the distribution will be stacked onto the first sets of entries.
```js
currency(12.35).distribute(3); // => [4.12, 4.12, 4.11]
currency(12.00).distribute(3); // => [4.00, 4.00, 4.00]
```
### format
`currency.format([ function | options ])`
A simple formatter that returns a human friendly currency format.
```js
currency(1000.00).format(); // => "$1,000.00"
currency("1,234,567/90").add("200,000").format(); // => "$1,434,567.89"
```
The default formatter can be overridden by passing in options as a second parameter.
```js
var euro = value => currency(value, { separator: ' ', decimal: ',', format: ... });
// ...
euro(1000.00).format(); // => "1 000,00"
euro(1234567.89).add("200 000").format(); // => "1 434 567,89"
```
```
--------------------------------
### Default Symbol Formatting
Source: https://github.com/scurker/currency.js/blob/main/docs/03-options.md
Demonstrates the default symbol used when formatting currency values.
```javascript
currency(1.23).format(); // => "$1.23"
```
--------------------------------
### Add values to a currency instance
Source: https://context7.com/scurker/currency.js/llms.txt
Use the `.add()` method to sum values, accepting numbers, strings, or other currency instances. Supports chaining and negative values.
```js
currency(2.51).add(0.01); // => { value: 2.52 }
currency(100).add("50.25"); // => { value: 150.25 }
currency(100).add("$25.00"); // => { value: 125.00 }
// Chaining
const total = currency(10.00)
.add(5.50)
.add("2.25")
.add(currency(1.25));
total.value; // => 19.00
total.format(); // => "$19.00"
// Works with negative values
currency(100).add(-25); // => { value: 75.00 }
```
--------------------------------
### Create Custom Currency Formatters
Source: https://github.com/scurker/currency.js/blob/main/docs/05-i18n.md
Define custom currency formatters for USD, JPY, and EURO with specific precision and symbols. These instances can then be used to format values according to their defined locales.
```javascript
const USD = value => currency(value);
const JPY = value => currency(value, { precision: 0, symbol: '¥' });
const EURO = value => currency(value, { symbol: '€', decimal: ',', separator: '.' });
USD(1234.567).format(); // => "$1,234.57"
JPY(1234.567).format(); // => "¥1,235"
EURO(1234.567).format(); // => "€1.234,57"
```
--------------------------------
### Internationalization (i18n) with Factory Functions
Source: https://context7.com/scurker/currency.js/llms.txt
Create immutable currency instances for different locales using factory functions. This pattern is recommended for managing multiple currencies simultaneously.
```javascript
const USD = v => currency(v);
const EUR = v => currency(v, { symbol: '€', decimal: ',', separator: '.' });
const JPY = v => currency(v, { symbol: '¥', precision: 0 });
const GBP = v => currency(v, { symbol: '£' });
const BRL = v => currency(v, { symbol: 'R$', decimal: ',', separator: '.' });
USD(1234.567).format(); // => "$1,234.57"
EUR(1234.567).format(); // => "€1.234,57"
JPY(1234.567).format(); // => "¥1,235"
GBP(1234.567).format(); // => "£1,234.57"
BRL(1234.567).format(); // => "R$1.234,57"
```
```javascript
// Cross-currency arithmetic (same internal integer representation)
const subtotal = USD(100.00).add(USD(24.99));
subtotal.format(); // => "$124.99"
```
--------------------------------
### Format Currency with Default Settings
Source: https://github.com/scurker/currency.js/blob/main/docs/04-api.md
Formats the currency into a human-friendly string using default locale settings. Handles large numbers with commas and specifies decimal places.
```javascript
currency(1000.00).format(); // => "$1,000.00"
```
```javascript
currency("1,234,567/90").add("200,000").format(); // => "$1,434,567.89"
```
--------------------------------
### currency.format([options | function])
Source: https://context7.com/scurker/currency.js/llms.txt
Returns a human-readable formatted string of the currency value. Supports default USD formatting and customizable options or a custom formatter function.
```APIDOC
## `currency.format([options | function])`
Returns a human-readable formatted string. By default formats as USD (`$1,234.56`). Accepts an options object to override formatting, or a custom formatter function for full control.
### Parameters
#### Path Parameters
- **options** (object | function) - Optional - An object with formatting options or a custom formatter function.
- **symbol** (string) - The currency symbol.
- **separator** (string) - The thousands separator.
- **decimal** (string) - The decimal separator.
- **pattern** (string) - The pattern for formatting the number and symbol.
- **negativePattern** (string) - The pattern for negative numbers.
- **format** (function) - A custom function to format the currency.
### Request Example
```js
// Default USD formatting
currency(1000).format(); // => "$1,000.00"
currency(-42.5).format(); // => "-$42.50"
// Override options inline
currency(1234.56).format({ symbol: '€', separator: '.', decimal: ',' });
// => "€1.234,56"
// Custom pattern: symbol after the number
currency(1.23, { pattern: '# !' }).format(); // => "1.23 $"
// Custom negative pattern
currency(-1.23, { negativePattern: '(!#)' }).format(); // => "($1.23)"
// Custom formatter function — full control over output
currency(1234.56, {
format(c, opts) {
return `${opts.symbol}${c.dollars()}.${String(c.cents()).padStart(2, '0')}`;
}
}).format(); // => "$1234.56"
```
### Response
#### Success Response (200)
- **string** - The formatted currency string.
```
--------------------------------
### Properties
Source: https://github.com/scurker/currency.js/blob/main/docs/04-api.md
Accessors for retrieving specific parts of the currency value.
```APIDOC
## Properties
### value
`currency.value`
Returns the decimal value of the currency.
```js
currency("123.45").add(.01).value; // => 123.46
```
### intValue
`currency.intValue`
Returns the integer value of the currency.
```js
currency("123.45").add(.01).intValue; // => 12346
```
### dollars
`currency.dollars`
Returns the dollar value of the currency.
```js
currency(123.45).dollars(); // => 123
currency("0.99").dollars(); // => 0
```
### cents
`currency.cents`
Returns the cent value of the currency.
```js
currency(123.45).cents(); // => 45
currency("0.99").cents(); // => 99
```
```
--------------------------------
### Access Raw Integer and String Values
Source: https://github.com/scurker/currency.js/blob/main/docs/02-usage.md
Explains how to retrieve the internal integer representation or the default string representation of a currency value using the .intValue and .value properties.
```javascript
// Get the internal values
currency(123.45).add(.1).value; // => 123.55
currency(123.45).add(.1).intValue; // => 12355
```
--------------------------------
### Custom Format Function
Source: https://github.com/scurker/currency.js/blob/main/docs/03-options.md
Provide a custom function to format the currency, receiving the currency object and options.
```javascript
function format(currency, options) {
return `${currency.dollars()}.${currency.cents()}`;
}
currency(1234.56, { format }).format(); // => "1234.56"
```
--------------------------------
### Format Currency to String
Source: https://context7.com/scurker/currency.js/llms.txt
Returns a human-readable formatted string. Defaults to USD format. Accepts options to override symbol, separator, decimal, or a custom formatter function for complete control.
```javascript
// Default USD formatting
currency(1000).format(); // => "$1,000.00"
currency(-42.5).format(); // => "-$42.50"
// Override options inline
currency(1234.56).format({ symbol: '€', separator: '.', decimal: ',' });
// => "€1.234,56"
// Custom pattern: symbol after the number
currency(1.23, { pattern: '# !' }).format(); // => "1.23 $"
// Custom negative pattern
currency(-1.23, { negativePattern: '(!#)' }).format(); // => "($1.23)"
// Custom formatter function — full control over output
currency(1234.56, {
format(c, opts) {
return `${opts.symbol}${c.dollars()}.${String(c.cents()).padStart(2, '0')}`;
}
}).format(); // => "$1234.56"
```
--------------------------------
### Custom Pattern Formatting
Source: https://github.com/scurker/currency.js/blob/main/docs/03-options.md
Define a custom pattern for currency formatting using '!' for the symbol and '#' for the amount.
```javascript
currency(1.23, {
pattern: `# !`
}).format(); // => "1.23 $"
```
--------------------------------
### Handle Formatted Strings and Negative Values
Source: https://github.com/scurker/currency.js/blob/main/docs/02-usage.md
Shows how currency.js can parse and manipulate currency values represented as strings, including those with currency symbols, commas, and negative signs. The format() method can be used for display.
```javascript
var c = currency("$1,234.56").add("890.12"); // 2124.68
c.format(); // 2,124.68
// Negative values
currency("-$5,000").add(1234.56); // -3765.44
currency("($5,000)").add(1234.56); // -3765.44
```
--------------------------------
### Customizing Currency Formatting
Source: https://github.com/scurker/currency.js/blob/main/readme.md
Customize the currency symbol, separator, and decimal point for formatting. This is useful for internationalization.
```javascript
currency(1.23, { separator: " ", decimal: ",", symbol: "€" });
```
--------------------------------
### currency.distribute(count)
Source: https://context7.com/scurker/currency.js/llms.txt
Distributes the currency value as evenly as possible into a specified number of parts. Any remainder is added to the first entries.
```APIDOC
## `currency.distribute(count)`
Distributes the currency value as evenly as possible into `count` parts. Any remainder cents are stacked onto the first entries in the returned array, ensuring the total always sums to the original value.
### Parameters
#### Path Parameters
- **count** (number) - Required - The number of parts to distribute the currency into.
### Request Example
```js
currency(12.35).distribute(3);
// => [{ value: 4.12 }, { value: 4.12 }, { value: 4.11 }]
currency(12.00).distribute(3);
// => [{ value: 4.00 }, { value: 4.00 }, { value: 4.00 }]
const tip = currency(10.00);
const shares = tip.distribute(3);
shares.map(s => s.format());
// => ["$3.34", "$3.33", "$3.33"]
currency(-10.00).distribute(3);
// => [{ value: -3.34 }, { value: -3.33 }, { value: -3.33 }]
```
### Response
#### Success Response (200)
- **Array