NumberFormat aligned library to format numbers with scaled units.
npm install @ni/unit-formatni | unit format
The @ni/unit-format library provides a way to format numbers with units. The library:
- Provides opinionated number formatters that are well-suited for:
- numbers that can appear in large ranges (very small or very large).
- numbers that are always decimal with a configurable number of digits.
- Can scale number values on a unit scale, for example, a metric scale of voltage.
- Provides internationalized number formatting and unit strings.
The library is intended to align well with the Intl.NumberFormat API to make it relatively straightforward to swap in.
Choose a UnitFormat and create an instance with an optional UnitScale reference:
``ts`
const formatter = new UnitFormatDefault('en', {
unitScale: unitScaleByte
});
console.log(formatter.format(1000));
// Output: '1 kB'
There are multiple UnitFormats that represent different configurations for formatting numbers. These represent wrappers around Intl.NumberFormat with opinionated configurations.
For example, the UnitFormatDefault will represent "very large" and "very small" numbers with an exponential notation and numbers between those ranges as decimal. The different UnitFormats take an optional unitScale that provides units and automatic conversions of numbers for that unit scale.
A UnitScale represents a collection of ScaledUnits where a scale factor is used to define each scaled unit. Each UnitScale must have a "base" ScaledUnit with scale factor 1. For example, a byte UnitScale may contain:
- a ScaledUnit of scale factor 1 representing bytes (the base ScaledUnit)ScaledUnit
- a of scale factor 1000 representing kilobytes.
Each ScaledUnit represents a scale factor and a factory function for creating a ScaledUnitFormat instance. This system is used so that the top-level UnitFormat objects can pass configuration settings to individual ScaledUnitFormat instances.
A ScaledUnitFormat is an object for formatting a particular ScaledUnit on the UnitScale.
There are two main types of ScaledUnitFormats:
- ScaledUnitFormatIntlNumberFormat which are scaled units can be translated by Intl.NumberFormat.ScaledUnitFormatManuallyTranslated
- which are scaled units manually translated for a set of supported languages via UnitTranslation string collections.
The different ScaledUnitFormat objects have a static function to assist with their factory creation, for example:
`ts`
new ScaledUnit(
10 ** 3,
ScaledUnitFormatIntlNumberFormat.createFactory({
style: 'unit',
unit: 'kilobyte',
unitDisplay: 'short'
})
),