partial-json

The Allow object is an Enum used to control which types of data can be returned in a partial state. You pass these constants to the parse function using a bitwise OR (|).

If a type is not included in the allow bitmask, the parser will only include that value in the result once it is fully completed. For example, if you only allow OBJ but not STR, an incomplete string inside an object will cause that key to be omitted entirely until the string is closed.

import { parse, OBJ, STR } from "partial-json";

// Without STR, the key is omitted because the value is incomplete
const result1 = parse('{"key": "v', OBJ);
console.log(result1); // Outputs: {}

// With STR, the partial value is captured
const result2 = parse('{"key": "v', STR | OBJ);
console.log(result2); // Outputs: { key: 'v' }

Install the library using your preferred package manager:

npm i partial-json

partial-json is implemented in pure JavaScript and provides both commonjs and esm builds.

npm i partial-json # or pnpm / bun / yarn

If the input string is truly malformed (not just partial, but syntactically invalid in a way the parser cannot recover from), parse will throw a MalformedJSON [Error] containing a SyntaxError message.

// This will throw an error
parse("wrong"); 
// Error: MalformedJSON [Error]: SyntaxError: Unexpected token 'w', "wrong" is not valid JSON at position 0

The parse function allows you to decode JSON strings that are incomplete (e.g., during LLM streaming). When a JSON string is incomplete, parse can return the data it has successfully gathered so far, provided you specify which types of partial data are allowed using the Allow object constants.

import { parse, STR, OBJ } from "partial-json";

// Returns partial data if STR and OBJ are allowed
const result = parse('{"key": "v', STR | OBJ);
console.log(result); // Outputs: { key: 'v' }

The Allow object contains bitwise constants that define which partial types are acceptable during parsing. You can import these directly from partial-json.

// Available constants in the Allow object:
// STR: Allow partial string.
// NUM: Allow partial number.
// ARR: Allow partial array.
// OBJ: Allow partial object.
// NULL: Allow partial null.
// BOOL: Allow partial boolean.
// NAN: Allow partial NaN.
// INFINITY: Allow partial Infinity.
// _INFINITY: Allow partial -Infinity.
// INF: Allow both partial Infinity and -Infinity.
// SPECIAL: Allow all special values.
// ATOM: Allow all atomic values.
// COLLECTION: Allow all collection values.
// ALL: Allow all values (default).

When using parse or parseJSON, you should handle two specific error classes to distinguish between incomplete data and invalid syntax:

• PartialJSON: Thrown when the input ends prematurely but the allow parameter permits the current state (e.g., an unterminated string or object).
• MalformedJSON: Thrown when the input contains syntax that is fundamentally invalid and cannot be parsed even as a partial structure.

Both errors include the error message and the character position where the issue was detected.

import { parse, PartialJSON, MalformedJSON } from 'partial-json';

try {
  const data = parse('{"key": "val');
} catch (e) {
  if (e instanceof PartialJSON) {
    console.error('JSON is incomplete:', e.message);
  } else if (e instanceof MalformedJSON) {
    console.error('JSON is invalid:', e.message);
  }
}

The primary function for decoding JSON strings.

/**
 * @param jsonString <string> - The JSON string to parse.
 * @param allowPartial <number> - Specify what kind of partialness is allowed (default: Allow.ALL).
 * @returns The parsed JavaScript value.
 */
function parse(jsonString: string, allowPartial?: number): any;