Zum Inhalt springen
Deutsch

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 }
  • 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.

  • Plain-Objekte, Arrays.
  • Strings, Zahlen, Booleans, null.
  • Verschachtelte Kombinationen.
  • Date, Uint8Array, Map, Set und bigint — über Type-Tags (__date__, __bytes__, __map__, __set__, __bigint__) zurück in echte Instanzen round-getrippt.
  • BidirectionalMap und BidirectionalMultiMap — 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 bei JSON.stringify.
  • toJSON() — wird wie bei JSON.stringify respektiert, sodass Luxon/Temporal-Wrapper und eigene toJSON-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:

TypVerhalten
undefinedWirft 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 / WeakSetWerfen einen SerializationError — prinzipiell nicht serialisierbar.
Zirkuläre ReferenzenWerfen einen SerializationError mit dem Key-Pfad (statt den Stack zu sprengen).
KlasseninstanzentoJSON() wird genutzt, wenn vorhanden; sonst als plain { ...fields } dekodiert — Methoden + Klassenidentität verloren.
Date / Map / Set / bigint / Uint8ArrayRound-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.

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.

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:

ObergrenzeDefaultWas sie ablehnt
max-nesting-depth256Einen tiefer verschachtelten Baum — Arrays, Objekte und getaggte Container zählen je eine Ebene.
max-document-bytes0 (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.

Mit Nicht-JSON-Systemen interoperieren? → Custom (Protobuf/Avro)
Bandbreitenkritisch (große oder viele kleine Nachrichten)? → CBOR
Typisierte Schemas in Versionskontrolle nötig? → Custom (Protobuf)
Sonst → Bei JSON bleiben

Die meisten Produktions-Apps bleiben für Actor-Wire und Persistenz bei JSON — die Perf-/Größenvorteile eines Wechsels rechtfertigen selten die operative Komplexität.