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.

Getting Started

Choose a UnitFormat and create an instance with an optional UnitScale reference:

const formatter = new UnitFormatDefault('en', {
    unitScale: unitScaleByte
});
console.log(formatter.format(1000));
// Output: '1 kB'

Concepts

UnitFormat

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.

UnitScale

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)
• a ScaledUnit 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.

ScaledUnitFormat

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:

new ScaledUnit(
    10 ** 3,
    ScaledUnitFormatIntlNumberFormat.createFactory({
        style: 'unit',
        unit: 'kilobyte',
        unitDisplay: 'short'
    })
),

Contributing

See Getting Started in CONTRIBUTING.md.