flat-json-diff

flat-json-diff
==============


An experimental library to diff JSON objects/arrays by flattening them. It can create a patch between two JSON objects/arrays, and apply the patch to another JSON object/array. Use by bookmark-to-gist.

Installation
------------

``
npm install flat-json-diff
`

Usage
-----

`JavaScript
import {createPatch, applyPatch} from "flat-json-diff";

const a = [
{title: "foo", tags: ["a", "b"]},
{title: "bar", tags: ["b", "c"]},
];
const b = [
{title: "foo", tags: ["a", "b", "d"]},
{title: "bar", tags: ["c"]},
{title: "baz", tags: []},
];
const patch = createPatch(a, b);
const c = applyPatch([
{title: "bak", tags: ["x"]},
{title: "foo", tags: []},
{title: "bar", tags: ["b"]},
], patch);
console.log(c);
// [
// { title: 'bak', tags: ["x"] }
// { title: 'foo', tags: ["d"] },
// { title: 'bar', tags: [] },
// { title: 'baz', tags: [] }
// ]
``

How it works
------------

The library flattens the JSON objects/arrays to diff-friendly lines, diffs the lines to create a patch.

When applying the patch, it flattens the target object/array to lines, apply the patch to the lines, and finally unflattens it back to JSON.

Limitations
-----------

There are some limitations: https://github.com/kpdecker/jsdiff

> Regardless of fuzzFactor, lines to be deleted in the hunk must be present for a hunk to match, and the context lines immediately before and after an insertion must match exactly.

1. Modifying a deleted line/Deleting a modified line will always fail.
2. When adding property, the property before/after the changed property must be the same. Ideally, adding an object property should always succeed.

API references
--------------

Check the .d.ts file for TypeScript type definitions.

Alternatives
------------

Because I'm working with bookmark JSON diff, it is crucial to detect move operations. Also bookmarks don't have an object ID, so most of the simple solutions won't work well.

* diff: The underlying diff library used in this project. It is designed for text diff.

Other json diff tools:

* rfc6902: Support remove, add, replace.
* mini-rfc6902: A minimal RFC6902 implementation.
* json-diff-ts: Support object ID. No move operation.
* diffptch: Treats arrays as non-ordered set.
* json-diff-kit: Support multiple array diff methods. No move operation.
* jsondiffpatch: Probably the most robust JSON diff library. Uses object hash to detect move operations.

The best solution should be something like:

1. Suppose we have three versions: A -> B, A -> C, and we need a merge of B and C.
2. Diff A -> B to get a patch P1.
3. Diff A -> C to get a patch P2.
4. According the information on A, merge P1 and P2 to get P3.
5. Apply P3 to A to get the merged result.

When diffing arrays, it should calculate the smallest changes between two arrays, considering move, add, delete, and modify operations, with munkres or similar algorithms.

Changelog
---------

* 0.1.1 (Nov 28, 2025)

- Fix: include types.

* 0.1.0 (Nov 28, 2025)

- First release