binencode

TypeScript library for encoding and decoding structured binary data. Supports scalars, strings, arrays, objects, and arbitrary nesting — all serialized to a compact big-endian binary wire format.

Installation

npm install binencode
# or
pnpm add binencode

Quick Start

import { bin, serial } from "binencode";

// 1. Create a Binary value
const value = bin.auto({ name: "Alice", score: 42, tags: ["admin", "user"] });

// 2. Encode to bytes
const buffer = serial.encode(value);

// 3. Decode back
const decoded = serial.decode(buffer);

// 4. Convert to plain JS
const js = serial.toJS(decoded);
// => { name: "Alice", score: 42, tags: ["admin", "user"] }

Core Concepts

All values in binencode are represented as Binary objects — typed wrappers around raw byte buffers. The bin namespace provides constructors, serial handles encode/decode, and BinaryBuffer is the underlying growable byte buffer.

Creating Binary Values

bin.auto(value) — automatic conversion

Converts any plain JS value to the appropriate Binary type:

bin.auto(null)           // => BinaryNull
bin.auto(true)           // => BinaryBool
bin.auto(42)             // => BinaryInt32
bin.auto(3.14)           // => BinaryFloat32
bin.auto(42n)            // => BinaryInt64
bin.auto("hello")        // => BinaryString
bin.auto([1, 2, 3])      // => BinaryArray
bin.auto({ x: 1 })       // => BinaryObject

| JS type | Binary type | |-------------|----------------| | null/undefined | BinaryNull | | boolean | BinaryBool | | integer | BinaryInt32 | | float | BinaryFloat32| | bigint | BinaryInt64 | | string | BinaryString | | Array | BinaryArray | | plain object | BinaryObject |

Explicit constructors

Use these when you need precise control over the numeric type:

bin.nil()                // null
bin.bool(true)           // boolean
bin.byte(0xff)           // unsigned 8-bit integer
bin.int32(-100)          // signed 32-bit integer
bin.uint32(4294967295)   // unsigned 32-bit integer
bin.int64(-9007199254740993n)  // signed 64-bit integer (bigint)
bin.uint64(18446744073709551615n) // unsigned 64-bit integer (bigint)
bin.float32(3.14)        // 32-bit float
bin.float64(3.141592653589793) // 64-bit float
bin.string("hello 🌍")  // UTF-8 string (supports emoji)
bin.char("A")            // single character scalar

Collections

// Array — heterogeneous elements are fine
bin.array(
  bin.int32(1),
  bin.string("two"),
  bin.nil(),
)

// Object — from a plain record or a Map
bin.object({ x: bin.int32(10), y: bin.float32(3.14) })

bin.object(new Map([
  ["key", bin.string("value")],
]))

Serialization

serial.encode(binary, out?)

Serializes a Binary value into a BinaryBuffer. Optionally appends into an existing buffer.

import { bin, serial } from "binencode";

const encoded = serial.encode(bin.auto({ id: 1, name: "Alice" }));
// encoded.data is a Uint8Array

serial.decode(buffer)

Deserializes a BinaryBuffer back into a Binary value.

const decoded = serial.decode(encoded);

serial.toJS(binary)

Converts a Binary back to a plain JavaScript value.

serial.toJS(bin.int32(42))          // => 42
serial.toJS(bin.string("hi"))       // => "hi"
serial.toJS(bin.array(bin.int32(1), bin.int32(2))) // => [1, 2]
serial.toJS(bin.object({ a: bin.bool(true) }))     // => { a: true }

Examples

Round-trip a primitive

import { bin, serial } from "binencode";

const original = bin.float64(Math.PI);
const buffer = serial.encode(original);
const result = serial.toJS(serial.decode(buffer));
// => 3.141592653589793

Round-trip a nested structure

const data = bin.auto({
  config: {
    host: "localhost",
    port: 8080,
    tags: ["primary", "read-only"],
  },
  count: 2,
});

const encoded = serial.encode(data);
const decoded = serial.toJS(serial.decode(encoded));
// => { config: { host: "localhost", port: 8080, tags: ["primary", "read-only"] }, count: 2 }

Append to an existing buffer

import { BinaryBuffer, bin, serial } from "binencode";

const out = new BinaryBuffer();
serial.encode(bin.int32(1), out);
serial.encode(bin.string("hello"), out);
// Both values are now packed into `out`

Check if a value is Binary

import { bin, isBin } from "binencode";

isBin(bin.int32(5))  // => true
isBin(42)            // => false
isBin({})            // => false

Wire Format

Each value is encoded as:

[type: i32][componentType: i32][count: i32][data...]

All integers are big-endian. Arrays and objects encode their children recursively. Object keys are encoded as strings before each value.

API Reference

bin namespace

| Function | Description | |---|---| | bin.auto(x) | Converts any JS value to Binary | | bin.nil() | Null value | | bin.bool(v) | Boolean | | bin.byte(v) | Unsigned 8-bit integer | | bin.int32(v) | Signed 32-bit integer | | bin.uint32(v) | Unsigned 32-bit integer | | bin.int64(v) | Signed 64-bit integer (bigint) | | bin.uint64(v) | Unsigned 64-bit integer (bigint) | | bin.float32(v) | 32-bit float | | bin.float64(v) | 64-bit float | | bin.char(v) | Single character scalar | | bin.string(v) | UTF-8 string | | bin.array(...items) | Heterogeneous array of Binary | | bin.object(record \| map) | Key-value object |

serial namespace

| Function | Description | |---|---| | serial.encode(binary, out?) | Encode a Binary to a BinaryBuffer | | serial.decode(buffer) | Decode a BinaryBuffer to a Binary | | serial.toJS(binary) | Convert a Binary to a plain JS value |

isBin(x)

Type guard — returns true if x is a branded Binary value.

BinaryBuffer

Low-level growable byte buffer used internally. Useful if you need direct byte access or want to manage a shared output buffer.

import { BinaryBuffer } from "binencode";

const buf = new BinaryBuffer();
buf.writeInt32(42);
buf.setCursor(0);
buf.readInt32(); // => 42