Read and write binary data on the bit level. With support for fine-tuning the storage BitStream is your one-stop shop for compact data representation.
npm install @nick-hill-dev/bitstreambash
npm install @nick-hill-dev/bitstream
`
Examples are in the demos directory. To run them, execute the following commands:
`bash
npm install
npx tsc
npx rollup -c --bundleConfigAsCjs # Creates js file in the bin directory, and now you can open the pages in the demos directory
`
Writing Data
To create a bit stream with some data in it, use the write* methods on an instance of the BitStream object. It is possible to define how much space each item of data occupies:
`js
let bits = new BitStream();
bits.writeBoolean(false);
bits.writeByte(100);
bits.writeString('Hello World!');
alert(Bit Stream is ${bits.size()} bytes long.);
`
Reading Data
Following on from the above, it is possible to extract the data from the bit stream:
`js
bits.position = 0; // Position advances as you write so set it to 0 here to reset the cursor to the beginning of the stream
alert(Boolean: ${bits.readBoolean()}\n +
Byte: ${bits.readByte()}\n +
String: ${bits.readString()});
`
$3
- Fully documented with JSDoc, integrated with IntelliSense in Visual Studio Code.
- Support for bits, arrays of bits.
- Supports all kinds of whole numbers: half-nibbles, nibbles, bytes, 2-byte numbers, 4-byte numbers and 8-byte numbers.
- Can use arbitrary numbers of bits to represent a number.
- Can read and write strings.
- Can convert bit streams from and into base64 encoded strings.
- Highly useful for network communications when state needs to be represented with as few bits as possible.
Maximum Control
It is possible to determine exactly how many bits to write via writeUInt or writeUIntMixed. The writeUIntMixed method supports representation of a number using a smaller number of bits if it is possible to do so (I.E. if a small number is typical) yet supports writing larger numbers with more bits in the "unlikely" scenario of having to write a larger number.
`js
let bits = new BitStream();
bits.writeHalfNibble(3); // Maximum number that can be stored in 2 bits
bits.writeNibble(15); // Maximum number that can be stored in 4 bits
bits.writeByte(255); // Maximum number that can be stored in 8 bits
bits.writeUInt16(65535); // Etc
bits.writeUInt32(Math.pow(2, 32) - 1);
bits.writeUInt64(Math.pow(2, 63) - 1);
bits.writeUInt(63, 6); // Use a maximum of 6 bits, in this case the maximum number that can be stored is 63
let value = Math.floor(Math.random() * 32768);
bits.writeUIntMixed(value, 4, 16); // Use ~4 or ~16 bits to store the number depending on how many bits are actually required
`
Base64 Encoding
A bit stream can be converted to, I.E. serialized into a base64-encoded string and a base64-encoded string can be deserialized into a bit stream instance.
`js
let bits = new BitStream();
bits.writeBoolean(true);
bits.writeByte(123);
bits.writeString('Hello World!');
let str = bits.toString();
alert(Bit Stream as base64-encoded string:\n\n${str}); // vYYkMrY2N5Art7k2MhCA
let bitsDecoded = BitStream.fromString(str);
alert(Boolean: ${bits.readBoolean()}\n +
Byte: ${bits.readByte()}\n +
String: ${bits.readString()});
``