{"id":15651,"library":"incomplete-json-parser","title":"Incomplete JSON Parser","description":"incomplete-json-parser is a TypeScript module designed to robustly parse JSON strings that may be incomplete, chunked, or arriving in a streaming fashion. It provides an `IncompleteJsonParser` class and a static `parse` method to handle scenarios where standard `JSON.parse` would fail due to premature termination or fragmented input. The library, currently at version `1.1.5`, allows developers to incrementally feed JSON data via a `write` method and retrieve the most complete possible JavaScript object at any point using `getObjects()`. This makes it particularly suitable for processing real-time data streams, large file parsing, or handling responses from APIs that might send data in chunks or terminate early (e.g., during AI model responses). While a precise release cadence isn't defined, its versioning indicates active development and minor updates. A key differentiator is its fault tolerance, aiming to yield valid partial results even from highly fragmented inputs, unlike strict parsers that would immediately throw errors.","status":"active","version":"1.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/1000ship/incomplete-json-parser","tags":["javascript","json","parser","stream","streaming","incomplete","fragment","typescript"],"install":[{"cmd":"npm install incomplete-json-parser","lang":"bash","label":"npm"},{"cmd":"yarn add incomplete-json-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add incomplete-json-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const IncompleteJsonParser = require('incomplete-json-parser');","symbol":"IncompleteJsonParser","correct":"import { IncompleteJsonParser } from 'incomplete-json-parser';"},{"note":"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.","wrong":"import { parse } from 'incomplete-json-parser';","symbol":"IncompleteJsonParser.parse","correct":"const result = IncompleteJsonParser.parse('{\"data\": \"value\"');"},{"note":"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.","symbol":"IncompleteJsonParser (type)","correct":"import type { IncompleteJsonParser } from 'incomplete-json-parser';"}],"quickstart":{"code":"import { IncompleteJsonParser } from 'incomplete-json-parser';\n\nasync function parseStreamingJson() {\n  const parser = new IncompleteJsonParser();\n\n  console.log('--- Initializing streaming JSON parsing ---');\n\n  // Simulate receiving data in multiple, incomplete chunks\n  parser.write('{\"user\": {\"id\": 123, \"name\": \"Alice\", \"email\": \"alice@example');\n  console.log('Chunk 1 received. Current object:', parser.getObjects());\n\n  parser.write('.com\"}, \"preferences\": {\"theme\": \"dark\", \"notifications\": tru');\n  console.log('Chunk 2 received. Current object:', parser.getObjects());\n\n  parser.write('e}, \"items\": [\"apple\", \"banana\", \"orange\"');\n  console.log('Chunk 3 received. Current object:', parser.getObjects());\n\n  parser.write(']}'); // Final closing bracket\n  const finalResult = parser.getObjects();\n  console.log('Final chunk received. Final object:', finalResult);\n\n  // Demonstrating reset and reuse\n  parser.reset();\n  console.log('\\n--- Parser reset for new data ---');\n  parser.write('{\"status\": \"complete\", \"code\": 200}');\n  console.log('New data parsed:', parser.getObjects());\n}\n\nparseStreamingJson();","lang":"typescript","description":"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."},"warnings":[{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `parser.reset()` is invoked whenever a new, independent JSON stream or string begins using the same parser instance.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ESM, ensure `import { IncompleteJsonParser } from 'incomplete-json-parser';` is used. For CommonJS, use `const { IncompleteJsonParser } = require('incomplete-json-parser');`.","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.","error":"TypeError: IncompleteJsonParser is not a constructor"},{"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.","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.","error":"Parsed object is empty or does not reflect recent `write()` calls."},{"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.","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.","error":"Resulting object contains unexpected partial or malformed data that was expected to be completed."}],"ecosystem":"npm"}