{"id":15541,"library":"binary-parser-encoder","title":"Binary Parser and Encoder","description":"binary-parser-encoder is a JavaScript/TypeScript library designed for declaratively building binary data parsers and encoders. It stands as a feature-rich fork of the popular `binary-parser` project, notably extending its capabilities by adding an `encode` method to convert JavaScript objects back into binary buffers—a key differentiator absent in the original library. The current stable version, 1.5.3, has recently incorporated updates from the upstream `binary-parser` v1.7.0, ensuring continued compatibility while expanding functionality. The library dynamically generates and compiles parser/encoder code on-the-fly, achieving performance comparable to hand-written implementations. It supports a comprehensive set of data types including 8-bit to 64-bit integers, floating-point numbers, bit fields, strings, arrays, choices, and user-defined structures. Its release cadence is primarily influenced by updates to the upstream `binary-parser` and the ongoing development of its unique encoding features, with an explicit long-term goal of merging these enhancements back into the main project.","status":"active","version":"1.5.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/Ericbla/binary-parser","tags":["javascript","binary","parser","decode","encoder","encode","unpack","struct","buffer","typescript"],"install":[{"cmd":"npm install binary-parser-encoder","lang":"bash","label":"npm"},{"cmd":"yarn add binary-parser-encoder","lang":"bash","label":"yarn"},{"cmd":"pnpm add binary-parser-encoder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for constructing binary parsers and encoders is a named export, not a default export. While CommonJS `require` is supported, ESM `import` is the recommended approach, especially in modern TypeScript projects.","wrong":"import Parser from 'binary-parser-encoder';\n// OR\nconst Parser = require('binary-parser-encoder');","symbol":"Parser","correct":"import { Parser } from 'binary-parser-encoder';"},{"note":"For CommonJS environments, ensure you destructure the `Parser` class from the module export to correctly access it.","wrong":"const Parser = require('binary-parser-encoder');","symbol":"Parser (CommonJS)","correct":"const { Parser } = require('binary-parser-encoder');"},{"note":"In TypeScript, use `import type` when only referencing the type definition of `Parser`. This ensures the import is removed during compilation if not strictly needed at runtime, promoting better tree-shaking.","symbol":"Parser (Type Import)","correct":"import type { Parser } from 'binary-parser-encoder';"}],"quickstart":{"code":"import { Parser } from 'binary-parser-encoder';\nimport { Buffer } from 'buffer'; // Explicitly import Buffer for clarity/bundler compatibility\n\n// Build an IP packet header Parser with encoding capabilities\nconst ipHeader = new Parser()\n  .endianess(\"big\")\n  .bit4(\"version\")\n  .bit4(\"headerLength\")\n  .uint8(\"tos\")\n  .uint16(\"packetLength\")\n  .uint16(\"id\")\n  .bit3(\"offset\")\n  .bit13(\"fragOffset\")\n  .uint8(\"ttl\")\n  .uint8(\"protocol\")\n  .uint16(\"checksum\")\n  .array(\"src\", {\n    type: \"uint8\",\n    length: 4\n  })\n  .array(\"dst\", {\n    type: \"uint8\",\n    length: 4\n  });\n\n// Prepare buffer to parse.\nconst buf = Buffer.from(\"450002c5939900002c06ef98adc24f6c850186d1\", \"hex\");\n\n// Parse buffer and show result\nconsole.log('Parsed IP Header:', ipHeader.parse(buf));\n\n// Define an object to be encoded\nconst anIpHeader = {\n  version: 4,\n  headerLength: 5,\n  tos: 0,\n  packetLength: 709,\n  id: 37785,\n  offset: 0,\n  fragOffset: 0,\n  ttl: 44,\n  protocol: 6,\n  checksum: 61336,\n  src: [ 173, 194, 79, 108 ],\n  dst: [ 133, 1, 134, 209 ]\n};\n\n// Encode an IP header object and show result as hex string\nconsole.log('Encoded IP Header (hex):', ipHeader.encode(anIpHeader).toString(\"hex\"));\n","lang":"typescript","description":"This quickstart demonstrates how to define a binary parser and encoder for an IP packet header, then parse a hex buffer and encode a JavaScript object back to binary."},"warnings":[{"fix":"Always install `binary-parser-encoder` when encoding capabilities are required. Be mindful that API methods and options related to encoding are unique to this fork.","message":"This package is a fork of the original `binary-parser` library. It specifically adds an `encode` feature not present in the upstream project. Developers migrating from or expecting the exact behavior of `binary-parser` should be aware of this distinction and potential API differences.","severity":"gotcha","affected_versions":">=1.4.0"},{"fix":"Review your TypeScript configuration and ensure compatibility. If type errors occur, consider updating your `@types/node` package or adjusting type assertions. Pure JavaScript users should perform thorough regression testing.","message":"Version 1.5.2 introduced a migration of the codebase to TypeScript. While largely designed for compatibility, this change might lead to stricter type checking, subtle differences in type inference, or require minor adjustments in existing TypeScript projects. Pure JavaScript projects might also be affected depending on their build toolchain.","severity":"breaking","affected_versions":">=1.5.2"},{"fix":"Ensure that `binary-parser-encoder` is correctly installed and that your import statements are referencing `Parser` from `binary-parser-encoder` to access the encoding functionality.","message":"The `encode()` method is a core and unique feature of `binary-parser-encoder` and is not available in the original `binary-parser` package. Attempting to call `encode()` on a `Parser` instance imported from `binary-parser` will result in a runtime `TypeError`.","severity":"gotcha","affected_versions":">=1.4.0"},{"fix":"Understand that `smartBufferSize` is an optimization for encoding performance and memory usage. Adjust its value based on your specific encoding workload and system memory constraints.","message":"The `new Parser([options])` constructor accepts an optional `smartBufferSize` option, which primarily controls the chunk size of the internal buffer used during encoding. This option is specific to the encoding feature and does not impact parsing operations.","severity":"gotcha","affected_versions":">=1.4.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const { Parser } = require('binary-parser-encoder');`. For ESM, use `import { Parser } from 'binary-parser-encoder';`.","cause":"This error typically occurs when attempting to import the `Parser` class using an incorrect syntax, such as `const Parser = require('binary-parser-encoder');` (CommonJS) or `import Parser from 'binary-parser-encoder';` (ESM default import). The `Parser` class is a named export.","error":"TypeError: Parser is not a constructor"},{"fix":"Verify your `package.json` to ensure `binary-parser-encoder` is installed. Double-check your import statements to confirm that you are importing `Parser` specifically from `binary-parser-encoder`.","cause":"This runtime error indicates that you have likely installed or are importing the `Parser` class from the original `binary-parser` package, which does not include the `encode` method, instead of `binary-parser-encoder`.","error":"TypeError: ipHeader.encode is not a function"},{"fix":"Ensure that `@types/binary-parser` is not installed if you are exclusively using `binary-parser-encoder`. This package ships its own type definitions, which correctly include the `encode` method. Restart your TypeScript language server or IDE after making dependency changes.","cause":"In a TypeScript project, this type error suggests that the TypeScript compiler is using type definitions from the original `binary-parser` package, even if you have `binary-parser-encoder` installed. This can result from conflicting `@types/` packages or incorrect module resolution.","error":"Property 'encode' does not exist on type 'Parser<any>'. Did you mean 'parse'?"}],"ecosystem":"npm"}