JSON Toolkit

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.

Intermedio~5 min di letturaPubblicato il 2026-11-16Aggiornato il 2026-11-16
Diagramma di analisi parziale e riparazione incrementale sui blocchi di un JSON in streaming

JSON.parse promette «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.

Riferimenti

Strumenti correlati

Articoli correlati

Guida alla riparazione JSON: recuperare gli output LLM rotti senza perdere fiducia

Gli output LLM avvolti in recinti markdown, con virgole finali e letterali Python, non sopravvivono a un parser rigoroso — nemmeno le config modificate a mano senza virgolette. Questa guida traccia il confine reale tra nove classi di errori che un riparatore corregge e quattro che non correggerà mai, spiega perché le macchine a stati battono le regex e fornisce una catena di parsing pronta per la produzione con jsonrepair e json-repair.

Intermedio~6 min di letturaAggiornato il 2026-11-08

Il JSON dell'LLM è troncato: prima guarda il motivo di arresto, poi parla di riparazione

Il JSON restituito dal modello manca della chiusura e il parser offre solo un numero di colonna: aggiungere le parentesi fa girare il codice, ma il buco finisce nascosto nei dati. Questo articolo traccia il confine tra ciò che si può riparare e ciò che richiede un retry negli scenari di troncamento: diagnosi dal motivo di arresto, dimensionamento dell'output su p99, ordinamento dei campi dello schema e divulgazione onesta del recupero parziale.

Pratico~5 min di letturaAggiornato il 2026-11-14

JSONL in pratica: aprire, convertire e diagnosticare le righe difettose

Passare un intero file .jsonl a JSON.parse e ricevere un errore quasi mai significa che il file è rotto — significa che la strategia di lettura è sbagliata. Questa guida copre i modi standard di ispezionare e leggere JSONL riga per riga, i comandi per convertire da e verso array JSON, una tabella di sei tipi di righe difettose e il modo corretto di consumare NDJSON da risposte HTTP in streaming.

Intermedio~9 min di letturaAggiornato il 2026-11-06