Analizar JSON antes de que termine de llegar: vista previa en streaming y reparación incremental
En resumen: Los LLM emiten JSON token a token y las API entregan respuestas grandes por fragmentos, pero JSON.parse se niega a trabajar hasta que llega el documento completo. Esta guía separa tres estilos de implementación — reparación completa, incremento real y análisis parcial — y muestra cómo una máscara Allow mantiene estable la vista previa, con mediciones de pipeline y código listo para producción.

JSON.parsepromete «no arranco hasta que llegue el documento completo», mientras que el streaming promete «te entrego los datos fragmento a fragmento». El conflicto no está en la velocidad sino en la semántica de completitud: un documento sin terminar todavía no tiene un resultado de análisis correcto.
El síntoma: tres escenarios que no pueden esperar el texto completo
El primer escenario son las aplicaciones LLM. El modelo emite JSON token a token; una salida estructurada de 8 KB puede tardar decenas de segundos en llegar mientras el usuario mira un panel vacío — aunque los primeros campos estaban disponibles desde el primer segundo. El segundo escenario son las pasarelas y proxies: el upstream empuja una respuesta de decenas de megabytes en fragmentos HTTP, y un proxy que quiere filtrar campos antes de reenviar multiplica su pico de memoria si lo bufferiza todo con res.json(). El tercer escenario son las colas de mensajes y las tuberías de logs: los registros NDJSON llegan uno tras otro y el consumidor prefiere no acumular lotes.
El punto en común es claro: los datos llegan gradualmente mientras el analizador estándar solo acepta un documento completo. JSON.parse lanza Unexpected end of JSON input en el fragmento 1, lanza el mismo error en el 65 y solo devuelve un resultado en el último. Esperar no es la única opción — pero primero hay que decidir qué significa «analizar» un documento sin terminar.
Semántica del análisis por prefijos: ¿es válido cada fragmento?
Toma un array de pedidos de 7847 bytes, córtalo en fragmentos de 120 caracteres para simular la llegada en streaming (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7) y ejecuta tres analizadores sobre cada prefijo:
| Enfoque | Éxitos sobre 66 prefijos | Tiempo acumulado | Semántica |
|---|---|---|---|
JSON.parse |
1 (solo el último fragmento) | 2,1 ms | todo o nada |
partial-json (Allow.ALL) |
66 (desde el fragmento 1) | 14,3 ms | devuelve siempre «lo conocido hasta ahora» |
jsonrepair reejecutado por prefijo |
66 | 23,8 ms | analizable tras completar llaves, recalculado desde cero cada vez |
Dos conclusiones importan. Primera: el fallo de JSON.parse no aporta información — la posición reportada es siempre el final, y no sabes ni cuánto falta ni si lo recibido es coherente. Segunda: reejecutar la reparación completa en cada prefijo funciona pero no compensa: la longitud media por llamada crece linealmente y el coste acumulado sube en O(n²). 23,8 ms parece inofensivo; a escala de megabytes, el mismo factor se convierte en segundos de CPU desperdiciada.
Observa además que «analizable por prefijos» no significa «datos completos». El último número de un prefijo completado puede continuarse con el siguiente fragmento, y la última cadena puede quedar cortada en medio de una secuencia de escape — esa es la raíz de todos los problemas de estabilidad de la vista previa.
Tres estilos de implementación y su lugar
Las bibliotecas de streaming se dividen en tres posturas, y equivocarse de postura duele más que equivocarse de biblioteca:
| Biblioteca | Postura | Cuándo usarla | Cuándo evitarla |
|---|---|---|---|
jsonrepair (3.15.0) |
reparación completa + stream Transform | la entrada será un documento completo y se necesita salida sin pérdidas | solo se quiere vista previa (la reparación emite texto, no objetos de datos) |
partial-json (0.1.7) |
análisis parcial, puede descartar finales sin terminar | vistas previas de UI: cada prefijo debe dar un objeto utilizable | persistencia (la vista previa puede omitir campos y oscilar en números) |
jsonmend (0.1.3) |
reparación realmente incremental, corpus de conformidad abierto | pipelines que emiten una versión por fragmento alimentado sin re-escanear | documento terminado (el análisis completo directo es más rápido) |
No son competidores. La subruta ./stream de jsonrepair exporta jsonrepairTransform, un stream Transform estándar: los fragmentos entran por la izquierda, sale JSON reparado por la derecha, y la concatenación está garantizada igual que analizar el texto completo de una vez — cumple la promesa decode(encode(x)) === x. partial-json cumple otra promesa: cada prefijo da un objeto de inmediato, al precio de renunciar a «el resultado no cambiará». jsonmend ata una tercera vía con un corpus de conformidad público: incremento real, semántica alineada y una base de regresión compartida entre implementaciones.
La máscara Allow: qué campos se atreven a aparecer en la vista previa
El núcleo de partial-json no es «cuán rota puede ser la entrada que analiza», sino que quien llama declare cuánta incompletitud acepta. La máscara combina bits por tipo (STR, NUM, ARR, OBJ, ...); quitar un bit deja fuera de la vista previa los valores sin terminar de ese tipo:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } 12 es «lo leído hasta ahora»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } mismo campo, nuevo valor: la vista previa oscila
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} sin el bit NUM, los números sin terminar permanecen ocultos
Es el hallazgo con más valor de ingeniería del benchmark: los números que se van a continuar — precios, contadores — pueden cambiar en cada fotograma que aparecen, mientras que Allow.ALL & ~Allow.NUM los mantiene en silencio hasta completarse. Con las cadenas igual: una cadena cortada en medio de un escape Unicode la descarta con seguridad partial-json 0.1.7 en lugar de adivinar. La estabilidad de la vista previa no es un regalo del analizador; quien llama la paga con la máscara.
Lo que cuesta la reparación en streaming: buffer de retrovisión y copias cuadráticas
Una pipeline de streaming no es un bucle for alrededor de la API completa. En la misma muestra de 66 fragmentos, la pipeline jsonrepairTransform tomó 6,7 ms en total mientras la reparación completa reejecutada por prefijo acumuló 23,8 ms — la brecha de 3,5× vive en la implementación: la vía en streaming solo mira atrás en la ventana necesaria y añade la salida incrementalmente en lugar de recopiar el texto previo.
La portada del núcleo de streaming de jsonrepair a ArkTS en HarmonyOS documenta tres costes concretos: la vía streaming del upstream acumula un buffer de retrovisión, lo que paradójicamente hace que los documentos pequeños esperen el flush — el autor escribió un IncrementalRepairer aparte para previsualizar textos cortos mientras llegan; la vía regular del upstream copia la salida entera de forma cuadrática, eliminado en la portada con un OutputBuilder; y una trampa de caracteres de frontera — al cambiar la comprobación de fin de text[i] === undefined a charAt, ''.includes(''), siempre verdadero, engaña a las comprobaciones de pertenencia de caracteres, así que la lectura fuera de límites debe bloquearse antes con una guarda de cadena vacía. Estos detalles explican por qué la reparación en streaming merece casilla propia: su complejidad de ingeniería está a otro nivel que la reparación de una sola vez.
Una frontera conocida merece nota: el issue #214 de jsonrepair reporta que la reparación en streaming rechaza un prefijo legal al que falta una coma antes de un valor prefijado con barra — en un stream, «el siguiente carácter aún no llegó» y «la entrada es inválida» son difíciles de distinguir léxicamente, y la ventana de retrovisión es el precio de esa ambigüedad.
Puesta en marcha: la vista previa y la persistencia siguen caminos distintos
Combina la semántica en una pipeline con una sola regla: análisis parcial para la vista previa, análisis estricto para la persistencia.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// Vía 1: pipeline sin pérdidas. Entran fragmentos, sale JSON reparado, comprobación estricta al final
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink ejecuta JSON.parse más la validación de negocio
chunkStream.pipe(tr);
// Vía 2: pipeline de vista previa. Un fotograma por prefijo; números y cadenas sin terminar quedan enmascarados
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // dibuja solo los campos estables
}
Las dos vías tienen contratos distintos y no se sustituyen: los fotogramas de vista previa pueden omitir campos, los de persistencia no; un fotograma de persistencia debe esperar el fin del stream y pasar un JSON.parse completo más la validación de negocio, y un fotograma de vista previa jamás se persiste. Si el upstream es un LLM, la persistencia exige además juzgar el truncamiento por el motivo de parada — ese flujo de «mirar stop_reason antes de reparar» está desarrollado en Reparación del JSON truncado del LLM.
Cuándo no hacer streaming
Tres condiciones de veto; si alguna aplica, analiza todo directamente: archivos pequeños — por debajo de unos 22 MB un JSON.parse normal suele acabar en menos de un segundo y el streaming solo añade complejidad de código; estadísticas de una sola vez — para agregación, jq --stream o NDJSON línea a línea es más sencillo, ver el manual de archivos JSONL; el consumidor aguas abajo no acepta datos parciales — los totales son el caso clásico: un valor intermedio de vista previa multiplicado por error es un bug monetario, y la vista previa en streaming vale entonces poco más que una barra de progreso.
El streaming resuelve «no se puede esperar», no «quiero más velocidad». Con el mismo texto, el análisis completo siempre gasta menos CPU total que cualquier esquema en streaming; lo que compras es el tiempo hasta el primer fragmento utilizable, un nivel de memoria constante y la capacidad de procesar mientras recibes. Decide ese equilibrio con claridad y la elección de biblioteca dejará de tambalear.
FAQ
¿Puedo persistir directamente un objeto de vista previa?
No. Una vista previa es una instantánea de «lo conocido hasta ahora»: los números pueden continuarse con el siguiente fragmento, las cadenas pueden estar cortadas y los campos pueden faltar temporalmente. Antes de persistir, espera el fin del stream, ejecuta un JSON.parse estricto sobre el texto completo y pásalo por la validación de negocio. La vista previa pertenece solo a la capa de UI.
¿partial-json o jsonrepair?
Depende de si quieres texto u objetos. Para texto reparado sin pérdidas que un componente aguas abajo analizará de nuevo, usa jsonrepair — su salida en streaming está garantizada igual que el análisis del texto completo. Para un objeto por cada prefijo que alimente una vista previa de UI, usa partial-json y configura la máscara Allow campo a campo.
¿El streaming reduce el tiempo total?
No. En tiempo de CPU total, el análisis completo siempre es el más rápido; el streaming paga además el mantenimiento de estado. Lo que compra son tres cosas: el tiempo hasta el primer fragmento utilizable, un nivel de memoria que no crece con el tamaño del documento y la capacidad de reenviar, filtrar o mostrar mientras recibe.
Los elementos de un array llegan uno a uno y quiero procesarlos uno a uno
Esa es otra vía: el streamArray de stream-json emite {key, value} cuando cierra cada elemento y, combinado con for await, produce contrapresión natural — apto para importaciones por lotes «analizar e insertar», una granularidad distinta de la vista previa a nivel de documento descrita aquí.