Incomplete JSON Parser

Common errors

• TypeError: IncompleteJsonParser is not a constructor

  cause Attempting to use `require` for `IncompleteJsonParser` in a CommonJS context without correctly accessing the named export, or incorrect named import syntax in an ESM environment.
  fix For ESM, ensure `import { IncompleteJsonParser } from 'incomplete-json-parser';` is used. For CommonJS, use `const { IncompleteJsonParser } = require('incomplete-json-parser');`.

• Parsed object is empty or does not reflect recent `write()` calls.

  cause Forgetting to call `getObjects()` after `write()` operations to retrieve the current parsed state, or not properly resetting the parser between processing different JSON inputs.
  fix Ensure `getObjects()` is called to retrieve the current state of the parsed object. If parsing multiple independent JSON strings, call `parser.reset()` before feeding new data to the same parser instance.

• Resulting object contains unexpected partial or malformed data that was expected to be completed.

  cause The input stream, even with its fault tolerance, contained genuinely malformed JSON (e.g., deeply nested unclosed structures, invalid characters within values) that could not be reconciled into a valid partial object, or the stream ended prematurely without enough context for the parser to infer a complete structure.
  fix Review the source JSON stream for fundamental syntax errors beyond simple incompleteness. While the parser is robust, it cannot correct arbitrarily invalid JSON. Implement robust error handling or logging around the input source.

Warnings

• gotcha Incomplete JSON Parser is designed for fault tolerance and will attempt to yield a valid partial object from incomplete input. This means it may *not* throw an error where a strict `JSON.parse` would, potentially masking truly malformed JSON if not explicitly handled.
  Fix: Always validate the completeness and correctness of the final parsed object if strict JSON adherence or schema validation is required. Consider additional validation layers on the output from `getObjects()`.
• gotcha When reusing an `IncompleteJsonParser` instance for multiple distinct JSON strings, it's crucial to call `parser.reset()` before processing the next string. Failing to do so will cause subsequent data to be appended to the previously buffered content, leading to incorrect parsing.
  Fix: Ensure `parser.reset()` is invoked whenever a new, independent JSON stream or string begins using the same parser instance.
• gotcha This library processes string data and does not perform deep validation on the *meaning* or *schema* of the JSON. It primarily focuses on structural integrity to the extent possible with incomplete data. Trusting arbitrary external input directly without further sanitization could pose risks if the downstream application expects a specific data shape or content.
  Fix: Always sanitize and validate the parsed JavaScript object against an expected schema or data type before using it in security-sensitive contexts or persistent storage. Consider libraries like Zod or Joi for schema validation.

Install

• npm install incomplete-json-parser npm
• yarn add incomplete-json-parser yarn
• pnpm add incomplete-json-parser pnpm

Imports

• IncompleteJsonParser
  wrong:

  const IncompleteJsonParser = require('incomplete-json-parser');

  correct:

  import { IncompleteJsonParser } from 'incomplete-json-parser';

  The library is written in TypeScript and primarily designed for ESM. While CommonJS `require` might work for some bundlers, the explicit named import is the recommended and type-safe approach.
• IncompleteJsonParser.parse
  wrong:

  import { parse } from 'incomplete-json-parser';

  correct:

  const result = IncompleteJsonParser.parse('{"data": "value"');

  The `parse` method is a static utility on the `IncompleteJsonParser` class, not a standalone named export. It's intended for single-shot parsing of a chunk.
• IncompleteJsonParser (type)

  import type { IncompleteJsonParser } from 'incomplete-json-parser';

  Although TypeScript types are shipped, in modern TypeScript (4.5+), `import { IncompleteJsonParser } from 'incomplete-json-parser';` often handles both value and type imports efficiently. Using `import type` explicitly clarifies intent for type-only imports.

Quickstart

Demonstrates parsing a multi-chunk, incomplete JSON string into a JavaScript object incrementally, simulating a real-time stream. It also shows how to reset the parser for new data.

import { IncompleteJsonParser } from 'incomplete-json-parser';

async function parseStreamingJson() {
  const parser = new IncompleteJsonParser();

  console.log('--- Initializing streaming JSON parsing ---');

  // Simulate receiving data in multiple, incomplete chunks
  parser.write('{"user": {"id": 123, "name": "Alice", "email": "alice@example');
  console.log('Chunk 1 received. Current object:', parser.getObjects());

  parser.write('.com"}, "preferences": {"theme": "dark", "notifications": tru');
  console.log('Chunk 2 received. Current object:', parser.getObjects());

  parser.write('e}, "items": ["apple", "banana", "orange"');
  console.log('Chunk 3 received. Current object:', parser.getObjects());

  parser.write(']}'); // Final closing bracket
  const finalResult = parser.getObjects();
  console.log('Final chunk received. Final object:', finalResult);

  // Demonstrating reset and reuse
  parser.reset();
  console.log('\n--- Parser reset for new data ---');
  parser.write('{"status": "complete", "code": 200}');
  console.log('New data parsed:', parser.getObjects());
}

parseStreamingJson();