bytes-iec

Bytes utility

Utility to parse a size string in bytes (e.g. '1kB', '2KiB') to numeric (1000, 2048) and vice-versa.

This is a fork of the bytes module, except it

• supports all of both the binary and decimal prefixes defined by ISO/IEC 80000-13:2008
• supports JEDEC, a legacy mode in which metric units have binary values
• uses decimal metric units by default, which can be overridden per call or by default

TypeScript definitions included.

Supported Units

Supported units are as follows and are case-insensitive. Note that only the abbreviation will be parsed/formatted, the full names are for the reader's understanding only.

Metric

Also referred to as SI. See Compatibility Binary for legacy definitions.

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

More info

Binary

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

More info

Compatibility Binary

Also referred to as JEDEC or legacy units.

Overwrites the lower units of the metric system with the commonly misused values, i.e. metric units will be binary instead of decimal. This is the behavior of e.g. the Windows OS and bytes. Units greater than terabyte are not supported.

Value	Abbr	Name
10241	kB	kilobyte
10242	MB	megabyte
10243	GB	gigabyte
10244	TB	terabyte

More info

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-iec');

Modes

Passing a unit type as mode parameter in API calls determines

• the set of units that will be favored by autodetection when no unit is specified
• the value/size of metric units: Compatibility mode makes them base-2 instead of base-10

Unit type	mode
Metric	'metric' or 'decimal'
Binary	'binary'
Compatibility Binary	'compatibility' or 'jedec'

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

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

Arguments

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

Options

Property	Type	Description	Default
decimalPlaces	number｜null	Maximum number of decimal places to include in output	2
fixedDecimals	boolean｜null	Whether to always display the maximum number of decimal places, i.e. preserve trailing zeroes	false
thousandsSeparator	string｜null	What to separate large numbers with, e.g. ',', '.', ' ', ...	''
unit	string｜null	The unit in which the result will be returned: 'B', 'kB', 'KiB', ...	'' (autodetect)
unitSeparator	string｜null	Separator between numeric value and unit	''
mode	string｜null	Which mode to use (see Modes)	'metric'

Returns

Name	Type	Description
results	string｜null	Returns 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 value given has partial bytes, it's truncated (rounded down).

Arguments

Name	Type	Description
value	string｜number	String to parse, or number in bytes
options	Object	Conversion options

Property	Type	Description	Default
mode	string｜null	Which mode to use (see Modes)	'metric'

Returns

Name	Type	Description
results	number｜null	Returns 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: 'jedec'});
// output: 1024

bytes.withDefaultMode(string mode): object

Returns a new copy of the bytes-iec module, but with the given mode as the default.

Arguments

Name	Type	Description
mode	string	Default mode to use (see Modes)

Returns

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

Example

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

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