https://github.com/avivkeller/bitpackedbuffer
A high-performance JavaScript library for bit-level data manipulation with zero dependencies.
https://github.com/avivkeller/bitpackedbuffer
bits buffer bytes
Last synced: 10 months ago
JSON representation
A high-performance JavaScript library for bit-level data manipulation with zero dependencies.
- Host: GitHub
- URL: https://github.com/avivkeller/bitpackedbuffer
- Owner: avivkeller
- License: mit
- Created: 2024-12-07T14:24:17.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-22T21:27:27.000Z (about 1 year ago)
- Last Synced: 2025-03-19T23:18:36.904Z (10 months ago)
- Topics: bits, buffer, bytes
- Language: JavaScript
- Homepage:
- Size: 29.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/funding.yml
- License: LICENSE
Awesome Lists containing this project
README
# BitPackedBuffer
[](LICENSE)
[](https://www.npmjs.com/package/bitpacked)
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
```bash
npm install bitpacked
```
## Quick Examples
### Basic Usage
```javascript
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
```javascript
// 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
```typescript
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:
```javascript
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](https://www.npmjs.com/package/bitpacked)
- 📘 [GitHub Repository](https://github.com/avivkeller/bitpackedbuffer)
- 🐛 [Issue Tracker](https://github.com/avivkeller/bitpackedbuffer/issues)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
Made with ❤️ by [Aviv Keller](https://github.com/avivkeller)