Binary-decoder NPM

binary-decoder 1.0.0

Decoder for structure binary data

Decoder module for decoding binary data that has a structured but variable structure. The structure of the data is specified using an array of data parts.

Data Types

`byte`, `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint63`, `int64`

An integer

Options

id ID of field (will be used as the key in the output object)
littleEndian If true, will decode as littleEndian
partial If true, the nextByte counter that tracks the current position in the data will not be progressed.
useBigInt Always return a BigInt instead of a Number for integers. By default, if the number is 4 bytes or smaller, the value will be stored as a Number.

`bytes`

An custom byte-length integer

Options

id ID of field (will be used as the key in the output object)
littleEndian If true, will decode as littleEndian
partial If true, the nextByte counter that tracks the current position in the data will not be progressed.
useBigInt Always return a BigInt instead of a Number. By default, if the number is 4 bytes or smaller, the value will be stored as a Number.

`bits`

Bit-size structured data. Must total a number of bytes.

Options

id ID of field (will be used as the key in the output object). If not given, bit values will be set in containing object.
parts Array of bit parts that make up the data
- id ID of the bit part
- bit The number of bits in the bit part
- enums Enum of the bit value
partial If true, the nextByte counter that tracks the current position in the data will not be progressed. This is useful for using a map based on the first x-bits of a byte when the map includes the remaining bits in the byte

`bitsInt`

Integer spread across multiple, separated bits

Options

id ID of field (will be used as the key in the output object)
bits An array of bits to skip/take in an alternating fashion e.g. 0, 5, 3, 5, 3, 8 will be an 16-bit integer from 3 bytes, bits8:4 of the first byte, bits 8:4 of the second and the full last byte
partial If true, the nextByte counter that tracks the current position in the data will not be progressed. This is useful for using a map based on the first x-bits of a byte when the map includes the remaining bits in the byte
useBigInt Always return a BigInt instead of a Number. By default, if the number is 4 bytes or smaller, the value will be stored as a Number.

`variable`

Variable-length number

Options

id ID of field (will be used as the key in the output object)
length Length or key to value of length of data

`string`

String. If a NULL character (\0) is encountered, the string will be terminated and the rest of the bytes will be discarded unless the noDiscard option is set.

Options

id ID of field (will be used as the key in the output object)
length Length or key to value of length of string

`repeat`

n-parts of structured data

Options

id ID of field (will be used as the key in the output object)
repeats Number of parts
asArray Store parts in an array
asObject Store the parts in an object using the value for the given key as the part's key in the object

`map`

Data that can be any of a given number of structures

Options

id ID of field (will be used as the key in the output object)
key Key to value to determine structure of data
structures Object of value/structure of the possible data structures

Example

import { readFile } from 'fs/promises';
import { createDecoder } from 'binary-decoder';
import structure from './structure.js';

const decoder = createDecoder(structure, {
  littleEndian: false,
  throwOnInvalidEnumValue: true,
  logger: {
    debug: (...args) => console.debug(...args)
  }
});

const { nextByte, decodedMessage } = decoder.decode(new Uint8Array(await readFile('data.bin')));

console.log(decodedMessage);

structure.js

/** @type {import('binary-decoder').MessageStructure} */
export default [
  {
    type: 'uint16',
    id: 'messageLength'
  },
  {
    type: 'repeat',
    id: 'data',
    asObject: 'type',
    structure: [
      {
        type: 'byte',
        id: 'type',
        enums: [
          {
            value: 1,
            label: 'Header',
            key: 'header'
          },
          {
            value: 2,
            label: 'Payload',
            key: 'payload'
          }
        ]
      },
      {
        type: 'map',
        key: 'type',
        structures: {
          1: [
            {
              type: 'uint8',
              id: 'idLength'
            },
            {
              type: 'string',
              id: 'id',
              length: 'idLength'
            }
          ],
          2: [
            {
              type: 'uint16',
              id: 'payloadLength'
            },
            {
              type: 'variable',
              id: 'payload',
              length: 'payloadLength'
            }
          ]
        }
      }
    ]
  }
];

Development

Feel free to post errors or feature requests to the project issue tracker or email them to us. Please submit security concerns as a confidential issue

The source is hosted on Gitlab and uses prettier, lint-staged and husky to keep things pretty. As such, when you first clone the repository, as well as installing the npm dependencies, you will also need to install husky.

# Install NPM dependencies
npm install
# Set up husky Git hooks stored in .husky
npx husky install

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

1.0.0 - 2024-05-19

Breaking Change Now uses BigInt (ES2020) so older browsers and versions of Node (<10.4.0) are not supported.

Added

Ability to integers larger than 32 bits
useBigInt option to always return BigInts

0.6.2 - 2024-05-14

Fixed

Fixed handling of 4 byte integers

0.6.1 - 2023-03-04

Fixed

Log level of initial log message

0.6.0 - 2022-12-21

Changed

Allowed bits values to be stored in an object using the id parameter

0.5.0 - 2022-08-05

Changed

If a NULL character \0 is encountered in a string, the string will be terminated and the rest of the bytes of the string will be discarded unless the noDiscard option is set

0.4.0 - 2022-07-25

Added

bitsInt for integers spread across multiple bytes with bits that should be ignored

0.3.0 - 2022-06-16

Fixed

Breaking Corrects mapping of enums for integer types (byte, uint8 etc).
This will break functionality if you were using the incorrect key of enum (instead of enums) for the enums array. enums is used instead of enum as enum is a reserved word in JavaScript/ECMAScript.

0.2.0 - 2022-06-16

Added

partial flag to bits type adding the ability to use a map from an key value smaller than a byte
Handling of multi-byte bit ranges
Throw error on not enough data