compact-buffer-util

compact-buffer-util is a package specializing in reading from and writing to node.js Buffers with bit-precision and automatically set offsets. ArrayBuffers are supported for browser usage, however you must use a tool like webpack to bundle this package. Each allows interaction with strings, numbers, and booleans. By default, data is read as a big endian to be consistent with irregular sizes like 9-bit or 23-bit integers.

Installation

npm install compact-buffer-util

Requires node.js v10.4.0 or later.

CompactBufferReader

Allows reading from a Buffer with bit precision. If you don't use bit precision, only standard node.js Buffer methods are used instead.

const CompactBufferReader = require('compact-buffer-util').CompactBufferReader;

let myBuf = Buffer.from([ 0x12, 0x34, 0x56, 0x78 ]),
    reader = new CompactBufferReader(myBuf);

reader.readUint16(); // 0x1234
reader.readUnsignedBits(4); // 0x5
reader.readUint8(); // 0x67
reader.readUint8(); // null

If you attempt to read outside the bounds of the Buffer, null will be returned, and the offset and bitOffset will not change.

CompactBufferWriter

Allows writing to a Buffer with bit precision. Like CompactBufferReader, only standard node.js Buffer methods are used if you don't change the bit offset.

const CompactBufferWriter = require('compact-buffer-util').CompactBufferWriter;

let writer = new CompactBufferWriter();
writer.writeUint8(0x12)
      .writeUnsignedBits(0x3, 4)
      .writeUint8(0x45);
console.log(writer.toBuffer()); // <Buffer 12 34 50>

It's worth noting that most CompactBufferWriter methods return this, allowing for method chaining. The only exceptions are toBuffer() and writeUTF8().

Use cases

This project was designed with multiplayer networking in mind to minimize bandwidth.

An example use case would be sending a party code that consists of letters A-Z; rather than sending the character code, or even a string of it, you can send a 5-bit number for each character, fitting every letter in the alphabet.

const CompactBufferWriter = require('compact-buffer-util').CompactBufferWriter;
const code = 'HELLO';

let writer = new CompactBufferWriter();
for (let i = 0; i < code.length; ++i)
    writer.writeUnsignedBits(code.charCodeAt(i) - 65, 5);

console.log(writer.toBuffer()); // <Buffer 41 4a c7 80>

And generally any number that might fit a different range than what normal bytes offer, like a map with dimensions just big enough to exceed the size of a byte, like 400x300, and each coordinate could be stored with 9 bits.

Reference

This package contains TypeScript declaration files.