# UnitFormat.js

[![NPM Package](https://img.shields.io/npm/v/unitformat.svg?style=flat)](https://npmjs.org/package/unitformat "View this project on npm")
[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)

UnitFormat.js is published as [`unitformat`](https://www.npmjs.com/package/unitformat). Its single function scales a number and appends a selected decimal or binary prefix, producing compact values such as `1.3km`, `1.5kB`, or `-1.5MW`.

Use it for compact engineering labels, telemetry, file sizes, and chart axes when a fixed three-decimal rounding policy is acceptable.

## Installation

You can install `UnitFormat.js` via npm:

```bash
npm install unitformat
```

Or with yarn:

```bash
yarn add unitformat
```

Alternatively, download or clone the repository:

```bash
git clone https://github.com/rawify/UnitFormat.js
```

## Usage

### CommonJS

```js
const UnitFormat = require('unitformat');
const formatted = UnitFormat(10000);
```

### ES modules

```js
import UnitFormat, { UnitFormat as NamedUnitFormat } from 'unitformat';
const formatted = UnitFormat(10000);
```

### Standalone browser script

```html
<script src="https://cdn.jsdelivr.net/npm/unitformat@1.1.5/dist/unitformat.min.js"></script>
<script>
  const formatted = UnitFormat(10000);
</script>
```

### Native browser module

```html
<script type="module">
  import UnitFormat from 'https://cdn.jsdelivr.net/npm/unitformat@1.1.5/dist/unitformat.mjs';
  const formatted = UnitFormat(10000);
</script>
```

The package has no runtime dependencies and supports Node.js 20 or newer.
CommonJS consumers can use the direct function export as well as its `.default`
and `.UnitFormat` aliases. These compatibility paths are covered by the test
suite and are part of the supported API.

The interface is a single function that takes the number to be formatted and
optionally the base unit, such as `m` for meters:

```js
const distance = UnitFormat(1000, 'm');   // "1km"
const frequency = UnitFormat(20000, 'Hz'); // "20kHz"
const scalar = UnitFormat(1000);           // "1k"
const small = UnitFormat(0.02, 'm');        // "0.02m"
```

## Recipes

### Format values with the default large SI prefixes

The default prefix set is `kMGTPE`; values below the base unit remain unscaled.

```js
import UnitFormat from 'unitformat';

console.log(UnitFormat(1300, 'm'));       // "1.3km"
console.log(UnitFormat(-1_500_000, 'W')); // "-1.5MW"
console.log(UnitFormat(0.02, 'm'));       // "0.02m"
```

Results are strings rounded to at most three decimal places. Decimal digits, separators, and signs follow the runtime locale when locale formatting is available; otherwise a locale-neutral representation is used.

### Enable small metric prefixes explicitly

The third argument is the exact set of allowed prefixes. Include `c`, `m`, `u`, or `μ` when values below one base unit should be scaled.

```js
import UnitFormat from 'unitformat';

const prefixes = 'kMGTPEhdcmunpfa';

console.log(UnitFormat(0.02, 'm', prefixes));    // "2cm"
console.log(UnitFormat(0.00015, 'm', prefixes)); // "150um"
console.log(UnitFormat(0.000001, 'm', 'μ'));     // "1μm"
```

Prefix characters are case-sensitive. An unknown character throws `Error: Unknown unit ...`.

### Format binary-scaled byte counts

Pass base `2` to interpret `k`, `M`, and larger prefixes as powers of 1024.

```js
import UnitFormat from 'unitformat';

console.log(UnitFormat(1024, 'B', 'kMGTPE', 2)); // "1kB"
console.log(UnitFormat(1536, 'B', 'kMGTPE', 2)); // "1.5kB"
console.log(UnitFormat(1024, 'B', 'kMGTPE', 10)); // "1.024kB"
```

Only bases `2` and `10` are supported; any other explicit base throws. The output uses the supplied symbols (`kB`, `MB`), not IEC labels such as `KiB`.

## Available Parameters


The whole package consists of a single function `UnitFormat` with the following signature

```js
UnitFormat(num, baseUnit="", prefixes="kMGTPE", base=10)
```

- *num*: the number to be formatted
- *baseUnit*: the base unit, like meters, Hertz, Joule, ...
- *prefixes*: allowed single-character prefixes; the default is `kMGTPE`
- *base*: scaling base, either `10` (default) or `2`

## Suffixes


The suffix parameter is a string list of single-character metric prefixes, like `kMGTPE`. For base 10 the following prefixes can be used:

- `E`: Exa
- `P`: Peta
- `T`: Tera
- `G`: Giga
- `M`: Mega
- `k`: Kilo
- `h`: Hecto
- `d`: Deci
- `c`: Centi
- `m`: Milli
- `u`: Micro
- `n`: Nano
- `p`: Pico
- `f`: Femto
- `a`: Atto

And for base 2 the following prefixes are possible:

- `k`: Kilo
- `M`: Mega
- `G`: Giga
- `T`: Tera
- `P`: Peta
- `E`: Exa


## Building the library

The implementation is written in strict TypeScript. The build emits CommonJS,
ES modules, a standalone browser bundle, source maps, and format-specific type
declarations without modifying source or documentation files.

After cloning the Git repository, run:

```
npm install
npm run build
```

## Run a test

Testing the source against the shipped test suite is as easy as

```
npm run test
```

## Copyright and Licensing

Copyright (c) 2026, [Robert Eisele](https://raw.org/)
Licensed under the MIT license.