JSON Toolkit

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.

Intermédio~5 min de leituraPublicado em 2026-11-16Atualizado em 2026-11-16
Diagrama de análise parcial e reparação incremental sobre os fragmentos de um JSON em streaming

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

Referências

Ferramentas relacionadas

Artigos relacionados

Guia de Reparo de JSON: resgatando saídas quebradas de LLM sem perder a confiança

Saídas de LLM embrulhadas em cercas de markdown, com vírgulas finais e literais Python, não sobrevivem a um parser estrito — o mesmo vale para configs editadas à mão sem aspas. Este guia traça a fronteira real entre nove classes de erros que um reparador corrige e quatro que ninguém corrige, explica por que máquinas de estados vencem regex e entrega uma cadeia de parse pronta para produção com jsonrepair e json-repair.

Intermediário~6 min de leituraAtualizado em 2026-11-08

O JSON do LLM veio truncado: olhe o motivo de parada antes de falar em reparo

O modelo devolve um JSON que termina no meio do valor e o parser só informa uma coluna. Fechar as chaves faz voltar a analisar, mas cada campo faltante fica escondido nos dados. O artigo traça a fronteira entre o que um reparo de truncamento pode recuperar com honestidade e o que precisa ser reenviado: gate por stop_reason, dimensionamento do limite e ordem dos campos do schema.

Prático~5 min de leituraAtualizado em 2026-11-14

JSONL na prática: abrir, converter e depurar linhas defeituosas

Entregar um arquivo .jsonl inteiro ao JSON.parse e receber um erro quase nunca significa que o arquivo está corrompido — significa que a estratégia de leitura está errada. Este guia cobre as formas padrão de inspecionar e ler JSONL linha por linha, os comandos para converter de e para arrays JSON, uma tabela com seis tipos de linhas defeituosas e a maneira correta de consumir NDJSON de respostas HTTP em streaming.

Intermediário~9 min de leituraAtualizado em 2026-11-06