streaming-json-parser

Incremental JSON parser for TypeScript/JavaScript, built for the "parse JSON while the model is still typing" problem: feed it chunks as they arrive from an LLM stream, subscribe to specific paths to be notified as values appear and grow, and get a best-effort result at any point — even mid-stream, from truncated input. Zero runtime dependencies.

Why

Streaming an LLM's JSON output (tool calls, structured responses) means you have an incomplete JSON document at every point until the stream ends. This package parses it incrementally with a character state machine, lets you subscribe to a path ("choices.0.delta.content") and get called every time that value updates, and can hand back a best-effort completed object from a stream cut off mid-token.

Install

npm install @ferrow/streaming-json-parser

Quickstart

import { StreamingJsonParser } from "streaming-json-parser";

const parser = new StreamingJsonParser();

parser.onValue("choices.0.delta.content", (value) => {
  process.stdout.write(String(value)); // fires on every streamed character
});

for await (const chunk of llmStream) {
  parser.feed(chunk);
}

const { value, wasTruncated, complete } = parser.getResult();

API

new StreamingJsonParser(options?: ParserOptions)

ParserOptions = { strict?: boolean } (default false). In strict mode, malformed syntax throws StreamingJsonParseError (with .position) immediately from feed(). In tolerant mode (default), malformed syntax is skipped cleanly rather than thrown — the "tolerant" behavior most callers want is really getResult()'s truncation completion (below), not silent recovery from garbage.

feed(chunk: string): void

Appends chunk to the internal buffer and advances the parser as far as the buffered text allows.

onValue(path: string, callback: (value: unknown) => void): () => void

Subscribes to a dot-separated path (array indices as plain numbers, e.g. "choices.0.delta"). Fires on every update at that path: strings fire per character/escape sequence appended, objects/arrays fire on every child change, numbers/booleans/null fire once on completion. Returns an unsubscribe function.

getResult(): ParseResult

ParseResult = { value: unknown; wasTruncated: boolean; complete: boolean }. If a complete top-level JSON value has been received, returns it with wasTruncated: false, complete: true. Otherwise returns a best-effort snapshot — any in-progress string is closed as-is, any in-progress object/ array already reflects everything parsed so far — with wasTruncated: true, complete: false.

class StreamingJsonParseError extends Error

{ message: string; position: number } — thrown by feed() in strict mode only.

Limits

• Numbers and true/false/null literals are only emitted via onValue once fully complete — only strings and objects/arrays stream incrementally. (An incomplete literal like "tr can't be guessed, so getResult() omits it rather than fabricating a value.)
• Trailing commas are not explicitly rejected as an error, even in strict mode — this is a pragmatic streaming parser, not a full RFC 8259 conformance checker.
• Assumes a single top-level JSON value per parser instance (the typical "one streamed object/array" case) — it does not parse a sequence of concatenated top-level values (JSON Lines) from one instance.
• getResult()'s force-completion closes open strings/containers into a valid JS value; it does not hand back the text of a repaired JSON string (there's no getPartialText()), only the parsed value.

---

Part of the ferrow-toolkit collection · Sponsored by Ferrow