@vantezzen/streamable-json

A small (<6kB, <2kB gzipped) JSON parser for streamed/possibly incomplete JSON data.

@vantezzen/streamable-json is a TypeScript library that provides a JSON parser capable of handling streamed or incomplete JSON data. This is particularly useful if you get JSON from an LLM or slow, chunked sources where you can still handle partial data.

Demo: https://vantezzen.github.io/streamable-json/

Installation

You can install the package:

npm i @vantezzen/streamable-json
yarn add @vantezzen/streamable-json
pnpm add @vantezzen/streamable-json
bun add @vantezzen/streamable-json

Usage

Simply provide parse(yourJsonString) and it will return the parsed JSON object, even if the JSON string is incomplete.

import parse, { type DeepPartial } from "@vantezzen/streamable-json";

const data = parse(myJsonString) as DeepPartial<MyType>;

API

parse(jsonString, config?)

The main function for parsing JSON strings. Handles incomplete/partial JSON gracefully.

import parse from "@vantezzen/streamable-json";

const result = parse('{"name": "John", "age": 30}');
// { name: "John", age: 30 }

// Partial JSON also works
const partial = parse('{"name": "John", "ag');
// { name: "John" }

Parameters:

| Parameter | Type | Description | | ------------ | ----------------------- | -------------------------------------------- | | jsonString | string | The JSON string to parse (can be incomplete) | | config | Partial<ParserConfig> | Optional configuration options |

Returns: unknown - The parsed JSON value, or undefined if parsing fails

ParserConfig

Configuration options for the parser:

type ParserConfig = {
  allowPartialStrings?: boolean;
  allowPartialNumbers?: boolean;
};

| Option | Type | Default | Description | | --------------------- | --------- | ------- | -------------------------------------------------------------------------- | | allowPartialStrings | boolean | false | Include strings that are not yet closed (missing ending ") | | allowPartialNumbers | boolean | false | Include numbers that may be incomplete (e.g., 123 when expecting 1234) |

Example with options:

import parse from "@vantezzen/streamable-json";

// Without allowPartialStrings (default)
parse('{"name": "Joh');
// { } - incomplete string is excluded

// With allowPartialStrings
parse('{"name": "Joh', { allowPartialStrings: true });
// { name: "Joh" } - incomplete string is included

Parser class

For more control, you can use the Parser class directly:

import { Parser } from "@vantezzen/streamable-json";

const parser = new Parser('{"key": "value"}', {
  allowPartialStrings: true,
});
const result = parser.parse();

Constructor:

new Parser(sourceContent: string, config?: ParserConfig)

Methods:

| Method | Returns | Description | | --------- | --------- | ---------------------------------------------------------------------------- | | parse() | Element | Parses the JSON and returns the result. Results are cached after first call. |

Types

Element

The type representing any valid JSON element:

type Element =
  | string
  | number
  | boolean
  | null
  | object
  | Element[]
  | undefined;

DeepPartial<T>

A utility type that makes all properties of an object (and nested objects) optional. Useful for typing parsed results from incomplete JSON:

import parse, { type DeepPartial } from "@vantezzen/streamable-json";

interface User {
  name: string;
  profile: {
    age: number;
    email: string;
  };
}

const data = parse(incompleteJson) as DeepPartial<User>;
// data.name might be undefined
// data.profile?.age might be undefined

Development

To install dependencies:

bun install && cd example && bun install

To run:

bun test # run the JSON test suite
bun start # Run the stream demo - this will parse example.json in 10% increments

bun run dev # in the example directory

To build:

bun run build