{"id":12889,"library":"binary-parser","title":"Declarative Binary Parser","description":"Binary-parser is a JavaScript/TypeScript library designed for declaratively building efficient parsers for structured binary data. It allows developers to define complex binary structures using a fluent API, supporting a wide range of data types including various integer sizes (8, 16, 32, 64-bit, signed/unsigned, big/little endian), floating-point numbers, bit fields, strings, arrays, and nested user-defined types. The library dynamically generates and compiles optimized parser code at runtime, aiming for performance comparable to hand-written parsers. The current stable version is 2.3.0, with an active development cadence including regular patch and minor releases, alongside significant major updates like v2.0.0. Key differentiators include its declarative syntax for defining complex structures and its focus on runtime performance through code generation.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/keichi/binary-parser","tags":["javascript","binary","parser","decode","unpack","struct","buffer","bit"],"install":[{"cmd":"npm install binary-parser","lang":"bash","label":"npm"},{"cmd":"yarn add binary-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add binary-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Parser is a named export, not a default export, in ESM environments.","wrong":"import Parser from 'binary-parser'","symbol":"Parser","correct":"import { Parser } from 'binary-parser'"},{"note":"In CommonJS, Parser is a property of the module export, not the entire module itself.","wrong":"const Parser = require('binary-parser');","symbol":"Parser (CommonJS)","correct":"const Parser = require('binary-parser').Parser;"},{"note":"For TypeScript, `import type` is recommended for importing the `Parser` type for annotations without bundling the value.","symbol":"Parser (Type Import)","correct":"import type { Parser } from 'binary-parser'"}],"quickstart":{"code":"import { Parser } from 'binary-parser';\nimport { Buffer } from 'buffer'; // Node.js Buffer or a compatible polyfill\n\n// Build an IP packet header Parser\nconst ipHeader = new Parser()\n  .endianness('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\nconst parsedIpHeader = ipHeader.parse(buf);\nconsole.log(parsedIpHeader);\n// Expected output:\n// {\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: 61304,\n//   src: [ 173, 194, 79, 108 ],\n//   dst: [ 133, 1, 134, 209 ]\n// }","lang":"typescript","description":"Demonstrates defining and parsing a simple IP packet header from a hexadecimal buffer using the fluent API. This example uses ESM syntax and explicit Buffer import for clarity."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14 or newer. If targeting browsers, ensure modern browser compatibility where `TextDecoder` and `BigInt` are available.","message":"As of v2.0.0, Node.js versions below 14 and Internet Explorer 11 (or lower) are officially unsupported. The package's `engines` field now explicitly requires Node.js `>=14` for full compatibility.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Explicitly enable context variables by calling `.useContextVars()` on your parser instance, e.g., `new Parser().useContextVars().endianness('big')...`.","message":"Context variables, which allow custom parsing logic to access previously parsed values via `this`, are disabled by default since v2.0.0 due to their performance impact. Attempting to use `this` within custom parsing functions without explicit activation will lead to runtime errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your runtime environment supports `BigInt`. For Node.js, upgrade to v12 or newer. Note that the library's overall requirement is Node.js >=14.","message":"The `uint64` and `int64` methods return JavaScript `BigInt` types. These methods require Node.js v12.0 or higher for native `BigInt` support. Using them in older environments will result in a `ReferenceError: BigInt is not defined`.","severity":"gotcha","affected_versions":">=1.9.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Always create an instance of `Parser` using `new Parser()` before chaining methods or calling `.parse()`. Example: `const parser = new Parser(); parser.parse(buffer);`.","cause":"This error occurs when you attempt to call the `.parse()` method on the `Parser` class constructor itself instead of an instantiated `Parser` object.","error":"TypeError: (intermediate value).parse is not a function"},{"fix":"Upgrade your Node.js runtime to version 12 or higher. For full library compatibility and best performance, Node.js 14 or newer is recommended.","cause":"You are attempting to use the `uint64` or `int64` methods in an environment that does not natively support JavaScript's `BigInt` type (e.g., Node.js versions older than v12 or very old browsers).","error":"ReferenceError: BigInt is not defined"},{"fix":"Enable context variables by adding `.useContextVars()` to your parser chain immediately after instantiation: `new Parser().useContextVars().endianness('big')...`.","cause":"After `binary-parser` v2.0.0, context variables are disabled by default. This error indicates an attempt to access a property (e.g., `this.propertyName`) within a custom parsing function without explicitly enabling context variables.","error":"Parser error: Cannot access 'propertyName' from context."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}