Verifier

(Since 1.2.0) This utility is a Writable stream. It is based on Parser, but its only purpose is to raise an error with an exact location (offset, line, position) when its input is not a valid JSON. Use it to troubleshoot when Parser fails to parse.

Introduction

The simple example (streaming from a file):

const verifier = require('stream-json/utils/verifier.js');

const fs = require('fs');

const stream = verifier.asStream();
stream.on('error', error => console.log(error));

fs.createReadStream('sample.json').pipe(stream);

Backgrounder

While the very first parser (ClassicParser) included descriptive errors, which included line and position of a wrong token, it proved to be useless for two reasons:

1. Calculating line and position consumed significant resources. Because stream-json is used with huge files even a small increase in data processing can waste hours of valuable time.
2. Usually, the exact position of the error does not help: are you going to edit a file of several terabytes? How?

Yet the non-conformant JSON files can happen in the wild. This utility exists for your peace of mind.

API

The module returns a factory function. verifier.asStream() returns a Writable stream. verifier() returns a composable function for use in chain(). It uses the same charCodeAt structural classification and whole-lexeme fast paths as the Parser, with byte-exact offset/line/pos tracking. The named export jsonVerifier is the raw inner validator (no fixUtf8Stream() front); the default/verifier is gen(fixUtf8Stream(), jsonVerifier()).

constructor(options)

options is an optional object described in details in node.js' Stream documentation. Additionally, the following custom flags are recognized, which can be truthy or falsy:

• jsonStreaming controls the parsing algorithm. If truthy, a stream of JSON objects is parsed as described in JSON Streaming as "Concatenated JSON". Technically it will recognize "Line delimited JSON" as well. Otherwise, it will follow the JSON standard assuming a singular value. The default: false.

By default, Verifier follows a strict JSON format.

Static methods and properties

verifier.verifier(options)

Alias of the factory function.

verifier.asStream(options)

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

const {chain} = require('stream-chain');
const verifier = require('stream-json/utils/verifier.js');

const fs = require('fs');

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

pipeline.on('error', error => console.log(error));

Web Streams

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

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

Both factories return the same flushable, so chain on either substrate auto-wraps it. Errors propagate via the readable stream — await the pipe to surface them.

// Web
import {chain} from 'stream-chain/web';
import verifier from 'stream-json/web/utils/verifier.js';

const pipeline = chain([source, verifier()]);
try {
  for await (const _ of pipeline.readable) {
    // Verifier produces no output; just drain the readable to completion.
  }
  console.log('Valid JSON');
} catch (err) {
  console.error(`Invalid at line ${err.line}, pos ${err.pos}: ${err.message}`);
}