{"id":15983,"library":"clarinet","title":"Clarinet","description":"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.","status":"active","version":"0.12.6","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/dscape/clarinet","tags":["javascript","sax","json","parser","stream","streaming","event","events","emitter"],"install":[{"cmd":"npm install clarinet","lang":"bash","label":"npm"},{"cmd":"yarn add clarinet","lang":"bash","label":"yarn"},{"cmd":"pnpm add clarinet","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import clarinet from 'clarinet';","symbol":"clarinet","correct":"const clarinet = require('clarinet');"},{"note":"The `parser()` function is a method on the `clarinet` module object, not a direct named export from the module itself.","wrong":"const { parser } = require('clarinet');","symbol":"parser","correct":"const clarinet = require('clarinet');\nconst parser = clarinet.parser();"},{"note":"The `createStream` factory function is a property of the `clarinet` module object and can be destructured directly for convenience.","wrong":"const createStream = require('clarinet/createStream');","symbol":"createStream","correct":"const { createStream } = require('clarinet');"}],"quickstart":{"code":"const clarinet = require(\"clarinet\");\nconst parser = clarinet.parser();\n\nparser.onerror = function (e) {\n  console.error(\"Parsing error: \", e.message, \"at line:\", parser.line, \"column:\", parser.column);\n  // Optional: clear the error and resume parsing if recoverable\n  this._parser.error = null; // Private, use with caution\n  this._parser.resume(); // Private, use with caution\n};\nparser.onvalue = function (v) {\n  console.log(\"Value:\", v);\n};\nparser.onopenobject = function (key) {\n  console.log(\"Open Object, first key:\", key);\n};\nparser.onkey = function (key) {\n  console.log(\"Key:\", key);\n};\nparser.oncloseobject = function () {\n  console.log(\"Close Object\");\n};\nparser.onopenarray = function () {\n  console.log(\"Open Array\");\n};\nparser.onclosearray = function () {\n  console.log(\"Close Array\");\n};\nparser.onend = function () {\n  console.log(\"Parser stream ended.\");\n};\n\nparser.write('{\"id\":123, \"name\":\"test\", \"data\": [true, null, 42]}').close();\n// Example with partial writes\n// parser.write('{\"foo\": \"bar\"').write(',\"baz\": \"qux\"}').close();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"An error occurred during parsing (e.g., malformed JSON) and no `onerror` or `error` event handler was attached.","error":"Error: Unhandled 'error' event (or similar runtime exception)"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'parser')"}],"ecosystem":"npm"}