chunkjson

Streaming JSON built on Web Streams. Split lines, parse NDJSON, stream the elements of a huge JSON array, and render a JSON value while it is still arriving.

Every streaming-JSON package on npm predates Web Streams: they are Node-only, CommonJS, and unmaintained for years. None of them run in a browser, a Cloudflare Worker, Vercel Edge, or Deno — which is exactly where streaming workloads now live.

import { parsePartialJson } from "chunkjson";

// A structured LLM response, usable before it finishes generating
for await (const partial of response.body.pipeThrough(parsePartialJson<Answer>())) {
  render(partial);
  // {}
  // { title: "Q3 R" }
  // { title: "Q3 Review", risks: ["supp"] }
  // { title: "Q3 Review", risks: ["supply", "fx"], confidence: 0.82 }
}

• Web Streams native — every export is a TransformStream, so it composes with .pipeThrough() and works on any runtime with fetch
• Correct at any chunk boundary — a multi-byte character, a string escape, or a number split across chunks is reassembled, not corrupted. Verified by a differential test against JSON.parse over a generated corpus at chunk sizes down to one byte
• Constant memory — nothing buffers the whole document
• Typed errors — a single ChunkJsonError with a literal code, plus the line or offset where it happened
• Small — zero dependencies, ~2.5 KB min+gzip, ESM + CJS

Install

npm install chunkjson
pnpm add chunkjson
yarn add chunkjson
bun add chunkjson
deno add npm:chunkjson

API

parsePartialJson<T>(options?)

Emits the value as it is being received. Containers appear as soon as they open and fill in progressively; a string still arriving appears truncated. The final snapshot is the complete value.

This is what makes a streamed structured response usable: fields populate as they generate instead of appearing all at once at the end.

for await (const partial of stream.pipeThrough(parsePartialJson<Draft>())) {
  setState(partial);
}

Snapshots share structure with the value under construction, so copy one (structuredClone) if you need to retain it.

| option | default | | | --------------- | ------- | ---------------------------------------------------------------------- | | skipUnchanged | true | Suppress snapshots for chunks that changed nothing, such as whitespace |

parseJsonArray<T>(options?)

Streams the elements of a top-level JSON array without holding the document in memory — the shape most HTTP APIs return, where await response.json() would buffer the entire body first.

for await (const row of response.body.pipeThrough(parseJsonArray<Row>())) {
  await insert(row);
}

| option | default | | | ----------- | ---------- | -------------------------------------------------------------------------- | | maxLength | Infinity | Character budget before document_too_large. Bounds work on hostile input |

Throws unexpected_root if the root value is not an array, and incomplete_input if the stream ends first.

parseNdjson<T>(options?) / stringifyNdjson<T>(options?)

Newline-delimited JSON (NDJSON / JSON Lines), the format of LLM batch APIs, training datasets, and log pipelines. Blank lines are ignored, CRLF is handled, and a malformed record reports its 1-based line number.

for await (const record of file.stream().pipeThrough(parseNdjson<Record>())) {
  ...
}

readable.pipeThrough(stringifyNdjson()).pipeTo(writable);

| option | default | | | -------------------------- | --------- | -------------------------------------------------- | | onInvalidLine | "error" | "skip" drops malformed lines instead of aborting | | plus all lines() options | | |

lines(options?)

Splits a byte or text stream into lines. UTF-8 decoding is incremental, so a character split across chunks is reassembled rather than replaced with �, and a leading byte-order mark is removed.

for await (const line of response.body.pipeThrough(lines())) {
  if (line.startsWith("data: ")) handle(line.slice(6));
}

| option | default | | | --------------- | ---------- | ------------------------------------------------------------------------- | | delimiter | "\n" | A \n delimiter also strips a preceding \r, so CRLF works unconfigured | | maxLineLength | Infinity | Guards against a delimiter-free stream buffering without bound | | emitTrailing | true | Emit the last line when the stream ends without a delimiter | | emitEmpty | false | Emit blank lines |

Errors

Every failure is a ChunkJsonError (exported, with isChunkJsonError) carrying a literal code:

| code | when | | -------------------- | --------------------------------------------- | | invalid_json | a record or document is not valid JSON | | incomplete_input | the stream ended inside a string or container | | trailing_content | a second value followed the root value | | unexpected_root | parseJsonArray received a non-array root | | line_too_long | a line exceeded maxLineLength | | document_too_large | input exceeded maxLength | | invalid_option | an option was rejected at construction |

line and offset locate the failure where they are known, and toJSON() makes the error safe to log structurally.

Notes

• Types are declarations, not validation. parseNdjson<T>() asserts the shape the way JSON.parse does — it does not check it. Parse with a schema at the boundary if the input is untrusted.
• parsePartialJson never emits invalid intermediate types. A number still being received is withheld until its last digit, because 1.5 truncated to 1. is not a number. Strings and containers stream; scalars land whole.
• Duplicate object keys follow JSON.parse: the last one wins.

Compared with the Node-stream generation

| | chunkjson | split2 / byline / ndjson / JSONStream | | --------------------------- | -------------------- | --------------------------------------------- | | runtimes | any with Web Streams | Node only | | modules | ESM + CJS | CommonJS | | dependencies | 0 | 2–10 | | partial/incremental parsing | yes | no | | last released | — | 3 to 10 years ago |

Contributing

bun install
bun run check   # format, lint, types, tests, build

License

MIT