@4bitlabs/readers

A collection of bit-readers for javascript and typescript.

Installation

Using npm:

$ npm install --save @4bitlabs/readers

Using yarn:

$ yarn add @4bitlabs/readers

Using pnpm:

$ pnpm add @4bitlabs/readers

Documentation

Full documentation for the library can be found here

Usage

import { createBitReader } from '@4bitlabs/readers';
const reader = createBitReader(sourceData);

// ...

const firstTenBits = reader.read32(10);

What is a bit-reader?

A bit-reader allows for bits level access to a sequence of bytes, allowing bit-level reads that easily cross byte-level boundaries. You can think of a bit-reader like a long sequence of bits that can be shifted off, providing access to later bits. Consider:

const source = Uint8Array.of(0b1111_0011, 0b1100_1111, 0b1010_1010);

If you wanted the most-significant 4-bits of this byte sequence, you could use a bitmask and a bitwise shifts:

const value = (source[0] & 0b1111_0000) >>> 4; // 15

This can be useful for simple encoded data, however, can become unweildly when crossing multiple bytes. Let's say you wanted to get the bits

        From           To
         |-------------|
         v             v
0b1111_0011_1100_1111_1010_1010

With bitwise operators on a Uint8Array, you'd have to:

const value =
  // select and shift the most-significant bits
  ((source[0] & 0b0000_0011) << 10) |
  // select and shift the middle bits
  (source[1] << 2) |
  // select and shift the least-significant bits
  ((source[2] & 0b1100_0000) >>> 6);

With a bit-reader, you can instead say:

const reader = createBitReader(source);
reader.skip(6); // skip the first 6 bits
const value = reader.read(12); // take the next 12 bits

This can be very useful when parsing densely-packed data-structures, especially when they use variable-length encoding.

Limitations

As of the initial version, both MsbReader and AsyncBitReader only support a maximum of 32-bit reads at time. However, those 32-bits do not need to be byte-aligned bits, and can occur anywhere in the bitstream. This limitation is due to the precision of the bitwise operators in javascript. In the future, this might be addressed to allow for 53-bit reads, the maximum-safe integer size for double-precision numbers.

License

ISC