Registry / serialization / incomplete-json-parser

incomplete-json-parser

library1.1.5jsnpmunverified

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.

serialization http-networking

npm install incomplete-json-parser

package ↗

INSTALL

IMPORT

SIG · INCOMPLETE-JSON-PA

incomplete-json-parser

serializationjavascriptv1.1.5

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.

IncompleteJsonParser

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

✗ const IncompleteJsonParser = require('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

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

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

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.

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

Debug

Known issues

gotchaIncomplete 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()`.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaThis 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: IncompleteJsonParser is not a constructor

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.

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.

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.

Upgrade

Version history

1.1.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/incomplete-json-parser ↗