json-diff-ts 5.0.0-alpha.1 → 5.0.0-alpha.4

package/README.md

@@ -10,34 +10,108 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow.svg?logo=buy-me-a-coffee)](https://buymeacoffee.com/leitwolf)
 
-## Overview
+**Deterministic JSON state transitions with key-based array identity.** A TypeScript JSON diff library that computes, applies, and reverts atomic changes using the [JSON Atom](https://github.com/ltwlf/json-atom-format) wire format -- a JSON Patch alternative with stable array paths, built-in undo/redo for JSON, and language-agnostic state synchronization.
 
-**Modern TypeScript JSON diff library** - `json-diff-ts` is a lightweight, high-performance TypeScript library for calculating and applying differences between JSON objects. Perfect for modern web applications, state management, data synchronization, and real-time collaborative editing.
+Zero dependencies. TypeScript-first. ESM + CommonJS. Trusted by thousands of developers ([500K+ weekly npm downloads](https://www.npmjs.com/package/json-diff-ts)).
 
-### 🚀 **Why Choose json-diff-ts?**
+## Why Index-Based Diffing Breaks
 
-- **🔥 Zero dependencies** - Lightweight bundle size
-- **⚡ High performance** - Optimized algorithms for fast JSON diffing and patching
-- **🎯 95%+ test coverage** - Thoroughly tested with comprehensive test suite
-- **📦 Modern ES modules** - Full TypeScript support with tree-shaking
-- **🔧 Flexible API** - Compare, diff, patch, and atomic operations
-- **🌐 Universal** - Works in browsers, Node.js, and edge environments
-- **✅ Production ready** - Used in enterprise applications worldwide
-- **🎯 TypeScript-first** - Full type safety and IntelliSense support
-- **🔧 Modern features** - ESM + CommonJS, JSONPath, atomic operations
-- **📦 Production ready** - Battle-tested with comprehensive test suite
+Most JSON diff libraries track array changes by position. Insert one element at the start and every path shifts:
 
-### ✨ **Key Features**
+```text
+Remove /items/0  ← was actually "Widget"
+Add    /items/0  ← now it's "NewItem"
+Update /items/1  ← this used to be /items/0
+...
+```
+
+This makes diffs fragile -- you can't store them, replay them reliably, or build audit logs on top of them. Reorder the array and every operation is wrong. This is the fundamental problem with index-based formats like JSON Patch (RFC 6902): paths like `/items/0` are positional, so any insertion, deletion, or reorder invalidates every subsequent path.
+
+**json-diff-ts solves this with key-based identity.** Array elements are matched by a stable key (`id`, `sku`, or any field), and paths use JSONPath filter expressions that survive insertions, deletions, and reordering:
+
+```typescript
+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' } });
+```
+
+The atom tracks _what_ changed, not _where_ it moved:
+
+```json
+{
+  "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 } }
+  ]
+}
+```
+
+Apply forward to get the new state, or revert to restore the original:
+
+```typescript
+// 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
+
+```typescript
+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 },
+  ],
+};
 
-- **Key-based array identification**: Compare array elements using keys instead of indices for more intuitive diffing
-- **JSONPath support**: Target specific parts of JSON documents with precision  
-- **Atomic changesets**: Transform changes into granular, independently applicable operations
-- **Dual module support**: Works with both ECMAScript Modules and CommonJS
-- **Type change handling**: Flexible options for handling data type changes
-- **Path skipping**: Skip nested paths during comparison for performance
+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);
+```
 
-This library is particularly valuable for applications where tracking changes in JSON data is crucial, such as state management systems, form handling, or data synchronization.
+That's it. `atom` is a plain JSON object you can store in a database, send over HTTP, or consume in any language.
 
 ## Installation
 
@@ -45,413 +119,634 @@ This library is particularly valuable for applications where tracking changes in
 npm install json-diff-ts
 ```
 
-## Quick Start
+```typescript
+// 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](https://github.com/ltwlf/json-atom-format) is a specification for representing atomic changes to JSON documents. json-diff-ts is the originating implementation from which the spec was derived.
+
+```text
+json-atom-format  (specification)
+    ├── json-diff-ts      (TypeScript implementation)  ← this package
+    └── json-atom-py     (Python implementation)
+```
+
+The specification defines the wire format. Each language implementation produces and consumes compatible atoms.
+
+An atom is a self-describing JSON document you can store, transmit, and consume in any language:
+
+- **Three operations** -- `add`, `remove`, `replace`. Nothing else to learn.
+- **JSONPath-based paths** -- `$.items[?(@.id==1)].name` identifies elements by key, not index.
+- **Reversible by default** -- every `replace` and `remove` includes `oldValue` for undo.
+- **Self-identifying** -- the `format` field makes atoms discoverable without external context.
+- **Extension-friendly** -- unknown properties are preserved; `x_`-prefixed properties are future-safe.
+
+### JSON Atom vs JSON Patch (RFC 6902)
+
+JSON Patch uses JSON Pointer paths like `/items/0` that reference array elements by index. When an element is inserted at position 0, every subsequent path shifts -- `/items/1` now points to what was `/items/0`. This makes stored patches unreliable for JSON change tracking, audit logs, or undo/redo across time.
+
+JSON Atom uses JSONPath filter expressions like `$.items[?(@.id==1)]` that identify elements by a stable key. The path stays valid regardless of insertions, deletions, or reordering.
+
+| | JSON Atom | JSON Patch (RFC 6902) |
+| --- | --- | --- |
+| Path syntax | JSONPath (`$.items[?(@.id==1)]`) | JSON Pointer (`/items/0`) |
+| Array identity | Key-based -- survives reorder | Index-based -- breaks on insert/delete |
+| Reversibility | Built-in `oldValue` | Not supported |
+| Self-describing | `format` field in envelope | No envelope |
+| Specification | [json-atom-format](https://github.com/ltwlf/json-atom-format) | [RFC 6902](https://tools.ietf.org/html/rfc6902) |
+
+---
+
+## JSON Atom API
+
+### `diffAtom` -- Compute an Atom
 
 ```typescript
-import { diff, applyChangeset } from 'json-diff-ts';
-
-// Two versions of data
-const oldData = { name: 'Luke', level: 1, skills: ['piloting'] };
-const newData = { name: 'Luke Skywalker', level: 5, skills: ['piloting', 'force'] };
-
-// Calculate differences
-const changes = diff(oldData, newData);
-console.log(changes);
-// Output: [
-//   { type: 'UPDATE', key: 'name', value: 'Luke Skywalker', oldValue: 'Luke' },
-//   { type: 'UPDATE', key: 'level', value: 5, oldValue: 1 },
-//   { type: 'ADD', key: 'skills', value: 'force', embeddedKey: '1' }
-// ]
+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
+
+Match array elements by identity key. Filter paths use canonical typed literals per the spec:
 
-// Apply changes to get the new object
-const result = applyChangeset(oldData, changes);
-console.log(result); // { name: 'Luke Skywalker', level: 5, skills: ['piloting', 'force'] }
+```typescript
+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' }]
 ```
 
-### Import Options
+#### Non-reversible Mode
+
+Omit `oldValue` fields when you don't need undo:
 
-**TypeScript / ES Modules:**
 ```typescript
-import { diff } from 'json-diff-ts';
+const atom = diffAtom(source, target, { reversible: false });
 ```
 
-**CommonJS:**
-```javascript
-const { diff } = require('json-diff-ts');
+### `applyAtom` -- Apply an Atom
+
+Applies operations sequentially. Always use the return value (required for root-level replacements):
+
+```typescript
+const result = applyAtom(structuredClone(source), atom);
 ```
 
-## Core Features
+### `revertAtom` -- Revert an Atom
 
-### `diff`
+Computes the inverse and applies it. Requires `oldValue` on all `replace` and `remove` operations:
+
+```typescript
+const original = revertAtom(structuredClone(target), atom);
+```
 
-Generates a difference set for JSON objects. When comparing arrays, if a specific key is provided, differences are determined by matching elements via this key rather than array indices.
+### `invertAtom` -- Compute the Inverse
 
-#### Basic Example with Star Wars Data
+Returns a new atom that undoes the original (spec Section 9.2):
 
 ```typescript
-import { diff } from 'json-diff-ts';
+const inverse = invertAtom(atom);
+// add ↔ remove, replace swaps value/oldValue, order reversed
+```
 
-// State during A New Hope - Desert planet, small rebel cell
-const oldData = {
-  location: 'Tatooine',
-  mission: 'Rescue Princess',
-  status: 'In Progress',
-  characters: [
-    { id: 'LUKE_SKYWALKER', name: 'Luke Skywalker', role: 'Farm Boy', forceTraining: false },
-    { id: 'LEIA_ORGANA', name: 'Princess Leia', role: 'Prisoner', forceTraining: false }
-  ],
-  equipment: ['Lightsaber', 'Blaster']
-};
+### `validateAtom` -- Validate Structure
 
-// State after successful rescue - Base established, characters evolved
-const newData = {
-  location: 'Yavin Base',
-  mission: 'Destroy Death Star',
-  status: 'Complete',
-  characters: [
-    { id: 'LUKE_SKYWALKER', name: 'Luke Skywalker', role: 'Pilot', forceTraining: true, rank: 'Commander' },
-    { id: 'HAN_SOLO', name: 'Han Solo', role: 'Smuggler', forceTraining: false, ship: 'Millennium Falcon' }
-  ],
-  equipment: ['Lightsaber', 'Blaster', 'Bowcaster', 'X-wing Fighter']
-};
+```typescript
+const { valid, errors } = validateAtom(maybeAtom);
+```
 
-const diffs = diff(oldData, newData, { embeddedObjKeys: { characters: 'id' } });
-console.log(diffs);
-// First operations:
-// [
-//   { type: 'UPDATE', key: 'location', value: 'Yavin Base', oldValue: 'Tatooine' },
-//   { type: 'UPDATE', key: 'mission', value: 'Destroy Death Star', oldValue: 'Rescue Princess' },
-//   { type: 'UPDATE', key: 'status', value: 'Complete', oldValue: 'In Progress' },
-//   ...
+### API Reference
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `diffAtom` | `(oldObj, newObj, options?) => IJsonAtom` | Compute a canonical JSON Atom |
+| `applyAtom` | `(obj, atom) => any` | Apply an atom sequentially. Returns the result |
+| `revertAtom` | `(obj, atom) => any` | Revert a reversible atom |
+| `invertAtom` | `(atom) => IJsonAtom` | Compute the inverse atom |
+| `validateAtom` | `(atom) => { valid, errors }` | Structural validation |
+| `toAtom` | `(changeset, options?) => IJsonAtom` | Bridge: v4 changeset to JSON Atom |
+| `fromAtom` | `(atom) => IAtomicChange[]` | Bridge: JSON Atom to v4 atomic changes |
+| `squashAtoms` | `(source, atoms, options?) => IJsonAtom` | Compact multiple atoms into one net-effect atom |
+| `atomMap` | `(atom, fn) => IJsonAtom` | Transform each operation in an atom |
+| `atomStamp` | `(atom, extensions) => IJsonAtom` | Set extension properties on all operations |
+| `atomGroupBy` | `(atom, keyFn) => Record<string, IJsonAtom>` | Group operations into sub-atoms |
+| `operationSpecDict` | `(op) => IAtomOperation` | Strip extension properties from operation |
+| `operationExtensions` | `(op) => Record<string, any>` | Get extension properties from operation |
+| `atomSpecDict` | `(atom) => IJsonAtom` | Strip all extensions from atom |
+| `atomExtensions` | `(atom) => Record<string, any>` | Get envelope extensions from atom |
+| `leafProperty` | `(op) => string \| null` | Terminal property name from operation path |
+
+### AtomOptions
+
+Extends the base `Options` interface:
+
+```typescript
+interface AtomOptions extends Options {
+  reversible?: boolean;       // Include oldValue for undo. Default: true
+  arrayIdentityKeys?: Record<string, string | FunctionKey>;
+  keysToSkip?: readonly string[];
+}
+```
+
+### Atom Workflow Helpers
+
+Transform, inspect, and compact atoms for workflow automation.
+
+#### `squashAtoms` -- Compact Multiple Atoms
+
+Combine a sequence of atoms into a single net-effect atom. Useful for compacting audit logs or collapsing undo history:
+
+```typescript
+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' }
 ```
 
-#### Advanced Options
+Options: `reversible`, `arrayIdentityKeys`, `target` (pre-computed final state), `verifyTarget` (default: true).
 
-##### Path-based Key Identification
+#### `atomMap` / `atomStamp` / `atomGroupBy` -- Atom Transformations
 
-```javascript
-import { diff } from 'json-diff-ts';
+All transforms are immutable — they return new atoms without modifying the original:
+
+```typescript
+import { diffAtom, atomMap, atomStamp, atomGroupBy } from 'json-diff-ts';
+
+const atom = diffAtom(
+  { name: 'Alice', age: 30, role: 'viewer' },
+  { name: 'Bob', age: 31, status: 'active' }
+);
 
-// Using nested paths for sub-arrays
-const diffs = diff(oldData, newData, { embeddedObjKeys: { 'characters.equipment': 'id' } });
+// Stamp metadata onto every operation
+const stamped = atomStamp(atom, { x_author: 'system', x_ts: Date.now() });
 
-// Designating root with '.' - useful for complex nested structures
-const diffs = diff(oldData, newData, { embeddedObjKeys: { '.characters.allies': 'id' } });
+// 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 }
 ```
 
-##### Type Change Handling
+#### `operationSpecDict` / `atomSpecDict` -- Spec Introspection
 
-```javascript
-import { diff } from 'json-diff-ts';
+Separate spec-defined fields from extension properties:
+
+```typescript
+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' }
 
-// Control how type changes are treated
-const diffs = diff(oldData, newData, { treatTypeChangeAsReplace: false });
+// Strip all extensions from an atom
+const clean = atomSpecDict(atom);
 ```
 
-Date objects can now be updated to primitive values without errors when `treatTypeChangeAsReplace` is set to `false`.
+#### `leafProperty` -- Path Introspection
 
-##### Skip Nested Paths
+Extract the terminal property name from an operation's path:
 
-```javascript
-import { diff } from 'json-diff-ts';
+```typescript
+import { leafProperty } from 'json-diff-ts';
 
-// Skip specific nested paths from comparison - useful for ignoring metadata
-const diffs = diff(oldData, newData, { keysToSkip: ['characters.metadata'] });
+leafProperty({ op: 'replace', path: '$.user.name' });          // 'name'
+leafProperty({ op: 'add', path: '$.items[?(@.id==1)]' });      // null (filter)
+leafProperty({ op: 'replace', path: '$' });                     // null (root)
 ```
 
-##### Dynamic Key Resolution
+---
 
-```javascript
-import { diff } from 'json-diff-ts';
+## Comparison Serialization
 
-// Use function to resolve object keys dynamically
-const diffs = diff(oldData, newData, {
-  embeddedObjKeys: {
-    characters: (obj, shouldReturnKeyName) => (shouldReturnKeyName ? 'id' : obj.id)
+Serialize enriched comparison trees to plain objects or flat change lists.
+
+```typescript
+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
+
+Store every change to a document as a reversible atom. Each entry records who changed what, when, and can be replayed or reverted independently -- a complete JSON change tracking system:
+
+```typescript
+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 }
+// ]
 ```
 
-##### Regular Expression Paths
+Because every atom is self-describing JSON, your audit log is queryable, storable in any database, and readable from any language.
 
-```javascript
-import { diff } from 'json-diff-ts';
+### Undo / Redo Stack
+
+Build undo/redo for any JSON state object. Atoms are small (only changed fields), reversible, and serializable:
+
+```typescript
+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
+
+Send only what changed between client and server. Atoms are compact -- a single field change in a 10KB document produces a few bytes of atom, making state synchronization efficient over the wire:
+
+```typescript
+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),
+});
 
-// Use regex for path matching - powerful for dynamic property names
-const embeddedObjKeys = new Map();
-embeddedObjKeys.set(/^characters/, 'id');  // Match any property starting with 'characters'
-const diffs = diff(oldData, newData, { embeddedObjKeys });
+// 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);
 ```
 
-##### String Array Comparison
+---
 
-```javascript
-import { diff } from 'json-diff-ts';
+## Bridge: v4 Changeset <-> JSON Atom
+
+Convert between the legacy internal format and JSON Atom:
+
+```typescript
+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);
 
-// Compare string arrays by value instead of index - useful for tags, categories
-const diffs = diff(oldData, newData, { embeddedObjKeys: { equipment: '$value' } });
+// v4 atomic changes → hierarchical changeset (if needed)
+const cs = unatomizeChangeset(atoms);
 ```
 
-##### Array Move Detection
+**Note:** `toAtom` is a best-effort bridge. Filter literals are always string-quoted (e.g., `[?(@.id=='42')]` instead of canonical `[?(@.id==42)]`). Use `diffAtom()` for fully canonical output.
 
-When working with arrays that have embedded object keys, you can enable detection of element reordering as MOVE operations:
+---
 
-```javascript
+## Legacy Changeset API (v4 Compatibility)
+
+All v4 APIs remain fully supported. Existing code continues to work without changes. For new projects, prefer the JSON Atom API above.
+
+### `diff`
+
+Generates a hierarchical changeset between two objects:
+
+```typescript
 import { diff } from 'json-diff-ts';
 
-const before = {
-  users: [
-    { id: 1, name: 'Alice' },
-    { id: 2, name: 'Bob' },
-    { id: 3, name: 'Charlie' }
-  ]
+const oldData = {
+  location: 'Tatooine',
+  characters: [
+    { id: 'LUKE', name: 'Luke Skywalker', role: 'Farm Boy' },
+    { id: 'LEIA', name: 'Princess Leia', role: 'Prisoner' }
+  ],
 };
 
-const after = {
-  users: [
-    { id: 2, name: 'Bob' },
-    { id: 3, name: 'Charlie' },
-    { id: 1, name: 'Alice' }
-  ]
+const newData = {
+  location: 'Yavin Base',
+  characters: [
+    { id: 'LUKE', name: 'Luke Skywalker', role: 'Pilot', rank: 'Commander' },
+    { id: 'HAN', name: 'Han Solo', role: 'Smuggler' }
+  ],
 };
 
-// Without move detection (default behavior)
-const diffsNoMoves = diff(before, after, { embeddedObjKeys: { users: 'id' } });
-console.log(diffsNoMoves); // [] - no changes detected since elements are unchanged
-
-// With move detection enabled
-const diffsWithMoves = diff(before, after, { 
-  embeddedObjKeys: { users: 'id' },
-  detectArrayMoves: true 
-});
-console.log(diffsWithMoves);
-// [
-//   {
-//     type: 'UPDATE',
-//     key: 'users',
-//     embeddedKey: 'id',
-//     changes: [
-//       { type: 'MOVE', key: 2, oldIndex: 1, newIndex: 0, value: { id: 2, name: 'Bob' } },
-//       { type: 'MOVE', key: 3, oldIndex: 2, newIndex: 1, value: { id: 3, name: 'Charlie' } },
-//       { type: 'MOVE', key: 1, oldIndex: 0, newIndex: 2, value: { id: 1, name: 'Alice' } }
-//     ]
-//   }
-// ]
+const changes = diff(oldData, newData, { arrayIdentityKeys: { characters: 'id' } });
 ```
 
-This feature is particularly useful for:
-- **UI reordering**: Drag-and-drop interfaces, sortable lists
-- **Priority changes**: Task lists, menu items
-- **Data synchronization**: Tracking positional changes in ordered collections
+### `applyChangeset` and `revertChangeset`
+
+```typescript
+import { applyChangeset, revertChangeset } from 'json-diff-ts';
+
+const updated = applyChangeset(structuredClone(oldData), changes);
+const reverted = revertChangeset(structuredClone(newData), changes);
+```
 
 ### `atomizeChangeset` and `unatomizeChangeset`
 
-Transform complex changesets into a list of atomic changes (and back), each describable by a JSONPath.
+Flatten a hierarchical changeset into atomic changes addressable by JSONPath, or reconstruct the hierarchy:
 
-```javascript
+```typescript
 import { atomizeChangeset, unatomizeChangeset } from 'json-diff-ts';
 
-// Create atomic changes
-const atomicChanges = atomizeChangeset(diffs);
-
-// Restore the changeset from a selection of atomic changes
-const changeset = unatomizeChangeset(atomicChanges.slice(0, 3));
-```
-
-**Atomic Changes Structure:**
-
-```javascript
-[
-  { 
-    type: 'UPDATE', 
-    key: 'location', 
-    value: 'Yavin Base', 
-    oldValue: 'Tatooine', 
-    path: '$.location', 
-    valueType: 'String' 
-  },
-  { 
-    type: 'UPDATE', 
-    key: 'mission', 
-    value: 'Destroy Death Star', 
-    oldValue: 'Rescue Princess', 
-    path: '$.mission', 
-    valueType: 'String' 
-  },
-  { 
-    type: 'ADD', 
-    key: 'rank', 
-    value: 'Commander', 
-    path: "$.characters[?(@.id=='LUKE_SKYWALKER')].rank", 
-    valueType: 'String' 
-  },
-  { 
-    type: 'ADD', 
-    key: 'HAN_SOLO', 
-    value: { id: 'HAN_SOLO', name: 'Han Solo', role: 'Smuggler', forceTraining: false, ship: 'Millennium Falcon' }, 
-    path: "$.characters[?(@.id=='HAN_SOLO')]", 
-    valueType: 'Object' 
-  }
-]
+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));
 ```
 
-### `applyChangeset` and `revertChangeset`
+### Advanced Options
 
-Apply or revert changes to JSON objects.
+#### Key-based Array Matching
 
-```javascript
-import { applyChangeset, revertChangeset } from 'json-diff-ts';
+```typescript
+// Named key
+diff(old, new, { arrayIdentityKeys: { characters: 'id' } });
 
-// Apply changes
-const updated = applyChangeset(oldData, diffs);
-console.log(updated);
-// { location: 'Yavin Base', mission: 'Destroy Death Star', status: 'Complete', ... }
+// Function key
+diff(old, new, {
+  arrayIdentityKeys: {
+    characters: (obj, shouldReturnKeyName) => (shouldReturnKeyName ? 'id' : obj.id)
+  }
+});
 
-// Revert changes
-const reverted = revertChangeset(newData, diffs);
-console.log(reverted);
-// { location: 'Tatooine', mission: 'Rescue Princess', status: 'In Progress', ... }
+// 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' } });
 ```
 
-## API Reference
+#### Path Skipping
 
-### Core Functions
+```typescript
+diff(old, new, { keysToSkip: ['characters.metadata'] });
+```
 
-| Function | Description | Parameters |
-|----------|-------------|------------|
-| `diff(oldObj, newObj, options?)` | Generate differences between two objects | `oldObj`: Original object<br>`newObj`: Updated object<br>`options`: Optional configuration |
-| `applyChangeset(obj, changeset)` | Apply changes to an object | `obj`: Object to modify<br>`changeset`: Changes to apply |
-| `revertChangeset(obj, changeset)` | Revert changes from an object | `obj`: Object to modify<br>`changeset`: Changes to revert |
-| `atomizeChangeset(changeset)` | Convert changeset to atomic changes | `changeset`: Nested changeset |
-| `unatomizeChangeset(atomicChanges)` | Convert atomic changes back to nested changeset | `atomicChanges`: Array of atomic changes |
+#### Type Change Handling
+
+```typescript
+diff(old, new, { treatTypeChangeAsReplace: false });
+```
+
+### Legacy API Reference
+
+| Function | Description |
+| --- | --- |
+| `diff(oldObj, newObj, options?)` | Compute hierarchical changeset |
+| `applyChangeset(obj, changeset)` | Apply a changeset to an object |
+| `revertChangeset(obj, changeset)` | Revert a changeset from an object |
+| `atomizeChangeset(changeset)` | Flatten to atomic changes with JSONPath |
+| `unatomizeChangeset(atoms)` | Reconstruct hierarchy from atomic changes |
 
 ### Comparison Functions
 
-| Function | Description | Parameters |
-|----------|-------------|------------|
-| `compare(oldObj, newObj)` | Create enriched comparison object | `oldObj`: Original object<br>`newObj`: Updated object |
-| `enrich(obj)` | Create enriched representation of object | `obj`: Object to enrich |
-| `createValue(value)` | Create value node for comparison | `value`: Any value |
-| `createContainer(value)` | Create container node for comparison | `value`: Object or Array |
+| Function | Description |
+| --- | --- |
+| `compare(oldObj, newObj)` | Create enriched comparison object |
+| `enrich(obj)` | Create enriched representation |
+| `comparisonToDict(node)` | Serialize comparison tree to plain object |
+| `comparisonToFlatList(node, options?)` | Flatten comparison to leaf change list |
 
-### Options Interface
+### Options
 
 ```typescript
 interface Options {
-  embeddedObjKeys?: Record<string, string | Function> | Map<string | RegExp, string | Function>;
-  keysToSkip?: string[];
-  treatTypeChangeAsReplace?: boolean;
-  detectArrayMoves?: boolean;
+  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
 }
 ```
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `embeddedObjKeys` | `Record<string, string | Function>` or `Map<string | RegExp, string | Function>` | Map paths of arrays to a key or resolver function used to match elements when diffing. Use a `Map` for regex paths. |
-| `keysToSkip` | `string[]` | Dotted paths to exclude from comparison, e.g. `"meta.info"`. |
-| `treatTypeChangeAsReplace` | `boolean` | When `true` (default), a type change results in a REMOVE/ADD pair. Set to `false` to treat it as an UPDATE. |
-| `detectArrayMoves` | `boolean` | When `true`, detect array element reordering as MOVE operations. Only works with `embeddedObjKeys`. Default: `false`. |
+---
 
-### Change Types
+## Migration from v4
 
-```typescript
-enum Operation {
-  REMOVE = 'REMOVE',
-  ADD = 'ADD', 
-  UPDATE = 'UPDATE',
-  MOVE = 'MOVE'
-}
-```
+1. **No action required** -- all v4 APIs work identically in v5.
+2. **Adopt JSON Atom** -- use `diffAtom()` / `applyAtom()` for new code.
+3. **Bridge existing data** -- `toAtom()` / `fromAtom()` for interop with stored v4 changesets.
+4. **Rename `embeddedObjKeys` to `arrayIdentityKeys`** -- the old name still works, but `arrayIdentityKeys` is the preferred name going forward.
+5. Both formats coexist. No forced migration.
+
+---
+
+## Why json-diff-ts?
+
+| Feature | json-diff-ts | deep-diff | jsondiffpatch | RFC 6902 |
+| --- | --- | --- | --- | --- |
+| TypeScript | Native | Partial | Definitions only | Varies |
+| Bundle Size | ~21KB | ~45KB | ~120KB+ | Varies |
+| Dependencies | Zero | Few | Many | Varies |
+| ESM Support | Native | CJS only | CJS only | Varies |
+| Array Identity | Key-based | Index only | Configurable | Index only |
+| Wire Format | JSON Atom (standardized) | Proprietary | Proprietary | JSON Pointer |
+| Reversibility | Built-in (`oldValue`) | Manual | Plugin | Not built-in |
+
+## FAQ
+
+**Q: How does JSON Atom compare to JSON Patch (RFC 6902)?**
+JSON Patch uses JSON Pointer (`/items/0`) for paths, which breaks when array elements are inserted, deleted, or reordered. JSON Atom uses JSONPath filter expressions (`$.items[?(@.id==1)]`) for stable, key-based identity. JSON Atom also supports built-in reversibility via `oldValue`.
+
+**Q: Can I use this with React / Vue / Angular?**
+Yes. json-diff-ts works in any JavaScript runtime -- browsers, Node.js, Deno, Bun, edge workers.
+
+**Q: Is it suitable for large objects?**
+Yes. The library handles large, deeply nested JSON structures efficiently with zero dependencies and a ~6KB gzipped footprint.
+
+**Q: Can I use the v4 API alongside JSON Atom?**
+Yes. Both APIs coexist. Use `toAtom()` / `fromAtom()` to convert between formats.
+
+**Q: What about arrays of primitives?**
+Use `$value` as the identity key: `{ arrayIdentityKeys: { tags: '$value' } }`. Elements are matched by value identity.
+
+---
 
 ## Release Notes
 
-- **v4.9.0:** Enhanced array handling for `undefined` values - arrays with `undefined` elements can now be properly reconstructed from changesets. Fixed issue where transitions to `undefined` in arrays were treated as removals instead of updates (fixes issue #316)
+- **v5.0.0-alpha.2:**
+  - Atom workflow helpers: `squashAtoms`, `atomMap`, `atomStamp`, `atomGroupBy`
+  - Atom/operation introspection: `operationSpecDict`, `operationExtensions`, `atomSpecDict`, `atomExtensions`, `leafProperty`
+  - Comparison serialization: `comparisonToDict`, `comparisonToFlatList`
+
+- **v5.0.0-alpha.0:**
+  - JSON Atom API: `diffAtom`, `applyAtom`, `revertAtom`, `invertAtom`, `toAtom`, `fromAtom`, `validateAtom`
+  - Canonical path production with typed filter literals
+  - Conformance with the [JSON Atom Specification](https://github.com/ltwlf/json-atom-format) v0
+  - Renamed `embeddedObjKeys` to `arrayIdentityKeys` (old name still works as deprecated alias)
+  - All v4 APIs preserved unchanged
+
+- **v4.9.0:**
+  - Fixed `applyChangeset` and `revertChangeset` for root-level arrays containing objects (fixes #362)
+  - Fixed `compare` on root-level arrays producing unexpected UNCHANGED entries (fixes #358)
+  - Refactored `applyChangelist` path resolution for correctness with terminal array indices
+  - `keysToSkip` now accepts `readonly string[]` (fixes #359)
+  - `keyBy` callback now receives the element index (PR #365)
+  - Enhanced array handling for `undefined` values (fixes #316)
+  - Fixed typo in warning message (#361)
+  - Fixed README Options Interface formatting (#360)
 - **v4.8.2:** Fixed array handling in `applyChangeset` for null, undefined, and deleted elements (fixes issue #316)
 - **v4.8.1:** Improved documentation with working examples and detailed options.
-- **v4.8.0:** Significantly reduced bundle size by completely removing es-toolkit dependency and implementing custom utility functions. This change eliminates external dependencies while maintaining identical functionality and improving performance.
-
+- **v4.8.0:** Significantly reduced bundle size by completely removing es-toolkit dependency and implementing custom utility functions.
 - **v4.7.0:** Optimized bundle size and performance by replacing es-toolkit/compat with es-toolkit for difference, intersection, and keyBy functions
-
 - **v4.6.3:** Fixed null comparison returning update when values are both null (fixes issue #284)
-
-- **v4.6.2:** Fixed updating to null when `treatTypeChangeAsReplace` is false and bumped Jest dev dependencies
+- **v4.6.2:** Fixed updating to null when `treatTypeChangeAsReplace` is false
 - **v4.6.1:** Consistent JSONPath format for array items (fixes issue #269)
 - **v4.6.0:** Fixed filter path regex to avoid polynomial complexity
-- **v4.5.1:** Updated package dependencies
 - **v4.5.0:** Switched internal utilities from lodash to es-toolkit/compat for a smaller bundle size
 - **v4.4.0:** Fixed Date-to-string diff when `treatTypeChangeAsReplace` is false
-- **v4.3.0:** Enhanced functionality:
-  - Added support for nested keys to skip using dotted path notation in the keysToSkip option
-  - This allows excluding specific nested object paths from comparison (fixes #242)
-- **v4.2.0:** Improved stability with multiple fixes:
-  - Fixed object handling in atomizeChangeset and unatomizeChangeset
-  - Fixed array handling in applyChangeset and revertChangeset
-  - Fixed handling of null values in applyChangeset
-  - Fixed handling of empty REMOVE operations when diffing from undefined
+- **v4.3.0:** Added support for nested keys to skip using dotted path notation (fixes #242)
+- **v4.2.0:** Improved stability with multiple fixes for atomize/unatomize, apply/revert, null handling
 - **v4.1.0:** Full support for ES modules while maintaining CommonJS compatibility
-- **v4.0.0:** Changed naming of flattenChangeset and unflattenChanges to atomizeChangeset and unatomizeChangeset; added option to set treatTypeChangeAsReplace
-- **v3.0.1:** Fixed issue with unflattenChanges when a key has periods
-- **v3.0.0:** Added support for both CommonJS and ECMAScript Modules. Replaced lodash-es with lodash to support both module formats
-- **v5.0.0-alpha.1:** Added MOVE operation for array reordering detection with embeddedObjKeys. New `detectArrayMoves` option enables tracking of element position changes within arrays when using key-based identification. Fully backward compatible.
-- **v4.8.2:** Latest stable release  
-- **v2.2.0:** Fixed lodash-es dependency, added exclude keys option, added string array comparison by value
-- **v2.1.0:** Fixed JSON Path filters by replacing single equal sign (=) with double equal sign (==). Added support for using '.' as root in paths
-- **v2.0.0:** Upgraded to ECMAScript module format with optimizations and improved documentation. Fixed regex path handling (breaking change: now requires Map instead of Record for regex paths)
-- **v1.2.6:** Enhanced JSON Path handling for period-inclusive segments
-- **v1.2.5:** Added key name resolution support for key functions
-- **v1.2.4:** Documentation updates and dependency upgrades
-- **v1.2.3:** Updated dependencies and TypeScript
+- **v4.0.0:** Renamed flattenChangeset/unflattenChanges to atomizeChangeset/unatomizeChangeset; added treatTypeChangeAsReplace option
 
 ## Contributing
 
 Contributions are welcome! Please follow the provided issue templates and code of conduct.
 
-## Performance & Bundle Size
-
-- **Zero dependencies**: No external runtime dependencies
-- **Lightweight**: ~21KB minified, ~6KB gzipped
-- **Tree-shakable**: Use only what you need with ES modules
-- **High performance**: Optimized for large JSON objects and arrays
-
-## Use Cases
-
-- **State Management**: Track changes in Redux, Zustand, or custom state stores  
-- **Form Handling**: Detect field changes in React, Vue, or Angular forms
-- **Data Synchronization**: Sync data between client and server efficiently
-- **Version Control**: Implement undo/redo functionality
-- **API Optimization**: Send only changed data to reduce bandwidth
-- **Real-time Updates**: Track changes in collaborative applications
+## Support
 
-## Comparison with Alternatives
+If you find this library useful, consider supporting its development:
 
-| Feature | json-diff-ts | deep-diff | jsondiffpatch |
-|---------|--------------|-----------|---------------|
-| TypeScript | ✅ Native | ❌ Partial | ❌ Definitions only |
-| Bundle Size | 🟢 21KB | 🟡 45KB | 🔴 120KB+ |
-| Dependencies | 🟢 Zero | 🟡 Few | 🔴 Many |
-| ESM Support | ✅ Native | ❌ CJS only | ❌ CJS only |
-| Array Key Matching | ✅ Advanced | ❌ Basic | ✅ Advanced |
-| JSONPath Support | ✅ Full | ❌ None | ❌ Limited |
-
-## FAQ
-
-**Q: Can I use this with React/Vue/Angular?**  
-A: Yes! json-diff-ts works with any JavaScript framework or vanilla JS.
-
-**Q: Does it work with Node.js?**  
-A: Absolutely! Supports Node.js 18+ with both CommonJS and ES modules.
-
-**Q: How does it compare to JSON Patch (RFC 6902)?**  
-A: json-diff-ts provides a more flexible format with advanced array handling, while JSON Patch is a standardized format.
-
-**Q: Is it suitable for large objects?**  
-A: Yes, the library is optimized for performance and can handle large, complex JSON structures efficiently.
+[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://buymeacoffee.com/leitwolf)
 
 ## Contact
 
-Reach out to the maintainer:
-
 - LinkedIn: [Christian Glessner](https://www.linkedin.com/in/christian-glessner/)
 - Twitter: [@leitwolf_io](https://twitter.com/leitwolf_io)