# @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](./src/adapters/eval-safe/eval-safe.md) — _(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](./src/codec/json/json-encode.md) — Implements the `serialize` function that converts any JavaScript value to a tagged JSON string preserving type informat… - [msgpack-decode](./src/codec/msgpack/msgpack-decode.md) — Implements `decodeBinary`, the inverse of `encodeBinary`. Given a MessagePack binary buffer produced by the encoder, it… - [msgpack-encode](./src/codec/msgpack/msgpack-encode.md) — Implements `encodeBinary`, the MessagePack counterpart to `serialize`. It converts any JavaScript value to a compact bi… - [stream](./src/codec/stream/stream.md) — _(no submodules)_ - [stream](./src/codec/stream/stream.md) — _(no submodules)_ - [wire](./src/codec/wire/wire.schemas.md) — _(no submodules)_ - [wire.schemas](./src/codec/wire/wire.schemas.md) — _(no submodules)_ - [error-codes](./src/error-codes/error-codes.md) — `error-codes` is the public re-export surface for the serialization error code registry. It imports `serialize-error` a… - [error-codes](./src/error-codes/error-codes.md) — `error-codes` is the public re-export surface for the serialization error code registry. It imports `serialize-error` a… - [codes](./src/errors/codes.md) — `codes` defines the canonical set of error codes for the `@suaveplan/serialize` package using `defineCodes` from `@suav… - [serialize-error](./src/errors/serialize-error.md) — Defines the error hierarchy for `@suaveplan/serialize`. All errors thrown by this package extend `SerializationError`,… - [legacy](./src/legacy/legacy.md) — _(no submodules)_ - [legacy](./src/legacy/legacy.md) — _(no submodules)_ - [observability](./src/observability/metrics.md) — _(no submodules)_ - [metrics](./src/observability/metrics.md) — _(no submodules)_ - [registry](./src/registry/registry.md) — _(no submodules)_ - [registry](./src/registry/registry.md) — _(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](./src/codec/json/json-encode.md) — Implements the `serialize` function that converts any JavaScript value to a tagged JSON string preserving type informat… - [msgpack-decode](./src/codec/msgpack/msgpack-decode.md) — Implements `decodeBinary`, the inverse of `encodeBinary`. Given a MessagePack binary buffer produced by the encoder, it… - [msgpack-encode](./src/codec/msgpack/msgpack-encode.md) — Implements `encodeBinary`, the MessagePack counterpart to `serialize`. It converts any JavaScript value to a compact bi… - [stream](./src/codec/stream/stream.md) — _(no submodules)_- [stream](./src/codec/stream/stream.md) — _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — _(no submodules)_- [wire.schemas](./src/codec/wire/wire.schemas.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes` defines the canonical set of error codes for the `@suaveplan/serialize` package using `defineCodes` from `@suav… - [serialize-error](./src/errors/serialize-error.md) — Defines the error hierarchy for `@suaveplan/serialize`. All errors thrown by this package extend `SerializationError`,… - [legacy](./src/legacy/legacy.md) — _(no submodules)_- [legacy](./src/legacy/legacy.md) — _(no submodules)_- [observability](./src/observability/metrics.md) — _(no submodules)_- [metrics](./src/observability/metrics.md) — _(no submodules)_- [registry](./src/registry/registry.md) — _(no submodules)_- [registry](./src/registry/registry.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — `error-codes` is the public re-export surface for the serialization error code registry. It imports `serialize-error` a… - [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](./src/codec/json/json-encode.md) — Implements the `serialize` function that converts any JavaScript value to a tagged JSON string preserving type informat… - [msgpack-decode](./src/codec/msgpack/msgpack-decode.md) — Implements `decodeBinary`, the inverse of `encodeBinary`. Given a MessagePack binary buffer produced by the encoder, it… - [msgpack-encode](./src/codec/msgpack/msgpack-encode.md) — Implements `encodeBinary`, the MessagePack counterpart to `serialize`. It converts any JavaScript value to a compact bi… - [stream](./src/codec/stream/stream.md) — _(no submodules)_- [stream](./src/codec/stream/stream.md) — _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — _(no submodules)_- [wire.schemas](./src/codec/wire/wire.schemas.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes` defines the canonical set of error codes for the `@suaveplan/serialize` package using `defineCodes` from `@suav… - [serialize-error](./src/errors/serialize-error.md) — Defines the error hierarchy for `@suaveplan/serialize`. All errors thrown by this package extend `SerializationError`,… - [legacy](./src/legacy/legacy.md) — _(no submodules)_- [legacy](./src/legacy/legacy.md) — _(no submodules)_- [observability](./src/observability/metrics.md) — _(no submodules)_- [metrics](./src/observability/metrics.md) — _(no submodules)_- [registry](./src/registry/registry.md) — _(no submodules)_- [registry](./src/registry/registry.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — `error-codes` is the public re-export surface for the serialization error code registry. It imports `serialize-error` a… - [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](./src/codec/json/json-encode.md) — Implements the `serialize` function that converts any JavaScript value to a tagged JSON string preserving type informat… - [msgpack-decode](./src/codec/msgpack/msgpack-decode.md) — Implements `decodeBinary`, the inverse of `encodeBinary`. Given a MessagePack binary buffer produced by the encoder, it… - [msgpack-encode](./src/codec/msgpack/msgpack-encode.md) — Implements `encodeBinary`, the MessagePack counterpart to `serialize`. It converts any JavaScript value to a compact bi… - [stream](./src/codec/stream/stream.md) — _(no submodules)_- [stream](./src/codec/stream/stream.md) — _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — _(no submodules)_- [wire.schemas](./src/codec/wire/wire.schemas.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes` defines the canonical set of error codes for the `@suaveplan/serialize` package using `defineCodes` from `@suav… - [serialize-error](./src/errors/serialize-error.md) — Defines the error hierarchy for `@suaveplan/serialize`. All errors thrown by this package extend `SerializationError`,… - [legacy](./src/legacy/legacy.md) — _(no submodules)_- [legacy](./src/legacy/legacy.md) — _(no submodules)_- [observability](./src/observability/metrics.md) — _(no submodules)_- [metrics](./src/observability/metrics.md) — _(no submodules)_- [registry](./src/registry/registry.md) — _(no submodules)_- [registry](./src/registry/registry.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — `error-codes` is the public re-export surface for the serialization error code registry. It imports `serialize-error` a… - [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](./src/codec/json/json-encode.md) — Implements the `serialize` function that converts any JavaScript value to a tagged JSON string preserving type informat… - [msgpack-decode](./src/codec/msgpack/msgpack-decode.md) — Implements `decodeBinary`, the inverse of `encodeBinary`. Given a MessagePack binary buffer produced by the encoder, it… - [msgpack-encode](./src/codec/msgpack/msgpack-encode.md) — Implements `encodeBinary`, the MessagePack counterpart to `serialize`. It converts any JavaScript value to a compact bi… - [stream](./src/codec/stream/stream.md) — _(no submodules)_ - [stream](./src/codec/stream/stream.md) — _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — _(no submodules)_ - [wire.schemas](./src/codec/wire/wire.schemas.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes` defines the canonical set of error codes for the `@suaveplan/serialize` package using `defineCodes` from `@suav… - [serialize-error](./src/errors/serialize-error.md) — Defines the error hierarchy for `@suaveplan/serialize`. All errors thrown by this package extend `SerializationError`,… - [legacy](./src/legacy/legacy.md) — _(no submodules)_ - [legacy](./src/legacy/legacy.md) — _(no submodules)_- [observability](./src/observability/metrics.md) — _(no submodules)_ - [metrics](./src/observability/metrics.md) — _(no submodules)_- [registry](./src/registry/registry.md) — _(no submodules)_ - [registry](./src/registry/registry.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — `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` - **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 ```typescript 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`](src/codec/json/json-encode.md) | Tagged JSON encoder | | [`src/codec/json/json-decode.md`](src/codec/json/json-decode.md) | Tagged JSON decoder | | [`src/codec/msgpack/msgpack-encode.md`](src/codec/msgpack/msgpack-encode.md) | MessagePack encoder | | [`src/codec/msgpack/msgpack-decode.md`](src/codec/msgpack/msgpack-decode.md) | MessagePack decoder | | [`src/codec/stream/stream.md`](src/codec/stream/stream.md) | Streaming framed codec | | [`src/registry/registry.md`](src/registry/registry.md) | Type registry | | [`src/errors/serialize-error.md`](src/errors/serialize-error.md) | Error hierarchy | | [`src/legacy/legacy.md`](src/legacy/legacy.md) | Legacy Date-only adapter | | [`src/adapters/eval-safe/eval-safe.md`](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 ```typescript import { serialize, deserialize } from "@suaveplan/serialize"; // main import { serializeEvalSafe } from "@suaveplan/serialize/unsafe"; // eval-capable (opt-in) ```