A high-performance JavaScript library for bit-level data manipulation with zero dependencies. Perfect for binary protocols, file formats, and low-level data operations.
Overview
BitPackedBuffer provides precise control over bit-level operations in JavaScript, supporting both big-endian and little-endian byte orders. Whether you're implementing a binary protocol, working with file formats, or handling low-level data, BitPackedBuffer is designed to meet your needs.
Key Features
🚀 Zero dependencies, minimal overhead
💫 Bit-level precision (1-32 bits)
🔄 Big and little-endian support
📦 Modern ES Module design
⚡ Efficient memory usage
🛡️ Comprehensive error checking
Installation
npm install bitpacked
Quick Examples
Basic Usage
import { BitPackedBuffer } from "bitpacked";// Write mixed-width valuesconst buffer = new BitPackedBuffer() .write.bits(5, 3) // Write value 5 using 3 bits .write.bits(10, 4) // Write value 10 using 4 bits .write.string("Hi") // Write a string .alignToByte(); // Align to byte boundary// Read them backbuffer.seek(0);console.log(buffer.read.bits(3)); // → 5console.log(buffer.read.bits(4)); // → 10console.log(buffer.read.string(2)); // → "Hi"
Working with Endianness
// Create a little-endian bufferconst buffer = new BitPackedBuffer(null, "little");// Write a 16-bit valuebuffer.write.bits(1000, 16);// Read it backbuffer.seek(0);console.log(buffer.read.bits(16)); // → 1000
API Reference
Constructor
new BitPackedBuffer( contents?: Uint8Array | Buffer, endian?: 'big' | 'little')
Reading Operations
Method
Description
Example
read.bits(count)
Read 1-32 bits
buffer.read.bits(5)
read.bytes(count)
Read multiple bytes
buffer.read.bytes(4)
read.string(length)
Read fixed-length string
buffer.read.string(10)
read.cString()
Read null-terminated string
buffer.read.cString()
read.int(bitCount)
Read signed integer
buffer.read.int(16)
read.uint(bitCount)
Read unsigned integer
buffer.read.uint(16)
Writing Operations
Method
Description
Example
write.bits(value, count)
Write 1-32 bits
buffer.write.bits(42, 7)
write.bytes(data)
Write byte array
buffer.write.bytes(bytes)
write.string(str)
Write string
buffer.write.string("hello")
write.cString(str)
Write null-terminated string
buffer.write.cString("hello")
write.int(value, bitCount)
Write signed integer
buffer.write.int(-42, 16)
write.uint(value, bitCount)
Write unsigned integer
buffer.write.uint(42, 16)
Buffer Management
Method
Description
seek(position)
Move to byte position
skip(bytes)
Skip ahead bytes
mark(name?)
Mark current position
reset(name?)
Return to marked position
alignToByte()
Align to byte boundary
clear()
Reset buffer state
getBuffer()
Get underlying buffer
isComplete()
Check if all data read
Peeking Operations
Peeking operations don't advance the buffer position. They contain the same methods as read but return values without modifying the position.
Method
Description
Example
peek.bits(count)
Peek 1-32 bits
buffer.peek.bits(5)
peek.bytes(count)
Peek multiple bytes
buffer.peek.bytes(4)
peek.string(length)
Peek fixed-length string
buffer.peek.string(10)
peek.cString()
Peek null-terminated string
buffer.peek.cString()
peek.int(bitCount)
Peek signed integer
buffer.peek.int(16)
peek.uint(bitCount)
Peek unsigned integer
buffer.peek.uint(16)
Common Use Cases
Binary file format parsing/writing
Network protocol implementation
Data compression/decompression
Game state serialization
Embedded systems communication
Error Handling
BitPackedBuffer includes comprehensive error checking: