# comma-number

> Format a number with commas or custom character

Latest version **2.1.0** (published 2021-05-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install comma-number
pnpm add comma-number
yarn add comma-number
bun add comma-number
```

## Health

**Score 33/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2021-05-05 |
| First published | 2015-05-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/comma-number) |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 11.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 31 |
| Author | Eli Doran |
| Maintainers | elidoran |
| Keywords | number, format, comma |

## Links

- npm: https://www.npmjs.com/package/comma-number
- Repository: https://github.com/elidoran/comma-number
- Homepage: https://github.com/elidoran/comma-number#readme
- Issues: https://github.com/elidoran/comma-number/issues
- npm.io page: https://npm.io/package/comma-number

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2021-05-05
- 2.0.2 — 2021-04-28
- 2.0.1 — 2019-04-29
- 2.0.0 — 2017-04-02
- 1.1.0 — 2015-07-16
- 1.0.0 — 2015-05-12

## README

# Comma number
[![Build Status](https://travis-ci.org/elidoran/comma-number.svg?branch=master)](https://travis-ci.org/elidoran/comma-number)
[![npm version](https://badge.fury.io/js/comma-number.svg)](http://badge.fury.io/js/comma-number)
[![Coverage Status](https://coveralls.io/repos/github/elidoran/comma-number/badge.svg?branch=master)](https://coveralls.io/github/elidoran/comma-number?branch=master)


## Install

```sh
$ npm install --save comma-number
```


## Usage

```js
const commaNumber = require('comma-number')

commaNumber(1000) // "1,000"
commaNumber(-1000) // "-1,000"
commaNumber(-1000, '.') // "-1.000"

commaNumber(1000.12) // "1,000.12"
commaNumber(-1000.12) // "-1,000.12"
commaNumber('-1000,12', '.', ',') // "-1.000,12"

// make a new function using custom separator and decimal char:
const format = commaNumber.bindWith('_', '!')
// use it as you would commaNumber().
format(1000)     // "1_000"
format(-1000)    // "-1_000"
format(1000.12)  // "1_000!12"
format(-1000.12) // "-1_000!12"
```


## Version 2 Changes

Revised implementation changes the API a bit:

1. input with a type other than `string` and `number` is returned **as is**, not as `'0'`.
2. supports decimals in the number
3. a string number may use an alternate decimal character, specify it as the third argument
4. added a `bindWith` function to use a currying style to bind options for a reusable format function.

Other changes:

1. Added benchmarking to test implementation performance
2. added code coverage
3. added new badges in this README
4. added more versions to the Travis CI config


## API

### commaNumber(number, [separator=','], [decimalChar='.'])

**Parameters:**

* number : {(Number|String)} Number to format
* separator : {String} Value used to separate numbers
* decimalChar : {String} Value used to separate the decimal value

**Returns:**

* {String} Comma formatted number


### bindWith(separator, decimalChar)

The `commaNumber` function accepts these same parameters as the second and third params. This prevents using currying to bind them and reuse that bound function.

The `bindWith` function accepts the options and returns a function bound with them.

```javascript
// the default commaNumber uses a comma separator and period for decimal char.
var commaNumber = require('comma-number')
  // can build a custom version using bindWith.
  , format = commaNumber.bindWith('_', '!')
  , result1 = commaNumber(1234567.89)
  , result2 = format('1234567.89')

console.log(result1) // outputs:  1,234,567.89
console.log(result2) // outputs:  1_234_567!89
```


## Scripts for Testing, Benchmarking, and Code Coverage

```sh
# run tests via tap
$ npm test

# benchmark current implementation versus previous
npm run benchmark

# get coverage info by default with testing:
npm test
```


## Performance Comparison

The rewrite has a considerable performance increase from the previous version.

I converted the benchmark output from my machine into a [table](docs/benchmark.md).

It compares the performance of version 1.1.0 with 2.0.0. The inputs with decimals can only be processed by the new version so those show as "invalid" for the previous version.


## [MIT License](LICENSE.md)

---
_Source: https://npm.io/package/comma-number · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._