dxc-struct

Node.js equivalent of Python's Struct library for parsing and writing binary data.

Installation

npm i @dexcalibur/dxc-struct

Description

dxc-struct provides a TypeScript/JavaScript implementation for converting between binary data and JavaScript values, similar to Python's struct module. It supports encoding and decoding various data types including integers, floats, strings, and byte arrays with configurable endianness.

Features

• Binary data parsing and encoding
• Multiple data types: integers (signed/unsigned), floats, doubles, strings, byte arrays
• Endianness control: Big-endian and little-endian support
• Format strings: Python-like format strings for structured data
• TypeScript support: Fully typed for type safety

Usage

Basic Example

import { Struct } from '@dexcalibur/dxc-struct';

// Pack data into binary format
const data = Struct.pack('<IHB', [0x12345678, 0xABCD, 0xFF]);

// Unpack binary data
const values = Struct.unpack('<IHB', data);
console.log(values); // [305419896, 43981, 255]

Format Strings

Format strings define the data structure with the following syntax:

Endianness

• < - Little-endian (default for native)
• No prefix - Big-endian

Data Types

| Format | Type | Size (bytes) | Description | |--------|------|--------------|-------------| | c | char | 1 | Single character | | b | signed byte | 1 | Signed integer (-128 to 127) | | B | unsigned byte | 1 | Unsigned integer (0 to 255) | | h | short | 2 | Signed integer (-32768 to 32767) | | H | unsigned short | 2 | Unsigned integer (0 to 65535) | | i / l | int/long | 4 | Signed integer (-2³¹ to 2³¹-1) | | I / L | unsigned int/long | 4 | Unsigned integer (0 to 2³²-1) | | q | long long | 8 | Signed 64-bit integer (BigInt) | | Q | unsigned long long | 8 | Unsigned 64-bit integer (BigInt) | | f | float | 4 | IEEE 754 single-precision | | d | double | 8 | IEEE 754 double-precision | | s | string | variable | Fixed-length string | | S | string | variable | Null-terminated string | | A | byte array | variable | Byte array | | x | padding | 1 | Padding byte |

Count Prefix

Add a number before the format character to specify count: 4I = four integers

Named Fields

Add field names in parentheses: I(id)H(value) returns an object with named fields

Examples

Unpacking with Named Fields

const buffer = Buffer.from([0x78, 0x56, 0x34, 0x12, 0xCD, 0xAB]);
const result = Struct.unpack('<I(id)H(value)', buffer);
console.log(result); // { id: 305419896, value: 43981 }

Packing Multiple Values

const buffer = Struct.pack('<3H', [0x1234, 0x5678, 0x9ABC]);

Working with Strings

// Fixed-length string
const data = Struct.pack('<5s', ['hello']);

// Null-terminated string
const nullTerm = Struct.pack('<S', ['hello']);

64-bit Integers (BigInt)

const data = Struct.pack('<Q', [BigInt('0xFFFFFFFFFFFFFFFF')]);
const values = Struct.unpack('<Q', data);
console.log(values[0]); // 18446744073709551615n

API Reference

Struct.pack(format, values)

Packs values into a new Buffer according to the format string.

Parameters:

• format (string): Format string defining data layout
• values (any[]): Array of values to pack

Returns: Buffer containing packed binary data

Struct.packTo(format, buffer, offset, values)

Packs values into an existing Buffer at a specific offset.

Parameters:

• format (string): Format string defining data layout
• buffer (Buffer | any[]): Target buffer
• offset (number): Starting offset in buffer
• values (any[]): Array of values to pack

Returns: Modified buffer

Struct.unpack(format, data, offset?)

Unpacks binary data according to the format string.

Parameters:

• format (string): Format string defining data layout
• data (Buffer | any[] | string): Binary data to unpack
• offset (number, optional): Starting offset (default: 0)

Returns: Array of unpacked values or object with named fields

Struct.calcLength(format, values)

Calculates the byte length required for packing the given values.

Parameters:

• format (string): Format string
• values (any): Values to be packed

Returns: Number of bytes required

Development

Build

npm run build

Test

npm test

License

AGPL-3.0-only

Copyright (C) 2026 Reversense SAS

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See LICENSE for more details.