_                   _      _     
  ___| |_ _ __ _   _  ___| |_   (_)___ 
 / __| __| '__| | | |/ __| __|  | / __|
 \__ \ |_| |  | |_| | (__| |_ _ | \__ \
 |___/\__|_|   \__,_|\___|\__(_)/ |___/
                              |__/     

Python struct module port to JavaScript — pack and unpack binary data using format strings.

Works in Node.js and browsers (no dependencies, uses Web APIs: ArrayBuffer, DataView, BigInt).

Install

npm install @teskevirtualsystem/struct.js

Usage

import { pack, unpack, calcSize } from "@teskevirtualsystem/struct.js";

// Pack an unsigned int (1234) — returns ArrayBuffer
const buf = pack("I", 1234);

// Unpack it back
unpack("I", buf); // [1234]

// Pack multiple fields
const buf2 = pack("Ifc", 9184, 10.5, "a");
unpack("Ifc", buf2); // [9184, 10.5, "a"]

// Big-endian
const buf3 = pack(">I", 1234);
unpack(">I", buf3); // [1234]

// Repeat counts
const buf4 = pack("3I", 10, 20, 30);
unpack("3I", buf4); // [10, 20, 30]

// Fixed-width strings
const buf5 = pack("10s", "hello");
unpack("10s", buf5); // ["hello\0\0\0\0\0"]

// Pascal strings (length-prefixed)
const buf6 = pack("10p", "hello");
unpack("10p", buf6); // ["hello"]

// Calculate size without packing
calcSize("IHHf"); // 14

API

unpack(fmt, input) → Array

Unpacks binary data according to the format string.

Input types: string (legacy), ArrayBuffer, or DataView.

pack(fmt, ...values) → ArrayBuffer

Packs values into an ArrayBuffer according to the format string.

calcSize(fmt) → number

Returns the byte size of the packed data for a given format.

StructError

Error class thrown on invalid formats, buffer size mismatches, value count mismatches, or out-of-range values.

Format String

First character (optional) sets endianness:

| Prefix | Endianness | |--------|-----------| | @, =, < | Little-endian | | >, ! | Big-endian |

Remaining characters define fields. A numeric prefix repeats the field:

| Format | C Type | Size | Description | |--------|---------|------|-------------| | x | pad byte | 1 | Skips bytes (no value consumed) | | c | char | 1 | Single character string | | b | signed char | 1 | Integer | | B | unsigned char | 1 | Integer | | ? | _Bool | 1 | Boolean | | h | short | 2 | Integer | | H | unsigned short | 2 | Integer | | i | int | 4 | Integer | | I | unsigned int | 4 | Integer | | l | long | 4 | Integer | | L | unsigned long | 4 | Integer | | q | long long | 8 | BigInt | | Q | unsigned long long | 8 | BigInt | | f | float | 4 | Float | | d | double | 8 | Double | | s | char[] | N | Fixed-width string (N bytes, padded with \0) | | p | char[] | N | Pascal string (1 length byte + N-1 data bytes) | | P | void * | 4 | Integer (pointer, 32-bit) |

Dev

npm run build      # Copy src/ to dist/
npm test           # Run tests (vitest)
npm run test:watch # Watch mode
npm run lint       # ESLint
npm run typecheck  # TypeScript declaration check

License

MIT