{"id":24750668,"url":"https://github.com/avivkeller/bitpackedbuffer","last_synced_at":"2025-03-23T03:40:58.935Z","repository":{"id":267026572,"uuid":"899974125","full_name":"avivkeller/bitpackedbuffer","owner":"avivkeller","description":"A high-performance JavaScript library for bit-level data manipulation with zero dependencies.","archived":false,"fork":false,"pushed_at":"2024-12-22T21:27:27.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-19T23:18:36.904Z","etag":null,"topics":["bits","buffer","bytes"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avivkeller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"redyetidev"}},"created_at":"2024-12-07T14:24:17.000Z","updated_at":"2025-02-21T00:39:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"0430d2ed-94cf-432e-aabb-ed9935666ce0","html_url":"https://github.com/avivkeller/bitpackedbuffer","commit_stats":null,"previous_names":["redyetidev/bitpackedbuffer","onlyaviv/bitpackedbuffer","avivkeller/bitpackedbuffer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivkeller%2Fbitpackedbuffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivkeller%2Fbitpackedbuffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivkeller%2Fbitpackedbuffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivkeller%2Fbitpackedbuffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avivkeller","download_url":"https://codeload.github.com/avivkeller/bitpackedbuffer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245052637,"owners_count":20553162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bits","buffer","bytes"],"created_at":"2025-01-28T09:08:37.154Z","updated_at":"2025-03-23T03:40:58.915Z","avatar_url":"https://github.com/avivkeller.png","language":"JavaScript","readme":"# BitPackedBuffer\n\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![npm version](https://badge.fury.io/js/bitpacked.svg)](https://www.npmjs.com/package/bitpacked)\n\nA high-performance JavaScript library for bit-level data manipulation with zero dependencies. Perfect for binary protocols, file formats, and low-level data operations.\n\n## Overview\n\nBitPackedBuffer 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.\n\n### Key Features\n\n- 🚀 Zero dependencies, minimal overhead\n- 💫 Bit-level precision (1-32 bits)\n- 🔄 Big and little-endian support\n- 📦 Modern ES Module design\n- ⚡ Efficient memory usage\n- 🛡️ Comprehensive error checking\n\n## Installation\n\n```bash\nnpm install bitpacked\n```\n\n## Quick Examples\n\n### Basic Usage\n\n\u003c!-- prettier-ignore --\u003e\n```javascript\nimport { BitPackedBuffer } from \"bitpacked\";\n\n// Write mixed-width values\nconst buffer = new BitPackedBuffer()\n  .write.bits(5, 3) // Write value 5 using 3 bits\n  .write.bits(10, 4) // Write value 10 using 4 bits\n  .write.string(\"Hi\") // Write a string\n  .alignToByte(); // Align to byte boundary\n\n// Read them back\nbuffer.seek(0);\nconsole.log(buffer.read.bits(3)); // → 5\nconsole.log(buffer.read.bits(4)); // → 10\nconsole.log(buffer.read.string(2)); // → \"Hi\"\n```\n\n### Working with Endianness\n\n```javascript\n// Create a little-endian buffer\nconst buffer = new BitPackedBuffer(null, \"little\");\n\n// Write a 16-bit value\nbuffer.write.bits(1000, 16);\n\n// Read it back\nbuffer.seek(0);\nconsole.log(buffer.read.bits(16)); // → 1000\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nnew BitPackedBuffer(\n  contents?: Uint8Array | Buffer,\n  endian?: 'big' | 'little'\n)\n```\n\n### Reading Operations\n\n| Method                | Description                 | Example                  |\n| --------------------- | --------------------------- | ------------------------ |\n| `read.bits(count)`    | Read 1-32 bits              | `buffer.read.bits(5)`    |\n| `read.bytes(count)`   | Read multiple bytes         | `buffer.read.bytes(4)`   |\n| `read.string(length)` | Read fixed-length string    | `buffer.read.string(10)` |\n| `read.cString()`      | Read null-terminated string | `buffer.read.cString()`  |\n| `read.int(bitCount)`  | Read signed integer         | `buffer.read.int(16)`    |\n| `read.uint(bitCount)` | Read unsigned integer       | `buffer.read.uint(16)`   |\n\n### Writing Operations\n\n| Method                        | Description                  | Example                         |\n| ----------------------------- | ---------------------------- | ------------------------------- |\n| `write.bits(value, count)`    | Write 1-32 bits              | `buffer.write.bits(42, 7)`      |\n| `write.bytes(data)`           | Write byte array             | `buffer.write.bytes(bytes)`     |\n| `write.string(str)`           | Write string                 | `buffer.write.string(\"hello\")`  |\n| `write.cString(str)`          | Write null-terminated string | `buffer.write.cString(\"hello\")` |\n| `write.int(value, bitCount)`  | Write signed integer         | `buffer.write.int(-42, 16)`     |\n| `write.uint(value, bitCount)` | Write unsigned integer       | `buffer.write.uint(42, 16)`     |\n\n### Buffer Management\n\n| Method           | Description               |\n| ---------------- | ------------------------- |\n| `seek(position)` | Move to byte position     |\n| `skip(bytes)`    | Skip ahead bytes          |\n| `mark(name?)`    | Mark current position     |\n| `reset(name?)`   | Return to marked position |\n| `alignToByte()`  | Align to byte boundary    |\n| `clear()`        | Reset buffer state        |\n| `getBuffer()`    | Get underlying buffer     |\n| `isComplete()`   | Check if all data read    |\n\n### Peeking Operations\n\nPeeking operations don't advance the buffer position. They contain the same methods as `read` but return values without modifying the position.\n\n| Method                | Description                 | Example                  |\n| --------------------- | --------------------------- | ------------------------ |\n| `peek.bits(count)`    | Peek 1-32 bits              | `buffer.peek.bits(5)`    |\n| `peek.bytes(count)`   | Peek multiple bytes         | `buffer.peek.bytes(4)`   |\n| `peek.string(length)` | Peek fixed-length string    | `buffer.peek.string(10)` |\n| `peek.cString()`      | Peek null-terminated string | `buffer.peek.cString()`  |\n| `peek.int(bitCount)`  | Peek signed integer         | `buffer.peek.int(16)`    |\n| `peek.uint(bitCount)` | Peek unsigned integer       | `buffer.peek.uint(16)`   |\n\n## Common Use Cases\n\n- Binary file format parsing/writing\n- Network protocol implementation\n- Data compression/decompression\n- Game state serialization\n- Embedded systems communication\n\n## Error Handling\n\nBitPackedBuffer includes comprehensive error checking:\n\n```javascript\ntry {\n  buffer.read.bits(33); // Throws RangeError\n} catch (error) {\n  console.error(\"Invalid bit count:\", error.message);\n}\n```\n\n## Performance Considerations\n\n- Align to byte boundaries when possible for better performance\n- Use `mark()`/`reset()` for temporary position changes\n- Pre-allocate buffers when size is known\n- Use the appropriate endianness for your data format\n\n## Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and commit: `git commit -m 'Add amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\nPlease ensure your PR:\n\n- Includes tests for new functionality\n- Updates documentation as needed\n- Follows the existing code style\n- Includes a clear description of changes\n\n## Support\n\n- 📦 [npm package](https://www.npmjs.com/package/bitpacked)\n- 📘 [GitHub Repository](https://github.com/avivkeller/bitpackedbuffer)\n- 🐛 [Issue Tracker](https://github.com/avivkeller/bitpackedbuffer/issues)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\nMade with ❤️ by [Aviv Keller](https://github.com/avivkeller)\n","funding_links":["https://github.com/sponsors/redyetidev"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favivkeller%2Fbitpackedbuffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favivkeller%2Fbitpackedbuffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favivkeller%2Fbitpackedbuffer/lists"}