111 lines
15 KiB
Markdown
111 lines
15 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [eval-safe](./src/adapters/eval-safe/eval-safe.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [eval-safe](./src/adapters/eval-safe/eval-safe.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [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) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [stream](./src/codec/stream/stream.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [wire](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [wire.schemas](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [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) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [legacy](./src/legacy/legacy.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [observability](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [metrics](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [eval-safe](./src/adapters/eval-safe/eval-safe.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [stream](./src/codec/stream/stream.md) — <!-- begin:auto-docs --> _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [wire.schemas](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [legacy](./src/legacy/legacy.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_- [metrics](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [stream](./src/codec/stream/stream.md) — <!-- begin:auto-docs --> _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [wire.schemas](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [legacy](./src/legacy/legacy.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_- [metrics](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [stream](./src/codec/stream/stream.md) — <!-- begin:auto-docs --> _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [wire.schemas](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [legacy](./src/legacy/legacy.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_- [metrics](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_ - [stream](./src/codec/stream/stream.md) — <!-- begin:auto-docs --> _(no submodules)_- [wire](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wire.schemas](./src/codec/wire/wire.schemas.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_ - [legacy](./src/legacy/legacy.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_ - [metrics](./src/observability/metrics.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_ - [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(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<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
|
|
|
|
```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)
|
|
```
|