# full-numbers

> A nice JS package to convert numbers to words.

Latest version **1.2.0** (published 2020-07-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install full-numbers
pnpm add full-numbers
yarn add full-numbers
bun add full-numbers
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2020-07-13 |
| First published | 2020-04-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 17.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Julio Lozovei |
| Maintainers | jlozovei |
| Keywords | converter, number, string, full numbers, numbers in full, numbers to words, currency to words |

## Links

- npm: https://www.npmjs.com/package/full-numbers
- Repository: https://github.com/jlozovei/full-numbers
- Homepage: https://github.com/jlozovei/full-numbers#readme
- Issues: https://github.com/jlozovei/full-numbers/issues
- npm.io page: https://npm.io/package/full-numbers

## 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

- 1.2.0 (latest) — 2020-07-13
- 1.1.0 — 2020-05-02
- 1.0.0 — 2020-05-02
- 0.0.3 — 2020-05-01
- 0.0.2 — 2020-05-01
- 0.0.1 — 2020-04-30
- 0.0.0 — 2020-04-30

## README

# full-numbers
A nice JS package to convert numbers to words. :zero: :arrow_right: :abc:

:tada: Multilanguage and currency support :tada:

[![codecov](https://codecov.io/gh/jlozovei/full-numbers/branch/master/graph/badge.svg)](https://codecov.io/gh/jlozovei/full-numbers)
![Release](https://github.com/jlozovei/full-numbers/workflows/Release/badge.svg?branch=master)


## :closed_book: Usage
First things first - install the package using `npm` or `yarn`:

```bash
# using npm
npm i full-numbers

# using yarn
yarn add full-numbers
```

After that, import the helper wherever you want to use it:

```js
// es-modules
import fullNumbers from 'full-numbers';

// commonjs
const fullNumbers = require('full-numbers');
```

Then, you'll be able to use it:

```js
const words = fullNumbers(1234); // "one thousand, two hundred thirty-four"

// or

const words = fullNumbers({
  value: 1234,
  lang: 'pt-BR',
}); // "um mil, duzentos e trinta e quatro"
```

To use with `currency` support:

```js
// "simple" values
const words = fullNumbers({
  value: 1234,
  lang: 'pt-BR',
  currency: {
    name: {
      singular: 'real',
      plural: 'reais'
    },
    decimals: {
      singular: 'centavo',
      plural: 'centavos'
    }
  }
}); // "um mil, duzentos e trinta e quatro reais"

// with decimals
const words = fullNumbers({
  value: 1234.5,
  lang: 'pt-BR',
  currency: {
    name: {
      singular: 'real',
      plural: 'reais'
    },
    decimals: {
      singular: 'centavo',
      plural: 'centavos'
    }
  }
}); // "um mil, duzentos e trinta e quatro reais e cinquenta centavos"
```


### Avaliable Options
| Name               | Type           | Description         | Example      |
| ------------------ | -------------- | ------------------- | ------------ |
| `value`            | number         | The value           | `123`        |
| `lang`             | string         | The output language | `pt-BR`      |
| `currency`         | object         | The output currency | See below    |

The currency object should look like this:

```js
{
  name: {
    singular: 'real',
    plural: 'reais'
  },
  decimals: {
    singular: 'centavo',
    plural: 'centavos'
  }
}
```

The `singular`/`plural` keys are important to avoid mismatch of grammar rules.


## :computer: Developing
First, fork the project. After it, install the dependencies (preferably using [npm](https://npmjs.com/) - since the project is using it) and do the work.

Also, take a look at the [contributing guide](https://github.com/jlozovei/full-numbers/blob/master/.github/CONTRIBUTING.md)!

### :books: Adding a new language
To add a new language, follow the steps below:

- Create a new `.json` file within `src/languages` directory. The name of this file should be a valid language code (i.e. `en`, `pt-BR`...)
- The file must have the following keys:
  - `PUNCTUATION`: an object of punctuations used between `dozens`, `hundreds` and `decimals` - if the language doesn't use them, leave the values blank;
  - `LESS_THAN_TWENTY`: an array of numbers' names between 0 and 19.
  - `DOZENS`: an array of dozens' names bewteen 0 and 90;
  - `HUNDREDS`: an object with the singular/plural names of hundreds between 100 and 900 - if the names are equal, leave the two keys with the same value;
  - `SHORT_SCALE_NAME`: an object with the [short scale name](https://en.wikipedia.org/wiki/Long_and_short_scales#Short_scale) from 100 (hundred) to 1000000000000000 (quadrillion).

You can follow the [`en.json`](https://github.com/jlozovei/full-numbers/blob/master/src/languages/en.json) file as an example to follow, and see the [supported languages here](https://github.com/jlozovei/full-numbers/tree/master/src/languages).


## :closed_lock_with_key: License
Licensed under the [MIT](https://github.com/jlozovei/full-numbers/blob/master/LICENSE).

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