@4bitlabs/readers

@4bitlabs/readers

A collection of bit-readers for javascript and typescript.

Installation

# npm
❯ npm install --save @4bitlabs/readers

# yarn
❯ yarn add @4bitlabs/readers

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.

BitReader API

BitReader is the interface that provides a bit-reader that sequentially reads bits from an Uint8Array source.

const source = Uint8Array.of(0b1110_0001);
const br = createBitReader(source);

br.read32(3); // 0b111
br.read32(1); // 0b0
br.read32(3); // 0b000
br.read32(1); // 0b1

The default behavior to read most-significant bits first, however, you can select reading from the least-significant side:

const source = Uint8Array.of(0b1110_0001);
const r = createBitReader(source, { mode: 'lsb' });

br.read32(3); // 0b001
br.read32(1); // 0b0
br.read32(3); // 0b110
br.read32(1); // 0b1

Instance properties

r.peek32(n: number): number

Peek n bits in the bit-stream.

r.skip(n: number): BitReader

Skip n bits in the bit-stream.

r.read32(n: number): number

Read n bits from the bit-stream. Shorthand for:

const value = reader.peek32(n);
reader.skip(n);

r.seek(offset: number): BitReader

Seek to an arbitrary byte-position in the underlying ArrayBuffer, always from the beginning of the byte-array.

r.isByteAligned(): boolean

Returns true if the bit-reader is currently aligned to a byte

r.align(): BitReader

Re-aligns to the nearest next byte-boundary in the bit-stream.

AsyncBitReader

AsyncBitReader provides a bit-reader that sequentially reads bits from an AsyncIterable. This allows it to consume bytes from a variety of sources, from files and network sources. For instance:

import fs from 'node:fs';
import { AsyncBitReader } from '@4bitlabs/readers';

const source = fs.createReadStream(path, { encoding: 'utf-8' });
const reader = new AsyncBitReader(source);
/* ...start reading! */

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.