Home

Awesome

ByteParser (xbytes)

NodeJS Byte Parser Parse bytes to human readable sizes (4747) → ('4.75 KB') and vice versa.

NPM Version NPM Downloads

NPM

Installing

Via NPM:

npm install xbytes

Usage

// Node CommonJS
const xbytes = require('xbytes');
// Or Node ES6 Modules
import xbytes from 'xbytes';
// Or TypeScript
import * as xbytes from 'xbytes';

<!-- Or in the Browser -->
<script src="xbytes/dist/index.js"></script>

Examples

xbytes(4747); // '4.75 KB'
xbytes(-3946); // '-3.95 KB'
xbytes(34.724e+4); // '347.24 KB'
xbytes(32000000000); // '32.00 GB'
xbytes(21474836480, {iec: true}); // '20.00 GiB'
xbytes.parseSize('10 GB'); // 10000000
xbytes.parseSize('-50 GiB'); // -53687091200

IEC Specification*

xbytes(5242880, {iec: true}); // '5 MiB'

xbytes.parseSize('10 GiB'); // 10485760

API

<a id='fn:xbytes'></a> xbytes(byte[, options])

Parse byte to human readable size. If byte is not a number or an number-like string, return null appropriately.

xbytes(2472946)
// << '2.47 MB'
xbytes(49392123904, {iec: true})
// << '46.00 GiB'

<a id='fn:parsesize'></a> xbytes.parseSize(str[, config])

Parse human readable size to bytes

xbytes.parseSize('15.967 MB')
// << 15967000
xbytes.parseSize('5.97 PiB')
// << 6721622443850465

<a id='fn:parse'></a> xbytes.parse(size)

Create a ByteUnitObject around the specified HybridByte

xbytes.parse('10 MiB')
// << ByteUnitObject { bytes: 10485760 }
xbytes.parse('10 MiB').add('20 MiB')
// << ByteUnitObject { bytes: 31457280 }
xbytes.parse('10 MiB').add('20 MiB').toIECBytes()
// << '30.00 MiB'

<a id='fn:isbytes'></a> xbytes.isBytes(str)

Check if the provided string is a ByteString

xbytes.isBytes('10 MiB')
// << true
xbytes.isBytes('Hello')
// << false
xbytes.isBytes('10 iB')
// << false
xbytes.isBytes('10b')
// << true

<a id='fn:isunit'></a> xbytes.isUnit(str)

Check if the provided string is an UnitString

xbytes.isUnit('GB')
// << true
xbytes.isUnit('giB')
// << true
xbytes.isUnit('iB')
// << false
xbytes.isUnit('BB')
// << false

<a id='fn:isparsable'></a> xbytes.isParsable(input)

Check if the provided argument is parsable i.e raw_bytes (number) or ByteString.

<a id='fn:relative'></a> xbytes.relative(size[, options])

<a id='fn:relative:bits'></a> xbytes.relative.bits(size[, options])

Show the input size in relation to its bit format

<a id='fn:relative:bytes'></a> xbytes.relative.bytes(size[, options])

Show the input size in relation to its byte format

<a id='fn:relative:iecBits'></a> xbytes.relative.iecBits(size[, options])

Show the input size in relation to its bit format under IEC Standards

<a id='fn:relative:iecBytes'></a> xbytes.relative.iecBytes(size[, options])

Show the input size in relation to its bytes format under IEC Standards

<a id='fn:relative:size'></a> xbytes.relative.size(size[, unit[, options]])

<a id='fn:parsestring'></a> xbytes.parseString(str)

Parse a human readable byte into its components

<a id='fn:parsebytes'></a> xbytes.parseBytes(str, options)

Parse a human readable byte into its components. Extended from parseString(), but with a few extra properties. And flexibility to use parse either an integer byte value or a ByteString resulting in the same object.

<a id='fn:extractbytes'></a> xbytes.extractBytes(str)

Extract all ByteStrings within a string into an array, alternative to str.match(xbytes.byteFilter)

<a id='fn:createbyteparser'></a> xbytes.createByteParser(config)

Construct a static ByteParser with predefined configurations

<a id='fn:createsizeparser'></a> xbytes.createSizeParser(config)

Construct a static SizeParser with predefined configurations

<a id='fn:createrelativesizer'></a> xbytes.createRelativeSizer(unit[, config])

Create a RelativeSizer for converting a hybrid byte into any set unit under predefined configuration

<a id='unitmatcher'></a> xbytes.unitMatcher: RegExp

The raw Regular expression used in scanning all string byte units.

<a id='genericmatcher'></a> xbytes.genericMatcher: RegExp

The raw regular expression used in scanning all byte containing strings.

<a id='bytefilter'></a> xbytes.byteFilter: RegExp

An regular expression extension of genericMatcher with the 'i' flag.

<a id='globalbytefilter'></a> xbytes.globalByteFilter: RegExp

An regular expression extension of genericMatcher with the 'gi' flags.

<a id='unitstring'></a> UnitString: String

Supported Unit Strings

IndexPrefixDecimal BitsBinary Bits (IEC)Decimal BytesBinary Bytes (IEC)
0-b (Bits)b (Bits)b (Bits)b (Bits)
0-B (Bytes)B (Bytes)B (Bytes)B (Bytes)
1KKb (KiloBits)Kib (KiloBits)KB (KiloBytes)KiB (KibiBytes)
2MMb (MegaBits)Mib (MebiBits)MB (MegaBytes)MiB (MebiBytes)
3GGb (GigaBits)Gib (GibiBits)GB (GigaBytes)GiB (GibiBytes)
4TTb (TeraBits)Tib (TebiBits)TB (TeraBytes)TiB (TebiBytes)
5PPb (PetaBits)Pib (PebiBits)PB (PetaBytes)PiB (PebiBytes)
6EEb (ExaBits)Eib (ExbiBits)EB (ExaBytes)EiB (ExbiBytes)
7ZZb (ZettaBits)Zib (ZebiBits)ZB (ZettaBytes)ZiB (ZebiBytes)
8YYb (YottaBits)Yib (YobiBits)YB (YottaBytes)YiB (YobiBytes)

<a id='bytestring'></a> ByteString: String

A stringed byte representation. The result of a parsed byte value.

<a id='hybridbyte'></a> HybridByte: Number|ByteString

Used to identify a variable thats either a ByteString or a number

<a id='byteoptions'></a> ByteOptions: Object

<a id='parseoptions'></a> ParseOptions: Object

<a id='byteparser'></a> ByteParser: Function

Byte parser with predefined configuration. Result of createByteParser.

<a id='sizeparser'></a> SizeParser: Function

ByteString parser with predefined configuration. Result of createSizeParser.

<a id='relativesizer'></a> RelativeSizer: Function

HybridByte parser with predefined configuration. Result of createRelativeSizer.

<a id='parsedunit'></a> ParsedUnit: Object

<a id='parsedbytestring'></a> ParsedByteString <sub>extends</sub> ParsedUnit: Object

<a id='parsedbytes'></a> ParsedBytes <sub>extends</sub> ParsedByteString: Object

<a id='byteunitobject'></a> class ByteUnitObject

Wrap a HybridByte in a chainable, transformative object.

new ByteUnitObject('10 MiB')
// << ByteUnitObject { bytes: 10485760 }
new ByteUnitObject('10 MiB').add('20 MiB')
// << ByteUnitObject { bytes: 31457280 }
new ByteUnitObject('10 MiB').add('20 MiB').toIECBytes()
// << '30.00 MiB'

ByteUnitObject().add(bytes)

Add byte(s) to the internal bytes, resulting in a new ByteUnitObject object with the value

ByteUnitObject().subtract(bytes)

Subtract byte(s) from the internal bytes, resulting in a new ByteUnitObject object with the value

ByteUnitObject().multiply(bytes)

Multiply byte(s) with the internal bytes, resulting in a new ByteUnitObject object with the value

ByteUnitObject().divide(bytes)

Divide internal bytes by byte(s) specified, resulting in a new ByteUnitObject object with the value

ByteUnitObject().convertTo(unit)

Parse the internal byte into any unit, following the relativity.

new ByteUnitObject('10 MiB')
// >> ByteUnitObject { bytes: 10485760 }
new ByteUnitObject('10 MiB').convertTo('MB')
// >> '10.49 MB'
new ByteUnitObject('10 MiB').add('50 MB').convertTo('KB')
    '60485.76 KB'

ByteUnitObject().objectify(opts)

Parse the internal bytes property to a byte object.

ByteUnitObject().checkInternalByteVal(bytes)

Method to check integrity of internal bytes. Throw if there's an error somewhere.

<a id='hybridbyterelations'></a> HybridByteRelations: Object

More Examples

Check out some examples in the examples folder

$ node examples/index.js 'Hey, its 6GB, but my 8 TB flash drive is better'
┌─────────┬──────────┬───────────┬────────┬───────────┬────────────┬────────────┬─────────────┐
│ (index) │  parsed  │   size    │  raw   │   bytes   │  iecBytes  │    bits    │   iecBits   │
├─────────┼──────────┼───────────┼────────┼───────────┼────────────┼────────────┼─────────────┤
│    0    │ [Object] │ '6.00 GB' │ '6GB'  │ '6.00 GB' │ '5.59 GiB' │ '48.00 Gb' │ '44.70 Gib' │
│    1    │ [Object] │ '8.00 TB' │ '8 TB' │ '8.00 TB' │ '7.28 TiB' │ '64.00 Tb' │ '58.21 Tib' │
└─────────┴──────────┴───────────┴────────┴───────────┴────────────┴────────────┴─────────────┘
$ node examples/parse.js 'The 10GB file was downloaded in 50MB/s'
The 10737418240 file was downloaded in 52428800/s
$ node examples/relative.js mb '10GiB, 1mb 6   gb'
85899.35 Mb, 1.00 Mb 6000.00 Mb
$ node examples/random.js 10 // Parse 10 random bytes
[tabular data]
$ node examples/extract.js 'Hey, its 6GB, but my 8 TB flash drive is better'
┌─────────┬────────┬───────────────┐
│ (index) │  size  │     bytes     │
├─────────┼────────┼───────────────┤
│    0    │ '6GB'  │  6000000000   │
│    1    │ '8 TB' │ 8000000000000 │
└─────────┴────────┴───────────────┘

Features

Compatible with all versions of NodeJS (tested from v1.8.4)

$ nvm exec v1.8.4 node -pe 'require(".")(3748587)'
"3.75 MB"
$ nvm exec v5.12.0 node -pe 'require(".").parseSize("476 TiB")'
523367534821376
$ nvm exec v11.10.0 node -e '
  let xbytes = require("./dist");
  let str = "My 10GB drive transmits at 250MiB/sec"
  console.log(str.replace(xbytes.globalByteFilter, xbytes.relative.bits))
'
"My 80.00 Gb drive transmits at 2.10 Gb/sec"

Decimal parsing

xbytes(524334545.847775856); // 524.33 MB
xbytes.parseSize('665.284 TiB'); // 731487493773328.4

xbytes(.24283884748955); // 0.24 B
xbytes.parseSize('.295 MB'); // 295000

Parse human readable sizes in binary (IEC) format to bytes

xbytes.parseSize('1 MiB'); // 1048576

Parse byte values to extended human readable sizes

xbytes(50000000, {short: false}); // '50.00 MegaBytes'

Match or extract ByteStrings in a string

let data = 'My 16GB flash drive has a 4GB Zip Archive and a 5MB JavaScript file';
xbytes.extractBytes(data);
  //> [ '16GB', '4GB', '5MB' ]
data.match(xbytes.globalByteFilter)
  //> [ '16GB', '4GB', '5MB' ]
data.replace(xbytes.globalByteFilter, xbytes.parseSize)
  //> 'My 16000000000 flash drive has a 4000000000 Zip Archive and a 5000000 JavaScript file'
data.replace(xbytes.globalByteFilter, xbytes.createSizeParser({ iec: false }))
  //> 'My 17179869184 flash drive has a 4294967296 Zip Archive and a 5242880 JavaScript file'

Decimal and Binary Unit Relativity

import { parseSize, relative } from 'xbytes';

relative('35 TiB').bits // '307.86 Tb'
relative('35 TiB').bytes // '38.48 TB'
relative('35 TiB').iecBits // '280.00 Tib'
relative('35 TiB').iecBytes // '35.00 TiB'

parseSize(relative('35 TiB', {fixed: 20}).bits);
  //> 38482906972160
parseSize(relative('35 TiB', {fixed: 20}).bytes);
  //> 38482906972160
parseSize(relative('35 TiB', {fixed: 20}).iecBits);
  //> 38482906972160
parseSize(relative('35 TiB', {fixed: 20}).iecBytes);
  //> 38482906972160

Development

Building

Feel free to clone, use in adherance to the license and perhaps send pull requests

git clone https://github.com/miraclx/xbytes.git
cd xbytes
npm install
# hack on code
npm run build
npm test

Testing

Tests are executed with Jest. To use it, simple run npm install, it will install Jest and its dependencies in your project's node_modules directory followed by npm run build and finally npm test.

To run the tests:

npm install
npm run build
npm test

License

Apache 2.0 © Miraculous Owonubi (@miraclx) <omiraculous@gmail.com>