Analizzare JSON prima che finisca di arrivare: anteprima in streaming e riparazione incrementale
In sintesi: Gli LLM emettono JSON token per token e le API consegnano risposte grandi a blocchi, ma JSON.parse si rifiuta di lavorare finché il documento completo non arriva. Questa guida distingue tre stili di implementazione — riparazione completa, incremento vero e analisi parziale — e mostra come una maschera Allow mantiene stabile l'anteprima, con misure di pipeline e codice pronto per la produzione.

JSON.parsepromette «parto solo quando arriva il documento completo», mentre lo streaming promette «ti consegno i dati blocco per blocco». Il conflito non riguarda la velocità ma la semantica della completezza: un documento non ancora finito non ha ancora un risultato di analisi corretto.
Il sintomo: tre scenari che non possono aspettare il testo completo
Il primo scenario sono le applicazioni LLM. Il modello emette JSON token per token; un output strutturato di 8 KB può impiegare decine di secondi ad arrivare mentre l'utente guarda un pannello vuoto — anche se i primi campi erano mostrabili già dal primo secondo. Il secondo scenario sono gateway e proxy: l'upstream spinge una risposta di decine di megabyte in blocchi HTTP, e un proxy che vuole filtrare campi prima di inoltrare moltiplica il proprio picco di memoria se bufferizza tutto con res.json(). Il terzo scenario sono le code di messaggi e le pipeline di log: i record NDJSON arrivano uno dopo l'altro e il consumatore preferisce non accumulare lotti.
Il punto comune è chiaro: i dati arrivano gradualmente mentre il parser standard accetta solo un documento completo. JSON.parse lancia Unexpected end of JSON input al blocco 1, lancia lo stesso errore al blocco 65 e restituisce un risultato solo all'ultimo. Aspettare non è l'unica opzione — ma bisogna prima decidere cosa significa «analizzare» un documento incompleto.
Semantica dell'analisi per prefissi: ogni blocco è valido?
Prendi un array di ordini da 7847 byte, taglialo in blocchi da 120 caratteri per simulare l'arrivo in streaming (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7) ed esegui tre parser su ogni prefisso:
| Approccio | Successi su 66 prefissi | Tempo cumulato | Semantica |
|---|---|---|---|
JSON.parse |
1 (solo l'ultimo blocco) | 2,1 ms | tutto o nulla |
partial-json (Allow.ALL) |
66 (dal blocco 1) | 14,3 ms | restituisce sempre «ciò che è noto finora» |
jsonrepair rieseguito per ogni prefisso |
66 | 23,8 ms | analizzabile dopo il completamento delle graffe, ricalcolato da zero ogni volta |
Contano due conclusioni. Prima: il fallimento di JSON.parse non porta alcuna informazione — la posizione riportata è sempre la fine, e non si sa né quanto manchi né se la parte ricevuta sia coerente. Seconda: rieseguire la riparazione completa su ogni prefisso funziona ma non conviene: la lunghezza media per chiamata cresce linearmente e il costo cumulato sale come O(n²). 23,8 ms sembrano innocui; alla scala dei megabyte lo stesso fattore diventa secondi di CPU sprecati.
Nota inoltre che «analizzabile per prefisso» non significa «dati completi». L'ultimo numero di un prefisso completato può essere prolungato dal blocco successivo, e l'ultima stringa può risultare tagliata in mezzo a una sequenza di escape — quella è la radice di tutti i problemi di stabilità dell'anteprima.
Tre stili di implementazione e il loro posto
Le librerie di streaming si dividono in tre posture, e sbagliare postura costa più che sbagliare libreria:
| Libreria | Postura | Quando usala | Quando evitarla |
|---|---|---|---|
jsonrepair (3.15.0) |
riparazione completa + stream Transform | l'input diventerà un documento completo e serve output senza perdite | si vuole solo un'anteprima (la riparazione emette testo, non oggetti dati) |
partial-json (0.1.7) |
analisi parziale, può scartare le code incomplete | anteprime UI: ogni prefisso deve dare un oggetto utilizzabile | persistenza (l'anteprima può mancare di campi e vacillare sui numeri) |
jsonmend (0.1.3) |
riparazione realmente incrementale, corpus di conformità aperto | pipeline che emettono una versione per blocco fornito senza ri-scansione | documento terminato (l'analisi completa diretta è più veloce) |
Non sono concorrenti. Il sottopercorso ./stream di jsonrepair esporta jsonrepairTransform, uno stream Transform standard: i blocchi entrano a sinistra, esce JSON riparato a destra, e la concatenazione è garantita uguale all'analisi del testo completo in una volta — mantiene la promessa decode(encode(x)) === x. partial-json mantiene un'altra promessa: ogni prefisso dà subito un oggetto, al prezzo di rinunciare a «il risultato non cambierà». jsonmend vincola una terza via con un corpus di conformità pubblico: incremento vero, semantica allineata e una base di regressione condivisa tra implementazioni.
La maschera Allow: quali campi osano apparire nell'anteprima
Il nucleo di partial-json non è «parsare input per quanto rotti siano», ma il chiamante dichiara quanta incompiutezza accetta. La maschera combina bit per tipo (STR, NUM, ARR, OBJ, ...); togliere un bit esclude dall'anteprima i valori incompleti di quel tipo:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } 12 è «letto fin qui»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } stesso campo, nuovo valore: l'anteprima vacilla
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} senza il bit NUM, i numeri incompleti restano nascosti
È il reperto con più valore ingegneristico del test: i numeri destinati a essere prolungati — prezzi, contatori — possono cambiare in ogni fotogramma in cui compaiono, mentre Allow.ALL & ~Allow.NUM li tiene in silenzio fino al completamento. Per le stringhe vale lo stesso: una stringa tagliata in mezzo a un escape Unicode viene scartata in sicurezza da partial-json 0.1.7 invece che indovinata. La stabilità dell'anteprima non è un regalo del parser; chi chiama la paga con la maschera.
Quanto costa la riparazione in streaming: buffer di retrovisione e copie quadratiche
Una pipeline in streaming non è un ciclo for attorno all'API completa. Sullo stesso campione di 66 blocchi, la pipeline jsonrepairTransform ha richiesto 6,7 ms totali mentre la riparazione completa rieseguita per prefisso ha accumulato 23,8 ms — il divario di 3,5× vive nell'implementazione: la via in streaming guarda indietro solo nella finestra necessaria e aggiunge l'output in modo incrementale invece di ricopiare il testo precedente.
La portabilità del nucleo di streaming di jsonrepair su ArkTS in HarmonyOS documenta tre costi concreti: la via streaming upstream accumula un buffer di retrovisione, il che paradossalmente fa aspettare i documenti piccoli fino al flush — l'autore ha scritto a parte un IncrementalRepairer per prevedere i testi brevi durante la ricezione; la via regolare upstream ricopia l'intero output in modo quadratico, eliminato nella portabilità con un OutputBuilder; e una trappola dei caratteri di confine — dopo aver sostituito il controllo di fine text[i] === undefined con charAt, ''.includes(''), sempre vero, inganna i controlli di appartenenza dei caratteri, quindi la lettura fuori limite va prima bloccata con una guardia di stringa vuota. Questi dettagli spiegano perché la riparazione in streaming merita uno slot proprio: la sua complessità ingegneristica è su un altro livello rispetto alla riparazione puntuale.
Un confine noto merita nota: l'issue #214 di jsonrepair segnala che la riparazione in streaming rifiuta un prefisso legale a cui manca una virgola prima di un valore prefissato da barra — in uno stream, «il carattere successivo non è ancora arrivato» e «l'input è invalido» sono difficili da distinguere lessicalmente, e la finestra di retrovisione è il prezzo pagato per quell'ambiguità.
Realizzazione: anteprima e persistenza seguono strade separate
Riunisci la semantica in una pipeline con una sola regola: analisi parziale per l'anteprima, analisi rigorosa per la persistenza.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// Via 1: pipeline senza perdite. Entrano blocchi, esce JSON riparato, controllo rigoroso alla fine
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink esegue JSON.parse più la validazione di business
chunkStream.pipe(tr);
// Via 2: pipeline di anteprima. Un fotogramma per prefisso; numeri e stringhe incompleti restano mascherati
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // disegna solo i campi stabili
}
Le due vie hanno contratti diversi e non si sostituiscono: i fotogrammi di anteprima possono mancare di campi, quelli di persistenza no; un fotogramma di persistenza deve attendere la fine dello stream e passare un JSON.parse completo più la validazione di business, e un fotogramma di anteprima non viene mai persistito. Se l'upstream è un LLM, la persistenza esige anche di giudicare il troncamento dal motivo di arresto — quel flusso «guardare stop_reason prima di riparare» è sviluppato in Riparazione del JSON troncato dell'LLM.
Quando non fare streaming
Tre condizioni di veto; se ne vale una, analizza tutto semplicemente: file piccoli — sotto i 22 MB circa un normale JSON.parse finisce di solito in meno di un secondo e lo streaming aggiunge solo complessità di codice; statistiche una tantum — per l'aggregazione, jq --stream o NDJSON riga per riga è più semplice, vedi il manuale dei file JSONL; il consumatore a valle non accetta dati parziali — i totali sono il caso classico: un valore intermedio dell'anteprima moltiplicato per errore è un bug monetario, e l'anteprima in streaming vale allora poco più di una barra di avanzamento.
Lo streaming risolve «non si può aspettare», non «voglio più velocità». A parità di testo, l'analisi completa spende sempre meno CPU totale di qualsiasi schema in streaming; ciò che compri è il tempo fino al primo blocco utilizzabile, un livello di memoria costante e la capacità di elaborare mentre ricevi. Decidi quel compromesso con chiarezza e la scelta della libreria smette di vacillare.
FAQ
Posso persistere direttamente un oggetto di anteprima?
No. Un'anteprima è un istantanea di «ciò che è noto finora»: i numeri possono essere prolungati dal blocco successivo, le stringhe tagliate, i campi temporaneamente assenti. Prima di persistere, attendi la fine dello stream, esegui un JSON.parse rigoroso sul testo completo e passa la validazione di business. L'anteprima appartiene solo al livello UI.
partial-json o jsonrepair?
Dipende se vuoi testo o oggetti. Per testo riparato senza perdite che un componente a valle analizzerà di nuovo, usa jsonrepair — il suo output in streaming è garantito uguale all'analisi del testo completo. Per un oggetto a ogni prefisso che alimenti un'anteprima UI, usa partial-json e configura la maschera Allow campo per campo.
Lo streaming riduce il tempo totale?
No. In tempo CPU totale, l'analisi completa resta sempre la più rapida; lo streaming paga anche la manutenzione dello stato. Ciò che compra sono tre cose: il tempo fino al primo blocco utilizzabile, un livello di memoria che non cresce con la dimensione del documento e la capacità di inoltrare, filtrare o mostrare mentre riceve.
Gli elementi di un array arrivano uno a uno e voglio elaborarli uno a uno
Quella è un'altra via: lo streamArray di stream-json emette {key, value} quando ogni elemento si chiude e, combinato con for await, produce contro-pressione naturale — adatto agli import in batch «analizza poi inserisci», una granularità diversa dall'anteprima a livello di documento descritta qui.