JSON-Serializer
JsonSerializer ist der Default-Serializer. Er umschließt
JSON.stringify + JSON.parse (Bytes sind UTF-8) mit einem
Baum-Walk, der zusätzlich Date, Uint8Array, Map, Set und
bigint über Type-Tags round-trippt.
import { JsonSerializer } from 'actor-ts/serialization';
const serializer = new JsonSerializer();const bytes = serializer.toBinary({ kind: 'increment', n: 1 });// → Uint8Array von '{"kind":"increment","n":1}' als UTF-8
const decoded = serializer.fromBinary(bytes, '');// → { kind: 'increment', n: 1 }Warum JSON der Default ist
Abschnitt betitelt „Warum JSON der Default ist“- Universell — jede Sprache hat einen JSON-Parser.
- Menschenlesbar — öffne eine Journal-Datei mit
cat; sieh die Events. - Schema-flexibel — kein Compile-Schritt; Typen entwickeln sich durch ganz normale Code-Änderungen weiter (+ Schema- Migrations-Adapter).
- Kampferprobt — jede Web-API spricht JSON.
Für die meisten Apps wirst du nie Serializer wechseln — JSON deckt es ab.
Was er behandelt
Abschnitt betitelt „Was er behandelt“- Plain-Objekte, Arrays.
- Strings, Zahlen, Booleans,
null. - Verschachtelte Kombinationen.
Date,Uint8Array,Map,Setundbigint— über Type-Tags (__date__,__bytes__,__map__,__set__,__bigint__) zurück in echte Instanzen round-getrippt.BidirectionalMapundBidirectionalMultiMap— die beiden Framework-Klassen mit eigenen Tags (__bidirectionalmap__, #1035;__bidirectionalmultimap__, #1037), damit sie ohne Adapter im persistenten State liegen können. Geschrieben wird nur die Vorwärtsrichtung — Paare bei der ersten, eine Adjazenzliste bei der zweiten; die Umkehrung wird beim Dekodieren rekonstruiert.NaN/Infinity/-Infinity/-0,RegExp(Source + Flags),URL,Error(Name + Message + Cause — ohne Stack) und jedes Typed Array /DataView/ArrayBuffer— ebenfalls über Type-Tags round-getrippt (#889).Number/String/Boolean-Wrapper-Objekte entpacken zu ihrem Primitiv, wie beiJSON.stringify.toJSON()— wird wie beiJSON.stringifyrespektiert, sodass Luxon/Temporal-Wrapper und eigenetoJSON-Typen als ihre JSON-Form encodieren.- Nutzerdaten, die wie ein Tag aussehen — ein Objekt, dessen
einziger Key ein reservierter Tag-Name ist — werden beim Encode
in ein
__literal__-Escape gewrappt und round-trippen als Plain-Data. Ein Tag wird nur interpretiert, wenn er der einzige eigene Key eines Objekts ist.
Die Persistenz nutzt exakt dieses Tree-Format: Jeder Journal, Snapshot-Store und Durable-State-Store schreibt seine Payloads durch denselben getaggten Tree (siehe was Events und State enthalten dürfen).
Worauf du achten musst:
| Typ | Verhalten |
|---|---|
undefined | Wirft einen SerializationError (strenger als rohes JSON.stringify, das es verwirft). Der Persistenz-Payload-Codec verwirft stattdessen undefined-Objekt-Properties wie JSON.stringify und erhält undefined in Wertpositionen (Array-Slots, Set-Member, Map-Einträge) über einen Tag (#889). CborSerializer trägt es überall nativ, Keys eingeschlossen — die eine Stelle, an der sich die beiden Codecs unterscheiden (#1036). |
Function / Symbol / Promise / WeakMap / WeakSet | Werfen einen SerializationError — prinzipiell nicht serialisierbar. |
| Zirkuläre Referenzen | Werfen einen SerializationError mit dem Key-Pfad (statt den Stack zu sprengen). |
| Klasseninstanzen | toJSON() wird genutzt, wenn vorhanden; sonst als plain { ...fields } dekodiert — Methoden + Klassenidentität verloren. |
Date / Map / Set / bigint / Uint8Array | Round-trippen als echte Instanzen, aber das JSON trägt eine actor-ts-spezifische Tag-Form (z. B. {"__date__":"…"}) — ein einfacher (Nicht-actor-ts-)JSON-Leser sieht keinen blanken Wert. |
Für die meisten Actor-Nachrichten ist das okay — die Message-Konventionen des Frameworks raten ohnehin von nicht serialisierbaren Formen ab.
JSON ist größer als Binärformate für dieselben Daten:
- Zahlen sind Dezimal-Strings (
"42"sind 4 Bytes vs. 2 bei CBOR). - Feldnamen wiederholen sich (jeder Record hat
"kind":"..."). - Binärdaten (
Uint8Array) werden base64-kodiert (33 % Overhead).
Für textlastige oder sich wiederholende Daten ist JSONs Overhead klein. Für binärlastige Daten (Bilder, kodierte Payloads) spart CBOR spürbar.
Performance
Abschnitt betitelt „Performance“Grobe Zahlen pro Serialize-/Deserialize-Paar:
- Kleines Objekt (~50 Bytes): ~1–2 Mikrosekunden.
- Mittleres Objekt (~1 KB): ~5–15 Mikrosekunden.
- Großes Objekt (~100 KB): ~1–2 ms.
JSON.parse / JSON.stringify sind nativer Code in V8/JSC —
schnell genug, dass JSON-Serialisierung selten zum Bottleneck wird.
Was der Decoder ablehnt
Abschnitt betitelt „Was der Decoder ablehnt“fromBinary lehnt ein Dokument, das gar kein JSON ist, mit einem
SerializationError ab, der den Parse-Fehler benennt, und einen fehlerhaften
Type-Tag in wohlgeformtem JSON mit einem, der den Tag benennt, sodass sich die
beiden Fehler im Log auseinanderhalten lassen; der Persistenz-Payload-Codec
meldet eine gespeicherte Zeile, die sich nicht parsen lässt, auf dieselbe Weise.
Ein __error__, dessen name oder message kein String ist, ist ein solcher
fehlerhafter Tag. Ein name ohne eingebaute Fehlerklasse dahinter ist es
nicht: Dieser Fehler kommt als einfacher Error an, der den Namen behält — so
kommt jede eigene Fehlerklasse über das Wire —, und ein Member von
Object.prototype wie toString oder constructor ist keine Ausnahme.
Beim Dekodieren gehören die Bytes jemand anderem, deshalb wendet der
JSON-Decoder die Obergrenzen aus
actor-ts.serialization.read-constraints
an:
| Obergrenze | Default | Was sie ablehnt |
|---|---|---|
max-nesting-depth | 256 | Einen tiefer verschachtelten Baum — Arrays, Objekte und getaggte Container zählen je eine Ebene. |
max-document-bytes | 0 (aus) | Ein größeres Dokument — geprüft bevor JSON.parse läuft, und auf dem Cluster-Wire, bevor die Bytes des Frames überhaupt gepuffert werden. |
max-nesting-depth ist keine Dekoration. JSON.parse bietet hier nichts, worauf
man sich stützen könnte: auf Bun, Node und Deno gleichermaßen gemessen,
akzeptiert er klaglos hunderttausend [-Ebenen. Was überläuft,
ist der eigene Tagged-Tree-Walker von actor-ts, der pro Ebene einmal rekursiert
— und auf dem Cluster-Wire wird dieser Walker direkt erreicht, mit Bytes, die
jeder Peer senden kann, der den Handshake abgeschlossen hat. Ein Payload
jenseits der Grenze ist ein SerializationError, der die Tiefe benennt und
geworfen wird, bevor der Walk weiter absteigt.
Die Grenze darf gesenkt, aber nicht über 256 angehoben werden — das ist die
harte Obergrenze des Encoders: ein Knoten, der tiefer liest als er schreibt,
würde ein Payload akzeptieren, das er selbst nicht erzeugen kann. Beide sind
Obergrenzen pro Dekodierung — über das, was toBinary ausgibt, sagen sie nichts.
max-document-bytes begrenzt die Kosten statt der Form und ist die einzige
Obergrenze, die greifen kann, bevor das Parsen überhaupt etwas alloziert. Auf
dem Cluster-Wire wird sie gegen das 4-Byte-Längenpräfix des Frames geprüft — und
damit früher, als es beiden Serializern möglich ist: die bekommen Bytes, die es
bereits gibt. Ausgeliefert wird 0, es ändert sich also nichts, solange eine
Installation sie nicht setzt.
Bleibt ein Rest, der klar benannt gehört: in der Auslieferungskonfiguration
wird ein zu tiefer Frame erst abgelehnt, nachdem JSON.parse ihn bereits
aufgebaut hat. Auf Bun 1.4 gemessen kostet ein einzelner 16-MiB-Frame aus
ausbalancierten [ rund 1,0 s CPU und 260 MiB Heap, bevor die Tiefengrenze ihn
meldet — etwa das Vierfache eines legitimen Frames derselben Größe, und
wiederholbar für jeden Peer, der den Handshake abgeschlossen hat. Zwei
Stellschrauben begrenzen das, keine davon ist per Default aktiv:
actor-ts.remote.max-frame-bytes deckelt die Bytes bei 16 MiB, und
max-document-bytes deckelt das Dokument auf demselben Präfix. Ein Vorab-Scan
des Rohpuffers würde es ohne beide schließen; er wurde gemessen und nicht
ausgeliefert, weil er 18–28 % jeder Frame-Dekodierung kostet, um eine
vierfache Verstärkung zu beseitigen.
Journal- und Snapshot-Zeilen sind bewusst ausgenommen. Diese Bytes hat actor-ts selbst geschrieben; eine verschärfte Grenze würde dort wiederherstellbare Historie in unlesbare verwandeln.
Eine Grenze ist nicht konfigurierbar, und sie gilt für jede Kodierung und jede
Dekodierung, Journal- und Snapshot-Zeilen eingeschlossen: Ein bigint reist
nur in dem Bereich, den die 1-KiB-Bignum-Grenze des CBOR-Serializers zulässt,
-2^8192 bis 2^8192 - 1, sodass beide Serializer dieselben Integer
transportieren. Ein Integer außerhalb davon wird dort abgelehnt, wo er
geschrieben wird — toBinary wirft, persist() scheitert, ohne etwas zu
speichern, ein entferntes tell verwirft genau diese Nachricht und
protokolliert es —, statt zu einer Zeile zu werden, an der die nächste Recovery
scheitert. Ein Dokument, das trotzdem einen enthält, wird beim Lesen
abgelehnt. Die Ziffernfolge wird gemessen, bevor sie geparst wird — höchstens
2467 Ziffern, die Länge von 2^8192 - 1, nach einem optionalen Minuszeichen —,
weil das Parsen von Dezimalziffern mehr als linear mit ihrer Anzahl kostet: Auf
Bun 1.4 gemessen brauchte eine Million Ziffern eine Drittelsekunde und vier
Millionen fast zwei. Geparst wird überhaupt nur die Schreibweise, die der
Encoder in ein __bigint__ schreibt — ein Minuszeichen nur unter null, dann
Dezimalziffern ohne führende Null —, sodass +5, 007, -0, Leerraum und
Hex auf jeder Runtime gleichermaßen abgelehnt werden. Danach wird der geparste
Wert am Bereich selbst gemessen, denn 2467 Ziffern reichen etwa neunmal
darüber hinaus. Jede Ablehnung ist ein SerializationError, und die
verbleibenden Kosten wachsen nur im Gleichschritt mit dem Dokument, das
max-document-bytes begrenzt. Ein Integer, der breiter als 8192 Bit ist,
reist als String-Feld; prüfe seine Länge, bevor dein eigener Code ihn an
BigInt() übergibt.
Wann auf etwas anderes wechseln
Abschnitt betitelt „Wann auf etwas anderes wechseln“Mit Nicht-JSON-Systemen interoperieren? → Custom (Protobuf/Avro)Bandbreitenkritisch (große oder viele kleine Nachrichten)? → CBORTypisierte Schemas in Versionskontrolle nötig? → Custom (Protobuf)Sonst → Bei JSON bleibenDie meisten Produktions-Apps bleiben für Actor-Wire und Persistenz bei JSON — die Perf-/Größenvorteile eines Wechsels rechtfertigen selten die operative Komplexität.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Serialization-Übersicht — das große Bild.
- CBOR-Serializer — die binäre Alternative.
- Eigene Serializer — Protobuf / Avro / usw.
- Nachrichten — die Konventionen für serialisierungsfreundliche Formen.
