binarius

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:

import Binarius from 'binarius';

// or
const Binarius = require('binarius');

By default, Binarius operates on 31 bit long bitfield where bits are indexed from least significant to most:

const Binarius = require('binarius');
const bitfield = new Binarius(29); // 29 === 0b11101
bitfield.get(0);
//=> 1
bitfield.get(1);
//=> 0
bitfield.has(2, 3, 4);
//=> true

You can extend Binarius and use your own schema by specifying field names and their respective sizes in bits:

class Person extends Binarius {}
Person.fields = [
  { name: 'age', size: 7 },
  { name: 'gender', size: 1 },
];

const person = new Person([20, 1]);
person.get('age');
//=> 20

person.get('gender');
//=> 1

person.set('age', 18);
person.get('age');
//=> 18
person.value
//=> 41
person.toObject();
//=> { age: 20, gender: 1 }

You can forgo specifying sizes if your field size is 1 bit:

class Privileges extends Binarius {}
Privileges.fields = ['user', 'moderator', 'administrator'];

const privileges = new Privileges(0);
privileges.set('user').set('moderator');
privileges.has('user', 'moderator');
//=> true
privileges.set('moderator', 0).has('moderator');
//=> 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:

class LargeField extends Binarius {}
LargeField.fields = [
  { name: 'width', size: 20 },
  { name: 'height', size: 20 },
];

const largeField = new LargeField([1048576, 1048576]);
largeField.value
//=> 1099512676352n
largeField.set('width', 1000).get('width')
//=> 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:

class OldPerson extends Binarius {}
OldPerson.fields = [
  { name: 'age', size: 7 },
  { name: 'gender', size: 1 },
];

const oldPerson = OldPerson.encode([20, 1]);
//=> oldPerson === 41

class Person extends Binarius {}
Person.fields = [
  { name: 'age', size: 7 },
  { name: 'gender', size: 1 },
  { name: 'weight', size: 8 },
];
const newPerson = new Person(oldPerson);
newPerson.get('age');
//=> 20
newPerson.get('weight');
//=> 0
newPerson.set('weight', 100).get('weight');
//=> 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:

class Person extends Binarius {}
Person.fields = [
  { name: 'age', size: 7 },
  { name: 'gender', size: 1 },
];

Person.encode([20, 1]);
//=> 41

Person.decode(41);
//=> { 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.getMinSize(100);
//=> 7

class Person extends Binarius {}
Person.fields = [
  { name: 'age', size: Binarius.getMinSize(100) },
  { 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:

class Person extends Binarius {}
Person.fields = [
  { name: 'age', size: 7 },
  { name: 'gender', size: 1 },
];

Person.isValid({age: 100});
//=> true
Person.isValid({age: 100, gender: 3});
//=> false
Person.isValid([100, 1]);
//=> true
Person.isValid([100, 3]);
//=> false

Documentation

• API 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