JSON Toolkit

Parsing JSON Before It Finishes Arriving: Streaming Preview and Incremental Repair

Bottom line: LLMs emit JSON token by token and APIs deliver big responses in chunks, but JSON.parse refuses to run until the whole document arrives. This guide separates three implementation styles — full repair, true incremental repair and partial parsing — and shows how an Allow mask keeps previews stable, backed by measured pipeline numbers and production-ready code.

Intermediate~5 min readPublished 2026-11-16Updated 2026-11-16
Diagram of partial parsing and incremental repair over chunks of a streaming JSON payload

JSON.parse promises "I will run once the whole document is here", while streaming promises "I will hand you data one chunk at a time". The conflict is not about speed — it is about completeness semantics: a document that is not finished writing does not have a correct parse result yet.

The symptom: three scenarios that cannot wait for the full text

The first scenario is LLM applications. A model emits JSON one token at a time; an 8 KB structured output can take tens of seconds to arrive while the user stares at an empty panel — even though the first fields were available after second one. The second scenario is gateways and proxies: an upstream pushes a response of dozens of megabytes as HTTP chunks, and a proxy that wants to filter fields before forwarding will multiply its memory peak if it buffers everything through res.json(). The third scenario is message queues and log pipelines: one NDJSON record lands after another, and the consumer would rather not batch.

What the scenarios share is that data arrives gradually while the standard parser only accepts a complete document. JSON.parse throws Unexpected end of JSON input at chunk 1, throws the same error at chunk 65, and only returns at the very last chunk. Waiting is not the only option — but you must first decide what a parse of an unfinished document even means.

Prefix parsing semantics: is each chunk valid?

Take a 7847-byte array of orders, cut it into 120-character chunks to simulate streaming arrival (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), and run three parsers on every prefix:

Parsing approach Successes across 66 prefixes Cumulative time Semantics
JSON.parse 1 (only the last chunk) 2.1 ms all or nothing
partial-json (Allow.ALL) 66 (from chunk 1) 14.3 ms always returns "what is known so far"
jsonrepair re-run on every prefix 66 23.8 ms parseable after bracket completion, recomputed from scratch each time

Two conclusions matter. First, a JSON.parse failure carries no information: the reported position is always the end, so you learn neither how much is missing nor whether what arrived is self-consistent. Second, re-running the full repair on every prefix works but does not scale: the average text length per call grows linearly, so the cumulative cost rises as O(n²). 23.8 ms looks harmless; at megabyte scale the same factor turns into seconds of wasted CPU.

Also note that "parseable per prefix" is not "complete". The last number of a completed prefix may be continued by the next chunk, and the last string may be cut in the middle of an escape sequence — that is the root of every preview-stability problem in this space.

Three implementation styles and where each belongs

Streaming libraries split into three postures, and picking the wrong posture hurts more than picking the wrong library:

Library Posture Use when Avoid when
jsonrepair (3.15.0) full repair + Transform stream the input will become a complete document and you need lossless output you only want a preview (repair emits text, not data objects)
partial-json (0.1.7) partial parsing, may drop unfinished tails UI previews: every prefix must yield a usable object persistence (previews can miss fields and wobble on numbers)
jsonmend (0.1.3) true incremental repair, open conformance corpus pipelines that emit a version per fed chunk without rescanning a finished document (plain full parsing is faster)

These are not competitors. The ./stream subpath of jsonrepair exports jsonrepairTransform, a standard Transform stream: chunks go in on the left, repaired JSON text comes out on the right, and the concatenation is guaranteed to equal parsing the full text in one go — it keeps the decode(encode(x)) === x promise. partial-json keeps a different promise: every prefix immediately yields an object, at the cost of giving up "the result will not change". jsonmend constrains a third path with an open conformance corpus: true incrementality with aligned semantics, so independent implementations have a shared regression baseline.

The Allow mask: which fields dare to show up in a preview

The core of partial-json is not "how broken an input can it parse" but the caller declaring how much incompleteness it accepts. The mask combines per-type bits (STR, NUM, ARR, OBJ, ...); dropping a bit removes that type's unfinished value from the preview:

import { parse, Allow } from 'partial-json';

parse('{"price": 12', Allow.ALL);
// → { price: 12 }        12 is "what has been read so far"
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 }    same field, new value: the preview wobbles
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {}                   drop the NUM bit and unfinished numbers stay hidden

This is the most engineering-valuable finding of the benchmark: numbers that will be continued — prices, counters — can change on every frame they appear, while Allow.ALL & ~Allow.NUM keeps them quiet until they are finished. Strings work the same way: a string truncated inside a Unicode escape is safely dropped by partial-json 0.1.7 rather than guessed at. Preview stability is not a gift from the parser; the caller pays for it with the mask.

What streaming repair costs to implement: lookback buffers and quadratic copies

A streaming pipeline is not a for-loop around the full API. On the same 66-chunk sample, the jsonrepairTransform pipeline took 6.7 ms in total while re-running full repair per prefix accumulated 23.8 ms — the 3.5× gap lives in the implementation: the streaming path only looks back inside a necessary window and appends output incrementally instead of re-copying preceding text.

A port of the jsonrepair streaming core to ArkTS on HarmonyOS documents three concrete costs: the upstream streaming path accumulates a lookback buffer, which paradoxically makes small documents wait for a flush, so the author wrote a separate IncrementalRepairer for short texts that previews while receiving; the upstream regular path re-copies the whole output repeatedly (quadratic behavior), fixed in the port with an OutputBuilder; and a boundary-character trap — after switching the end-of-input check from text[i] === undefined to charAt, ''.includes('') being always true fools character-membership tests, so out-of-bounds reads must be blocked by an empty-string guard first. These details explain why streaming repair earns its own slot in a formats taxonomy: its engineering complexity is on a different level from one-shot repair.

One known boundary deserves a note: jsonrepair issue #214 reports that streaming repair rejects a legal prefix missing a comma before a slash-prefixed value — in a stream, "the next character has not arrived yet" and "the input is invalid" are lexically hard to tell apart, and the lookback window is the price paid for that ambiguity.

Putting it together: preview and persistence take separate paths

Combine the semantics into one pipeline with a single rule: parse partially for previews, parse strictly for persistence.

import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';

// Path one: lossless pipeline. Chunks in, repaired JSON text out, strict check at the end
const tr = jsonrepairTransform();
tr.pipe(finalSink);                 // finalSink runs JSON.parse plus business validation
chunkStream.pipe(tr);

// Path two: preview pipeline. One frame per prefix; unfinished numbers and strings are masked
function onChunk(buffer) {
  const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
  render(preview);                  // draw only stable fields; wobbly ones wait
}

The two paths have different contracts and cannot replace each other: preview frames may miss fields, persisted frames may not; a persisted frame must wait for stream end and pass a full JSON.parse plus business validation, and preview frames are never persisted. When the upstream is an LLM, persistence also requires judging truncation by the stop reason — that "check stop_reason first, then repair" flow is covered in LLM JSON truncation repair and is not repeated here.

When not to stream

Three veto conditions; if any hits, just parse the whole thing: small files — under about 22 MB a plain JSON.parse usually finishes in under a second, and streaming only adds code complexity; one-shot statistics — for aggregation, jq --stream or line-by-line NDJSON is simpler, see the JSONL file handbook; downstream cannot accept partial data — totals are the classic case: one wrong intermediate value in a preview frame is a money bug, so streaming preview is worth nothing more than a progress bar.

Streaming solves "cannot afford to wait", not "want more speed". For the same amount of text, full parsing always spends less total CPU than any streaming scheme; what you buy is time-to-first-byte, a flat memory watermark, and the ability to process while receiving. Decide that trade-off explicitly and the library choice stops wobbling.

FAQ

Can I persist a preview object directly?

No. A preview is a snapshot of "what is known so far": numbers may be continued by the next chunk, strings may be truncated, fields may be temporarily missing. Before persistence, wait for the stream to end, run a strict JSON.parse on the complete text, then apply business validation. Previews belong to the UI layer only.

partial-json or jsonrepair — which one?

Ask whether you want text or objects. For lossless repaired text that a downstream component parses again, use jsonrepair — its streamed output is guaranteed to equal parsing the full text. For an object on every prefix to drive a UI preview, use partial-json and configure the Allow mask per field to control instability.

Does streaming reduce total runtime?

No. In total CPU time, full parsing is always the fastest; streaming additionally pays for state maintenance. What streaming buys is three things: time to the first usable chunk, a memory watermark that does not grow with document size, and the ability to forward, filter or display while still receiving.

What if array elements arrive one by one and I want one-by-one handling?

That is a different path: stream-json's streamArray emits {key, value} when each element closes, and paired with for await it backpressures naturally — a good fit for parse-then-insert batch imports, a different granularity from the document-level streaming preview in this article.

References

Matching tools

Related articles

JSON Repair Guide: Salvaging Broken LLM Output Without Losing Trust

LLM responses wrapped in markdown fences, trailing commas, and Python literals will not survive a strict parser — neither will hand-edited configs missing quotes. This guide draws the real line between nine error classes a repairer fixes and four it cannot, explains why state machines beat regex, and gives you a production-ready parse chain with jsonrepair and json-repair.

Intermediate~6 min readUpdated 2026-11-08

When an LLM JSON Output Is Truncated: Read the Stop Reason First

The model returns JSON that stops mid-value, and the parser only gives you a column number. Closing the brackets makes it parse again, but every missing field is now hidden inside the data. This article draws the line between what truncation repair can honestly recover and what must be retried, from stop_reason gating to schema field ordering.

Advanced~5 min readUpdated 2026-11-14

Working with JSONL Files: Open, Convert, and Debug Bad Lines

Feeding a whole .jsonl file to JSON.parse and getting an error almost never means the file is broken — it means the wrong reading strategy. This guide covers the standard ways to inspect and read JSONL line by line, the commands for converting to and from JSON arrays, a six-row table of common bad lines, and the correct way to consume JSONL from streaming HTTP responses.

Intermediate~9 min readUpdated 2026-11-06