helpers.ts - @hertzg/binstruct documentation

Helper functions for simplified binary encoding and decoding operations.

This module provides convenient wrapper functions that abstract away buffer management complexities, making it easier to encode and decode binary data without manually handling buffer allocation and sizing.

The helper functions automatically manage buffer allocation using resizable ArrayBuffers with exponential growth strategies, following best practices for efficient memory usage and performance. Buffers start at 4KB and grow by 2x when needed, up to a maximum of 400MB by default.

Examples

Basic encoding and decoding

import { assertEquals } from "@std/assert";
import { encode, decode, struct, u16le, u8le } from "@hertzg/binstruct";

const coder = struct({ id: u16le(), flag: u8le() });
const data = { id: 42, flag: 7 };

// Encode without providing a buffer - auto-allocates
const encoded = encode(coder, data);
assertEquals(encoded.length, 3);

// Decode and get the decoded data
const decodedData = decode(coder, encoded);
assertEquals(decodedData.id, 42);
assertEquals(decodedData.flag, 7);

Using provided target buffer

import { assertEquals } from "@std/assert";
import { encode, decode, struct, u32le } from "@hertzg/binstruct";

const coder = struct({ value: u32le() });
const data = { value: 12345 };
const buffer = new Uint8Array(100);

// Encode to provided buffer
const encoded = encode(coder, data, undefined, buffer);
assertEquals(encoded.length, 4);
assertEquals(encoded.buffer, buffer.buffer);

// Decode from buffer
const decodedData = decode(coder, encoded);
assertEquals(decodedData.value, 12345);

Round-trip encoding and decoding

import { assertEquals } from "@std/assert";
import { encode, decode, struct, u16le, u8le, string } from "@hertzg/binstruct";

const coder = struct({
  id: u16le(),
  name: string(u16le()), // Length-prefixed string
  active: u8le(),
});

const originalData = { id: 1001, name: "test", active: 1 };

// Encode
const encoded = encode(coder, originalData);
assertEquals(encoded.length, 9); // 2 (id) + 2 (name length) + 4 (name bytes) + 1 (active)

// Decode
const decodedData = decode(coder, encoded);

assertEquals(decodedData.id, originalData.id);
assertEquals(decodedData.name, originalData.name);
assertEquals(decodedData.active, originalData.active);

Using custom context

import { assertEquals } from "@std/assert";
import { encode, decode, createContext, struct, u16le } from "@hertzg/binstruct";

const coder = struct({ value: u16le() });
const data = { value: 42 };
const context = createContext("encode");

const encoded = encode(coder, data, context);
assertEquals(encoded.length, 2);

const decodeContext = createContext("decode");
const decodedData = decode(coder, encoded, decodeContext);
assertEquals(decodedData.value, 42);