Clarinet

0.12.6 · active · verified Tue Apr 21

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.

Common errors

```
Error: Unhandled 'error' event (or similar runtime exception)
```
cause 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')
```
cause 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.

Warnings

gotcha Clarinet 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.
gotcha Unhandled 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.
gotcha The `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()`.

Install

npm install clarinet npm
yarn add clarinet yarn
pnpm add clarinet pnpm

Imports

clarinet
wrong:
```
import clarinet from 'clarinet';
```
correct:
```
const clarinet = require('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
wrong:
```
const { parser } = require('clarinet');
```
correct:
```
const clarinet = require('clarinet');
const parser = clarinet.parser();
```
The `parser()` function is a method on the `clarinet` module object, not a direct named export from the module itself.
createStream
wrong:
```
const createStream = require('clarinet/createStream');
```
correct:
```
const { createStream } = require('clarinet');
```
The `createStream` factory function is a property of the `clarinet` module object and can be destructured directly for convenience.

Quickstart

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();

view raw JSON →