unclosed 1.0.0

package/dist/types/parse.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Tolerant JSON parser for incomplete ("unclosed") input.
+ *
+ * The parser reads as much of a JSON document as is present and closes any
+ * containers that were still open when the input ended. It never guesses at
+ * data it has not seen: a truncated object key, a half-written escape sequence
+ * or an unrecoverable number is dropped rather than invented.
+ *
+ * Zero dependencies. No configuration files. No runtime requirements beyond
+ * ES2020.
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface ParseOptions {
+    /**
+     * Keep the received prefix of a string that has not been closed yet.
+     * Disable to drop unterminated strings entirely. Default: `true`.
+     */
+    partialStrings?: boolean;
+    /**
+     * Resolve truncated literals (`tru` -> `true`, `nul` -> `null`).
+     * Default: `true`.
+     */
+    partialLiterals?: boolean;
+    /**
+     * Skip Markdown code fences and any prose before the first `{` or `[`.
+     * Default: `true`.
+     */
+    scan?: boolean;
+}
+export interface ParseResult<T = Json> {
+    /** Best-effort value, or `undefined` when nothing could be recovered. */
+    value: T | undefined;
+    /** `true` when the input contained a whole, untruncated JSON value. */
+    complete: boolean;
+    /**
+     * Path to the node that was still being written when the input ended,
+     * or `null` when the value is complete. Useful for skipping fields that
+     * are not final yet.
+     */
+    incompletePath: Array<string | number> | null;
+}
+/** Thrown for input that is malformed rather than merely unfinished. */
+export declare class UnclosedError extends SyntaxError {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/**
+ * Strip Markdown fences and leading prose so that model output such as
+ * "Sure! ```json\n{..." parses without pre-processing on the caller's side.
+ */
+export declare function scanToJson(input: string): string;
+/**
+ * Parse possibly-incomplete JSON and report how much of it is final.
+ *
+ * @throws {UnclosedError} when the input is malformed rather than unfinished.
+ */
+export declare function parseWithMeta<T = Json>(input: string, options?: ParseOptions): ParseResult<T>;
+/**
+ * Parse possibly-incomplete JSON.
+ *
+ * Returns `undefined` when no value could be recovered at all.
+ *
+ * @throws {UnclosedError} when the input is malformed rather than unfinished.
+ */
+export declare function parse<T = Json>(input: string, options?: ParseOptions): T | undefined;
+/** Parse without throwing. Returns `undefined` on malformed input. */
+export declare function tryParse<T = Json>(input: string, options?: ParseOptions): T | undefined;
+/** `true` when the input holds one whole, untruncated JSON value. */
+export declare function isComplete(input: string, options?: ParseOptions): boolean;
+/**
+ * Turn possibly-incomplete JSON into a valid JSON string.
+ *
+ * @throws {UnclosedError} when the input is malformed rather than unfinished.
+ */
+export declare function repair(input: string, options?: ParseOptions): string;

package/dist/types/stream.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Incremental helpers for feeding model output in as it arrives.
+ */
+import type { Json, ParseOptions, ParseResult } from "./parse.js";
+export interface StreamSnapshot<T = Json> extends ParseResult<T> {
+    /** Raw text received so far. */
+    text: string;
+}
+/**
+ * Accumulates chunks and exposes the best-effort value after each one.
+ *
+ * ```ts
+ * const acc = new PartialJson()
+ * for await (const chunk of tokens) {
+ *   const snapshot = acc.push(chunk)
+ *   render(snapshot.value)
+ * }
+ * ```
+ */
+export declare class PartialJson<T = Json> {
+    private buffer;
+    private snapshot;
+    private readonly options;
+    constructor(options?: ParseOptions);
+    /** Append a chunk and return the current snapshot. */
+    push(chunk: string): StreamSnapshot<T>;
+    /** Latest best-effort value. */
+    get value(): T | undefined;
+    /** `true` once a whole JSON value has been received. */
+    get complete(): boolean;
+    /** Path of the node still being written, or `null`. */
+    get incompletePath(): Array<string | number> | null;
+    /** Everything received so far. */
+    get text(): string;
+    /** Clear all state so the instance can be reused. */
+    reset(): void;
+}
+export interface StreamOptions extends ParseOptions {
+    /**
+     * Only yield when the parsed value actually changed, instead of once per
+     * chunk. Default: `true`.
+     */
+    onlyOnChange?: boolean;
+}
+/**
+ * Turn a stream of text chunks into a stream of progressively complete values.
+ *
+ * ```ts
+ * for await (const { value, complete } of parseStream(tokens)) {
+ *   render(value)
+ * }
+ * ```
+ */
+export declare function parseStream<T = Json>(source: AsyncIterable<string> | Iterable<string>, options?: StreamOptions): AsyncGenerator<StreamSnapshot<T>, void, void>;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "unclosed",
+  "version": "1.0.0",
+  "description": "Parse JSON that hasn't finished arriving yet. Zero dependencies, built for streaming LLM output.",
+  "keywords": [
+    "json",
+    "partial",
+    "incomplete",
+    "streaming",
+    "parser",
+    "llm",
+    "openai",
+    "anthropic",
+    "tolerant",
+    "repair",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "test": "npm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OWNER/unclosed.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OWNER/unclosed/issues"
+  },
+  "homepage": "https://github.com/OWNER/unclosed#readme"
+}