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 RedYetiDev