numerable

numerable is a number formatting library for Javascript and Typescript apps.

---

:gear: Installation

Use npm or yarn to install numerable.

``bash
npm install --save numerable

or

yarn add numerable
`

:book: Usage

`javascript
import { format, parse } from 'numerable';

format(1500250.2, '0,0.00');
//=> '1,500,250.20'

format(0.25, '0.0 %');
//=> '25.0 %'

format(1200, '0.00 a');
//=> '1.20 K'

parse('80.5%');
//=> 0.805
`

---

$3

Numbers formatting in numerable is done through a pattern-based syntax. With these patterns you can easily define common number formats, similar to date formatting.

The numeric pattern syntax defines:
- Amount of decimal places
- Thousands separator (grouping)
- Number sign type (+ - and ())
- Number sign position
- Positive sign visibility


Examples

| Number | Pattern | Result | Locale |
|---------------: |-------------: |-------------------: |:-----------------:|
| 10000 | "0,0.0000" | "10,000.0000" | en (English) |
| 1.23 | "0.0" | "1.2" | en (English) |
| 10000.23 | "0,0" | "10,000" | en (English) |
| 1000.2345 | "0,0.X" | "1,000.2345" | en (English) |
| 1000.2345 | "0,0.X" | "1 000,2345" | fr (French) |
| 0 | "0.00" | "0,00" | fr (French) |
| -10000 | "0,0.0" | "-10.000,0" | es (Spanish) |
| 10000.1234 | "0.000" | "10000.123" | en (English) |
| 10000.001 | "0[.]00" | "10000" | en (English) |
| 10000 | "(0,0.0)" | "10,000.0" | en (English) |
| -10000 | "(0,0.0)" | "(10,000.0)" | en (English) |
| -12300 | "+0,0.00" | "-12,300.00" | en (English) |
| 12300 | "+0,0.00" | "+1,2300.00" | ja (Japanese) |
| 1230 | "0,0+" | "1,230+" | en (English) |
| 1230 | "0,0-" | "1,230" | en (English) |
| 0.67 | "0.0####" | "0.67" | en (English) |
| 0.67 | "0.000##" | "0.670" | en (English) |
| 3162.63 | "0.0####" | "3162.63" | en (English) |
| 3162.6338 | "0.0####" | "3162.6338" | en (English) |
| 0.23 | "000.##" | "000.23" | en (English) |
| 1234.567 | "0,0.00" | "١‎٬٢‎٣‎٤‎٫٥‎٧‎" | arEG (Arabic) |
| undefined | "0,0.00" | "" | en (English) |
| null | "0.00" | "" | en (English) |
| NaN | "0.0" | "" | en (English) |
| | | | |


#### :small_orange_diamond: Percentages

By adding the % symbol to any of the previous patterns, the value is multiplied by 100 and the % symbol is added in the place indicated.


| Number | Pattern | Result | Locale |
|---------------: |-------------: |-------------------: |:-----------------:|
| 0.52 | "0.##%" | "52%" | en (English) |
| 1 | "0.##%" | "100%" | en (English) |
| 1 | "0,0.00 %" | "100.00 %" | en (English) |
| -0.88 | "0 %" | "-88 %" | en (English) |
| | | | |


#### :small_orange_diamond: Abbreviated numbers

If an abbreviation is specified in the pattern (a), numerable will look for the shortest abbreviation for your number, and it will display the number with a locale-specific abbreviation.

| Number | Pattern | Result | Locale |
|---------------: |-------------: |-------------------: |:------------------:|
| 2000000000 | "0.0a" | "2.0B" | en (English) |
| 1230974 | "0.0a" | "1.2M" | en (English) |
| 2460 | "0 a" | "2 mil" | es (Spanish) |
| -104000 | "0 a" | "-104 K" | en (English) |
| 999950 | "0.0a" | "1.0тыс." | ru (Russian) |
| 999999999 | "0 a" | "1 Mio." | de (German) |
| | | | |


#### :small_orange_diamond: Currency

numerable will format the currency symbol if the currency ISO code (ISO 4217) is passed as a format option (e.g. format(155, '$ 0.00', { currency: 'EUR' })) and the dollar symbol ($) is found in the pattern.

| Number | Pattern | Result | Currency |
|---------------: |-------------: |-------------------: |:------------------: |
| 1500.143 | "$0,0.00" | "$1,500.14" | USD (US Dollar) |
| 1500.143 | "$0,0.00" | "€1,500.14" | EUR (Euro) |
| -1500.143 | "0,0.00 $" | "-1,500.14 £" | GBP (Pound Sterling) |
| 1500.143 | "0,0.00 $" | "1,500.14 ¥" | JPY (Yen) |
| 1500.143 | "(0,0.00 $)" | "1,500.14 CN¥" | CNY (Yuan Renminbi) |
| -1500.143 | "(0,0.00 $)" | "(1,500.14 A$)" | AUD (Australian dollar) |
| | | | |


#### :small_orange_diamond: Bytes

numerable allows you to format bytes by adding the 'bd' or 'bb' characters to the pattern.
- 'bd' format bytes in a decimal scale (1000)
- 'bb' format bytes in a binary scale (1024)


| Number | Pattern | Result | Locale |
|---------------: |-------------: |-------------------: |:-----------------:|
| 3500 | "0.00bd" | "3.50KB" | en (English) |
| 3500 | "0.00bb" | "3.42KiB" | en (English) |
| -3500000 | "0.00bb" | "-3.34MiB" | en (English) |
| 2444222000000 | "0.00bd" | "2.44TB" | en (English) |
| 2444222000000 | "0.00bb" | "2.22TiB" | en (English) |
| | | | |


#### :small_orange_diamond: Ordinal numbers

numerable allows you to format ordinal numbers based on the locale. The character 'o' in the mask will enable the ordinal numbers formatting.


| Number | Pattern | Result | Locale |
|---------------: |-------------: |-------------------: |:-----------------:|
| 1 | "0o" | "1st" | en (English) |
| 2 | "0o" | "2nd" | en (English) |
| 3 | "0o" | "3rd" | en (English) |
| 4 | "0o" | "4th" | en (English) |
| 1 | "0o" | "1er" | fr (French) |
| 12 | "0o" | "12º" | es (Spanish) |
| 8 | "0o" | "8." | de (German) |
| | | | |


#### :small_orange_diamond: Time durations

Given an amount of seconds, it will display hours, minutes, and seconds.

| Number | Pattern | Result | Locale |
|---------------: |-------------: |-------------------: |:------------------:|
| 0 | "00:00:00" | "0:00:00" | en (English) |
| 37 | "00:00:00" | "0:00:37" | en (English) |
| 520 | "00:00" | "0:08:40" | en (English) |
| 48923 | "00:00" | "13:35:23" | en (English) |
| -48923 | "00:00" | "-13:35:23" | en (English) |
| | | | |

---

$3

\- Syntax
`
format(number, [pattern="0,0.##########"], [options=DEFAULT_OPTIONS])
`

- number
- type: number | string | null | undefined
- The number to format

- pattern
- type: string | null | undefined
- default: "0,0.##########"
- The pattern used to format the provided number.
- examples:
- "0.00"
- "0,0.00##"
- "0,0.00 %"
- "0.0 a"

- options
- type: FormatOptions | null | undefined
- The options to apply in the format process.
- example:
`javascript
format(1234.56, '0,0.00', {
defaultPattern: '0,0.##########',
nullFormat: 'N/A',
nanFormat: 'NaN',
zeroFormat: '-',
rounding: 'floor',
locale: fr,
});
`
- FormatOptions properties:
- defaultPattern:
- type: string
- default: "0,0.##########"
- It will be the formatting pattern applied in case that the provided pattern in the arguments is null, undefined or "" (empty string).

- rounding:
- type:
- string: "truncate" | "ceil" | "floor" | "half-up" | "half-away-from-zero"
or
- function: (value: number) => number
- default: "half-away-from-zero"
- It will be the rounding function applied to the number in the resolved maximum amount of decimal places.

- nullFormat:
- type: string
- default: ""
- If defined, it will be the returned string when the value is null | undefined | NaN.

- nanFormat:
- type: string
- default: ""
- If defined, it will be the returned string when the value is NaN.

- zeroFormat:
- type: string
- default: undefined
- If defined, it will be the returned string when the value is 0.

- locale:
- type: NumerableLocale
- default: en (english NumerableLocale)
- If a NumerableLocale is provided, it will format the number with the specified locale configuration.

- scalePercentage:
- type: boolean
- default: true
- If true (default), it will multiply the number by 100 when a percentage format is detected. If false, the number won't be scaled when a percentage format is detected.

- trim:
- type: boolean
- default: true
- If true (default), it will trim the output formatted string. If false, the surrounding spaces will be preserved.

- signedZero:
- type: boolean
- default: false
- If true, it will display a negative sign for numbers that before the rounding where negative, but after rounding became zero. If false (default), it will never append the minus sign (-) to zero.
- This option also applies to the positive zeros if the force sign option is defined on the pattern (+ sign in the pattern).
- Example:
- format(-0.008, '0.0', { signedZero: true }) //=> '-0.0'
- format(0.008, '+0.0', { signedZero: true }) //=> '+0.0'

- nonBreakingSpace:
- type: boolean
- default: false
- If true, the spaces in the resulting string will be replaced with non-breaking-spaces. This will help preventing a line break when a normal space is found (although in the end, this will depend on the display engine).


---

$3

\- Syntax
`
parse(numberString, [options=DEFAULT_OPTIONS])
`

- numberString
- type: string
- The numeric string to parse

- options
- type: FormatOptions | null | undefined
- The options to apply in the parse process.
- Same options as in format() function.

---

:crossed_flags: Internationalization (i18n)

numerable includes two functions that support i18n:
- format
- parse

---

$3

In order to handle internationalization:

- Import a numerable locale and pass it to the locale option.
`javascript
import { format, parse } from 'numerable';
import { es, enIN, fr, de } from 'numerable/locale';

format(2500000, '0,0.0 a', { locale: es }); //=> '2,5 M'
format(2500000, '0,0.0 a', { locale: enIN }); //=> '25.0 L'
format(2500000.25, '0,0.00', { locale: fr }); //=> '2 500 000,25'

format(1.5, '0.00', { locale: de }); //=> '1,5'
parse('1,5', { locale: de }); //=> 1.5
`

---

$3

#### - Using custom wrappers

To make your app internationalization handling easy, you can create your own function wrappers and use those instead of the original functions. With this approach, you can make your app localized number formatting API simple.

`javascript
// my-app/utils/format.js
​
import { format } from 'numerable';
import { es, fr, enIN } from 'numerable/locale';
​
const locales = {
es,
fr,
'en-in': enIN,
};
​
export default function (value, pattern = '0,0.000', options) {
const appLocaleId = window.__myLocaleId__;
return format(value, pattern, { locale: locales[appLocaleId], ...options });
}
​
`


`javascript
// Later...

// Importing my custom localized format wrapper
import format from 'my-app/utils/format';
​
window.__myLocaleId__ = 'es';
format(1234.56, '0,0.00');
// => "1.234,56"
​
// With our wrapper function, if the pattern is omitted, it will take the default from the wrapper function.
window.__myLocaleId__ = 'fr';
format(1234.56);
// => "1 234,560"
​
window.__myLocaleId__ = 'en-in';
format(123456789.12, '0,0.0');
// => "12,34,56,789.1"

// 'en' will work, as it is the default locale of numerable
window.__myLocaleId__ = 'en';
format(1234.56, '0,0.00');
// => "1,234.56"
`

---

$3

If a NumerableLocale is provided in any format function, it will format the number with the specified locale.

The locales provided by numerable allow localized support for the following formatting options:
- Thousands and decimal delimiters
- Abbreviations (e.g. "1.5 K")
- Digit grouping style (e.g. "10,00,000.00" or "100,0000.00")
- Different numeral systems (e.g. "٢‎٬٥‎٩‎٩‎٬٦‎٥‎٤‎٫٠‎")
- Ordinal numbers (e.g. "3rd")

`javascript
import { format } from 'numerable';
import { fr, es, enIN, zh } from 'numerable/locale';

format(1234.56, '0.000', { locale: fr }); // Returns "1 234,560"
format(2500000, '0,0.0 a', { locale: es }); //=> '2,5 M'
format(2500000, '0,0.0 a', { locale: enIN }); //=> '25.0 L'
format(2500000, '0,0.0', { locale: zh }); //=> '250,0000.0'
format(2544609, '0,0.0', { locale: arEG }); //=> '٢‎٬٥‎٤‎٤‎٬٦‎٠‎٩‎٫٠‎'
`
---

$3

If you app is simple and you are not supporting legacy browsers or Node. You can create a NumerableLocale based on the platform.

> :warning: Take into account that the support for platform locales is limited. And some of the features, like "ordinal numbers formatting" won't be available if you obtain the locale from the platform.

numerable provides the function getLocaleFromPlatform. This function will dynamically generate a NumerableLocale using the platform Intl.NumberFormat configuration.


`javascript
import { format, getLocaleFromPlatform } from 'numerable';

format(2500, '0,0.0 a', { locale: getLocaleFromPlatform('fr') }); //=> '2,5 k'
format(2500, '0,0.0 a', { locale: getLocaleFromPlatform('cs') }); //=> '2,5 tis.'
format(2500, '0.0 a', { locale: getLocaleFromPlatform('es') }); //=> '2,5 mil'
``

> Cons:
> - Some features won't work on legacy browsers like IE11 or Node (they will fallback to en language), resulting in potential inconsistency across browsers.
> - No full support for formatting features like "ordinal number formatting"

---

:star: Acknowledgements

numerable started as a fork from Adam Draper's project Numeral.js.
It has been completely rewriten in Typescript with a functional API and extended features.
Also, date-fns served as inspiration for some of the features.

> The patterns used in numerable are an extended version of the original patterns created by Numeral.js.

:raised_hands: Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

:pencil: License

MIT © Gaston Meseri