npm package: @pgm/number-formatter
Description: Fork from: https://github.com/Mottie/javascript-number-formatter
Latest version: 1.0.0

# This is a fork

Fork from: https://github.com/Mottie/javascript-number-formatter

Differences are:

- Converted to typescript ;
- Change transpiler to esbuild, unit testing framework to jest ;
- Added a cache to not process masks everytime.


# Original README (Javascript Number Formatter)

Lightweight & Fast JavaScript Number Formatter

## Introduction

This standalone number formatter<sup>&dagger;</sup> is intended to be short and fast. As they are the main factors for a high performance JavaScript app. Development release is around 150 lines including license info, blank lines and comments. And production release is less than 2,000 bytes.

```js
format( "#,##0.####", 1234567.890 );  // output: "1,234,567.89"
format( "$ #,###.00", -1234567.890 ); // output: "$ -1,234,567.89"

// Added in v2.0.0
format( "$ #,###.00", -1234567.890, {enforceMaskSign: true});  // output: "$ 1,234,567.89"
format( "$ -#,###.00", -1234567.890, {enforceMaskSign: true}); // output: "$ -1,234,567.89"
format( "$ +#,###.00", -1234567.890, {enforceMaskSign: true}); // output: "$ -1,234,567.89"
format( "$ +#,###.00", 1234567.890, {enforceMaskSign: true});  // output: "$ +1,234,567.89"
```

&dagger; Initial development release of this code was written by KPL and hosted at [Google Code](https://code.google.com/p/javascript-number-formatter/).

## Features

* Short, fast, flexible yet standalone.
* Accept standard number formatting like `#,##0.00` or with negation `-000.####`.
* Accept any country format like `# ##0,00`, `#,###.##`, `#'###.##` or any type of non-numbering symbol.
* Accept any numbers of digit grouping. `#,##,#0.000` or `#,###0.##` are all valid.
* Accept any redundant/fool-proof formatting. `##,###,##.#` or `0#,#00#.###0#` are all OK.
* Auto number rounding.
* Simple interface, just supply mask & value like this: `format( "0.0000", 3.141592)`.
* Include a prefix &amp; suffix with the mask.

## Limitations

* No scientific/engineering formatting.
* Not for date or phone formation.
* No color control.
* <del>No prefix or suffix is allowed except leading negation symbol. So `$#,##0.00` or `#,###.##USD` will not yield expected outcome. Use `'$'+format('#,##0.00', 123.45)` or `format('#,##0.00', 456.789) + 'USD'`</del>
* The prefix or suffix *can not* include any numbers (`0-9`), dashes (`-`), or plus signs (`+`).

## Format Symbols

| Description   | Symbol | Summary |
|---------------|--------|---------|
| Mask symbols  | #0123456789+- | Mask symbols used for formatting the value. |
| Placeholders  | #123456789    | Un-forced digit*; this optional digit will only show if it is required as a placeholder. |
| Zero          | 0             | Forced digit; the digit will be shown whether or not the digit is relevant to the value. |
| Signs         | +-            | Indicates a positive or negative value; visible depending on the value sign and the `enforceMaskSign` setting. |
| Leftmost      |               | _Any_ non-mask symbol&dagger; inside the mask will be set to represent a thousands separator. |
| Rightmost     |               | _Any_ non-mask symbol&dagger; inside the mask&Dagger; will be set to represent the decimal separator. |
| Prefix/Suffix |               | _Any_ non-mask symbol&dagger; outside the mask. |

\* Non-zero mask digits (`1` through `9`) behave the same as the `#`.<br>
&dagger; Anything not a digit, and not a `+`, `-` or `#`.<br>
&Dagger; In the case where there is a trailing decimal or comma, it will be included in the mask, e.g. `#.` or `0,`.

## Note

When only one symbol is supplied, the library will always treat that symbol as a decimal. For example, `format( '#,###', 1234567.890)` will output `1234567,890`.

To force a single symbol to be used as a separator, add a trailing symbol. In this example, a period is added to the end of the mask - `format( '#,###.', 1234567.890)` - resulting in it being used as a decimal and forcing the first symbol to be the separator and return this output: `1,234,567`.