Signature: text → {key, value} items

(Since 1.6.0) This is a convenience component for parsing large JSONL (AKA NDJSON) files. It consumes text and produces a stream of JavaScript objects. It is always the first in a pipe chain being directly fed with text from a file, a socket, the standard input, or any other text stream.

⚠️ Deprecated — use stream-chain/jsonl/parser instead. As of stream-chain 4.2.1 this module is a thin re-export of stream-chain's JSONL parser, with the identical {key, value} output and the full reviver / errorIndicator API (plus ignoreErrors). stream-json is a JSON token library; JSONL yields whole objects per line and belongs in stream-chain alongside the other substrate components, so stream-json's JSONL is slated for removal in a future major version. Migrate now by importing from stream-chain directly. For reading JSONL files directly with bounded memory, stream-chain also ships file components — use parseFile() from stream-chain/jsonl/file/parser.js (an async block reader producing {key, value} objects) instead of wiring a file stream into the parser.

Functionally, jsonl/Parser replaces a combination of Parser with jsonStreaming set to true, which immediately follows by StreamValues. The only reason for its existence is improved performance.

Just like StreamValues it produces a stream of objects like that:

StreamValues assumes that a token stream represents subsequent values and streams them out one by one.

// From JSONL:
// 1
// "a"
// []
// {}
// true
// It produces:
{key: 0, value: 1}
{key: 1, value: 'a'}
{key: 2, value: []}
{key: 3, value: {}}
{key: 4, value: true}

The simple example (streaming from a file):

import jsonlParser from 'stream-json/jsonl/parser.js';

import fs from 'node:fs';

const pipeline = fs.createReadStream('sample.jsonl').pipe(jsonlParser.asStream());

let objectCounter = 0;
pipeline.on('data', () => ++objectCounter);
pipeline.on('end', () => console.log(`Found ${objectCounter} objects.`));

The alternative example:

import jsonlParser from 'stream-json/jsonl/parser.js';
import fs from 'node:fs';

const pipeline = fs.createReadStream('sample.jsonl').pipe(jsonlParser.asStream());

let objectCounter = 0;
pipeline.on('data', data => ++objectCounter);
pipeline.on('end', () => console.log(`Found ${objectCounter} objects.`));

Functionally equivalent to:

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

const pipeline = chain([fs.createReadStream('sample.jsonl'), parser({jsonStreaming: true}), streamValues()]);

let objectCounter = 0;
pipeline.on('data', () => ++objectCounter);
pipeline.on('end', () => console.log(`Found ${objectCounter} objects.`));

The module returns a factory function. jsonlParser() returns a composable function for use in chain(). jsonlParser.asStream() wraps it as a Duplex stream. The named export jsonlParser is the raw per-line parser — the bare parse function without the fixUtf8Stream() + line-splitting front; the default/parser is gen(fixUtf8Stream(), lines(), jsonlParser()).

In many real cases, while files are huge, individual data items can fit in memory. It is better to work with them as a whole, so they can be inspected. jsonl/Parser leverages JSONL format and returns a stream of JavaScript objects exactly like StreamValues.

options is an optional object described in detail in node.js' Stream documentation. Additionally, the following custom flags are recognized:

• reviver is an optional function, which takes two arguments and returns a value.

  • See JSON.parse() for more details.

• (Since 1.7.2) checkErrors is an optional boolean value. If it is truthy, every call to JSON.parse() is checked for an exception, which is passed to a callback. Otherwise, JSON.parse() errors are ignored for performance reasons. Default: false.

• (Since 1.8.0) errorIndicator is an optional value. If it is specified it supersedes checkError. When it is present, every call to JSON.parse() is checked for an exception and processed like that:

  • If errorIndicator is undefined the error is completely suppressed. No value is produced and the global key is not advanced.
  • If errorIndicator is a function, it is called with an error object. Its result is used this way:
    • If it is undefined ⇒ skip as above.
    • Any other value is returned as a value.
  • Any other value of errorIndicator is returned as a value.

  Default: none.

Alias of the factory function.

Returns a Duplex stream suitable for .pipe() usage:

import chain from 'stream-chain';
import jsonlParser from 'stream-json/jsonl/parser.js';

import fs from 'node:fs';

const pipeline = chain([fs.createReadStream('sample.jsonl'), jsonlParser.asStream()]);

let objectCounter = 0;
pipeline.on('data', () => ++objectCounter);
pipeline.on('end', () => console.log(`Found ${objectCounter} objects.`));

jsonlParser ships in two substrate-specific entries with the same factory shape:

• Node — stream-json/jsonl/parser.js. Has asStream (Node Duplex) and asWebStream (Web {readable, writable} pair).
• Web — stream-json/web/jsonl/parser.js. Has asWebStream only. Pulls in no Node-stream imports.

Both factories return the same generator pipeline, so chain on either substrate auto-wraps it.

// Web
import {chain} from 'stream-chain/web';
import jsonlParser from 'stream-json/web/jsonl/parser.js';

const pipeline = chain([source, jsonlParser()]);
for await (const {key, value} of pipeline.readable) console.log(key, value);