JSON Toolkit

JSON parsen, bevor er vollständig angekommen ist: Streaming-Vorschau und inkrementelle Reparatur

Fazit: LLMs geben JSON Token für Token aus und APIs liefern große Antworten in Chunks, doch JSON.parse weigert sich, bis das ganze Dokument da ist. Dieser Leitfaden trennt drei Implementierungsstile — vollständige Reparatur, echtes Inkrement und partielles Parsen — und zeigt, wie eine Allow-Maske die Vorschau stabil hält, mit gemessenen Pipeline-Zahlen und produktionsreifem Code.

Mittel~5 Min. LesezeitVeröffentlicht 2026-11-16Aktualisiert 2026-11-16
Diagramm von partiellem Parsing und inkrementeller Reparatur über die Chunks eines Streaming-JSON

JSON.parse verspricht „ich starte erst, wenn das ganze Dokument da ist", das Streaming verspricht „ich liefere Dir Daten Chunk für Chunk". Der Konflikt liegt nicht in der Geschwindigkeit, sondern in der Vollständigkeits-Semantik: Ein unvollendetes Dokument hat noch kein korrektes Parsergebnis.

Das Symptom: drei Szenarien, die nicht auf den ganzen Text warten können

Das erste Szenario sind LLM-Anwendungen. Das Modell gibt JSON Token für Token aus; eine strukturierte Ausgabe von 8 KB kann Dutzende Sekunden brauchen, während der Nutzer auf ein leeres Panel starrt — obwohl die ersten Felder schon nach einer Sekunde anzeigbar waren. Das zweite Szenario sind Gateways und Proxys: Das Upstream schiebt eine Antwort von Dutzenden Megabyte als HTTP-Chunks durch, und ein Proxy, der vor dem Weiterleiten Felder filtern will, vervielfacht seinen Speicherpeak, wenn er alles über res.json() puffert. Das dritte Szenario sind Message-Queues und Log-Pipelines: NDJSON-Datensätze treffen nacheinander ein, und der Verbraucher will ungern stapeln.

Der gemeinsame Nenner: Die Daten kommen allmählich an, während der Standardparser nur ein vollständiges Dokument akzeptiert. JSON.parse wirft bei Chunk 1 Unexpected end of JSON input, bei Chunk 65 denselben Fehler und liefert erst beim allerletzten Chunk ein Ergebnis. Warten ist nicht die einzige Option — aber man muss zuerst entscheiden, was das Parsen eines unvollendeten Dokuments überhaupt bedeutet.

Präfix-Parsing-Semantik: Ist jeder Chunk gültig?

Nimm ein 7847-Byte-Array von Bestellungen, schneide es in 120-Zeichen-Chunks, um Streaming-Ankunft zu simulieren (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), und führe auf jedem Präfix drei Parser aus:

Ansatz Erfolge über 66 Präfixe Kumulierte Zeit Semantik
JSON.parse 1 (nur der letzte Chunk) 2,1 ms alles oder nichts
partial-json (Allow.ALL) 66 (ab Chunk 1) 14,3 ms liefert immer „was bisher bekannt ist"
jsonrepair je Präfix neu ausgeführt 66 23,8 ms nach Klammerergänzung parsbar, aber rechnet jedes Mal von vorn

Zwei Schlussfolgerungen zählen. Erstens trägt ein JSON.parse-Fehler keine Information: Die gemeldete Position ist immer das Ende; man erfährt weder, wie viel fehlt, noch ob das Ankommende in sich stimmig ist. Zweitens funktioniert die vollständige Neu-Reparatur pro Präfix, lohnt aber nicht: Die mittlere Textlänge pro Aufruf wächst linear, die kumulierten Kosten steigen als O(n²). 23,8 ms wirken harmlos; bei Megabyte-Größe wird derselbe Faktor zu Sekunden verschwendeter CPU.

Beachte außerdem: „Pro Präfix parsbar" heißt nicht „vollständig". Die letzte Zahl eines ergänzten Präfixes kann vom nächsten Chunk fortgeschrieben werden, der letzte String kann mitten in einer Escape-Sequenz abgeschnitten sein — das ist die Wurzel jedes Vorschau-Stabilitätsproblems.

Drei Implementierungsstile und ihr Platz

Streaming-Bibliotheken teilen sich in drei Haltungen, und die falsche Haltung kostet mehr als die falsche Bibliothek:

Bibliothek Haltung Wann verwenden Wann vermeiden
jsonrepair (3.15.0) vollständige Reparatur + Transform-Stream die Eingabe wird ein vollständiges Dokument, verlustfreie Ausgabe nötig nur Vorschau gewünscht (Reparatur gibt Text aus, keine Datenobjekte)
partial-json (0.1.7) partielles Parsen, darf unfertige Enden verwerfen UI-Vorschau: jeder Präfix muss ein brauchbares Objekt liefern Persistenz (Vorschau kann Felder vermissen lassen und bei Zahlen wackeln)
jsonmend (0.1.3) echte inkrementelle Reparatur, offenes Konformitätskorpus Pipelines, die pro gefüttertem Chunk eine Version ausgeben, ohne zurückzuscannen fertiges Dokument (einfaches Voll-Parsing ist schneller)

Keine drei sind Konkurrenten. Der ./stream-Unterpfad von jsonrepair exportiert jsonrepairTransform, einen Standard-Transform-Stream: Chunks laufen links hinein, reparierter JSON-Text kommt rechts heraus, und die Konkatenation ist garantiert gleich dem Parsen des vollständigen Textes — das Versprechen decode(encode(x)) === x hält es. partial-json hält ein anderes Versprechen: Jeder Präfix liefert sofort ein Objekt, um den Preis, „das Ergebnis ändert sich nicht mehr" aufzugeben. jsonmend bindet einen dritten Weg an ein öffentliches Konformitätskorpus: echtes Inkrement, ausgerichtete Semantik, gemeinsame Regressionsbasis für unabhängige Implementierungen.

Die Allow-Maske: welche Felder dürfen in die Vorschau

Der Kern von partial-json ist nicht „wie kaputte Eingabe kann es parsen", sondern der Aufrufer erklärt, welche Unvollständigkeit er akzeptiert. Die Maske kombiniert Bits pro Typ (STR, NUM, ARR, OBJ, ...); fehlt ein Bit, bleiben die unfertigen Werte dieses Typs außerhalb der Vorschau:

import { parse, Allow } from 'partial-json';

parse('{"price": 12', Allow.ALL);
// → { price: 12 }        12 ist „bisher gelesen"
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 }    gleiches Feld, neuer Wert: die Vorschau wackelt
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {}                   ohne das NUM-Bit bleiben unfertige Zahlen verborgen

Das ist der ingenieurstechnisch wertvollste Befund des Benchmarks: Zahlen, die fortgeschrieben werden — Preise, Zähler — können in jedem angezeigten Frame wechseln, während Allow.ALL & ~Allow.NUM sie ruhig bis zur Fertigstellung wartet. Strings gelten analog: Ein String, mitten in einer Unicode-Escape-Sequenz abgeschnitten, wird von partial-json 0.1.7 sicher verworfen statt geraten. Vorschau-Stabilität ist kein Geschenk des Parsers; der Aufrufer zahlt sie mit der Maske.

Was Streaming-Reparatur kostet: Lookback-Puffer und quadratische Kopien

Eine Streaming-Pipeline ist keine for-Schleife um die volle API. Auf derselben 66-Chunk-Stichprobe brauchte die jsonrepairTransform-Pipeline 6,7 ms gesamt, während die vollständige Reparatur pro Präfix 23,8 ms kumulierte — die 3,5-fache Lücke steckt in der Implementierung: Der Streaming-Weg blickt nur im nötigen Fenster zurück und hängt die Ausgabe inkrementell an, statt vorausgehenden Text neu zu kopieren.

Die Portierung des jsonrepair-Streaming-Kerns nach ArkTS auf HarmonyOS dokumentiert drei konkrete Kosten: Der Upstream-Streaming-Pfad akkumuliert einen Lookback-Puffer, was kleine Dokumente paradoxerweise bis zum flush warten lässt — der Autor schrieb daher einen separaten IncrementalRepairer, der kurze Texte beim Empfang voransieht; der reguläre Upstream-Pfad kopiert die gesamte Ausgabe wiederholt (quadratisches Verhalten), im Port mit einem OutputBuilder beseitigt; und eine Grenzzeichen-Falle — nach dem Wechsel der Ende-Prüfung von text[i] === undefined zu charAt überlistet ''.includes(''), das immer true ist, die Zeichen-Mitgliedschaftstests, also muss das Lesen außerhalb der Grenzen zuerst durch eine Leere-String-Sperre geblockt werden. Diese Details erklären, warum Streaming-Reparatur einen eigenen Platz in der Format-Taxonomie verdient: Ihre technische Komplexität liegt auf einer anderen Stufe als die Einmalreparatur.

Eine bekannte Grenze verdient eine Notiz: jsonrepair-Issue #214 meldet, dass Streaming-Reparatur ein legales Präfix ablehnt, dem ein Komma vor einem mit Schrägstrich beginnenden Wert fehlt — im Stream sind „das nächste Zeichen ist noch nicht da" und „die Eingabe ist ungültig" lexikalisch schwer zu unterscheiden, und das Lookback-Fenster ist der Preis für diese Mehrdeutigkeit.

Umsetzung: Vorschau und Persistenz gehen getrennte Wege

Führe die Semantik in einer Pipeline mit einer einzigen Regel zusammen: teilweise parsen für Vorschauen, streng parsen für Persistenz.

import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';

// Pfad 1: verlustfreie Pipeline. Chunks rein, reparierter JSON-Text raus, strenge Prüfung am Ende
const tr = jsonrepairTransform();
tr.pipe(finalSink);                 // finalSink führt JSON.parse plus Geschäftsvalidierung aus
chunkStream.pipe(tr);

// Pfad 2: Vorschau-Pipeline. Ein Frame pro Präfix; unfertige Zahlen und Strings sind maskiert
function onChunk(buffer) {
  const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
  render(preview);                  // nur stabile Felder zeichnen
}

Die zwei Wege haben verschiedene Verträge und können sich nicht ersetzen: Vorschau-Frames dürfen Felder vermissen, Persistenz-Frames nicht; ein Persistenz-Frame muss das Stream-Ende abwarten und ein volles JSON.parse plus Geschäftsvalidierung bestehen, und ein Vorschau-Frame wird nie persistiert. Kommt die Eingabe von einem LLM, verlangt die Persistenz zusätzlich die Beurteilung der Kürzung am Stop-Grund — jener Ablauf „erst stop_reason ansehen, dann reparieren" ist in LLM-JSON-Kürzungsreparatur ausgeführt.

Wann man nicht streamt

Drei Vetobedingungen; trifft eine zu, parsiere einfach alles: kleine Dateien — unter etwa 22 MB beendet ein gewöhnliches JSON.parse die Arbeit meist in unter einer Sekunde, Streaming fügt nur Code-Komplexität hinzu; Einmal-Statistiken — für Aggregation ist jq --stream oder zeilenweise NDJSON einfacher, siehe das JSONL-Datei-Handbuch; das Downstream akzeptiert keine Teil-Daten — Summen sind der klassische Fall: ein falsch multiplizierter Zwischenwert einer Vorschau ist ein Geld-Bug, dann ist Streaming-Vorschau kaum mehr als ein Fortschrittsbalken wert.

Streaming löst „Warten ist unzumutbar", nicht „mehr Tempo". Bei gleichem Text verbraucht das vollständige Parsen immer weniger CPU-Gesamtzeit als jedes Streaming-Schema; gekauft werden die Zeit bis zum ersten nutzbaren Chunk, ein gleichbleibender Speicherpegel und die Fähigkeit, beim Empfang zu verarbeiten. Dieses Trade-off klar entscheiden, und die Bibliothekswahl hört auf zu wackeln.

FAQ

Kann ich ein Vorschau-Objekt direkt in die Datenbank schreiben?

Nein. Eine Vorschau ist ein Schnappschuss von „was bisher bekannt ist": Zahlen können vom nächsten Chunk fortgeschrieben werden, Strings abgeschnitten, Felder vorübergehend fehlen. Vor der Persistenz wartet man das Stream-Ende ab, führt ein strenges JSON.parse über den vollständigen Text aus und durchläuft die Geschäftsvalidierung. Vorschauen gehören allein zur UI-Schicht.

partial-json oder jsonrepair?

Entscheidend ist, ob Du Text oder Objekte willst. Für verlustfreien reparierten Text, den eine nachgelagerte Komponente erneut parst, nimm jsonrepair — seine Streaming-Ausgabe ist garantiert gleich dem Parsen des vollen Textes. Für ein Objekt pro Präfix, um eine UI-Vorschau zu treiben, nimm partial-json und stelle die Allow-Maske pro Feld ein.

Reduziert Streaming die Gesamtlaufzeit?

Nein. Bei der CPU-Gesamtzeit bleibt das vollständige Parsen immer am schnellsten; Streaming zahlt zusätzlich für Zustandspflege. Gekauft werden drei Dinge: die Zeit bis zum ersten nutzbaren Chunk, ein Speicherpegel, der nicht mit der Dokumentgröße wächst, und die Fähigkeit, beim Empfang weiterzuleiten, zu filtern oder anzuzeigen.

Array-Elemente kommen einzeln an und ich will sie einzeln verarbeiten?

Das ist ein anderer Weg: stream-jsons streamArray gibt {key, value} beim Schließen jedes Elements aus und erzeugt mit for await natürlichen Gegendruck — passend für Batch-Importe „parsen dann einfügen", eine andere Granularität als die hier beschriebene Vorschau auf Dokumentebene.

Quellen

Passende Tools

Verwandte Artikel

JSON-Reparatur-Leitfaden: Kaputte LLM-Ausgaben retten, ohne das Vertrauen zu verlieren

LLM-Ausgaben in Markdown-Zäunen, mit trailing commas und Python-Literalen übersteht kein strikter Parser — ebenso wenig wie manuell editierte Konfigurationen ohne Anführungszeichen. Dieser Leitfaden zieht die echte Grenze zwischen neun reparierbaren Fehlerklassen und vier unheilbaren, erklärt, warum Zustandsmaschinen Regex schlagen, und liefert eine produktionsreife Parse-Kette mit jsonrepair und json-repair.

Fortgeschritten~6 Min. LesezeitAktualisiert 2026-11-08

Das JSON eines LLM ist abgeschnitten: erst den Stoppgrund prüfen, dann über Reparatur reden

Das Modell liefert JSON, das mitten im Wert endet, und der Parser nennt nur eine Spaltennummer. Klammern schließen macht es wieder parsebar, aber jedes fehlende Feld verschwindet in den Daten. Der Artikel zieht die Grenze zwischen dem, was eine Reparatur bei Abschneiden ehrlich retten kann, und dem, was erneut angefragt werden muss: stop_reason, Token-Budget, Feldreihenfolge.

Praxis~5 Min. LesezeitAktualisiert 2026-11-14

JSONL in der Praxis: Öffnen, Konvertieren und Defekte Zeilen finden

Wer eine ganze .jsonl-Datei an JSON.parse oder json.load übergibt und einen Fehler erhält, hat fast immer die falsche Lesestrategie gewählt — nicht die Datei ist kaputt. Dieser Leitfaden zeigt die Standardmuster zum Prüfen und zeilenweisen Lesen, die Kommandos für die Umwandlung in und aus JSON-Arrays, eine Tabelle mit sechs Typen defekter Zeilen und die korrekte Art, NDJSON aus einer Streaming-HTTP-Antwort zu konsumieren.

Fortgeschritten~9 Min. LesezeitAktualisiert 2026-11-06