Registry / data / vstream-json-parser

vstream-json-parser

JSON →
library1.0.1jsnpmunverified

vstream-json-parser is a Node.js object-mode Transform stream designed for parsing chunks of UTF-8 text, typically newline-separated JSON objects, into plain JavaScript objects. Its current stable version is 1.0.1. The library differentiates itself by leveraging the `vstream` interface for warning management rather than emitting fatal `error` events for common operational issues like malformed JSON or `null` values. It processes transformations synchronously but throttles to one input per tick to maintain event loop liveness. Key features include its object-mode output, customizable `highWaterMark` (defaulting to 0 for low memory usage), and specific handling for `null` JSON values, which are ignored because Node.js streams cannot represent them without ending the stream. This package is particularly suited for processing large streams of structured log data or similar continuous JSON feeds where error recovery and liveness are critical. Given the last activity on GitHub (2015 copyright), the project appears to be in a maintenance or abandoned state.

dataserializationhttp-networking
npm install vstream-json-parser
github ↗package ↗
INSTALL
IMPORT
SIG · VSTREAM-JSON-PARSE
V
vstream-json-parser
datajavascriptv1.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

JsonParserStream
✓ const JsonParserStream = require('vstream-json-parser');
✗ import { JsonParserStream } from 'vstream-json-parser';
This library is CommonJS-only, reflecting its older codebase. Direct ESM import is not supported.
stream options
✓ new JsonParserStream({ highWaterMark: 1 });
Constructor accepts an optional object for Node.js Stream options, though `objectMode` is always overridden to `true`.
vstream warnings
✓ stream.on('warning', (warning) => console.warn(warning.message));
Operational errors (malformed JSON, null values) are emitted as 'warning' events via the vstream interface, not 'error' events.

This quickstart demonstrates parsing a stream of newline-separated JSON objects, including malformed input and `null` values, and handling `vstream` warnings.

const JsonParserStream = require('vstream-json-parser'); const { Writable } = require('stream'); // Create a custom writable stream to consume the parsed objects class MyObjectConsumer extends Writable { constructor(options) { super({ objectMode: true, ...options }); this.parsedObjects = []; } _write(chunk, encoding, callback) { this.parsedObjects.push(chunk); console.log('Received object:', chunk); callback(); } } const parser = new JsonParserStream(); const consumer = new MyObjectConsumer(); parser.pipe(consumer); parser.on('warning', (warning) => { console.warn(`[WARNING]: ${warning.message}`); }); parser.write('{ "id": 1, "name": "Alice" }\n'); parser.write('{ "id": 2, "value": null }\n'); // This will trigger a warning and be ignored parser.write('{ "id": 3, "data": "{\n'); // Malformed JSON, will trigger a warning parser.write(' "key": "value" }\n'); parser.write('{ "id": 4, "status": "active" }\n'); parser.end(); consumer.on('finish', () => { console.log('\n--- Parsing complete ---'); console.log('Total objects received:', consumer.parsedObjects.length); console.log('Final objects:', consumer.parsedObjects); });
Debug
Known issues
gotchaThe stream will not emit 'error' events for malformed JSON input or when an input object parses to `null`. Instead, these conditions are emitted as 'warning' events via the `vstream` interface.
fix
Implement an event listener for `stream.on('warning', handler)` to properly handle parsing issues and null value notifications.
affects: >=1.0.0
gotchaJSON objects that parse to the JavaScript `null` value are silently ignored and not emitted downstream. This is due to Node.js stream limitations where `null` signifies end-of-stream.
fix
If `null` as a value is semantically important for your application, you must pre-process the stream to replace `null` with a placeholder (e.g., `{"_null_value": true}`) before piping it to `vstream-json-parser`.
affects: >=1.0.0
breakingThis package is a CommonJS module only and does not directly support ES Modules (`import`). Attempting to use `import` syntax will result in errors.
fix
Always use `const JsonParserStream = require('vstream-json-parser');` to import the module.
affects: >=1.0.0
gotchaThe `objectMode` option passed to the constructor is always overridden to `true` internally. This stream always outputs JavaScript objects.
fix
Do not explicitly set `objectMode: false` in constructor options, as it will be ignored. Ensure downstream streams are also in `objectMode` to handle the output.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".js" for /path/to/your/script.js
Attempting to use `require()` in an ES Module context or vice-versa, or incorrect module resolution setup.
fix
Ensure your project is configured for CommonJS (`"type": "commonjs"` in `package.json` or omit `"type"`) or run with Node.js `--experimental-json-modules` flag if attempting to `import` a `.json` file directly (though not relevant for this parser).
Error: stream.push() after EOF
Attempting to write more data to the stream after `stream.end()` has been called.
fix
Ensure all data is written to the `JsonParserStream` before calling `stream.end()`. If using `pipe`, the `end` event from the source stream will correctly call `end()` on the parser.
TypeError: Invalid argument type: expected a string or buffer
Attempting to write non-string/non-buffer chunks to the `JsonParserStream`.
fix
The parser expects UTF-8 text chunks. Ensure that upstream streams provide string or buffer data. If receiving objects, use a `Transform` stream to stringify them first, or ensure input is byte streams representing JSON.
Upgrade
Version history
1.0.1latest on npm
Audit
Dependencies
vstreamrequiredCore dependency for stream interface and warning emission.
lstreamoptionalCommonly used upstream to split input by newlines before piping to the JSON parser.
Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
githubhttps://github.com/joyent/node-vstream-json-parser ↗
packagehttps://www.npmjs.com/package/vstream-json-parser ↗
vstream-json-parser — npm install vstream-json-parser · libregistry