BitPackedBuffer

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 values
const 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 back
buffer.seek(0);
console.log(buffer.read.bits(3)); // → 5
console.log(buffer.read.bits(4)); // → 10
console.log(buffer.read.string(2)); // → "Hi"

Working with Endianness

// Create a little-endian buffer
const buffer = new BitPackedBuffer(null, "little");

// Write a 16-bit value
buffer.write.bits(1000, 16);

// Read it back
buffer.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:

try {
  buffer.read.bits(33); // Throws RangeError
} catch (error) {
  console.error("Invalid bit count:", error.message);
}

Performance Considerations

• Align to byte boundaries when possible for better performance
• Use mark()/reset() for temporary position changes
• Pre-allocate buffers when size is known
• Use the appropriate endianness for your data format

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and commit: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please ensure your PR:

• Includes tests for new functionality
• Updates documentation as needed
• Follows the existing code style
• Includes a clear description of changes

Support

• 📦 npm package
• 📘 GitHub Repository
• 🐛 Issue Tracker

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by Aviv Keller