Registry / serialization / clarinet

clarinet

JSON →
library0.12.6jsnpmunverified

Clarinet is a SAX-like streaming JSON parser for JavaScript, designed for efficient processing of JSON data in both browser and Node.js environments. Inspired by `sax-js` and `yajl`, it provides an evented API that allows developers to process JSON incrementally without needing to load the entire document into memory. This makes it particularly suitable for tasks such as indexing large JSON files or handling continuous streams of JSON where a full DOM-like object model is unnecessary. The package is currently at version 0.12.6, with recent releases (v0.12.x) focusing on minor bug fixes, performance optimizations, and dependency updates, indicating a maintenance cadence rather than rapid feature development. Its key differentiators include portability, robust error reporting with context (line/column numbers), the ability to parse JSON data off a stream incrementally, and a lightweight, simple-to-use API. It explicitly clarifies that it is not a direct replacement for `JSON.parse` but rather a tool for event-driven JSON consumption.

serializationdata
npm install clarinet
github ↗package ↗
INSTALL
IMPORT
SIG · CLARINET
C
clarinet
serializationjavascriptv0.12.6
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.

clarinet
✓ const clarinet = require('clarinet');
✗ import clarinet from 'clarinet';
This package is a CommonJS module. Use `require()` to import the main module object, as direct ESM `import` is not natively supported for this library.
parser
✓ const clarinet = require('clarinet'); const parser = clarinet.parser();
✗ const { parser } = require('clarinet');
The `parser()` function is a method on the `clarinet` module object, not a direct named export from the module itself.
createStream
✓ const { createStream } = require('clarinet');
✗ const createStream = require('clarinet/createStream');
The `createStream` factory function is a property of the `clarinet` module object and can be destructured directly for convenience.

Demonstrates basic event-driven parsing of a JSON string, showing how to handle object, array, key, and value events, as well as errors and stream completion for incremental processing.

const clarinet = require("clarinet"); const parser = clarinet.parser(); parser.onerror = function (e) { console.error("Parsing error: ", e.message, "at line:", parser.line, "column:", parser.column); // Optional: clear the error and resume parsing if recoverable this._parser.error = null; // Private, use with caution this._parser.resume(); // Private, use with caution }; parser.onvalue = function (v) { console.log("Value:", v); }; parser.onopenobject = function (key) { console.log("Open Object, first key:", key); }; parser.onkey = function (key) { console.log("Key:", key); }; parser.oncloseobject = function () { console.log("Close Object"); }; parser.onopenarray = function () { console.log("Open Array"); }; parser.onclosearray = function () { console.log("Close Array"); }; parser.onend = function () { console.log("Parser stream ended."); }; parser.write('{"id":123, "name":"test", "data": [true, null, 42]}').close(); // Example with partial writes // parser.write('{"foo": "bar"').write(',"baz": "qux"}').close();
Debug
Known issues
gotchaClarinet is a SAX-like streaming parser, not a `JSON.parse` replacement. It processes JSON events incrementally and does not build a full JavaScript object model in memory. Do not use it when you need a complete object graph; use `JSON.parse` instead.
fix
Evaluate if an evented streaming parser is truly required for your use case. If you need a complete JavaScript object from your JSON, use `JSON.parse()` or a library that builds a DOM-like structure.
affects: >=0.1.0
gotchaUnhandled errors during parsing will cause the Node.js process to throw and potentially crash. Clarinet errors are emitted via `onerror` for the parser and `error` event for the stream. You must explicitly handle these events.
fix
Always attach `onerror` handler to the parser or an `error` event listener to the stream. After handling an error, you may need to call `this._parser.error = null; this._parser.resume();` (using internal properties with caution) to continue parsing if the error is recoverable.
affects: >=0.1.0
gotchaThe `close()` method signals that no more data will be written to the parser. It does not mean all buffered data has been processed. Wait for the `onend` event to confirm that the parser stream is entirely done and ready for more operations.
fix
Ensure that subsequent logic that depends on full JSON processing is placed within or triggered by the `parser.onend` event handler, not immediately after `parser.close()`.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Unhandled 'error' event (or similar runtime exception)
An error occurred during parsing (e.g., malformed JSON) and no `onerror` or `error` event handler was attached.
fix
Implement an `onerror` handler for the parser instance or an `error` event listener for the stream, as shown in the usage examples. Remember to potentially `resume()` the parser after clearing the error if you want to continue.
TypeError: Cannot read properties of undefined (reading 'parser')
The `clarinet` module was not correctly imported, or `parser` was accessed as a direct named export instead of a method on the imported module object.
fix
Ensure you are using `const clarinet = require('clarinet');` and then `const parser = clarinet.parser();`. Do not use `const { parser } = require('clarinet');` for the parser function.
Upgrade
Version history
0.12.6latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
17 hits · last 30 days
node
12
OpenAI (training)
1
Resources
githubhttps://github.com/dscape/clarinet ↗
packagehttps://www.npmjs.com/package/clarinet ↗
clarinet — npm install clarinet · libregistry