skills/plugins/document-navigator/docs/foundation/data/serialize/README.md

@suaveplan/serialize - Round-trip-preserving structured serialization — tagged JSON, MessagePack binary, streaming, eval-safe by default

Summary

Round-trip-preserving structured serialization for JavaScript's rich type system. The standard JSON.stringify/JSON.parse pair silently drops Date objects, Map, Set, BigInt, Uint8Array, URL, RegExp, undefined, NaN, and ±Infinity. This package preserves all of them via a tagged-JSON codec (serialize/deserialize) and an efficient MessagePack binary codec (encodeBinary/decodeBinary). It also provides 4-byte-framed streaming codecs for ReadableStream pipelines, cycle detection with path context, a pluggable type registry for custom classes, and an opt-in /unsafe subpath that handles Function-bearing payloads. The default entry point is eval-safe. Use @suaveplan/serialize whenever you need to serialise application state across process boundaries, persist structured data, or stream binary payloads — and want to get back exactly what you put in.

Documentation tree

• eval-safe — (no submodules)
  • eval-safe — (no submodules)
• json-decode — Implements deserialize, the inverse of serialize. Given a tagged JSON string produced by the encoder, it reconstruc…
• json-encode — Implements the serialize function that converts any JavaScript value to a tagged JSON string preserving type informat…
• msgpack-decode — Implements decodeBinary, the inverse of encodeBinary. Given a MessagePack binary buffer produced by the encoder, it…
• msgpack-encode — Implements encodeBinary, the MessagePack counterpart to serialize. It converts any JavaScript value to a compact bi…
• stream — (no submodules)
  • stream — (no submodules)
• wire — (no submodules)
  • wire.schemas — (no submodules)
• error-codes — error-codes is the public re-export surface for the serialization error code registry. It imports serialize-error a…
  • error-codes — error-codes is the public re-export surface for the serialization error code registry. It imports serialize-error a…
• codes — codes defines the canonical set of error codes for the @suaveplan/serialize package using defineCodes from `@suav…
• serialize-error — Defines the error hierarchy for @suaveplan/serialize. All errors thrown by this package extend SerializationError,…
• legacy — (no submodules)
  • legacy — (no submodules)
• observability — (no submodules)
  • metrics — (no submodules)
• registry — (no submodules)
  • registry — (no submodules)

- [eval-safe](./src/adapters/eval-safe/eval-safe.md) — _(no submodules)_- [json-decode](./src/codec/json/json-decode.md) — Implements `deserialize`, the inverse of `serialize`. Given a tagged JSON string produced by the encoder, it reconstruc…

• json-encode — Implements the serialize function that converts any JavaScript value to a tagged JSON string preserving type informat…
• msgpack-decode — Implements decodeBinary, the inverse of encodeBinary. Given a MessagePack binary buffer produced by the encoder, it…
• msgpack-encode — Implements encodeBinary, the MessagePack counterpart to serialize. It converts any JavaScript value to a compact bi…
• stream — (no submodules)- stream — (no submodules)- wire — (no submodules)- wire.schemas — (no submodules)- codes — codes defines the canonical set of error codes for the @suaveplan/serialize package using defineCodes from `@suav…
• serialize-error — Defines the error hierarchy for @suaveplan/serialize. All errors thrown by this package extend SerializationError,…
• legacy — (no submodules)- legacy — (no submodules)- observability — (no submodules)- metrics — (no submodules)- registry — (no submodules)- registry — (no submodules)- error-codes — error-codes is the public re-export surface for the serialization error code registry. It imports serialize-error a…
• eval-safe — (no submodules)- json-decode — Implements deserialize, the inverse of serialize. Given a tagged JSON string produced by the encoder, it reconstruc…
• json-encode — Implements the serialize function that converts any JavaScript value to a tagged JSON string preserving type informat…
• msgpack-decode — Implements decodeBinary, the inverse of encodeBinary. Given a MessagePack binary buffer produced by the encoder, it…
• msgpack-encode — Implements encodeBinary, the MessagePack counterpart to serialize. It converts any JavaScript value to a compact bi…
• stream — (no submodules)- stream — (no submodules)- wire — (no submodules)- wire.schemas — (no submodules)- codes — codes defines the canonical set of error codes for the @suaveplan/serialize package using defineCodes from `@suav…
• serialize-error — Defines the error hierarchy for @suaveplan/serialize. All errors thrown by this package extend SerializationError,…
• legacy — (no submodules)- legacy — (no submodules)- observability — (no submodules)- metrics — (no submodules)- registry — (no submodules)- registry — (no submodules)- error-codes — error-codes is the public re-export surface for the serialization error code registry. It imports serialize-error a…
• eval-safe — (no submodules)- json-decode — Implements deserialize, the inverse of serialize. Given a tagged JSON string produced by the encoder, it reconstruc…
• json-encode — Implements the serialize function that converts any JavaScript value to a tagged JSON string preserving type informat…
• msgpack-decode — Implements decodeBinary, the inverse of encodeBinary. Given a MessagePack binary buffer produced by the encoder, it…
• msgpack-encode — Implements encodeBinary, the MessagePack counterpart to serialize. It converts any JavaScript value to a compact bi…
• stream — (no submodules)- stream — (no submodules)- wire — (no submodules)- wire.schemas — (no submodules)- codes — codes defines the canonical set of error codes for the @suaveplan/serialize package using defineCodes from `@suav…
• serialize-error — Defines the error hierarchy for @suaveplan/serialize. All errors thrown by this package extend SerializationError,…
• legacy — (no submodules)- legacy — (no submodules)- observability — (no submodules)- metrics — (no submodules)- registry — (no submodules)- registry — (no submodules)- error-codes — error-codes is the public re-export surface for the serialization error code registry. It imports serialize-error a…
• eval-safe — (no submodules)- json-decode — Implements deserialize, the inverse of serialize. Given a tagged JSON string produced by the encoder, it reconstruc…
• json-encode — Implements the serialize function that converts any JavaScript value to a tagged JSON string preserving type informat…
• msgpack-decode — Implements decodeBinary, the inverse of encodeBinary. Given a MessagePack binary buffer produced by the encoder, it…
• msgpack-encode — Implements encodeBinary, the MessagePack counterpart to serialize. It converts any JavaScript value to a compact bi…
• stream — (no submodules) - stream — (no submodules)- wire — (no submodules) - wire.schemas — (no submodules)- codes — codes defines the canonical set of error codes for the @suaveplan/serialize package using defineCodes from `@suav…
• serialize-error — Defines the error hierarchy for @suaveplan/serialize. All errors thrown by this package extend SerializationError,…
• legacy — (no submodules) - legacy — (no submodules)- observability — (no submodules) - metrics — (no submodules)- registry — (no submodules) - registry — (no submodules)- error-codes — error-codes is the public re-export surface for the serialization error code registry. It imports serialize-error a…

Features

• Tagged JSON — serialize/deserialize preserve Date, Map, Set, BigInt, all TypedArrays, URL, RegExp, undefined, NaN, ±Infinity
• MessagePack binary — encodeBinary/decodeBinary produce compact binary with canonical key ordering
• Streaming — encodeStream/decodeStream via 4-byte-framed ReadableStream<Uint8Array>
• Custom type registry — registerType adds arbitrary classes with encode/decode hooks
• Eval-safe adapter — @suaveplan/serialize/unsafe for Function-including payloads (opt-in only)
• AbortSignal support on all codec paths
• Cycle detection — CircularReferenceError with path context

Quick Start

import { deserialize, serialize } from "@suaveplan/serialize";

const obj = {
  created: new Date(),
  tags: new Set(["a", "b"]),
  count: BigInt(9007199254740993),
};

const json = serialize(obj);
const restored = deserialize(json);
// restored.created instanceof Date → true
// restored.tags instanceof Set → true
// restored.count === 9007199254740993n → true

Modules

Module	Purpose
src/codec/json/json-encode.md	Tagged JSON encoder
src/codec/json/json-decode.md	Tagged JSON decoder
src/codec/msgpack/msgpack-encode.md	MessagePack encoder
src/codec/msgpack/msgpack-decode.md	MessagePack decoder
src/codec/stream/stream.md	Streaming framed codec
src/registry/registry.md	Type registry
src/errors/serialize-error.md	Error hierarchy
src/legacy/legacy.md	Legacy Date-only adapter
src/adapters/eval-safe/eval-safe.md	Eval-safe adapter (unsafe subpath)

API

See co-located .md files for each module's full API reference.

Subpath Exports

import { serialize, deserialize } from "@suaveplan/serialize";          // main
import { serializeEvalSafe } from "@suaveplan/serialize/unsafe";        // eval-capable (opt-in)