@jimpick/bytes-iec

(IEC) Utility to parse a string bytes to bytes and vice-versa

Usage no npm install needed!

<script type="module">
  import jimpickBytesIec from 'https://cdn.skypack.dev/@jimpick/bytes-iec';
</script>

README

Bytes utility

NPM Version NPM Downloads

Utility to parse a string bytes (ex: 1TB) to bytes (1,000,000,000,000) and vice-versa.

This uses the byte units defined in ISO/IEC 80000-13:2008, both the binary prefixes and the original SI units.

This is a fork of the bytes module, except:

  • It uses IEC units by default
  • Supports a wider range of units
  • Supports changing to compatability (JEDEC) mode, and formatting in whichever prefix type you prefix (binary, metric, compatibility)

Supported Units

Supported units and abbreviations are as follows and are case-insensitive:

Metric/Decimal Prefixes

Value Abbr Name
1 B byte
10001 kB kilobyte
10002 MB megabyte
10003 GB gigabyte
10004 TB terabyte
10005 PB petabyte
10006 EB exabyte
10007 ZB zettabyte
10008 YB yottabyte

Binary Prefixes:

Value Abbr Name
1 B byte
10241 KiB kibibyte
10242 MiB mebibyte
10243 GiB gibibyte
10244 TiB tebibyte
10245 PiB pebibyte
10246 EiB exbibyte
10247 ZiB zebibite
10248 YiB yobibite

Compatibility Binary Prefixes (JEDEC)

Overwrites the lower units of the metric system with the commonly misused prefixes

Value Abbr Name
10001 kB kilobyte
10002 MB megabyte
10003 GB gigabyte
10004 TB terabyte

Installation

This is a Node.js module available through the npm registry. Installation is done using the npm install command:

npm install bytes-iec

Usage

var bytes = require('bytes');

bytes.format(number value, [options]): string|null

Format the given value in bytes into a string. If the value is negative, it is kept as such. If it is a float, it is rounded.

It supports the following output formats:

  • binary: uses the binary prefixes (KiB, MiB...)
  • decimal|metric: uses the metric system (decimal) prefixes (kB, MB...)
  • compatibility: uses the binary units, but the metric prefixes (kB == 1024B, MB...)

Arguments

Name Type Description
value number Value in bytes
options Object Conversion options

Options

Property Type Description
decimalPlaces numbernull Maximum number of decimal places to include in output. Default value to 2.
fixedDecimals booleannull Whether to always display the maximum number of decimal places. Default value to false
thousandsSeparator stringnull Example of values: ' ', ',' and .... Default value to ''.
unit stringnull The unit in which the result will be returned (B/KB/MB/GB/TB). Default value to '' (which means auto detect).
unitSeparator stringnull Separator to use between number and unit. Default value to ''.
mode string&124;null Which format to output: binary, metric, decimal, compatibility. Default value is metric

Returns

Name Type Description
results stringnull Return null upon error. String value otherwise.

Example

bytes(1000);
// output: '1kB'

bytes(1000, {thousandsSeparator: ' '});
// output: '1 000B'

bytes(1024);
// output: '1.02kB'

bytes(1024 * 1.7, {decimalPlaces: 0});
// output: '2KB'

bytes(1000, {unitSeparator: ' '});
// output: '1 kB'

bytes(2048, {mode: 'binary'});
// output: '2 KiB'

bytes(1024 * 1024 * 2, {unit: 'KiB'});
// output: '2048 KiB'

bytes(1024 * 1024 * 2, {unit: 'KB'});
// output: '2097.152 KB'

bytes(1024 * 1024 * 2, {unit: 'KB', mode: 'compatibility'});
// output: '2048 KB'

bytes.parse(string|number value): number|null

Parse the string value into an integer in bytes. If no unit is given, or value is a number, it is assumed the value is in bytes.

If the unit given has partial bytes, they are dropped (rounded down).

Arguments

Name Type Description
value stringnumber String to parse, or number in bytes.
options Object Conversion options
Property Type Description
mode string|null Which mode to use (see bytes.format)

Returns

Name Type Description
results numbernull Return null upon error. Value in bytes otherwise.

Example

bytes('1kB');
// output: 1024

bytes('1024');
// output: 1024

bytes('1.0001 kB');
// output: 1000
bytes('1.0001 KiB');
// output: 1024

bytes('1kB', {mode: compatibility});
// output: 1024

bytes.withDefaultMode(string mode): object

Returns a new module which acts like the bytes module, except with the given mode as the default.

Arguments

Name Type Description
mode string Default mode to use

Returns

Name Type Description
results object Returns the byte.js module, with a default mode

Example

var bytes = require('bytes').withDefaultMode('compatibility');

bytes('1kB');
// output: 1024

bytes('1KiB');
// output: 1024

bytes(1024);
// output: 1 kB

bytes(1024, {mode: 'metric'});
// output: 1.02kB

bytes('1kB', {mode: 'metric'});
// output: 1000

License

MIT