json-diff-ts

Why Index-Based Diffing Breaks

Remove /items/0 ← was actually "Widget"
Add /items/0 ← now it's "NewItem"
Update /items/1 ← this used to be /items/0
...

import { diffAtom, applyAtom, revertAtom } from 'json-diff-ts';
const before = {
 items: [
 { id: 1, name: 'Widget', price: 9.99 },
 { id: 2, name: 'Gadget', price: 24.99 },
 ],
};
const after = {
 items: [
 { id: 2, name: 'Gadget', price: 24.99 }, // reordered
 { id: 1, name: 'Widget Pro', price: 14.99 }, // renamed + repriced
 { id: 3, name: 'Doohickey', price: 4.99 }, // added
 ],
};
const atom = diffAtom(before, after, { arrayIdentityKeys: { items: 'id' } });

{
 "format": "json-atom",
 "version": 1,
 "operations": [
 { "op": "replace", "path": "$.items[?(@.id==1)].name", "value": "Widget Pro", "oldValue": "Widget" },
 { "op": "replace", "path": "$.items[?(@.id==1)].price", "value": 14.99, "oldValue": 9.99 },
 { "op": "add", "path": "$.items[?(@.id==3)]", "value": { "id": 3, "name": "Doohickey", "price": 4.99 } }
 ]
}

// Clone before applying — applyAtom mutates the input object
const updated = applyAtom(structuredClone(before), atom); // updated === after
const restored = revertAtom(structuredClone(updated), atom); // restored === before

Quick Start

import { diffAtom, applyAtom, revertAtom } from 'json-diff-ts';
const oldObj = {
 items: [
 { id: 1, name: 'Widget', price: 9.99 },
 { id: 2, name: 'Gadget', price: 24.99 },
 ],
};
const newObj = {
 items: [
 { id: 1, name: 'Widget Pro', price: 9.99 },
 { id: 2, name: 'Gadget', price: 24.99 },
 { id: 3, name: 'Doohickey', price: 4.99 },
 ],
};
// 1. Compute an atom between two JSON objects
const atom = diffAtom(oldObj, newObj, {
 arrayIdentityKeys: { items: 'id' }, // match array elements by 'id' field
});
// atom.operations =>
// [
// { op: 'replace', path: '$.items[?(@.id==1)].name', value: 'Widget Pro', oldValue: 'Widget' },
// { op: 'add', path: '$.items[?(@.id==3)]', value: { id: 3, name: 'Doohickey', price: 4.99 } }
// ]
// 2. Apply the atom to produce the new state
const updated = applyAtom(structuredClone(oldObj), atom);
// 3. Revert the atom to restore the original state
const reverted = revertAtom(structuredClone(updated), atom);

Installation

npm install json-diff-ts

// ESM / TypeScript
import { diffAtom, applyAtom, revertAtom } from 'json-diff-ts';
// CommonJS
const { diffAtom, applyAtom, revertAtom } = require('json-diff-ts');

What is JSON Atom?

json-atom-format (specification)
 ├── json-diff-ts (TypeScript implementation) ← this package
 └── json-atom-py (Python implementation)

JSON Atom vs JSON Patch (RFC 6902)

JSON Atom API

diffAtom -- Compute an Atom

const atom = diffAtom(
 { user: { name: 'Alice', role: 'viewer' } },
 { user: { name: 'Alice', role: 'admin' } }
);
// atom.operations → [{ op: 'replace', path: '$.user.role', value: 'admin', oldValue: 'viewer' }]

Keyed Arrays

const atom = diffAtom(
 { users: [{ id: 1, role: 'viewer' }, { id: 2, role: 'editor' }] },
 { users: [{ id: 1, role: 'admin' }, { id: 2, role: 'editor' }] },
 { arrayIdentityKeys: { users: 'id' } }
);
// atom.operations → [{ op: 'replace', path: '$.users[?(@.id==1)].role', value: 'admin', oldValue: 'viewer' }]

Non-reversible Mode

const atom = diffAtom(source, target, { reversible: false });

applyAtom -- Apply an Atom

const result = applyAtom(structuredClone(source), atom);

revertAtom -- Revert an Atom

const original = revertAtom(structuredClone(target), atom);

invertAtom -- Compute the Inverse

const inverse = invertAtom(atom);
// add ↔ remove, replace swaps value/oldValue, order reversed

validateAtom -- Validate Structure

const { valid, errors } = validateAtom(maybeAtom);

API Reference

AtomOptions

interface AtomOptions extends Options {
 reversible?: boolean; // Include oldValue for undo. Default: true
 arrayIdentityKeys?: Record<string, string | FunctionKey>;
 keysToSkip?: readonly string[];
}

Atom Workflow Helpers

squashAtoms -- Compact Multiple Atoms

import { diffAtom, applyAtom, squashAtoms } from 'json-diff-ts';
const source = { name: 'Alice', role: 'viewer' };
const d1 = diffAtom(source, { name: 'Bob', role: 'viewer' });
const d2 = diffAtom({ name: 'Bob', role: 'viewer' }, { name: 'Bob', role: 'admin' });
const squashed = squashAtoms(source, [d1, d2]);
// squashed.operations => [
// { op: 'replace', path: '$.name', value: 'Bob', oldValue: 'Alice' },
// { op: 'replace', path: '$.role', value: 'admin', oldValue: 'viewer' }
// ]
// Verify: applying the squashed atom equals applying both sequentially
const result = applyAtom(structuredClone(source), squashed);
// result => { name: 'Bob', role: 'admin' }

atomMap / atomStamp / atomGroupBy -- Atom Transformations

import { diffAtom, atomMap, atomStamp, atomGroupBy } from 'json-diff-ts';
const atom = diffAtom(
 { name: 'Alice', age: 30, role: 'viewer' },
 { name: 'Bob', age: 31, status: 'active' }
);
// Stamp metadata onto every operation
const stamped = atomStamp(atom, { x_author: 'system', x_ts: Date.now() });
// Transform operations
const prefixed = atomMap(atom, (op) => ({
 ...op,
 path: op.path.replace('$', '$.data'),
}));
// Group by operation type
const groups = atomGroupBy(atom, (op) => op.op);
// groups => { replace: IJsonAtom, add: IJsonAtom, remove: IJsonAtom }

operationSpecDict / atomSpecDict -- Spec Introspection

import { operationSpecDict, operationExtensions, atomSpecDict } from 'json-diff-ts';
const op = { op: 'replace', path: '$.name', value: 'Bob', x_author: 'system' };
operationSpecDict(op); // { op: 'replace', path: '$.name', value: 'Bob' }
operationExtensions(op); // { x_author: 'system' }
// Strip all extensions from an atom
const clean = atomSpecDict(atom);

leafProperty -- Path Introspection

import { leafProperty } from 'json-diff-ts';
leafProperty({ op: 'replace', path: '$.user.name' }); // 'name'
leafProperty({ op: 'add', path: '$.items[?(@.id==1)]' }); // null (filter)
leafProperty({ op: 'replace', path: '$' }); // null (root)

Comparison Serialization

import { compare, comparisonToDict, comparisonToFlatList } from 'json-diff-ts';
const result = compare(
 { name: 'Alice', age: 30, role: 'viewer' },
 { name: 'Bob', age: 30, status: 'active' }
);
// Recursive plain object
const dict = comparisonToDict(result);
// {
// type: 'CONTAINER',
// value: {
// name: { type: 'UPDATE', value: 'Bob', oldValue: 'Alice' },
// age: { type: 'UNCHANGED', value: 30 },
// role: { type: 'REMOVE', oldValue: 'viewer' },
// status: { type: 'ADD', value: 'active' }
// }
// }
// Flat list of leaf changes with paths
const flat = comparisonToFlatList(result);
// [
// { path: '$.name', type: 'UPDATE', value: 'Bob', oldValue: 'Alice' },
// { path: '$.role', type: 'REMOVE', oldValue: 'viewer' },
// { path: '$.status', type: 'ADD', value: 'active' }
// ]
// Include unchanged entries
const all = comparisonToFlatList(result, { includeUnchanged: true });

Practical Examples

Audit Log

import { diffAtom, applyAtom, revertAtom, IJsonAtom } from 'json-diff-ts';
interface AuditEntry {
 timestamp: string;
 userId: string;
 atom: IJsonAtom;
}
const auditLog: AuditEntry[] = [];
let doc = {
 title: 'Project Plan',
 status: 'draft',
 items: [
 { id: 1, task: 'Design', done: false },
 { id: 2, task: 'Build', done: false },
 ],
};
function updateDocument(newDoc: typeof doc, userId: string) {
 const atom = diffAtom(doc, newDoc, {
 arrayIdentityKeys: { items: 'id' },
 });
 if (atom.operations.length > 0) {
 auditLog.push({ timestamp: new Date().toISOString(), userId, atom });
 doc = applyAtom(structuredClone(doc), atom);
 }
 return doc;
}
// Revert the last change
function undo(): typeof doc {
 const last = auditLog.pop();
 if (!last) return doc;
 doc = revertAtom(structuredClone(doc), last.atom);
 return doc;
}
// Example usage:
updateDocument(
 { ...doc, status: 'active', items: [{ id: 1, task: 'Design', done: true }, ...doc.items.slice(1)] },
 'alice'
);
// auditLog[0].atom.operations =>
// [
// { op: 'replace', path: '$.status', value: 'active', oldValue: 'draft' },
// { op: 'replace', path: '$.items[?(@.id==1)].done', value: true, oldValue: false }
// ]

Undo / Redo Stack

import { diffAtom, applyAtom, revertAtom, IJsonAtom } from 'json-diff-ts';
class UndoManager<T extends object> {
 private undoStack: IJsonAtom[] = [];
 private redoStack: IJsonAtom[] = [];
 constructor(private state: T) {}
 apply(newState: T): T {
 const atom = diffAtom(this.state, newState);
 if (atom.operations.length === 0) return this.state;
 this.undoStack.push(atom);
 this.redoStack = [];
 this.state = applyAtom(structuredClone(this.state), atom);
 return this.state;
 }
 undo(): T {
 const atom = this.undoStack.pop();
 if (!atom) return this.state;
 this.redoStack.push(atom);
 this.state = revertAtom(structuredClone(this.state), atom);
 return this.state;
 }
 redo(): T {
 const atom = this.redoStack.pop();
 if (!atom) return this.state;
 this.undoStack.push(atom);
 this.state = applyAtom(structuredClone(this.state), atom);
 return this.state;
 }
}

Data Synchronization

import { diffAtom, applyAtom, validateAtom } from 'json-diff-ts';
// Client side: compute and send atom
const atom = diffAtom(localState, updatedState, {
 arrayIdentityKeys: { records: 'id' },
});
await fetch('/api/sync', {
 method: 'POST',
 body: JSON.stringify(atom),
});
// Server side: validate and apply
const result = validateAtom(req.body);
if (!result.valid) return res.status(400).json(result.errors);
// ⚠️ In production, sanitize paths/values to prevent prototype pollution
// (e.g. reject paths containing "__proto__" or "constructor")
currentState = applyAtom(structuredClone(currentState), req.body);

Bridge: v4 Changeset <-> JSON Atom

import { diff, toAtom, fromAtom, unatomizeChangeset } from 'json-diff-ts';
// v4 changeset → JSON Atom
const changeset = diff(source, target, { arrayIdentityKeys: { items: 'id' } });
const atom = toAtom(changeset);
// JSON Atom → v4 atomic changes
const atoms = fromAtom(atom);
// v4 atomic changes → hierarchical changeset (if needed)
const cs = unatomizeChangeset(atoms);

Legacy Changeset API (v4 Compatibility)

diff

import { diff } from 'json-diff-ts';
const oldData = {
 location: 'Tatooine',
 characters: [
 { id: 'LUKE', name: 'Luke Skywalker', role: 'Farm Boy' },
 { id: 'LEIA', name: 'Princess Leia', role: 'Prisoner' }
 ],
};
const newData = {
 location: 'Yavin Base',
 characters: [
 { id: 'LUKE', name: 'Luke Skywalker', role: 'Pilot', rank: 'Commander' },
 { id: 'HAN', name: 'Han Solo', role: 'Smuggler' }
 ],
};
const changes = diff(oldData, newData, { arrayIdentityKeys: { characters: 'id' } });

applyChangeset and revertChangeset

import { applyChangeset, revertChangeset } from 'json-diff-ts';
const updated = applyChangeset(structuredClone(oldData), changes);
const reverted = revertChangeset(structuredClone(newData), changes);

atomizeChangeset and unatomizeChangeset

import { atomizeChangeset, unatomizeChangeset } from 'json-diff-ts';
const atoms = atomizeChangeset(changes);
// [
// { type: 'UPDATE', key: 'location', value: 'Yavin Base', oldValue: 'Tatooine',
// path: '$.location', valueType: 'String' },
// { type: 'ADD', key: 'rank', value: 'Commander',
// path: "$.characters[?(@.id=='LUKE')].rank", valueType: 'String' },
// ...
// ]
const restored = unatomizeChangeset(atoms.slice(0, 2));

Advanced Options

Key-based Array Matching

// Named key
diff(old, new, { arrayIdentityKeys: { characters: 'id' } });
// Function key
diff(old, new, {
 arrayIdentityKeys: {
 characters: (obj, shouldReturnKeyName) => (shouldReturnKeyName ? 'id' : obj.id)
 }
});
// Regex path matching
const keys = new Map();
keys.set(/^characters/, 'id');
diff(old, new, { arrayIdentityKeys: keys });
// Value-based identity for primitive arrays
diff(old, new, { arrayIdentityKeys: { tags: '$value' } });

Path Skipping

diff(old, new, { keysToSkip: ['characters.metadata'] });

Type Change Handling

diff(old, new, { treatTypeChangeAsReplace: false });

Legacy API Reference

Comparison Functions

Options

interface Options {
 arrayIdentityKeys?: Record<string, string | FunctionKey> | Map<string | RegExp, string | FunctionKey>;
 /** @deprecated Use arrayIdentityKeys instead */
 embeddedObjKeys?: Record<string, string | FunctionKey> | Map<string | RegExp, string | FunctionKey>;
 keysToSkip?: readonly string[];
 treatTypeChangeAsReplace?: boolean; // default: true
}

Migration from v4

Why json-diff-ts?

FAQ

Release Notes

Contributing

Support

Contact

Acknowledgments

License