Bitpacked NPM | npm.io

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:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and commit: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
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

License

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

Made with ❤️ by RedYetiDev

bit packed buffer bitpacked binary data serialization endian

7 months ago

7 months ago

7 months ago

7 months ago