@arcblock/xbytes
v1.9.1
Published
Parse bytes to human readable sizes (4747) → ('4.75 KB') and vice versa.
Downloads
222
Readme
ByteParser (xbytes)
NodeJS Byte Parser Parse bytes to human readable sizes (4747) → ('4.75 KB') and vice versa.
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
xbytes(byte[, options])
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.
xbytes(2472946)
// << '2.47 MB'
xbytes(49392123904, {iec: true})
// << '46.00 GiB'
xbytes.parseSize(str[, config])
str
: <ByteString>config
: <ParseOptions>- Returns: <number>
Parse human readable size to bytes
xbytes.parseSize('15.967 MB')
// << 15967000
xbytes.parseSize('5.97 PiB')
// << 6721622443850465
xbytes.parse(size)
str
: <HybridByte>- Returns: <ByteUnitObject>
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'
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
xbytes.isUnit(str)
str
: <UnitString>- Returns: <boolean>
Check if the provided string is an UnitString
xbytes.isUnit('GB')
// << true
xbytes.isUnit('giB')
// << true
xbytes.isUnit('iB')
// << false
xbytes.isUnit('BB')
// << false
xbytes.isParsable(input)
input
: <HybridByte>- Returns: <boolean>
Check if the provided argument is parsable i.e raw_bytes (number) or ByteString.
xbytes.relative(size[, options])
size
: <HybridByte>options
: <ByteOptions>- Returns: <HybridByteRelations>
xbytes.relative.bits(size[, options])
size
: <HybridByte>options
: <ByteOptions>- Returns: <ByteString>
Show the input size in relation to its bit
format
xbytes.relative.bytes(size[, options])
size
: <HybridByte>options
: <ByteOptions>- Returns: <ByteString>
Show the input size in relation to its byte
format
xbytes.relative.iecBits(size[, options])
size
: <HybridByte>options
: <ByteOptions>- Returns: <ByteString>
Show the input size in relation to its bit
format under IEC Standards
xbytes.relative.iecBytes(size[, options])
size
: <HybridByte>options
: <ByteOptions>- Returns: <ByteString>
Show the input size in relation to its bytes
format under IEC Standards
xbytes.relative.size(size[, unit[, options]])
size
: <HybridByte>unit
: <UnitString>options
: <ByteOptions>- Returns: <ByteString>
xbytes.parseString(str)
str
: <ByteString>- Returns: <ParsedByteString>
Parse a human readable byte into its components
xbytes.parseBytes(str, options)
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.
xbytes.extractBytes(str)
str
: <string>- Returns: <ByteString[]>
Extract all ByteStrings within a string into an array, alternative to str.match(xbytes.byteFilter)
xbytes.createByteParser(config)
config
: <ByteOptions>- Returns: <ByteParser>
Construct a static ByteParser with predefined configurations
xbytes.createSizeParser(config)
config
: <ParseOptions>- Returns: <SizeParser>
Construct a static SizeParser with predefined configurations
xbytes.createRelativeSizer(unit[, config])
unit
: <UnitString>config
: <ByteOptions>- Returns: <RelativeSizer>
Create a RelativeSizer for converting a hybrid byte into any set unit under predefined configuration
xbytes.unitMatcher: RegExp
The raw Regular expression used in scanning all string byte units.
xbytes.genericMatcher: RegExp
The raw regular expression used in scanning all byte containing strings.
xbytes.byteFilter: RegExp
An regular expression extension of genericMatcher
with the 'i' flag.
xbytes.globalByteFilter: RegExp
An regular expression extension of genericMatcher
with the 'gi' flags.
UnitString: String
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) |
ByteString: String
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'
HybridByte: Number
|ByteString
Used to identify a variable thats either a ByteString or a number
- '47 MiB'
- '50kb'
- 74753
- '105'
ByteOptions: Object
iec
: <boolean> Whether or not to parse under the IEC standard 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].
ParseOptions: Object
iec
: <boolean> Whether or not to enforce compliance to IEC standards. Default:true
.bits
: <boolean> Whether or not to parse a lower case 'b' in bit format. Default:true
.
ByteParser: Function
size
: <number>- Returns: <ByteString>
Byte parser with predefined configuration. Result of createByteParser
.
SizeParser: Function
str
: <ByteString[]>- Returns: <number>
ByteString parser with predefined configuration. Result of createSizeParser
.
RelativeSizer: Function
size
: <HybridByte>- Returns: <ByteString>
HybridByte parser with predefined configuration. Result of createRelativeSizer
.
ParsedUnit: Object
iec
: <boolean> Whether or not the byte is represented under the IEC standard 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 abit
.true
in84 Yb
false
in278.58 KB
bytes
: <boolean> Whether or not the size is specifically represented as abyte
.true
in92 EB
false
in28 Mb
unit
: <UnitString> Re-parsed UnitString ofinputUnit
, 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'
ParsedByteString extends
ParsedUnit: Object
input
: <ByteString> The unparsed String as was provided.'47TB'
in'47TB'
value
: <number> The value for the size.83
in'83MB'
ParsedBytes extends
ParsedByteString: Object
input
: <HybridByte> The unparsed String as was provided.1024
in1024
'47TB'
in'47TB'
size
: <ByteString> The value for the size.83
in'83MB'
bytes
: <number> The value for the size.10485760
from'10 MiB'
class ByteUnitObject
bytes
: <number> Internal byte value.
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)
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.
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.
HybridByteRelations: Object
raw
: <HybridByte> The unparsed databits
: <ByteString> A relative bit parsing of the input HybridBytesize
: <number> The numeric byte format of the input HybridBytebytes
: <ByteString> A relative byte parsing of the input HybridByteiecBits
: <ByteString> A relative bit parsing of the input HybridByte under the IEC Specificationparsed
: <ByteString> A relative bit parsing of the input HybridByte under the IEC SpecificationiecBytes
: <ByteString> A relative byte parsing of the input HybridByte under the IEC Specification
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) <[email protected]>