Pretty-money NPM

THIS PROJECT IS DEPRECATED
Starting with Node 14, all currency values are formatted correctly. You can use the built-in Number.prototype.toLocaleString() method instead.
This project will not be developed any further.

pretty-money

A tiny currency formatting library for JavaScript.

Small. Dependency-free. ~500 bytes minified and gzipped. Controlled by Size Limit.
Functional. The function is automatically curried (think Ramda).
Flexible. It can be tweaked to present any modern currency.

import prettyMoney from "pretty-money";
let price = prettyMoney({ currency: "EUR" }, 10000); //=> "10000 EUR"

Works in any environment, be that Node.js or a browser. Try it yourself!

Install

pretty-money is available on NPM, so you can install it your usual way:

npm install pretty-money
# or
yarn add pretty-money

If you only need to use pretty-money on the client side, you can install the latest version with jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/pretty-money@1/dist/pretty-money.umd.js"></script>

In modern browsers, you can use:

<script type="module">
  import prettyMoney from "https://cdn.jsdelivr.net/npm/pretty-money@1/dist/pretty-money.modern.js"
</script>

Usage

There are two ways to use pretty-money: traditional and functional.

Traditional way is to call the function with two parameters: the config object and the number you need to format:

const prettyDollarConfig = {
    currency: "$",
    position: "before",
    spaced: false,
    thousandsDelimiter: ","
}

const priceA = prettyMoney(prettyDollarConfig, 1234); //=> "$1,234"
const priceB = prettyMoney(prettyDollarConfig, 567.89); //=> "$567.89"

Functional way is to curry the function, i.e. to create a function with a set config and to later call it with only one parameter — the number to format:

const prettyEuro = prettyMoney({
    currency: "€",
    decimals: "fixed",
    decimalDelimiter: ",",
    thousandsDelimiter: "."
})

const priceA = prettyEuro(1234); //=> "1.234,00 €"
const priceB = prettyEuro(567.89); //=> "567,89 €"

You can read more about the available configuration parameters in the next section, Config.

Config

`currency`

Type: string
Default: ""

The string to be used as currency symbol.
It can be a respective sign (like "$"), currency code (like "GBP") or a word (like "peso").

`decimalDelimiter`

Type: string
Default: "."

The string that separates the integer and the fractional parts of the number.

`maxDecimal`

Type: number
Default: 2

The maximum number of decimal places allowed in the number.

`minDecimal`

Type: number
Default: 0

The minimum number of decimal places allowed in the number. Has no effect when decimals is set to "fixed".

`decimals`

Type: string
Values: "fixed", "fluid" or "minmax"
Default: "minmax"

Sets the strategy to calculate the amount of decimal places.

"fixed" — the amount of places will always stay at maxDecimal. minDecimal has no effect.
"fluid" — the amount of places will stay at any number between minDecimal and maxDecimal, in order not to have trailing zeros.
"minmax" — the amount of places will stay at maxDecimal unless it's possible to be at minDecimal without having trailing zeros.

`position`

Type: string
Values: "before" or "after"
Default: "after"

Sets the position of the currency symbol with respect to the number.

`spaced`

Type: boolean
Default: true

Sets whether there should be a space between the number and the currency symbol.

`thousandsDelimiter`

Type: string
Default: ""

A string that separates the thousands of the number.

Difference from `toLocaleString`

ECMAScript's Number has a method toLocaleString, which has a similar idea. It too can be used to format numbers as financial values, and it even has a lot of built-in locales. However, the output of it is different on different Node.js versions and browsers:

let price = (10000).toLocaleString("ru", {
    style: "currency",
    currency: "RUB"
});

console.log(price);
//=> "10 000,00 ₽"    in modern browsers
//=> "RUB 10,000.00"  in Node v12.13.0
//=> "RUB 10,000"     in Node v4.8.6

This can lead to unexpected output and difficulties in debugging.

While pretty-money doesn't have any locales built-in, it provides a flexible API, so that the end user can compose any currency formatting function they need.

let price = prettyMoney({
    currency: "₽",
    thousandsDelimiter: " "
}, 10000);

console.log(price);
//=> "10 000 ₽"       in every Node, in every browser

Development

If you want to improve pretty-money, create your own fork of it or just play around with the developer build, here's all you need to know:

yarn dev to start a dev server, which will automatically build the library after you change the source and output it to ./dist/
yarn build to build the production-ready minified version of the library and output it to ./dist/
yarn test to build the project and run all tests, which include:
- yarn test:lint to check the code formatting with ESLint (this won't auto fix errors)
- yarn test:unit to run the uvu unit tests and calculate coverage
- yarn test:size to check the size

There are no peer dependencies and other extra requirements. Any help is welcome when it keeps things simple and small.