# stream-json

> A micro-library of stream components for building custom JSON and JSONC processing pipelines with a minimal memory footprint — parse, filter, and transform JSON far larger than available memory with a SAX-inspired token API, on Node.js or Web Streams.

Latest version **3.7.0** (published 2026-09-19) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install stream-json
pnpm add stream-json
yarn add stream-json
bun add stream-json
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.7.0 |
| Published | 2026-09-19 |
| First published | 2013-08-11 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 404.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1197 |
| Author | Eugene Lazutkin |
| Maintainers | elazutkin |
| Keywords | json, json-parser, parser, stream, streaming, streaming-json, sax, tokenizer, pipeline, filter, jsonc, web-streams, large-files, memory-efficient, nodejs |

## Links

- npm: https://www.npmjs.com/package/stream-json
- Repository: https://github.com/uhop/stream-json
- Homepage: https://github.com/uhop/stream-json#readme
- Issues: https://github.com/uhop/stream-json/issues
- Funding: https://github.com/sponsors/uhop
- npm.io page: https://npm.io/package/stream-json

## Dependencies (1)

- [stream-chain](https://npm.io/package/stream-chain.md) ^4.2.5

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.7.0 (latest) — 2026-09-19
- 3.6.0 — 2026-08-28
- 3.5.0 — 2026-07-07
- 3.4.0 — 2026-06-08
- 3.3.0 — 2026-05-29
- 3.2.0 — 2026-05-27
- 3.1.0 — 2026-05-23
- 3.0.0 — 2026-05-21
- 2.1.0 — 2026-03-31
- 2.0.0 — 2026-03-19
- 1.9.1 — 2024-11-12
- 1.9.0 — 2024-10-23
- 1.8.0 — 2023-05-30
- 1.7.5 — 2022-11-23
- 1.7.4 — 2022-02-17
- … 42 more at https://npm.io/package/stream-json/versions

## README

# stream-json [![NPM version][npm-image]][npm-url]

[npm-image]: https://img.shields.io/npm/v/stream-json.svg
[npm-url]: https://npmjs.org/package/stream-json

`stream-json` is a micro-library of components for processing JSON files and streams, with a minimal memory footprint. Point it at a document far larger than available memory and it streams straight through — you pick out only the parts you care about and handle them one at a time, instead of loading the whole thing with `JSON.parse`. Even individual keys, strings, and numbers can be streamed piece by piece, and a SAX-inspired event API is included.

Each component is one stage of a pipeline: the parser turns text into a token stream, filters trim and reshape that stream on the fly, and streamers assemble the surviving tokens back into JavaScript objects. They compose with each other and with your own code through [stream-chain](https://www.npmjs.com/package/stream-chain), the zero-dependency library this one is built on; TypeScript typings are bundled.

Why it might be for you:

- **Surgical.** `pick`, `ignore`, `replace`, and `filter` keep just the subobjects you want out of a massive document and drop the rest — the bytes you skip are never assembled into memory.
- **Composable.** Every component is an ordinary pipeline stage. Mix them with each other, with plain functions and generators, and with any Node or Web stream.
- **Performance-minded.** The parser and assemblers are measured and tuned along the hot paths. Real numbers depend on your data and hardware, so [benchmark](https://github.com/uhop/stream-json/wiki/Benchmarks) on your own.
- **Solid.** ESM, bundled TypeScript typings, and a broad test suite exercised across Node, Bun, Deno, and the browser.

## Intended input

`stream-json` is built for data you own or trust — database dumps, exports, logs, and files produced by your own systems. It is not designed for hostile input: do not feed it JSON or JSONC from the open internet or from untrusted users. Untrusted JSON needs validation of its own before it reaches a pipeline.

## Example

Pull one array out of a JSON document larger than memory and tally it — one record at a time, in constant memory:

```js
import {parser} from 'stream-json';
import {pick} from 'stream-json/filters/pick.js';
import {streamArray} from 'stream-json/streamers/stream-array.js';
import chain from 'stream-chain';
import fs from 'node:fs';

// data.json: { "meta": {...}, "data": [ ...millions of records... ] }
const pipeline = chain([
  fs.createReadStream('data.json'), // a file far bigger than RAM is fine
  parser(),
  pick({filter: 'data'}), // descend into "data", ignore everything else
  streamArray() // emit one array element at a time
]);

const byDepartment = {};
pipeline.on('data', ({value}) => {
  byDepartment[value.department] = (byDepartment[value.department] ?? 0) + 1;
});
pipeline.on('end', () => console.log(byDepartment));
```

This works because `pick` selected a single array — `streamArray` then streams its elements. When `pick` matches **several** subobjects, its output is a sequence of separate sub-trees — structurally the same token stream a [JSON Streaming](https://en.wikipedia.org/wiki/JSON_Streaming) source produces — and [streamValues()](https://github.com/uhop/stream-json/wiki/StreamValues) assembles each match into its own object:

```js
import {parser} from 'stream-json';
import {pick} from 'stream-json/filters/pick.js';
import {streamValues} from 'stream-json/streamers/stream-values.js';
import chain from 'stream-chain';
import fs from 'node:fs';

// depts.json: {"departments": [
//   {"name": "dev", "head": {"name": "Alice", "id": 1}, "staff": 20},
//   {"name": "ops", "head": {"name": "Bob", "id": 2}, "staff": 10}
// ]}
const pipeline = chain([
  fs.createReadStream('depts.json'),
  parser(),
  pick({filter: /^departments\.\d+\.head\b/}), // every department's "head" subobject
  streamValues() // assemble each picked sub-tree
]);

pipeline.on('data', ({value}) => console.log(value.name));
// → Alice
// → Bob
```

Each stage is a building block; `stream-chain` wires them into one stream and handles the streaming and backpressure. To read straight from a file you can drop `createReadStream` and use the Node-only [parseFile()](https://github.com/uhop/stream-json/wiki/parseFile); to write a stream back to disk, use [stringerToFile()](https://github.com/uhop/stream-json/wiki/stringerToFile). See [Recipes](https://github.com/uhop/stream-json/wiki/Recipes) for more.

## Installation

```bash
npm install --save stream-json
```

ESM only; runs on actively-maintained Node, plus Bun and Deno — see [Supported runtimes](https://github.com/uhop/stream-json/wiki/Supported-runtimes).

## What's in the box

- **Parsers** — [JSON](https://github.com/uhop/stream-json/wiki/Parser), [JSONL](https://github.com/uhop/stream-chain/wiki/jsonl) (the fast path for line-delimited data dumps), and [JSONC](https://github.com/uhop/stream-json/wiki/jsonc-Parser) (JSON with comments).
- **Helpers for streamed objects** — pick out the parts you want, assemble objects from tokens, output JSON back, and read or write files directly.
- **Runtimes** — works out of the box on Node (Node streams); browser-safe (Web Streams) and dependency-free Core (no streams) builds are there when you need them.

Want the details? Follow the links, or browse the **[wiki](https://github.com/uhop/stream-json/wiki)** — [index](https://github.com/uhop/stream-json/wiki/Home) or [search](https://uhop.github.io/wiki-search/app/?wiki=uhop/stream-json).

## Companion projects

- [stream-chain](https://www.npmjs.com/package/stream-chain) — the pipeline-composition substrate `stream-json` is built on (wire functions, generators, and streams into one chain); also home to streaming [JSONL](https://github.com/uhop/stream-chain/wiki/jsonl).
- [stream-csv-as-json](https://www.npmjs.com/package/stream-csv-as-json) — streams huge CSV files in a `stream-json`-compatible token format: rows as arrays of strings, or as objects when a header row is present.

## License

BSD-3-Clause

## Release History

- 3.7.0 _New `maxDepth` option on `FlexAssembler` rules (thx [zx](https://github.com/manus-pi)), significant performance improvements for string and RegExp filters._
- 3.6.0 _Two security fixes (a `__proto__` key no longer replaces an assembled object's prototype; JSONC comments no longer rescan), JSONC comments stream as `startComment` / `commentChunk` / `endComment` plus `commentValue` (the `comment` token is renamed), `replace` takes any plain value as `replacement`, filters replay keys packed again. Thx [Ryan Cruz](https://github.com/cruzryan), [Iain](https://github.com/NotAFlightRisk), [WorldSEnder](https://github.com/WorldSEnder), and [Mike Tunnicliffe](https://github.com/tunniclm)._
- 3.5.0 _New `maxDepth` option on path filters. Thx [ataberk.xyz](https://github.com/ataberk-xyz)._
- 3.4.0 _Deprecated `stream-json/utils/{pipe,drain}` — use `stream-chain`'s generic helpers directly; the file-edge internals now delegate to `stream-chain`._
- 3.3.0 _File I/O components (`parseFile`, `stringerToFile`, `verifyFile`), faithful JSONC comma round-trip (`streamCommas` / `useCommas`), JSONL delegated to `stream-chain`._
- 3.2.0 _Improvements in TS typings, faster JSON parser._
- 3.1.0 _Web Streams parity sweep._
- 3.0.0 _Moved to ESM using `stream-chain` 4.x. See [Migrating from 2.x to 3.x](https://github.com/uhop/stream-json/wiki/Migrating-from-2.x-to-3.x)._
- 2.1.0 _new: [jsonc/Verifier](https://github.com/uhop/stream-json/wiki/jsonc-Verifier) — validates JSONC text with exact error locations. Parser performance improvements (pre-allocated token singletons)._
- 2.0.0 _major rewrite: functional API based on `stream-chain` 3.x, bundled TypeScript definitions. New: JSONC parser/stringer, FlexAssembler. See [Migrating from 1.x to 2.x](https://github.com/uhop/stream-json/wiki/Migrating-from-1.x-to-2.x)._

The full history is in the wiki: [Release history](https://github.com/uhop/stream-json/wiki/Release-history).

---
_Source: https://npm.io/package/stream-json · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._