# jsonrepair: turning broken JSON into parseable JSON instead of throwing

> A TypeScript library that fixes malformed JSON documents, from missing commas and single quotes through to truncated output, with a streaming mode for very large files.

**josdejong/jsonrepair** — Repair invalid JSON documents

- Repository: https://github.com/josdejong/jsonrepair
- Website: https://josdejong.github.io/jsonrepair/
- Stars: 2,408 · Forks: 91
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/josdejong-jsonrepair

## A long list of specific malformations, not general leniency

The README opens with an inventory of what gets fixed, and the inventory is the most useful part of the documentation. It adds missing quotes around keys, missing escape characters, missing commas and missing closing brackets. It repairs truncated JSON. It replaces single quotes with double quotes, replaces special quote characters such as curly quotes with regular double quotes, and replaces special whitespace characters with regular spaces.

It also handles the Python-shaped variants: `None`, `True` and `False` become `null`, `true` and `false`. Trailing commas are stripped, as are comments in both `/* */` and `//` form, fenced code blocks, and ellipsis in arrays and objects like `[1, 2, 3, ...]`.

Then there is the longer tail. JSONP notation such as `callback({ ... })` is stripped. Escape characters are removed from an escaped string like a double-encoded payload. MongoDB data types such as `NumberLong(2)` and `ISODate(...)` are stripped. Adjacent strings are concatenated, so a value split across lines with a `+` becomes one string.

The final item is the one that surprises people: newline delimited JSON is turned into a valid JSON array. Two objects on consecutive lines become an array containing both.

Every one of those is a malformation a specific tool produces. That is the difference between this library and a parser configured to be lenient, and it is why the error type still exists.

## The single function call, and what it returns

The regular API is one function. You pass in a string, and you either get back repaired JSON or an exception:

```ts
// @throws JSONRepairError 
jsonrepair(json: string) : string
```

In an ES module project the import is straightforward, and the README's example uses the exact case this library exists for, a fragment of a JavaScript object literal pasted into a tool that expects JSON:

```js
import { jsonrepair } from 'jsonrepair'

try {
  const json = "{name: 'John'}"
  
  const repaired = jsonrepair(json)
  
  console.log(repaired) // '{"name": "John"}'
} catch (err) {
  console.error(err)
}
```

The failure mode is deliberate. When the library meets something it cannot resolve it throws a `JSONRepairError` rather than guessing, so you find out that a document was too broken to interpret instead of receiving plausible-looking nonsense.

There is also a CommonJS entry point, and a UMD build for browsers, though the README marks both as not recommended in favour of the ES module version. The `package.json` confirms three separate builds are produced, with `main` pointing at the CommonJS output, `module` at the ESM output and `browser` at a minified UMD bundle.

## Streaming, and the buffer constraint that comes with it

The library has streaming support and can handle infinitely large documents, which is the capability that distinguishes it from a regular parser operating on a string.

The transform function is used in a Node stream pipeline, and both buffer sizes are configurable:

```ts
jsonrepairTransform(options?: { chunkSize?: number, bufferSize?: number }) : Transform
```

`chunkSize` sets the size of chunks the transform outputs and defaults to 65536 bytes; changing it can affect performance. `bufferSize` sets how many bytes of input and output are kept in memory, also defaulting to 65536 bytes.

The README explains why `bufferSize` has to exist at all, which is the part worth understanding. The transform must look ahead or look back to decide what to fix, and it sometimes has to walk back through generated output to insert a missing comma. That requires a moving window over both streams rather than a token at a time.

The constraint follows directly: `bufferSize` must be larger than the length of the largest string and the largest whitespace run in the data, otherwise an error is thrown. Making it very large costs memory and reduces performance. In practice this means a document containing a multi-megabyte string literal will fail in streaming mode until you raise the buffer, which is a real limit rather than a hypothetical one.

## Two implementations underneath, and that is a maintenance fact

The Develop section flags something that would otherwise be a surprise: there are currently two implementations of the library. `src/regular` is a non-streaming implementation, described as small and working for files up to 512MB, and identified as ideal for browser usage. `src/streaming` is the streaming implementation for Node.js, described as larger and more complex, using the configurable `bufferSize` and `chunkSize`.

That has a direct consequence. A behaviour fix has to be implemented twice, and until someone writes it in both places the two can disagree. The README documents this plainly rather than presenting the library as having a single code path, which is the kind of candour that saves a maintainer a support question later.

The README also notes that when the parsed document contains a string or number longer than the configured `bufferSize`, the library throws an Index out of range error because it cannot hold the full string in the buffer. That is a less graceful failure than `JSONRepairError`, and it is a consequence of the window design described above.

The project is not archived, the last push was on 2026-07-03, and the version in `package.json` is 3.15.0. There are no tagged releases listed on the repository, and 2,408 stars with 26 open issues indicates steady use with a manageable backlog.

## Where jsonrepair fits relative to a tolerant parser

The library names one alternative in the README, `dirty-json`, which is a reasonable point of comparison. The difference in approach is that a tolerant parser decides to accept non-standard input as a matter of policy, whereas jsonrepair rewrites the input into standards-compliant JSON and then hands it to an ordinary parser.

That has a practical upside in debugging. Because the output is valid JSON, anything downstream, a linter, a schema validator, a viewer, a database load, behaves normally. You have isolated the malformation rather than carrying a parser that tolerates it forever. It also means the repaired output is the artifact you can commit, inspect, or hand to someone else.

There is a real deployment to consider too. The author maintains a full application built on the library at jsoneditoronline.org, and the README points to a background article on fixing and validating JSON. Seeing the library inside a working tool is a reasonable way to judge whether it holds up outside its test fixtures.

The licensing position is one to note as well. The repository's detected licence is recorded as unknown rather than a specific permissive licence, while the tree contains a `LICENSE.md`. There is also a `CHANGELOG.md`. If you intend to ship this inside a product, confirm the terms with the author rather than relying on automated detection.

## Conclusion

jsonrepair sits in a specific place between a strict parser and a lenient one, and it is worth being precise about where that is. It does not accept anything, and it does not silently change values. It recognises a set of well-known malformations, each of which is common because a human or a language without a JSON serializer produced it, and it repairs those while still throwing a `JSONRepairError` when it meets something it cannot fix. That is the right trade for a debugging tool or a batch pipeline. The streaming mode with its `bufferSize` and `chunkSize` options is the part that lets it handle documents larger than memory, at the cost of a configuration constraint that trips people up. Start with the single function call, and read the Develop section before using the streaming path, because there are two implementations underneath.

## FAQ

### What is JSON repair?

It is taking a malformed JSON document and rewriting it into valid JSON. Most commonly it means fixing the specific mistakes that tools and humans produce: missing commas, unquoted keys, single quotes instead of double quotes, trailing commas, comments, Python constants such as `None` and `True`, or a document that was cut off partway through.

### How do I resolve a JSON parse error?

Read the position the parser reports, since it usually points at the malformation. If the document is machine-generated, fix the generator. If it is a fragment you pasted in, the missing piece is usually quotes around keys or commas between members. For a batch of files, this library repairs the whole set programmatically rather than one error at a time.

### Does jsonrepair always return valid JSON, or can it fail?

It can fail, by design. If it meets a problem it cannot resolve it throws a `JSONRepairError` rather than guessing, so you find out the document was too broken to interpret. The exception case is the streaming path, where a string longer than the configured `bufferSize` produces an Index out of range error instead.

### Can jsonrepair handle files too large to fit in memory?

Yes, through a streaming transform usable in a Node stream pipeline, with `chunkSize` and `bufferSize` options that both default to 65536 bytes. The buffer acts as a moving window because the repair sometimes needs to look ahead or walk back to insert a comma, and it must be larger than the largest string in the data.

## Sources

- [Issues](https://github.com/josdejong/jsonrepair/issues)
- [josdejong/jsonrepair on GitHub](https://github.com/josdejong/jsonrepair)
- [Project website](https://josdejong.github.io/jsonrepair/)
- [README](https://github.com/josdejong/jsonrepair/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/josdejong-jsonrepair