Registry / serialization / binary-parser

binary-parser

library0.0.4jsnpmunverified

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.

serialization

npm install binary-parser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BINARY-PARSER

binary-parser

serializationjavascriptv0.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ import { Parser } from 'binary-parser'

✗ import Parser from 'binary-parser'

Parser is a named export, not a default export, in ESM environments.

Parser (CommonJS)

✓ const Parser = require('binary-parser').Parser;

✗ const Parser = require('binary-parser');

In CommonJS, Parser is a property of the module export, not the entire module itself.

Parser (Type Import)

✓ import type { Parser } from 'binary-parser'

For TypeScript, `import type` is recommended for importing the `Parser` type for annotations without bundling the value.

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.

import { Parser } from 'binary-parser'; import { Buffer } from 'buffer'; // Node.js Buffer or a compatible polyfill // Build an IP packet header Parser const ipHeader = new Parser() .endianness('big') .bit4('version') .bit4('headerLength') .uint8('tos') .uint16('packetLength') .uint16('id') .bit3('offset') .bit13('fragOffset') .uint8('ttl') .uint8('protocol') .uint16('checksum') .array('src', { type: 'uint8', length: 4 }) .array('dst', { type: 'uint8', length: 4 }); // Prepare buffer to parse. const buf = Buffer.from('450002c5939900002c06ef98adc24f6c850186d1', 'hex'); // Parse buffer and show result const parsedIpHeader = ipHeader.parse(buf); console.log(parsedIpHeader); // Expected output: // { // version: 4, // headerLength: 5, // tos: 0, // packetLength: 709, // id: 37785, // offset: 0, // fragOffset: 0, // ttl: 44, // protocol: 6, // checksum: 61304, // src: [ 173, 194, 79, 108 ], // dst: [ 133, 1, 134, 209 ] // }

Debug

Known issues

breakingAs 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.

fix

Upgrade your Node.js runtime to version 14 or newer. If targeting browsers, ensure modern browser compatibility where `TextDecoder` and `BigInt` are available.

affects: >=2.0.0

breakingContext 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.

fix

Explicitly enable context variables by calling `.useContextVars()` on your parser instance, e.g., `new Parser().useContextVars().endianness('big')...`.

affects: >=2.0.0

gotchaThe `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`.

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.

affects: >=1.9.0

Errors

Common errors & fixes

TypeError: (intermediate value).parse is not a function

This error occurs when you attempt to call the `.parse()` method on the `Parser` class constructor itself instead of an instantiated `Parser` object.

fix

Always create an instance of `Parser` using `new Parser()` before chaining methods or calling `.parse()`. Example: `const parser = new Parser(); parser.parse(buffer);`.

ReferenceError: BigInt is not defined

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).

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.

Parser error: Cannot access 'propertyName' from context.

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.

fix

Enable context variables by adding `.useContextVars()` to your parser chain immediately after instantiation: `new Parser().useContextVars().endianness('big')...`.

Upgrade

Version history

0.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/keichi/binary-parser ↗

packagehttps://www.npmjs.com/package/binary-parser ↗

homepagehttps://binary-parser.github.io/binary-parser/ ↗