ByteParser (xbytes)

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

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]

[![NPM][npm-image-url]][npm-url]

Installing

Via [NPM][npm]:

`` bash
npm install xbytes
`

Usage

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

` html


`

Examples

` javascript
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*

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

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

API

$3

* byte: <[number][]>
* options: <ByteOptions>
* Returns: <ByteString>

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

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

$3

* str: <ByteString>
* config: <ParseOptions>
* Returns: <[number][]>

Parse human readable size to bytes

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

$3

* str: <HybridByte>
* Returns: <ByteUnitObject>

Create a ByteUnitObject around the specified HybridByte

`javascript
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'
`

$3

* str: <[string][]>
* Returns: <[boolean][]>

Check if the provided string is a ByteString

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

$3

* str: <UnitString>
* Returns: <[boolean][]>

Check if the provided string is an UnitString

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

$3

* input: <HybridByte>
* Returns: <[boolean][]>

Check if the provided argument is parsable _i.e_ raw_bytes ([number]) or ByteString.

$3

* size: <HybridByte>
* options: <ByteOptions>
* Returns: <HybridByteRelations>

$3

* size: <HybridByte>
* options: <ByteOptions>
* Returns: <ByteString>

Show the input size in relation to its bit format

$3

* size: <HybridByte>
* options: <ByteOptions>
* Returns: <ByteString>

Show the input size in relation to its byte format

$3

* size: <HybridByte>
* options: <ByteOptions>
* Returns: <ByteString>

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

$3

* size: <HybridByte>
* options: <ByteOptions>
* Returns: <ByteString>

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

$3

* size: <HybridByte>
* unit: <UnitString>
* options: <ByteOptions>
* Returns: <ByteString>

$3

* str: <ByteString>
* Returns: <ParsedByteString>

Parse a human readable byte into its components

$3

* str: <HybridByte>
* options: <ByteOptions>
* Returns: <ParsedBytes>

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.

$3

* str: <[string][]>
* Returns: <ByteString[]>

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

$3

* config: <ByteOptions>
* Returns: <ByteParser>

Construct a static ByteParser with predefined configurations

$3

* config: <ParseOptions>
* Returns: <SizeParser>

Construct a static SizeParser with predefined configurations

$3

* unit: <UnitString>
* config: <ByteOptions>
* Returns: <RelativeSizer>

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

$3

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

$3

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

$3

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

$3

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

$3

Supported Unit Strings

| Index | Prefix | Decimal Bits | Binary Bits ([IEC][]) | Decimal Bytes | Binary Bytes ([IEC][]) |
| :---: | :----: | :----------------: | :-------------------: | :-----------------: | :--------------------: |
| 0 | - | b (Bits) | b (Bits) | b (Bits) | b (Bits) |
| 0 | - | B (Bytes) | B (Bytes) | B (Bytes) | B (Bytes) |
| 1 | K | Kb (KiloBits) | Kib (KiloBits) | KB (KiloBytes) | KiB (KibiBytes) |
| 2 | M | Mb (MegaBits) | Mib (MebiBits) | MB (MegaBytes) | MiB (MebiBytes) |
| 3 | G | Gb (GigaBits) | Gib (GibiBits) | GB (GigaBytes) | GiB (GibiBytes) |
| 4 | T | Tb (TeraBits) | Tib (TebiBits) | TB (TeraBytes) | TiB (TebiBytes) |
| 5 | P | Pb (PetaBits) | Pib (PebiBits) | PB (PetaBytes) | PiB (PebiBytes) |
| 6 | E | Eb (ExaBits) | Eib (ExbiBits) | EB (ExaBytes) | EiB (ExbiBytes) |
| 7 | Z | Zb (ZettaBits) | Zib (ZebiBits) | ZB (ZettaBytes) | ZiB (ZebiBytes) |
| 8 | Y | Yb (YottaBits) | Yib (YobiBits) | YB (YottaBytes) | YiB (YobiBytes) |

$3

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

* '5 MB'
* '10 GiB'
* '0.67 Tb'
* '-50 KB'
* '2e+15 KB'
* '-9e-4 GB'

$3

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

* '47 MiB'
* '50kb'
* 74753
* '105'

$3

* iec: <[boolean][]> Whether or not to parse under the [IEC standard][IEC] i.e in terms of 1024. Default: true
* bits: <[boolean][]> Whether or not to convert inputed bytes to bits and parse in terms of bits [1 byte = 8 bits]. Default: false.
* fixed: <[number][]> Number of digits to include after decimal point. Default: 2.
* short: <[boolean][]> Whether or not to shorten unit String [short: 'MB', long: 'MegaBytes']. Default: true.
* space: <[boolean][]> Whether or not to include a white space inbetween value and unit. Default: true.
* sticky: <[boolean][]> Whether or not to retain unit on max unit values. e.g '1024.00 GiB' instead of '1.00 TiB'. Default: false.
* prefixIndex: <[number][]> The index of unit relativity See [UnitString].

$3

* iec: <[boolean][]> Whether or not to enforce compliance to [IEC standard][IEC]s. Default: true.
* bits: <[boolean][]> Whether or not to parse a lower case 'b' in bit format. Default: true.

$3

* size: <[number][]>
* Returns: <ByteString>

Byte parser with predefined configuration. Result of createByteParser.

$3

* str: <ByteString[]>
* Returns: <[number][]>

ByteString parser with predefined configuration. Result of createSizeParser.

$3

* size: <HybridByte>
* Returns: <ByteString>

HybridByte parser with predefined configuration. Result of createRelativeSizer.

$3

* iec: <[boolean][]> Whether or not the byte is represented under the [IEC standard][IEC] i.e in terms of 1024.
* true in '7 TiB'
* false in '3 TB'
* type: <[string][]> Whether the size is represented as bits(b) or bytes(B).
* 'b' in '499Yb'
* 'B' in '7 MB'
* bits: <[boolean][]> Whether or not the size is specifically represented as a bit.
* true in 84 Yb
* false in 278.58 KB
* bytes: <[boolean][]> Whether or not the size is specifically represented as a byte.
* true in 92 EB
* false in 28 Mb
* unit: <UnitString> Re-parsed UnitString of inputUnit, fixing formatting.
* 'TB' if 'TB'
* 'Gib' if 'gib'
* inputUnit: <UnitString> The unparsed String as was provided.
* '47TB' in '47TB'
* prefix: <[string][]> The prefix of the size string.
* 'K' in 'KB'
* prefixIndex: <[number][]> The index of the size unit See [UnitString].
* 3 in 'GB'

$3

* input: <ByteString> The unparsed String as was provided.
* '47TB' in '47TB'
* value: <[number][]> The value for the size.
* 83 in '83MB'

$3

* input: <HybridByte> The unparsed String as was provided.
* 1024 in 1024
* '47TB' in '47TB'
* size: <ByteString> The value for the size.
* 83 in '83MB'
* bytes: <[number][]> The value for the size.
* 10485760 from '10 MiB'

$3

* bytes: <[number][]> Internal byte value.

Wrap a HybridByte in a chainable, transformative object.

`javascript
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)

* bytes: <HybridByte|HybridByte[]> Byte(s) to subract from the root byte.
* Returns: <ByteUnitObject>

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

#### ByteUnitObject().subtract(bytes)

* bytes: <HybridByte|HybridByte[]> Subtract byte(s) from the internal bytes, resulting in a new ByteUnitObject object with the value.
* Returns: <ByteUnitObject>

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

#### ByteUnitObject().multiply(bytes)

* bytes: <HybridByte|HybridByte[]> Multiply byte(s) with the internal bytes, resulting in a new ByteUnitObject object with the value.
* Returns: <ByteUnitObject>

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

#### ByteUnitObject().divide(bytes)

* bytes: <HybridByte|HybridByte[]> Byte(s) to divide with.
* Returns: <ByteUnitObject>

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

#### ByteUnitObject().convertTo(unit)

* unit: <UnitString>
* Returns: <ByteString>

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

` javascript
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)

* opts: <ByteOptions>

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.

$3

* raw: <HybridByte> The unparsed data
* bits: <ByteString> A relative bit parsing of the input HybridByte
* size: <[number][]> The numeric byte format of the input HybridByte
* bytes: <ByteString> A relative byte parsing of the input HybridByte
* iecBits: <ByteString> A relative bit parsing of the input HybridByte under the IEC Specification
* parsed: <ByteString> A relative bit parsing of the input HybridByte under the IEC Specification
* iecBytes: <ByteString> A relative byte parsing of the input HybridByte under the IEC Specification

More Examples

Check out some examples in the examples folder

` javascript
$ 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

$3

` bash
$ 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"
`

$3

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

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

$3

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

$3

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

$3

` javascript
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'
`

$3

` javascript
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

$3

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

` bash
git clone https://github.com/miraclx/xbytes.git
cd xbytes
npm install


hack on code


npm run build
npm test
`

$3

Tests are executed with [Jest][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:

`bash
npm install
npm run build
npm test
``

License

[Apache 2.0][license] © Miraculous Owonubi ([@miraclx][author-url]) <omiraculous@gmail.com>

[IEC]: https://en.wikipedia.org/wiki/Units_of_information#Systematic_multiples 'International Electrotechnical Commission'
[npm]: https://github.com/npm/cli 'The Node Package Manager'
[jest]: https://github.com/facebook/jest 'Delightful JavaScript Testing'
[license]: LICENSE 'Apache 2.0 License'
[author-url]: https://github.com/miraclx

[npm-url]: https://npmjs.org/package/xbytes
[npm-image]: https://badgen.net/npm/node/xbytes
[npm-image-url]: https://nodei.co/npm/xbytes.png?stars&downloads
[downloads-url]: https://npmjs.org/package/xbytes
[downloads-image]: https://badgen.net/npm/dm/xbytes

[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
[regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function