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');
const verifier = new Verifier();

const fs = require('fs');

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

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

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 the constructor of Verifier. Being a Writable stream Verifier doesn't have any special interfaces. The only thing required is to configure it during construction.

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(options) and make(options)

make() and verifier() are two aliases of the factory function. It takes options described above, and return a new instance of Verifier. verifier() helps to reduce a boilerplate when creating data processing pipelines:

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

const fs = require('fs');

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

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

make.Constructor

Constructor property of make() (and verifier()) is set to Verifier. It can be used for indirect creating of verifiers or metaprogramming if needed.