JSON serializer

JsonSerializer is the default serializer. It wraps JSON.stringify + JSON.parse (bytes are UTF-8) with a tree walk that also round-trips Date, Uint8Array, Map, Set, and bigint via type tags.

import { JsonSerializer } from 'actor-ts';

const serializer = new JsonSerializer();
const bytes = serializer.toBinary({ kind: 'increment', n: 1 });
//  → Uint8Array of '{"kind":"increment","n":1}' as UTF-8

const decoded = serializer.fromBinary(bytes, '');
//  → { kind: 'increment', n: 1 }

Why JSON is the default

• Universal — every language has a JSON parser.
• Human-readable — open a journal file with cat; see the events.
• Schema-flexible — no compile step; types evolve via ordinary code changes (+ schema-migration adapters).
• Battle-tested — every Web API speaks JSON.

For most apps, you’ll never change serializers — JSON covers it.

What it handles

• Plain objects, arrays.
• Strings, numbers, booleans, null.
• Nested combinations.
• Date, Uint8Array, Map, Set, and bigint — round-tripped back into real instances via type tags (__date__, __bytes__, __map__, __set__, __bigint__).
• BidirectionalMap and BidirectionalMultiMap — the two framework classes with tags of their own (__bidirectionalmap__, #1035; __bidirectionalmultimap__, #1037), so they can be held in persistent state without an adapter. Only the forward direction is written — pairs for the first, an adjacency list for the second; the inverse is rebuilt on decode.
• NaN / Infinity / -Infinity / -0, RegExp (source + flags), URL, Error (name + message + cause — no stack), and every typed array / DataView / ArrayBuffer — round-tripped via type tags too (#889). Number/String/Boolean wrapper objects unwrap to their primitive, like JSON.stringify.
• toJSON() — honoured like JSON.stringify does, so Luxon/Temporal wrappers and your own toJSON types encode as their JSON form.
• User data that looks like a tag — an object whose sole key is a reserved tag name — is wrapped in a __literal__ escape on encode and round-trips as plain data. A tag is only ever interpreted when it is an object’s sole own key.

Persistence uses exactly this tree format: every journal, snapshot store and durable-state store writes its payloads through the same tagged tree (see what events and state may contain).

What needs care:

Type	Behavior
undefined	Throws a SerializationError (stricter than raw JSON.stringify, which drops it). The persistence payload codec instead drops undefined object properties like JSON.stringify and preserves undefined in value positions (array slots, Set members, Map entries) via a tag (#889). CborSerializer carries it natively everywhere, keys included — the one place the two codecs differ (#1036).
Function / Symbol / Promise / WeakMap / WeakSet	Throw a SerializationError — inherently non-serialisable.
Circular references	Throw a SerializationError naming the key path (instead of overflowing the stack).
Class instances	toJSON() is used when present; otherwise decoded as plain { ...fields } — methods + class identity lost.
Date / Map / Set / bigint / Uint8Array	Round-trip as real instances, but the JSON carries an actor-ts-specific tag shape (e.g. {"__date__":"…"}) — a plain (non-actor-ts) JSON reader won’t see a bare value.

For most actor messages, this is fine — the framework’s message conventions already discourage non-serializable shapes.

Size

JSON is larger than binary formats for the same data:

• Numbers are decimal strings ("42" is 4 bytes vs CBOR’s 2).
• Field names are repeated (every record has "kind":"...").
• Binary data (Uint8Array) base64-encodes (33 % overhead).

For text-heavy or repetitive data, JSON’s overhead is small. For binary-heavy data (images, encoded payloads), CBOR saves meaningfully.

Performance

Rough numbers per serialize/deserialize pair:

• Small object (~50 bytes): ~1-2 microseconds.
• Medium object (~1 KB): ~5-15 microseconds.
• Large object (~100 KB): ~1-2 ms.

JSON.parse / JSON.stringify are native code in V8/JSC — fast enough that JSON serialization is rarely the bottleneck.

When to switch to something else

Need to interop with non-JSON systems?              → Custom (Protobuf/Avro)
Bandwidth-bound (large or many small messages)?     → CBOR
Need typed schemas in source control?                → Custom (Protobuf)
Otherwise                                            → Stay on JSON

Most production apps stay on JSON for the actor wire and persistence — the perf / size gains from switching rarely justify the operational complexity.

Type tags round-trip real instances

const serializer = new JsonSerializer();
const bytes = serializer.toBinary({ at: new Date('2025-05-13T12:00:00Z') });
// → {"at":{"__date__":"2025-05-13T12:00:00.000Z"}}
const back = serializer.fromBinary(bytes, '') as { at: Date };
// → { at: Date(2025-05-13T12:00:00.000Z) }  ← a real Date

JsonSerializer restores Date, Map, Set, bigint, and Uint8Array as real instances — but via actor-ts-specific tags. A non-actor-ts consumer reading the raw JSON sees the tag shape, not a bare value. The cluster wire uses raw JSON.stringify (not this serializer), so cross-node tells do not get this round-trip — see the overview.

`undefined`, functions, and symbols throw

const serializer = new JsonSerializer();
serializer.toBinary({ run: () => 1 });   // ✗ SerializationError
serializer.toBinary({ x: undefined });   // ✗ SerializationError

Unlike raw JSON.stringify (which silently drops undefined and functions), JsonSerializer throws a SerializationError. Keep messages to plain data — bigint is fine, it round-trips via a tag.

Class identity is not preserved

class Money { constructor(readonly cents: number) {} plus(n: number) { return this.cents + n; } }
const serializer = new JsonSerializer();
const back = serializer.fromBinary(serializer.toBinary(new Money(500)), '');
// → { cents: 500 }  ← plain object, no `plus()` method, not `instanceof Money`

Class instances decode to plain objects — data fields survive, methods and instanceof do not. Register a custom serializer if you need class-preserving round-trips.

Where to next

• Serialization overview — the bigger picture.
• CBOR serializer — the binary alternative.
• Custom serializers — Protobuf / Avro / etc.
• Messages — the conventions for serialize-friendly shapes.