Analisar JSON antes de terminar de chegar: pré-visualização em streaming e reparação incremental
Resumo: Os LLMs emitem JSON token a token e as APIs entregam respostas grandes em fragmentos, mas o JSON.parse recusa-se a trabalhar até o documento completo chegar. Este guia separa três estilos de implementação — reparação completa, incremento real e análise parcial — e mostra como uma máscara Keep mantém a pré-visualização estável, com medições de pipeline e código pronto para produção.

O
JSON.parsepromete «só arranque quando o documento inteiro chegar», enquanto o streaming promete «entrego-te os dados fragmento a fragmento». O conflito não está na velocidade, mas na semântica de completude: um documento inacabado ainda não tem um resultado de análise correto.
O sintoma: três cenários que não podem esperar o texto completo
O primeiro cenário são as aplicações LLM. O modelo emite JSON token a token; uma saída estruturada de 8 KB pode levar dezenas de segundos a chegar enquanto o utilizador olha para um painel vazio — apesar de os primeiros campos estarem visíveis desde o primeiro segundo. O segundo cenário são gateways e proxies: o upstream empurra uma resposta de dezenas de megabytes em fragmentos HTTP, e um proxy que queira filtrar campos antes de reencaminhar multiplica o pico de memória se bufferizar tudo com res.json(). O terceiro cenário são as filas de mensagens e os pipelines de logs: os registos NDJSON chegam uns após os outros e o consumidor prefere não acumular lotes.
O ponto comum é claro: os dados chegam gradualmente enquanto o analisador padrão só aceita um documento completo. O JSON.parse lança Unexpected end of JSON input no fragmento 1, lança o mesmo erro no 65 e só devolve um resultado no último. Esperar não é a única opção — mas primeiro é preciso decidir o que significa «analisar» um documento inacabado.
Semântica da análise por prefixos: cada fragmento é válido?
Pega num array de encomendas de 7847 bytes, corta-o em fragmentos de 120 caracteres para simular a chegada em streaming (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7) e executa três analisadores sobre cada prefixo:
| Abordagem | Sucessos em 66 prefixos | Tempo acumulado | Semântica |
|---|---|---|---|
JSON.parse |
1 (só o último fragmento) | 2,1 ms | tudo ou nada |
partial-json (Allow.ALL) |
66 (desde o fragmento 1) | 14,3 ms | devolve sempre «o que é conhecido até agora» |
jsonrepair re-executado por prefixo |
66 | 23,8 ms | analisável após completar chavetas, recalculado do zero a cada vez |
Duas conclusões contam. Primeira: o falhanço do JSON.parse não traz informação nenhuma — a posição reportada é sempre o fim, e não se sabe nem quanto falta nem se o que chegou é coerente. Segunda: re-executar a reparação completa em cada prefixo funciona mas não compensa: o comprimento médio por chamada cresce linearmente e o custo acumulado sobe em O(n²). 23,8 ms parecem inofensivos; à escala de megabytes, o mesmo fator transforma-se em segundos de CPU desperdiçada.
Repara ainda que «analisável por prefixos» não significa «dados completos». O último número de um prefixo completado pode ser continuado pelo fragmento seguinte, e a última cadeia pode ficar cortada a meio de uma sequência de escape — essa é a raiz de todos os problemas de estabilidade da pré-visualização.
Três estilos de implementação e o lugar de cada um
As bibliotecas de streaming dividem-se em três posturas, e errar a postura custa mais do que errar a biblioteca:
| Biblioteca | Postura | Quando usar | Quando evitar |
|---|---|---|---|
jsonrepair (3.15.0) |
reparação completa + stream Transform | a entrada será um documento completo e é preciso saída sem perdas | só se quer pré-visualização (a reparação emite texto, não objetos de dados) |
partial-json (0.1.7) |
análise parcial, pode descartar finais inacabados | pré-visualizações de UI: cada prefixo deve dar um objeto utilizável | persistência (a pré-visualização pode omitir campos e oscilar nos números) |
jsonmend (0.1.3) |
reparação verdadeiramente incremental, corpus de conformidade aberto | pipelines que emitem uma versão por fragmento alimentado sem re-escanear | documento terminado (a análise completa direta é mais rápida) |
Não são concorrentes. O subcaminho ./stream do jsonrepair exporta jsonrepairTransform, um stream Transform padrão: os fragmentos entram à esquerda, sai JSON reparado à direita, e a concatenação é garantidamente igual à análise do texto completo de uma vez — cumpre a promessa decode(encode(x)) === x. O partial-json cumpre outra promessa: cada prefixo dá logo um objeto, ao preço de abandonar «o resultado não vai mudar». O jsonmend ata uma terceira via a um corpus de conformidade público: incremento real, semântica alinhada e uma base de regressão partilhada entre implementações.
A máscara Allow: que campos se atrevem a aparecer na pré-visualização
O núcleo do partial-json não é «analisar entradas por muito partidas que estejam», mas sim o chamador declarar quanta incompletude aceita. A máscara combina bits por tipo (STR, NUM, ARR, OBJ, ...); retirar um bit deixa de fora da pré-visualização os valores inacabados desse tipo:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } 12 é «o lido até agora»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } mesmo campo, novo valor: a pré-visualização oscila
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} sem o bit NUM, os números inacabados ficam escondidos
É a descoberta com mais valor de engenharia do teste: os números que vão ser continuados — preços, contadores — podem mudar em cada fotograma em que aparecem, enquanto Allow.ALL & ~Allow.NUM os mantém calmos até ficarem completos. Com as cadeias passa-se o mesmo: uma cadeia cortada a meio de um escape Unicode é descartada em segurança pelo partial-json 0.1.7 em vez de adivinhada. A estabilidade da pré-visualização não é um presente do analisador; quem chama paga-a com a máscara.
O que custa a reparação em streaming: buffer de retrovisão e cópias quadráticas
Uma pipeline de streaming não é um ciclo for à volta da API completa. Na mesma amostra de 66 fragmentos, a pipeline jsonrepairTransform demorou 6,7 ms no total enquanto a reparação completa re-executada por prefixo acumulou 23,8 ms — a diferença de 3,5× vive na implementação: a via em streaming só olha para trás na janela necessária e acrescenta a saída incrementalmente em vez de recopiar o texto anterior.
A portagem do núcleo de streaming do jsonrepair para ArkTS no HarmonyOS documenta três custos concretos: a via streaming do upstream acumula um buffer de retrovisão, o que paradoxalmente faz os documentos pequenos esperarem pelo flush — o autor escreveu à parte um IncrementalRepairer para pré-visualizar textos curtos enquanto chegam; a via regular do upstream copia a saída inteira de forma quadrática, eliminado na portagem com um OutputBuilder; e uma armadilha de caracteres de fronteira — ao mudar a verificação de fim de text[i] === undefined para charAt, o ''.includes(''), sempre verdadeiro, engana as verificações de pertença de caracteres, pelo que a leitura fora dos limites tem de ser bloqueada primeiro com uma guarda de cadeia vazia. Estes detalhes explicam porque é que a reparação em streaming merece um lugar próprio: a sua complexidade de engenharia está a outro nível da reparação pontual.
Um limite conhecido merece nota: o issue #214 do jsonrepair reporta que a reparação em streaming rejeita um prefixo legal a que falta uma vírgula antes de um valor prefixado por barra — num stream, «o próximo carácter ainda não chegou» e «a entrada é inválida» são difíceis de distinguir lexicalmente, e a janela de retrovisão é o preço dessa ambiguidade.
Implementação: a pré-visualização e a persistência seguem caminhos separados
Junta a semântica numa pipeline com uma única regra: análise parcial para a pré-visualização, análise estrita para a persistência.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// Via 1: pipeline sem perdas. Entram fragmentos, sai JSON reparado, verificação estrita no fim
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink executa JSON.parse mais a validação de negócio
chunkStream.pipe(tr);
// Via 2: pipeline de pré-visualização. Um fotograma por prefixo; números e cadeias inacabados ficam mascarados
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // desenha só os campos estáveis
}
As duas vias têm contratos diferentes e não se substituem: os fotogramas de pré-visualização podem omitir campos, os de persistência não; um fotograma de persistência tem de esperar pelo fim do stream e passar um JSON.parse completo mais a validação de negócio, e um fotograma de pré-visualização nunca é persistido. Se o upstream é um LLM, a persistência exige ainda julgar o truncamento pela razão de paragem — esse fluxo de «olhar o stop_reason antes de reparar» está desenvolvido em Reparação do JSON truncado do LLM.
Quando não fazer streaming
Três condições de veto; se alguma se aplica, analisa tudo simplesmente: ficheiros pequenos — abaixo de cerca de 22 MB um JSON.parse normal costuma acabar em menos de um segundo e o streaming só acrescenta complexidade de código; estatísticas de uma só vez — para agregação, o jq --stream ou NDJSON linha a linha é mais simples, ver o manual de ficheiros JSONL; o consumidor a jusante não aceita dados parciais — os totais são o caso clássico: um valor intermédio de pré-visualização multiplicado por engano é um bug monetário, e a pré-visualização em streaming vale então pouco mais que uma barra de progresso.
O streaming resolve «não dá para esperar», não «quero mais velocidade». Com o mesmo texto, a análise completa gasta sempre menos CPU total do que qualquer esquema em streaming; o que se compra é o tempo até ao primeiro fragmento utilizável, um nível de memória constante e a capacidade de processar enquanto recebe. Decide esse compromisso com clareza e a escolha da biblioteca deixa de oscilar.
FAQ
Posso persistir diretamente um objeto de pré-visualização?
Não. Uma pré-visualização é um retrato de «o que é conhecido até agora»: os números podem ser continuados pelo fragmento seguinte, as cadeias podem estar cortadas e os campos podem faltar temporariamente. Antes de persistir, espera pelo fim do stream, executa um JSON.parse estrito sobre o texto completo e passa pela validação de negócio. A pré-visualização pertence só à camada de UI.
partial-json ou jsonrepair?
Depende de queres texto ou objetos. Para texto reparado sem perdas que um componente a jusante voltará a analisar, usa jsonrepair — a sua saída em streaming é garantidamente igual à análise do texto completo. Para um objeto em cada prefixo que alimente uma pré-visualização de UI, usa partial-json e configura a máscara Allow campo a campo.
O streaming reduz o tempo total?
Não. Em tempo de CPU total, a análise completa é sempre a mais rápida; o streaming paga ainda a manutenção de estado. O que compra são três coisas: o tempo até ao primeiro fragmento utilizável, um nível de memória que não cresce com o tamanho do documento e a capacidade de reencaminhar, filtrar ou mostrar enquanto recebe.
Os elementos de um array chegam um a um e quero processá-los um a um
Esse é outro caminho: o streamArray do stream-json emite {key, value} quando cada elemento fecha e, combinado com for await, produz contrapressão natural — adequado para importações em lote «analisar e inserir», uma granularidade diferente da pré-visualização ao nível do documento descrita aqui.