format-data-size v0.1.0

format-data-size

NPM module for converting and formatting data sizes.

Installation

npm install format-data-size

Usage

import { formatDataSize, formatDataSizeToString } from 'format-data-size';

formatDataSize(1298);
// => { value: '1.30', unit: 'kB' }

formatDataSizeToString(11223.3, { fromUnit: 'kB' });
// => '11.22 MB'

API

formatDataSize(value, [options])

value: bigint | number | string

Specifies the value to be converted and/or formatted.

options: object

Contains the options that can change the way in which input are read and output are manipulated.

options.fromUnit: string

Default: 'B'

Specifies the data unit of the provided value.

options.locale: boolean | string

Default: undefined

Specifies the locale of the output. This only affects the numbers, grouping characters, and decimal character. true means to use system locale, while a [BCP 47 language tag], i.e., 'de', specifies the target language.

options.precision: number | { [min: number], [max: number] }

Default: 2

Specifies the result's precision. [number] means to return the value with exactly the given number of fraction digits, while an object containing properties min and/or max results in the return value possessing the number of fraction digits between min and max (inclusive).

options.toUnit: string

Default: undefined

Specifies which unit or type of units to format the input to. When not provided, the most reasonable target unit is auto selected based on the source unit, i.e.:

• A 4 digit integral kilobyte (kB) will become a 1 digit megabyte (MB).
• A 6 digit integral megabit (Mbit) will become a 3 digit gigabit (Gbit).

It is possible to provide one of 'byte', 'ibyte' (binary), 'bit', or 'ibit' (binary) to reduce the scope of the auto selection.

Rationale

The primary goal of this package is to support working with the bigint primitive type. Many packages with the same purpose lack such support. As memory and storage mediums continue to increase in size, we need larger numbers to represent them. However, working with bigint introduces new costs because there are limited built-in functionalities that can handle it, i.e., the Math functions and some operators such as x ** y are unavailable. Therefore, the initial versions of this package are expected to be less efficient.

Inspired by

• pretty-bytes
• byte-size