partial-json-stream 🚀

Ultra-fast, zero-dependency incremental state-machine parser & repair engine for streaming partial JSON (LLM token streams).

Available natively for both npm (Node.js, TypeScript, Browser, Edge/Cloudflare Workers) and PyPI (Python 3.8+).

Features

• ⚡ Zero-Dependency: Pure lightweight state machine with zero transitive package risk.
• 🔄 Incremental Push Parsing: Amortized $O(N)$ streaming token consumption instead of $O(N^2)$ full string re-parsing.
• 🛠️ Tolerant & Self-Healing: Automatically repairs:
  • Unclosed objects ({) and arrays ([)
  • Truncated strings and escaped characters (\)
  • Trailing commas ([1, 2, 3,])
  • Single quotes ('key': 'value')
  • Unquoted keys ({ name: "Alice" })
  • Truncated booleans/null (tr -> true, nul -> null)
  • Python literals (True, False, None)
• 🌐 Dual-Ecosystem Parity: Identical behavior and ergonomic API surface across TypeScript and Python.

Quick Install

npm (TypeScript / JavaScript):

npm install partial-json-stream

PyPI (Python):

pip install partial-json-stream

Usage

TypeScript / Node.js

import { PartialJsonStream, parsePartialJson } from 'partial-json-stream';

// Option 1: Incremental Push Stream Handler
const stream = new PartialJsonStream();

// Push token chunks as they arrive from LLM / SSE response
stream.push('{"user": {"name": "Alice",');
stream.push(' "skills": ["ts", "py"');

const currentObject = stream.push(']}}');
console.log(currentObject);
// Output: { user: { name: 'Alice', skills: ['ts', 'py'] } }

// Option 2: Direct Partial Parse
const partialSnippet = '{"message": "Hello \\"world';
const parsed = parsePartialJson(partialSnippet);
console.log(parsed); // { message: 'Hello "world' }

Python

from partial_json_stream import PartialJsonStream, parse_partial_json

# Option 1: Incremental Push Stream Handler
stream = PartialJsonStream()

stream.push('{"user": {"name": "Alice",')
stream.push(' "skills": ["ts", "py"')

current_object = stream.push(']}}')
print(current_object)
# Output: {'user': {'name': 'Alice', 'skills': ['ts', 'py']}}

# Option 2: Direct Partial Parse
partial_snippet = '{"message": "Hello \\"world'
parsed = parse_partial_json(partial_snippet)
print(parsed) # {'message': 'Hello "world'}

License

MIT © nhemlos