Utility to parse a string bytes (ex: 1 ZiB) to bytes (1.1805916207174113e+21) and vice-versa.
$ npm install bytes/pro | yarn install bytes/pro
import bytes from 'bytes/pro';
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. If options contain splitUnit, string array will be returned.
Arguments
Name | Type | Description |
---|---|---|
value | number |
Number value to format or string value to parse |
options | Object |
Conversion options for format |
Options
Property | Type | Description |
---|---|---|
decimalPlaces | number |undefined |
Maximum number of decimal places to include in output. Default value to 2 ;Use with fixedDecimals: true |
fixedDecimals | boolean |undefined |
Whether to always display the maximum number of decimal places. Default value to false ; Use with decimalPlaces |
thousandsSeparator | string |undefined |
Example of values: ' ' , ',' and '.' ... Default value to '' . Use with toUnit |
toUnit | "B" | "KB" | "MB" | "GB" | "TB" | "PB" | "EB" | "ZB" | Convert to specified byte unit |
unitSeparator | string |undefined |
Separator to use between number and unit. Default value to '' .Use with splitUnit: false |
withoutFloat | boolean |undefined |
Parse size without float:If it cannot be converted to integer byte value, the value displayed in B unit |
splitUnit | boolean |
Whether to split byte values and units |
capacityBase | number |
undefined |
Returns
Name | Type | Description |
---|---|---|
results | string |string[] |null |
Return null upon error. string value ; or string array value. |
Example
// fixedDecimals: true
bytes.format(1024 * 1024, { fixedDecimals: true });
// output: '1.00MiB'
// fixedDecimals: true + decimalPlaces: number
bytes.format(1024 * 1024, {
fixedDecimals: true,
decimalPlaces: 3,
});
// output: '1.000MiB'
// toUnit: "B" | "KB" | "MB" | "GB" | "TB" | "PB" | "EB" | "ZB"
bytes.format(1024 * 1024 * 1024, {
toUnit: 'B',
});
// output: '1073741824B'
// thousandsSeparator: string + toUnit: "B" | "KB" | "MB" | "GB" | "TB" | "PB" | "EB" | "ZB"
bytes.format(1024 * 1024 * 1024, {
thousandsSeparator: ',', // Thousands separator
toUnit: 'B',
});
// output: '1,073,741,824B'
// unitSeparator: string
bytes.format(1024 * 1024, { unitSeparator: ' ' });
// output: '1 MiB'
// withoutFloat: true
bytes.format(1024 + 1, {
withoutFloat: true,
});
// output: 1025B
bytes.format(1024, {
withoutFloat: true,
});
// output: 1KiB
// splitUnit: false | true
bytes.format(1024 * 1024, { splitUnit: false });
// output: '1MiB'
bytes.format(1024 * 1024, { splitUnit: true });
// output: ['1', 'MiB']
// capacityBase: 1024 | 1000
bytes.format(1000 * 1000, { capacityBase: 1024 }) | format(1000 * 1000);
// output: '976.56KiB'
bytes.format(1000 * 1000, { capacityBase: 1000 });
// output: '1MiB'
// if value is not isFinite, return null;
// output: 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.
Supported units and abbreviations are as follows and are case-insensitive:
b
for byteskb
for kilobytesmb
for megabytesgb
for gigabytestb
for terabytespb
for petabyteseb
for exabyteszb
for zetbytes
The units are in powers of two, not ten. This means 1kib = 1024b according to this parser.
Arguments
Name | Type | Description |
---|---|---|
value | string |
String to parse. |
Options
Name | Type | Description |
---|---|---|
convert | boolean |
undefined |
capacityBase | number |
undefined |
needUnit | boolean |
undefined |
Returns
Name | Type | Description |
---|---|---|
results | number |null |
Return null upon error. Value in bytes otherwise. |
Example
bytes.parse('10MB', { capacityBase: 1000, convert: false });
// output: 10000000
bytes.parse('10Mb', { convert: true }) | bytes.parse('10Mb');
// output: 10485760
bytes.parse('10Mib');
// output: 10485760
// if parse value isNaN, return null
// output: null
Convert byte string to specified unit string.
Arguments
Name | Type | Description |
---|---|---|
value | string |
string value to parse |
toUnit | "B" | "KB" |
capacityBase | 1024 | 1000 |
Returns
| Name | Type | Description |
| results | string
| null
| Convert to byte unit string |
Example
xbytes.parseToUnit('10TB', 'GB', 1024) | xbytes.parseToUnit('10TB', 'GB');
// output: '10000GB'
xbytes.parseToUnit('10TB', 'GB', 1000);
// output: '10000GB'