Json-stream

Incremental JSON and JSON5 parsing with selective value callbacks, streaming strings, JSONPath selectors and Web/Node input adapters. No runtime dependencies.

This README documents the 3.0.0-beta.1 prerelease, with breaking changes from 2.x and the alpha releases. Core parsers accept strings; transports decode bytes. For the stable 2.x API, see 2.0.1.

Install the beta explicitly; the stable 2.x release remains on latest:

npm install @sapientpro/json-stream@beta

import {JsonParser} from '@sapientpro/json-stream';

const parser = new JsonParser();
parser.onValue('$.items[*].id', (value, path) => {
  console.log(value, path);
});
parser.write('{"items":[{"id":42}]}');
parser.end();

Register consumers before the first write. Callbacks run synchronously; the caller controls input pacing. Use JSONL or prefix managers to consume multiple documents. The core accepts strings; input adapters decode UTF-8 bytes. Subscribe to $ or call getValue() before writing to retain the complete root.

Selectors support names, typed array indexes, wildcards and recursive descent such as $..id and $..*. Filters, slices, unions and negative indexes are explicitly rejected. See supported paths and streaming semantics.

Stream a string as it arrives

import {JsonParser} from '@sapientpro/json-stream';

const parser = new JsonParser();
parser.onString('$.text', fragment => console.log(fragment));
parser.write('{"text":"Hello ');
parser.end('world 🌍"}');

Fragments are decoded text; their boundaries depend on input and escapes. No complete string is retained unless a value consumer requests it too. Values and fragments can arrive before a later syntax error; await input completion when whole-document validity matters.

Documentation

• Usage: values, JSONPath, strings, Web/Node input and JSONL
• API reference: methods, lifecycle and option defaults
• Advanced: reset, document boundaries and reusable plans
• Compact memory mode and its limits
• Migration from 2.x
• Approximate throughput and package comparison
• Architecture, contributing and security policy

Documentation follows main; unreleased additions are marked in the reference.

MIT licensed.