msgpack-encode

Purpose

Implements encodeBinary, the MessagePack counterpart to serialize. It converts any JavaScript value to a compact binary Uint8Array using the same type-registry tag scheme as the JSON encoder. By pre-processing the input into plain msgpack-compatible intermediate values before handing off to @msgpack/msgpack, the codec avoids the complexity of a custom extension codec while still preserving all built-in and custom registered types.

Object keys are sorted canonically before encoding, so two structurally identical objects always produce bit-identical output regardless of property insertion order.

Features

Produces a compact binary wire format via @msgpack/msgpack
Same type-registry integration as the JSON codec: all built-in and custom types round-trip faithfully
Canonical key ordering for deterministic binary output
maxDepth, maxSize, and AbortSignal options parallel to the JSON encoder
Cycle detection via WeakSet — throws CircularReferenceError on cycles
Throws MaxDepthExceededError and MaxSizeExceededError on limit violations

Usage: Basic Example

import { decodeBinary, encodeBinary } from "@suaveplan/serialize";

const payload = { created: new Date(), ids: new Set([1, 2, 3]) };
const bytes = encodeBinary(payload);
// bytes is a compact Uint8Array — smaller than JSON for numeric-heavy data

const restored = decodeBinary(bytes);

Usage: Advanced Example

import { encodeBinary } from "@suaveplan/serialize";

const controller = new AbortController();

const bytes = encodeBinary(largeDataset, {
  maxDepth: 30,
  maxSize: 1_000_000, // 1 MB
  signal: controller.signal,
});

// Send over WebSocket, IndexedDB, etc.
socket.send(bytes);

API Reference

`encodeBinary(value: unknown, opts?: SerializeOptions): Uint8Array`

Encodes value to a MessagePack binary buffer.

Parameters:

value — any JavaScript value; functions and symbols are silently dropped
opts.maxDepth — maximum recursion depth (default: 100)
opts.maxSize — maximum byte length of the binary output; checked after encoding
opts.signal — AbortSignal; checked once before encoding begins

Returns: a Uint8Array containing the MessagePack payload.

Throws:

CircularReferenceError on cycles
MaxDepthExceededError when nesting exceeds maxDepth
MaxSizeExceededError when output exceeds maxSize bytes
The AbortSignal's reason if aborted

`SerializeOptions`

See json-encode.md — the same options interface is shared.

Implementation Notes

A single shared Encoder instance is reused across calls to amortise initialisation overhead; the encoder is stateless between calls.
The preEncode helper mirrors the logic in json-encode.ts but emits plain objects/arrays instead of a JSON string, avoiding a second parse step.
AbortSignal is checked once at the call boundary rather than every 256 nodes because msgpack encoding is typically fast and does not support mid-stream interruption without a custom streaming approach.
Canonical key sorting uses the default Array.prototype.sort comparator (lexicographic UTF-16 code units), matching the sort used by many canonical JSON implementations.

3.2 KiB Raw Blame History