Parsowanie JSON-a, który jeszcze nie dotarł w całości: podgląd strumieniowy i naprawa przyrostowa
Podsumowanie: LLM-y emitują JSON token po tokenie, a API zwracają duże odpowiedzi fragmentami, ale JSON.parse odmawia pracy do czasu dotarcia całego dokumentu. Ten artykuł rozdziela trzy style implementacji — pełna naprawa, prawdziwy przyrost i parsowanie częściowe — pokazuje, jak maska Allow utrzymuje stabilny podgląd, i dodaje pomiary pipeline oraz kod gotowy na produkcję.

JSON.parseobiecuje „zacznę, gdy dotrze cały dokument“, a strumieniowanie obiecuje „oddaję dane kawałek po kawałku“. Konflikt nie leży w szybkości, lecz w semantyce zupełności: niedokończony dokument nie ma jeszcze żadnego „poprawnego wyniku parsowania“.
Objaw: trzy scenariusze, które nie mogą czekać na cały tekst
Pierwszy scenariusz to aplikacje z LLM. Model wysyła JSON token po tokenie; strukturalne wyjście o rozmiarze 8 KB może spóźnić się o dziesiątki sekund, podczas gdy użytkownik patrzy na pusty panel — mimo że pierwsze pola były dostępne już w pierwszej sekundzie. Drugi scenariusz to bramy i proxy: upstream wypycha odpowiedź rzędu dziesiątek megabajtów fragmentami HTTP, a proxy, które chce filtrować pola przed przekazaniem, mnoży swój pik pamięci przy pełnym buforowaniu przez res.json(). Trzeci scenariusz to kolejki komunikatów i pipeline'y logów: rekordy NDJSON przychodzą jeden po drugim, a konsument nie chce gromadzić paczek.
Wspólny mianownik jest jasny: dane przychodzą stopniowo, a standardowy parser przyjmuje tylko kompletny dokument. JSON.parse rzuca Unexpected end of JSON input przy pierwszym kawałku, rzuca ten sam błąd przy sześćdziesiątym piątym i wynik zwraca dopiero przy ostatnim. Czekanie nie jest jedyną opcją — ale najpierw trzeba określić, co znaczy „sparsować“ niedokończony dokument.
Semantyka parsowania po prefiksach: czy każdy fragment jest poprawny?
Weź tablicę zamówień o 7847 bajtach, potnij ją na fragmenty po 120 znaków, aby symulować strumieniowe dostarczanie (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), i przepuść każdy prefiks przez trzy parsery:
| Podejście | Sukcesy na 66 prefiksach | Czas łącznie | Semantyka |
|---|---|---|---|
JSON.parse |
1 (tylko ostatni fragment) | 2,1 ms | wszystko albo nic |
partial-json (Allow.ALL) |
66 (od pierwszego fragmentu) | 14,3 ms | zawsze zwraca „dotychczas znane“ |
jsonrepair uruchamiany od zera na każdym prefiksie |
66 | 23,8 ms | parsowalne po uzupełnieniu nawiasów, ale liczone od nowa za każdym razem |
Dwa kluczowe wnioski. Pierwszy: porażka JSON.parse nie niesie żadnej informacji — zgłaszana pozycja to zawsze koniec, więc nie wiesz ani ile jeszcze brakuje, ani czy odebrana część jest sama w sobie spójna. Drugi: pełna naprawa uruchamiana na każdym prefiksie działa, ale się nie opłaca: średnia długość tekstu na wywołanie rośnie liniowo, a koszty skumulowane rosną kwadratowo, O(n²). 23,8 ms wygląda niewinnie; przy tekstach rzędu megabajtów ten sam współczynnik zamienia się w marnowane sekundy CPU.
I uwaga: „parsowalny po prefiksach“ nie znaczy „dane kompletne“. Ostatnia liczba uzupełnionego prefiksu może zostać dokończona przez kolejny fragment, a ostatni łańcuch może zostać ucięty w środku sekwencji ucieczki — właśnie stąd bierze się cała niestabilność podglądu strumieniowego.
Trzy style implementacji i ich miejsce
Biblioteki strumieniowe dzielą się na trzy postawy, a źle wybrana postawa szkodzi bardziej niż źle wybrana biblioteka:
| Biblioteka | Postawa | Pasuje | Nie pasuje |
|---|---|---|---|
jsonrepair (3.15.0) |
pełna naprawa + Transform stream | dostajesz „dokument, który kiedyś będzie kompletny“ i chcesz wyniku bezstratnego | sam podgląd (wynikiem jest cały naprawiony tekst, nie obiekt danych) |
partial-json (0.1.7) |
parsowanie częściowe, pozwala porzucić niedokończony ogon | podgląd w UI: każdy prefiks ma od razu użyteczny obiekt | zapis do bazy (podgląd może nie mieć pól, liczby są niestabilne) |
jsonmend (0.1.3) |
prawdziwy przyrost, publiczny korpus spójności | pipeline „przyszła paczka — wyszła wersja“ bez przegrywania przeszłości | już zakończony dokument (pełne parsowanie jest szybsze) |
To nie są konkurenci. jsonrepair przez podścieżkę ./stream eksportuje jsonrepairTransform, standardowy Transform stream: fragmenty wchodzą z lewej, z prawej wychodzą naprawione bloki tekstu JSON, a jest gwarantowane, że ich złożenie równa się parsowaniu całego tekstu za jednym razem — równość decode(encode(x)) === x jest utrzymana. partial-json trzyma inną linię: każdy prefiks od razu wydaje obiekt, w zamian za rezygnację z obietnicy „wynik już się nie zmieni“. jsonmend ogranicza trzecią linię publicznym korpusem spójności: prawdziwy przyrost, semantycznie wyrównywalny, obie implementacje mają ten sam fundament regresyjny.
Maska Allow: które pola wolno pokazać w podglądzie
Rdzeniem partial-json nie jest „umiem sparsować dowolnie zepsute wejście“, lecz deklaracja samego wywołującego, jaką niezupełność jest gotów znieść. Maska składa się bitowo według typów JSON (STR, NUM, ARR, OBJ…); usuniesz-li typ, niedokończone wartości tego typu nie trafiają do podglądu:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } liczba 12 jest „dotąd odczytana“
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } to samo pole się zmieniło: podgląd niestabilny
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} bez bitu NUM niedokończona liczba się nie wyświetli
To najbardziej inżyniersko cenne spostrzeżenie z pomiarów: liczby jak cena czy licznik, które kolejny fragment może dokończyć, zmieniają się na UI z każdą klatką; Allow.ALL & ~Allow.NUM każe im po cichu poczekać, aż będą gotowe. To samo dotyczy łańcuchów — łańcuch ucięty w środku sekwencji Unicode escape partial-json 0.1.7 bezpiecznie porzuca, zamiast zgadywać. Stabilność podglądu nie jest darem od parsera; kupuje się ją maską.
Koszt implementacji strumieniowej naprawy: bufor wsteczny i kopiowanie kwadratowe
Strumieniowa pipeline to nie „pełne API opakowane w pętlę for“. Na tym samym próbku 66 fragmentów pipeline z jsonrepairTransform zajęła łącznie 6,7 ms, podczas gdy pełna naprawa na każdym prefiksie 23,8 ms — różnica 3,5× bierze się z implementacji: implementacja strumieniowa patrzy wstecz tylko w koniecznym oknie, wynik dopisuje buforem przyrostowym i nie kopiuje poprzedniego tekstu w kółko.
Portowanie strumieniowego rdzenia jsonrepair na HarmonyOS ArkTS (adaptacja bibliotek openHarmony) ujawniło trzy konkretne koszty: upstreamowa ścieżka streaming wymaga „bufora wstecznego“, więc przy małych dokumentach wynik czeka na flush — autor napisał więc osobny IncrementalRepairer dla krótkich tekstów; upstreamowa ścieżka regular kopiuje wyjście w całości ponownie, co jest kwadratowe, i przy portowaniu zlikwidował to OutputBuilder; i jest jeszcze pułapka znaku granicznego — warunek text[i] === undefined jako test „doczytałem do końca“ przeniesiony na charAt oszukuje, bo ''.includes('') jest zawsze true, więc przekroczenie granicy trzeba z góry zasłonić pustym łańcuchem. Te szczegóły wyjaśniają, dlaczego „strumieniowa naprawa“ zasługuje na własną kategorię: jej inżynierska złożoność jest rzędu innego niż naprawa jednorazowa.
Warto odnotować też znaną granicę: issue #214 w jsonrepair zgłasza, że strumieniowa naprawa odrzuca poprawny prefiks z brakującym przecinkiem przed wartością ze slashem — w trybie strumieniowym leksykalnie trudno odróżnić „następny znak jeszcze nie dotarł“ od „wejście jest niepoprawne“; okno wsteczne jest ceną za tę niejednoznaczność.
Jak to złożyć: podgląd i persystencja idą osobno
Złóż poprzednią semantykę w jedną pipeline; zasada mieści się w jednym zdaniu: podgląd robi parsowanie częściowe, zapis robi parsowanie ścisłe.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// Linia 1: pipeline bezstratna. Wejście: fragmenty, wyjście: naprawiony tekst JSON, na końcu ścisła walidacja
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink potem zrobi JSON.parse + walidację biznesową
chunkStream.pipe(tr);
// Linia 2: pipeline podglądu. Każdy prefiks daje klatkę UI; niedokończone liczby i łańcuchy zatrzyma maska
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // rysuje tylko stabilne pola; szybkie pola niech poczekają
}
Kontrakty obu linii są różne i nie zastępują się nawzajem: klatka podglądu może nie mieć pola, klatka zapisu nie może; klatka zapisu musi poczekać na koniec strumienia i przejść pełne JSON.parse z walidacją biznesową, a klatka podglądu nigdzie się nie zapisuje. Jeśli upstream to wyjście LLM, przed zapisem trzeba według stop_reason ocenić, czy nie doszło do ucięcia — ten tok „najpierw stop_reason, dopiero potem naprawa“ rozbiera artykuł o naprawie uciętego JSON-a z LLM, tu go nie powtarzamy.
Kiedy odstąpić od strumieniowania
Trzy warunki odrzucenia; wystarczy spełnić jeden i uczciwie użyć pełnego parsowania: mały plik — zwykły JSON.parse do ~22 MB czyta jednym ciągiem zwykle poniżej sekundy, strumieniowanie tylko dokłada kod; tylko jednorazowa statystyka — agregacje załatwi jq --stream albo wierszowy NDJSON wygodniej, zobacz praktyczny przewodnik JSONL; odbiorca nie przyjmuje danych częściowych — na przykład suma kwot, gdzie jeden źle przemnożony wynik pośredni z podglądu oznacza stratę pieniędzy; tu podgląd strumieniowy ma wartość tylko jako pasek postępu.
Strumieniowe parsowanie rozwiązuje ciągle „nie da się czekać“, a nie „będzie szybciej“. Przy tym samym wolumenie tekstu całkowite CPU pełnego parsowania jest zawsze mniejsze niż dowolnej wariantu strumieniowego; wymieniasz czas do pierwszego użytecznego bajtu i stały poziom pamięci. Kto to uświadomi sobie, nie będzie huśtał się przy wyborze technologii.
Częste pytania
Czy obiekt podglądu mogę od razu zapisać do bazy?
Nie możesz. Podgląd to migawka „dotychczas znanego“: liczba może zostać dokończona kolejnym fragmentem, łańcuch może być ucięty, pola mogą chwilowo brakować. Przed zapisem musisz poczekać na koniec strumienia, puścić pełne ścisłe JSON.parse, a potem walidację biznesową. Podgląd należy tylko do warstwy UI.
partial-json czy jsonrepair?
Zależy od tego, czy chcesz tekst, czy obiekt. Bezstratny naprawiony tekst (przekażesz dalej do parsowania) da jsonrepair — jego strumieniowe wyjście gwarantuje zgodność z parsowaniem całości; obiekt dla każdego prefiksu od razu do podglądu UI da partial-json, z maską Allow ustawioną według tego, ile niestabilności uniesiesz.
Czy parsowanie strumieniowe skraca całkowity czas?
Nie. Całkowite CPU przy pełnym parsowaniu jest zawsze najmniejsze, a wariant strumieniowy dokłada koszt zarządzania stanem. Wymieniasz trzy rzeczy: czas do pierwszego fragmentu, pamięć, która nie rośnie z długością całości, i umiejętność przetwarzania w locie (przekazywanie, filtrowanie, wyświetlanie).
A gdyby elementy tablicy przychodziły po jednym i chciałbym je przetwarzać po kolei?
To inna ścieżka: stream-json ze streamArray rzuca {key, value} w momencie zamknięcia elementu i z for await naturalnie tworzy backpressure — pasuje do importu masowego typu „sparsować i zapisać“, podczas gdy ten artykuł zajmuje się podglądem na poziomie całego dokumentu.