verifyFile

(Since 3.3.0) verifyFile() is a Node-only, file-based JSON validator. It's a standalone async function (not a chain stage): it returns a Promise that resolves on valid input and rejects with a {message, line, pos, offset} error on invalid input.

Introduction

import {verifyFile} from 'stream-json/file/verifier.js';

try {
  await verifyFile('candidate.json');
  console.log('valid');
} catch (e) {
  console.log('invalid at line', e.line, 'pos', e.pos, 'offset', e.offset, ':', e.message);
}

JSONC variant (accepts comments and trailing commas):

import {verifyFile} from 'stream-json/file/jsonc/verifier.js';

How it works

Internally verifyFile constructs a one-shot pipeline pipe(asyncBlockReader(options), jsonVerifier(options))(path) and drains it. The verifier validates structure only — no tokens are emitted; line/pos/offset tracking stays byte-exact for error reporting. On valid input the drained pipeline resolves with undefined; on invalid input the verifier throws and the throw propagates out of the for-await.

verifyFile(path, options?)

• path — the file to validate.
• Returns Promise<void>.

Options:

• readBlockSize — read-block size in bytes. Default 65536 (64 KB).
• jsonStreaming — accept JSON Streaming (concatenated/line-delimited JSON). Default false. Same semantics as Verifier.

Error shape

The rejection mirrors Verifier's error:

{
  message: 'unexpected character',
  line: 1,        // 1-based line
  pos: 6,         // 1-based column within the line
  offset: 5       // 0-based byte offset
}

Standard Node errors (e.g. ENOENT) also propagate as-is.

Performance

verifyFile is at parity with the idiomatic chain([createReadStream(path), verifier.asStream()]) path in our benchmarks (~3.6ms median for a 100 KB fixture on Intel i3‑10110U, Node 26). The value is ergonomic — one import, one call — not raw throughput.

Related

• Verifier — the underlying token-validating flushable.
• parseFile — file-based parser; same starter shape.