Binarius
Store and operate on data in JavaScript Numbers and BigInts for memory savings, performance, and fun.
Installation
npm i binarius -S
Usage
Import the class:
; // orconst Binarius = ;
By default, Binarius operates on 31 bit long bitfield where bits are indexed from least significant to most:
const Binarius = ;const bitfield = 29; // 29 === 0b11101bitfield;//=> 1bitfield;//=> 0bitfield;//=> true
You can extend Binarius and use your own schema by specifying field names and their respective sizes in bits:
{}Personfields = name: 'age' size: 7 name: 'gender' size: 1 ; const person = 20 1;person;//=> 20 person;//=> 1 person;person;//=> 18personvalue//=> 41person;//=> { age: 20, gender: 1 }
You can forgo specifying sizes if your field size is 1 bit:
{}Privilegesfields = 'user' 'moderator' 'administrator'; const privileges = 0;privileges;privileges;//=> trueprivileges;//=> false
If the total size of your fields exceeds 31 bits, Binarius will internally use a BigInt to represent the resulting number, however, you can still use normal numbers to set each field and get their value as a number as well:
{}LargeFieldfields = name: 'width' size: 20 name: 'height' size: 20 ; const largeField = 1048576 1048576;largeFieldvalue//=> 1099512676352nlargeField//=> 1000
If you have to add more fields to your schema later on, you do not have to re-encode your existing values, just add new fields at the end of your new schema:
{}OldPersonfields = name: 'age' size: 7 name: 'gender' size: 1 ; const oldPerson = OldPerson;//=> oldPerson === 41 {}Personfields = name: 'age' size: 7 name: 'gender' size: 1 name: 'weight' size: 8 ;const newPerson = oldPerson;newPerson;//=> 20newPerson;//=> 0newPerson;//=> 100
If you only want to encode or decode a set of field values without creating an instance, you can do so by use static methods
Binarius.encode
and Binarius.decode
respectively:
{}Personfields = name: 'age' size: 7 name: 'gender' size: 1 ; Person;//=> 41 Person;//=> { age: 20, gender: 1 }
If you don't know beforehand how many bits you need for your field, you can call Binarius.getMinSize
with the maximum
possible value of your field to find out:
Binarius;//=> 7 {}Personfields = name: 'age' size: Binarius name: 'gender' size: 1 ;
For performance sake, Binarius doesn't check the size of values being set and setting values that exceed the specified
field size will lead to undefined behavior. If you want to check whether values fit their respective fields, you can use Binarius.isValid
:
{}Personfields = name: 'age' size: 7 name: 'gender' size: 1 ; Person;//=> truePerson;//=> falsePerson;//=> truePerson;//=> false
Documentation
Benchmark
>node benchmark.js
Construct:
binarius (Number) x 55,497,411 ops/sec ±1.43% (92 runs sampled)
tiny-binary-format x 35,752,705 ops/sec ±0.11% (95 runs sampled)
binarius (BigInt) x 1,356,673 ops/sec ±9.49% (74 runs sampled)
Get Field:
binarius (Number) x 16,288,487 ops/sec ±9.38% (73 runs sampled)
tiny-binary-format x 20,619,945 ops/sec ±9.72% (71 runs sampled)
binarius (BigInt) x 1,091,167 ops/sec ±9.14% (75 runs sampled)
Set Field:
binarius (Number) x 12,349,185 ops/sec ±9.53% (73 runs sampled)
binarius (BigInt) x 833,874 ops/sec ±9.15% (75 runs sampled)
Construct Small Bit Set:
binarius x 13,487,599 ops/sec ±10.04% (63 runs sampled)
parseInt x 12,194,221 ops/sec ±10.72% (63 runs sampled)
fast-bitset x 2,195,533 ops/sec ±9.05% (66 runs sampled)
bitflags x 2,085,162 ops/sec ±9.10% (67 runs sampled)
Get Small Bit Set:
binarius x 26,146,290 ops/sec ±9.87% (65 runs sampled)
vanilla x 72,901,685 ops/sec ±9.76% (75 runs sampled)
fast-bitset x 2,077,717 ops/sec ±9.47% (65 runs sampled)
bitflags x 2,205,870 ops/sec ±8.82% (71 runs sampled)
Set Small Bit Set:
binarius x 16,939,736 ops/sec ±10.00% (62 runs sampled)
vanilla x 62,144,478 ops/sec ±9.08% (67 runs sampled)
fast-bitset x 1,726,339 ops/sec ±9.24% (63 runs sampled)
bitflags x 2,133,856 ops/sec ±9.25% (68 runs sampled)
Construct Large Bit Set:
binarius (BigInt) x 13,367,659 ops/sec ±9.40% (72 runs sampled)
parseInt x 6,472,672 ops/sec ±9.30% (76 runs sampled)
fast-bitset x 1,749,372 ops/sec ±8.86% (66 runs sampled)
bitflags x 2,089,318 ops/sec ±9.59% (70 runs sampled)
Get Large Bit Set:
binarius (BigInt) x 2,796,970 ops/sec ±9.87% (60 runs sampled)
fast-bitset x 2,194,670 ops/sec ±9.49% (67 runs sampled)
bitflags x 2,057,710 ops/sec ±9.50% (65 runs sampled)
Set Large Bit Set:
binarius (BigInt) x 1,403,656 ops/sec ±10.19% (64 runs sampled)
fast-bitset x 1,932,073 ops/sec ±9.67% (68 runs sampled)
bitflags x 1,872,754 ops/sec ±9.57% (58 runs sampled)
License
MIT © Maga D. Zandaqo