@lightspeed/i18n-number-format

Introduction

A utility library that provides internationalized number, currency, and percentage formatting/parsing.

As our applications begin to scale it becomes necessary to begin thinking of internationalization and localization as a feature. Among the many challenges is both formatting as well as parsing numbers and currencies for different locales.

This library aims to facilitate the developer's job in needing to implement i18n/l10n number/currency/percentage formatting and parsing.

With a miniscule API surface it should be flexible enough to handle nearly any situation and easy to use efor developers.

The library is heavy. At the time of writing it weighs approximately 500kb (~60kb gzipped). This is because the library ships with every locale by default. The reason for this is because we are abstracting over Google's Closure Library and it only has compile-time dependency resolution+injection. Run-time injection + lazy-loading + code-splitting have not been implemented yet. Because we don't know which locales an application may need we ship with all of them. We may build hundreds of miniscule bundles per locale and allow lazy-loading of them at the application-level in the future. The Google Closure Library is under the Apache 2.0 license

Table of contents

• Quick Start
• Supported Features
• Usage

Quick Start

npm install --save @lightspeed/i18n-number-format or yarn install @lightspeed/i18n-number-format

Supported Features

• [x] Support for both JS and TS
• [x] Support 100s of locales 💯
• [x] Support 100+ currencies 💯
• [x] Format Numbers
• [x] Format currencies
• [x] Format currencies without symbol
• [x] Format percentage
• [x] Parse a formatted number string
• [x] Parse a formatted currency string
• [x] Parse a formatted percentage string
• [ ] Get all parts from a formatted number string
• [x] Get all parts from a formatted currency string
• [ ] Get all parts from a formatted percentage string

Usage

Note: Incorrect usage in JavaScript will throw errors to help the user avoid making API mistakes from having provided invalid arguments.

import { NumberFormat } from '@lightspeed/i18n-number-format';

const data = 123456.789;
const fmt = new NumberFormat({ locale: 'en-CA' });

const formattedNumber = fmt.format(data, { style: 'decimal' });
// "123,456.789"
const formattedNumberWithFractions = fmt.format(data, {
  style: 'decimal',
  minimumFractionDigits: 0,
  maximumFractionDigits: 2,
});
// "123,456.78"
const formattedMoney = fmt.format(data, { style: 'currency', currencyCode: 'CAD' });
// "$123,456.79"
const formattedMoneyNoSymbol = fmt.format(data, {
  style: 'currency',
  currencyCode: 'CAD',
  excludeCurrencySymbol: true,
});
// "123,456.79"
const formattedMoneyNoFraction = fmt.format(data, {
  style: 'currency',
  currencyCode: 'CAD',
  minimumFractionDigits: 0,
  maximumFractionDigits: 0,
});
// "$123,456"
const formattedPercentage = fmt.format(data, { style: 'percentage' });

const parsedNumber = fmt.parse(formattedNumber, { style: 'decimal' });
// 123456.789
const parsedMoney = fmt.parse(formattedMoney, { style: 'currency', currencyCode: 'CAD' });
// 123456.79
const parsedPercentage = fmt.parse(formattedPercentage, { style: 'percentage' });
// 123456.789

const moneyParts = fmt.getParts(formattedMoney, { style: 'currency', currencyCode: 'CAD' });
/*
 * {
 *   code: "CAD",
 *   decimal: ".",
 *   formattedCurrency: "$123,456.79",
 *   formattedNumber: "123,456.79",
 *   fraction: 79
 *   number: 123456.79,
 *   symbol: "$",
 *   wholeNumber: 123456,
 * }
 **/