numerable-format-demo

numerable

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

:gear: Installation

Use npm or yarn to install numerable.

npm install --save numerable
# or
yarn add numerable

:book: Usage

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

:1234: Formatting numbers

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)

format()

- 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:
```
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).

parse()

- 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

Usage (i18n)

In order to handle internationalization:

Import a numerable locale and pass it to the locale option.

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

App localization handling (i18n)

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

// 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 });
}

// 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"

Numerable locales (i18n)

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")

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 }); //=> '٢‎٬٥‎٤‎٤‎٬٦‎٠‎٩‎٫٠‎'

Using platform locales (i18n)

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.

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.

gastonmesseri / numerable

readme