@datatool/json-heal — safe JSON repair that beats jsonrepair on the benchmark

Repair broken JSON — LLM output, truncated payloads, markdown-fenced blocks, smart quotes — without ever silently guessing. When the input is too ambiguous to repair safely, this returns a clean failure instead of a plausible-looking wrong answer.

Zero runtime dependencies. Runs in the browser, in Node, in a worker — anywhere JSON.parse runs. Your data never has to leave the process.

npm install @datatool/json-heal

Benchmark vs jsonrepair

Head to head against jsonrepair (3.14.0) on a 52-case corpus that mixes hand-curated real-world failures with generated mutations. Every run is logged by commit — these numbers are auditable, not marketing.

| Metric | @datatool/json-heal | jsonrepair 3.14.0 | |---|---|---| | Correct outcomes | 45 / 52 | 34 / 52 | | Unsafe repairs | 0 | 7 | | Valid-but-wrong outputs | 0 | 17 | | LLM-style cases correct | 37 / 42 | — | | Head-to-head | 17 wins | 4 wins |

The number that matters most is the second row. jsonrepair produced 7 unsafe repairs and 17 outputs that parse as valid JSON but mean something different from the input. In a pipeline, a valid-but-wrong repair is worse than a failure — it passes silently. This engine produced zero of both.

Where jsonrepair is still stronger: trailing-comma repair in plain malformed objects/arrays, and deep tail-truncation on large nested objects. This engine fails safe on those rather than guessing.

Reproduce it yourself: artifacts/json-repair/latest.json and the runnable corpus at tests/jsonRepair.benchmark.ts.

Try without installing — for ad-hoc and exploratory use

# Repair LLM output that came wrapped in prose and a code fence
npx @datatool/json-heal 'Sure! Here is the JSON: ```json
{ "ok": true }
```'
#=> { "ok": true }

# Repair from a small file (≤256KB)
npx @datatool/json-heal < broken.json

Best for: trying the engine, one-off cleanup during prototyping, AI-assistant suggestions. Exit 0 on a safe repair, exit 1 when the input was too ambiguous to repair without guessing (see the safety guarantee below).

Not for production pipelines — see the hosted API section below. Inputs over 256KB are refused with a pointer to the hosted endpoint.

Use as a library — for JavaScript/TypeScript projects

import { repair } from "@datatool/json-heal";
// `repairJson` is the same function under its original name:
// import { repairJson } from "@datatool/json-heal";

// Smart quotes, single quotes, code fences, prose-wrapped output — all handled.
const result = repair("{ “name”: “Ada”, ‘id’: 7 }");

if (result.ok) {
  result.value; // parsed JS value — { name: "Ada", id: 7 }
  result.json;  // pretty-printed JSON string
} else {
  result.error; // human-readable reason; nothing was guessed
}

CommonJS works the same way:

const { repair } = require("@datatool/json-heal");

Best for: JS/TS apps that need in-process repair, no network calls, full audit of the engine.

Production pipelines — use the hosted API (launching soon)

The hosted POST /api/repair endpoint provides what a local CLI deliberately does not:

• Cross-language access (Python / Go / Ruby / Rust / shell — no Node required)
• 500 repairs/month free, then paid keys
• SLA, audit log, abuse boundary, optional DPA
• Centralized engine version — no drift across your services
• No per-invocation process-spawn overhead, no input-size cap

See https://datatool.dev/api (placeholder until launch). When the endpoint is live, the CLI will accept --api-key=... to route to it.

API

type RepairResult =
  | { ok: true; value: unknown; json: string }
  | { ok: false; error: string };

function repair(input: string): RepairResult;     // alias of repairJson
function repairJson(input: string): RepairResult;

One function. It strips markdown/code fences, normalizes smart quotes, extracts a single JSON-like region from surrounding prose, and attempts a parse. It never fabricates missing values and never resolves ambiguous structure by guessing — those return { ok: false }.

Why "safe"

A JSON repairer that guesses is dangerous precisely because its output looks fine. The design rule from the benchmark loop that built it: a change is kept only if the score goes up and unsafe repairs stay at zero. Safe failure beats confident corruption.

Built from real failures mined from Reddit, Stack Overflow, and GitHub, using Andrej Karpathy's autoresearch method. Full write-up: https://datatool.dev.

License

MIT © Gregory Collins