Home

Dashboard

stream-json parses and processes JSON as a stream of tokens, so you can work with documents far larger than memory. This page routes you to the right doc; for the 30-second pitch, see the README.

Search

🔍 Search this wiki — ranked, deep-linked search via wiki-search; install the bookmarklet to search in place. Fallback: GitHub wiki search.

Start here

New to stream-json? Read in this order:

1. Concepts — the model: parse to tokens, narrow, assemble — and what the library can and cannot do.
2. Intro by examples — the common pipelines as runnable code.
3. Recipes — ready-made solutions to common tasks.
4. Performance — once it works, how to keep it fast.

Components

• Parser — turns JSON text into a token stream (the source of every pipeline). The main module wraps it with emit(); Verifier pinpoints errors in invalid input.
• Filters — edit the token stream by path: pick keeps a subobject, ignore drops one, replace substitutes, filter selects while preserving shape.
• Streamers — tokens into objects, one item at a time: streamArray, streamObject, streamValues; shared options (including objectFilter) in StreamBase.
• Assemblers — tokens into one whole value: Assembler, or FlexAssembler for custom containers (Map / Set) at chosen paths.
• Output — Stringer (tokens → JSON text), Disassembler (value → tokens), Emitter (tokens → named events).
• Utilities — emit(), withParser(), Batch.
• File I/O (Node-only) — read or write a file as one fused pipeline: parseFile, stringerToFile, verifyFile.

Other formats

• JSONC (JSON with Comments) — parser, stringer, verifier, with faithful comma round-trip. The filters and streamers work on JSONC tokens too.
• JSONL — use stream-chain's JSONL. The old jsonl/Parser / jsonl/Stringer pages (now deprecated in this package) carry migration notes.

Tuning & reference

For when it works and you want speed, depth, or history:

• Performance — keeping pipelines on the fast path.
• Benchmarks — the measured comparisons.
• Supported runtimes — Node / Bun / Deno / browser policy.
• FAQ — common questions (including why import paths need the .js extension).
• Release history — what changed and when.
• Migrating: 2.x → 3.x, 1.x → 2.x, 0.x → 1.x.

Companion projects

• stream-chain — the pipeline substrate stream-json is built on; also home to streaming JSONL.
• stream-csv-as-json — huge CSV in a stream-json-compatible token format.
• stream-fork — splits a stream to several destinations.
• stream-join — merges side channels — with stream-fork, the tools for complex pipeline topologies.

Credits

tests/sample.json.gz combines several public datasets (Japanese birth/marriage statistics, US HUD metadata catalog, and a synthetic sample with non-ASCII data).

tests/sample.jsonl.gz is the first 100 rows of the CDC "Database of COVID-19 Research Articles" (7/9/2020 snapshot), converted to JSONL.