numerable

numerable-format-demo

# [numerable](https://github.com/gastonmesseri/numerable) **numerable** is a number formatting library for Javascript and Typescript apps. --- ## :gear: Installation Use [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/) 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 ``` --- ### :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](https://www.iso.org/iso-4217-currency-codes.html)) 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: ```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](https://en.wikipedia.org/wiki/Non-breaking_space)***. 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. ```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 ``` --- ### 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. ```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" ``` --- ### 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") ```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 }); //=> '٢‎٬٥‎٤‎٤‎٬٦‎٠‎٩‎٫٠‎' ``` --- ### 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://github.com/adamwdraper)'s project [Numeral.js](http://numeraljs.com/). It has been completely rewriten in Typescript with a functional API and extended features. Also, [date-fns](https://date-fns.org/) 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](http://numeraljs.com/). ## :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](LICENSE.md)