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.
An integer
- 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.
An custom byte-length integer
- 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.
Bit-size structured data. Must total a number of bytes.
- 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
Integer spread across multiple, separated bits
- 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-length number
- 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. 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.
- id ID of field (will be used as the key in the output object)
- length Length or key to value of length of string
n-parts of structured data
- 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
Data that can be any of a given number of structures
- 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
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);
/** @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'
}
]
}
}
]
}
];
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
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.
- Ability to integers larger than 32 bits
-
useBigInt
option to always return BigInts
0.6.2 - 2024-05-14
- Fixed handling of 4 byte integers
0.6.1 - 2023-03-04
- Log level of initial log message
0.6.0 - 2022-12-21
- Allowed
bits
values to be stored in an object using theid
parameter
0.5.0 - 2022-08-05
- 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 thenoDiscard
option is set
0.4.0 - 2022-07-25
-
bitsInt
for integers spread across multiple bytes with bits that should be ignored
0.3.0 - 2022-06-16
-
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 ofenums
) for the enums array.enums
is used instead ofenum
asenum
is a reserved word in JavaScript/ECMAScript.
0.2.0 - 2022-06-16
-
partial
flag tobits
type adding the ability to use amap
from an key value smaller than a byte - Handling of multi-byte bit ranges
- Throw error on not enough data
0.1.0 - 2022-06-15
Initial version!