json-diff-ts 5.0.0-alpha.0 → 5.0.0-alpha.2

package/README.md

@@ -129,7 +129,15 @@ const { diffDelta, applyDelta, revertDelta } = require('json-diff-ts');
 
 ## What is JSON Delta?
 
-[JSON Delta](https://github.com/ltwlf/json-delta-format) is a specification for representing atomic changes to JSON documents. json-diff-ts is the originating implementation from which the spec was derived. A Python implementation is also available: [json-delta-py](https://github.com/ltwlf/json-delta-py).
+[JSON Delta](https://github.com/ltwlf/json-delta-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-delta-format  (specification)
+    ├── json-diff-ts      (TypeScript implementation)  ← this package
+    └── json-delta-py     (Python implementation)
+```
+
+The specification defines the wire format. Each language implementation produces and consumes compatible deltas.
 
 A delta is a self-describing JSON document you can store, transmit, and consume in any language:
 
@@ -230,6 +238,15 @@ const { valid, errors } = validateDelta(maybeDelta);
 | `validateDelta` | `(delta) => { valid, errors }` | Structural validation |
 | `toDelta` | `(changeset, options?) => IJsonDelta` | Bridge: v4 changeset to JSON Delta |
 | `fromDelta` | `(delta) => IAtomicChange[]` | Bridge: JSON Delta to v4 atomic changes |
+| `squashDeltas` | `(source, deltas, options?) => IJsonDelta` | Compact multiple deltas into one net-effect delta |
+| `deltaMap` | `(delta, fn) => IJsonDelta` | Transform each operation in a delta |
+| `deltaStamp` | `(delta, extensions) => IJsonDelta` | Set extension properties on all operations |
+| `deltaGroupBy` | `(delta, keyFn) => Record<string, IJsonDelta>` | Group operations into sub-deltas |
+| `operationSpecDict` | `(op) => IDeltaOperation` | Strip extension properties from operation |
+| `operationExtensions` | `(op) => Record<string, any>` | Get extension properties from operation |
+| `deltaSpecDict` | `(delta) => IJsonDelta` | Strip all extensions from delta |
+| `deltaExtensions` | `(delta) => Record<string, any>` | Get envelope extensions from delta |
+| `leafProperty` | `(op) => string \| null` | Terminal property name from operation path |
 
 ### DeltaOptions
 
@@ -243,6 +260,125 @@ interface DeltaOptions extends Options {
 }
 ```
 
+### Delta Workflow Helpers
+
+Transform, inspect, and compact deltas for workflow automation.
+
+#### `squashDeltas` -- Compact Multiple Deltas
+
+Combine a sequence of deltas into a single net-effect delta. Useful for compacting audit logs or collapsing undo history:
+
+```typescript
+import { diffDelta, applyDelta, squashDeltas } from 'json-diff-ts';
+
+const source = { name: 'Alice', role: 'viewer' };
+const d1 = diffDelta(source, { name: 'Bob', role: 'viewer' });
+const d2 = diffDelta({ name: 'Bob', role: 'viewer' }, { name: 'Bob', role: 'admin' });
+
+const squashed = squashDeltas(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 delta equals applying both sequentially
+const result = applyDelta(structuredClone(source), squashed);
+// result => { name: 'Bob', role: 'admin' }
+```
+
+Options: `reversible`, `arrayIdentityKeys`, `target` (pre-computed final state), `verifyTarget` (default: true).
+
+#### `deltaMap` / `deltaStamp` / `deltaGroupBy` -- Delta Transformations
+
+All transforms are immutable — they return new deltas without modifying the original:
+
+```typescript
+import { diffDelta, deltaMap, deltaStamp, deltaGroupBy } from 'json-diff-ts';
+
+const delta = diffDelta(
+  { name: 'Alice', age: 30, role: 'viewer' },
+  { name: 'Bob', age: 31, status: 'active' }
+);
+
+// Stamp metadata onto every operation
+const stamped = deltaStamp(delta, { x_author: 'system', x_ts: Date.now() });
+
+// Transform operations
+const prefixed = deltaMap(delta, (op) => ({
+  ...op,
+  path: op.path.replace('$', '$.data'),
+}));
+
+// Group by operation type
+const groups = deltaGroupBy(delta, (op) => op.op);
+// groups => { replace: IJsonDelta, add: IJsonDelta, remove: IJsonDelta }
+```
+
+#### `operationSpecDict` / `deltaSpecDict` -- Spec Introspection
+
+Separate spec-defined fields from extension properties:
+
+```typescript
+import { operationSpecDict, operationExtensions, deltaSpecDict } 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 a delta
+const clean = deltaSpecDict(delta);
+```
+
+#### `leafProperty` -- Path Introspection
+
+Extract the terminal property name from an operation's path:
+
+```typescript
+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
+
+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
@@ -503,6 +639,8 @@ diff(old, new, { treatTypeChangeAsReplace: false });
 | --- | --- |
 | `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
 
@@ -561,6 +699,11 @@ Use `$value` as the identity key: `{ arrayIdentityKeys: { tags: '$value' } }`. E
 
 ## Release Notes
 
+- **v5.0.0-alpha.2:**
+  - Delta workflow helpers: `squashDeltas`, `deltaMap`, `deltaStamp`, `deltaGroupBy`
+  - Delta/operation introspection: `operationSpecDict`, `operationExtensions`, `deltaSpecDict`, `deltaExtensions`, `leafProperty`
+  - Comparison serialization: `comparisonToDict`, `comparisonToFlatList`
+
 - **v5.0.0-alpha.0:**
   - JSON Delta API: `diffDelta`, `applyDelta`, `revertDelta`, `invertDelta`, `toDelta`, `fromDelta`, `validateDelta`
   - Canonical path production with typed filter literals

package/dist/index.cjs

@@ -28,8 +28,15 @@ __export(index_exports, {
   atomizeChangeset: () => atomizeChangeset,
   buildDeltaPath: () => buildDeltaPath,
   compare: () => compare2,
+  comparisonToDict: () => comparisonToDict,
+  comparisonToFlatList: () => comparisonToFlatList,
   createContainer: () => createContainer,
   createValue: () => createValue,
+  deltaExtensions: () => deltaExtensions,
+  deltaGroupBy: () => deltaGroupBy,
+  deltaMap: () => deltaMap,
+  deltaSpecDict: () => deltaSpecDict,
+  deltaStamp: () => deltaStamp,
   diff: () => diff,
   diffDelta: () => diffDelta,
   enrich: () => enrich,
@@ -37,10 +44,14 @@ __export(index_exports, {
   fromDelta: () => fromDelta,
   getTypeOfObj: () => getTypeOfObj,
   invertDelta: () => invertDelta,
+  leafProperty: () => leafProperty,
+  operationExtensions: () => operationExtensions,
+  operationSpecDict: () => operationSpecDict,
   parseDeltaPath: () => parseDeltaPath,
   parseFilterLiteral: () => parseFilterLiteral,
   revertChangeset: () => revertChangeset,
   revertDelta: () => revertDelta,
+  squashDeltas: () => squashDeltas,
   toDelta: () => toDelta,
   unatomizeChangeset: () => unatomizeChangeset,
   validateDelta: () => validateDelta
@@ -783,6 +794,74 @@ var compare2 = (oldObject, newObject) => {
   }
   return applyChangelist(enrich(oldObject), atomizeChangeset(diff(oldObject, newObject)));
 };
+var comparisonToDict = (node) => {
+  const result = { type: node.type };
+  if (node.type === "CONTAINER" /* CONTAINER */) {
+    if (Array.isArray(node.value)) {
+      const children = node.value;
+      const serialized = new Array(children.length);
+      for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        serialized[i] = child != null ? comparisonToDict(child) : null;
+      }
+      result.value = serialized;
+    } else if (node.value && typeof node.value === "object") {
+      const obj = /* @__PURE__ */ Object.create(null);
+      for (const [key, child] of Object.entries(
+        node.value
+      )) {
+        if (child == null) continue;
+        obj[key] = comparisonToDict(child);
+      }
+      result.value = obj;
+    }
+  } else {
+    if (node.type === "UNCHANGED" /* UNCHANGED */ || node.type === "ADD" /* ADD */ || node.type === "UPDATE" /* UPDATE */) {
+      result.value = node.value;
+    }
+    if (node.type === "REMOVE" /* REMOVE */ || node.type === "UPDATE" /* UPDATE */) {
+      result.oldValue = node.oldValue;
+    }
+  }
+  return result;
+};
+var IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var comparisonToFlatList = (node, options = {}) => {
+  const results = [];
+  flattenNode(node, "$", options.includeUnchanged ?? false, results);
+  return results;
+};
+function flattenNode(node, path, includeUnchanged, results) {
+  if (node.type === "CONTAINER" /* CONTAINER */) {
+    if (Array.isArray(node.value)) {
+      for (let i = 0; i < node.value.length; i++) {
+        const child = node.value[i];
+        if (child == null) continue;
+        flattenNode(child, `${path}[${i}]`, includeUnchanged, results);
+      }
+    } else if (node.value && typeof node.value === "object") {
+      for (const [key, child] of Object.entries(
+        node.value
+      )) {
+        if (child == null) continue;
+        const childPath = IDENT_RE.test(key) ? `${path}.${key}` : `${path}['${key.replace(/'/g, "''")}']`;
+        flattenNode(child, childPath, includeUnchanged, results);
+      }
+    }
+    return;
+  }
+  if (node.type === "UNCHANGED" /* UNCHANGED */ && !includeUnchanged) {
+    return;
+  }
+  const entry = { path, type: node.type };
+  if (node.type === "UNCHANGED" /* UNCHANGED */ || node.type === "ADD" /* ADD */ || node.type === "UPDATE" /* UPDATE */) {
+    entry.value = node.value;
+  }
+  if (node.type === "REMOVE" /* REMOVE */ || node.type === "UPDATE" /* UPDATE */) {
+    entry.oldValue = node.oldValue;
+  }
+  results.push(entry);
+}
 
 // src/deltaPath.ts
 function formatFilterLiteral(value) {
@@ -1511,6 +1590,113 @@ function revertDelta(obj, delta) {
   const inverse = invertDelta(delta);
   return applyDelta(obj, inverse);
 }
+
+// src/deltaHelpers.ts
+var OP_SPEC_KEYS = /* @__PURE__ */ new Set(["op", "path", "value", "oldValue"]);
+var DELTA_SPEC_KEYS = /* @__PURE__ */ new Set(["format", "version", "operations"]);
+function operationSpecDict(op) {
+  const result = { op: op.op, path: op.path };
+  if ("value" in op) result.value = op.value;
+  if ("oldValue" in op) result.oldValue = op.oldValue;
+  return result;
+}
+function operationExtensions(op) {
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const key of Object.keys(op)) {
+    if (!OP_SPEC_KEYS.has(key)) {
+      result[key] = op[key];
+    }
+  }
+  return result;
+}
+function leafProperty(op) {
+  const segments = parseDeltaPath(op.path);
+  if (segments.length === 0) return null;
+  const last = segments[segments.length - 1];
+  return last.type === "property" ? last.name : null;
+}
+function deltaSpecDict(delta) {
+  return {
+    format: delta.format,
+    version: delta.version,
+    operations: delta.operations.map(operationSpecDict)
+  };
+}
+function deltaExtensions(delta) {
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const key of Object.keys(delta)) {
+    if (!DELTA_SPEC_KEYS.has(key)) {
+      result[key] = delta[key];
+    }
+  }
+  return result;
+}
+function deltaMap(delta, fn) {
+  return { ...delta, operations: delta.operations.map((op, i) => fn(op, i)) };
+}
+function deltaStamp(delta, extensions) {
+  return deltaMap(delta, (op) => ({ ...op, ...extensions }));
+}
+function deltaGroupBy(delta, keyFn) {
+  const groups = /* @__PURE__ */ Object.create(null);
+  for (const op of delta.operations) {
+    const k = keyFn(op);
+    if (!groups[k]) groups[k] = [];
+    groups[k].push(op);
+  }
+  const envelope = /* @__PURE__ */ Object.create(null);
+  for (const key of Object.keys(delta)) {
+    if (key !== "operations") {
+      envelope[key] = delta[key];
+    }
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const [k, ops] of Object.entries(groups)) {
+    result[k] = { ...envelope, operations: ops };
+  }
+  return result;
+}
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+function squashDeltas(source, deltas, options = {}) {
+  const { target, verifyTarget = true, ...diffOptions } = options;
+  let final;
+  if (target !== void 0 && deltas.length > 0 && verifyTarget) {
+    let computed = deepClone(source);
+    for (const d of deltas) {
+      computed = applyDelta(computed, d);
+    }
+    const verification = diffDelta(computed, target, diffOptions);
+    if (verification.operations.length > 0) {
+      throw new Error(
+        "squashDeltas: provided target does not match sequential application of deltas to source"
+      );
+    }
+    final = target;
+  } else if (target !== void 0) {
+    final = target;
+  } else {
+    final = deepClone(source);
+    for (const d of deltas) {
+      final = applyDelta(final, d);
+    }
+  }
+  const result = diffDelta(source, final, diffOptions);
+  for (const d of deltas) {
+    for (const key of Object.keys(d)) {
+      if (!DELTA_SPEC_KEYS.has(key)) {
+        Object.defineProperty(result, key, {
+          value: d[key],
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+      }
+    }
+  }
+  return result;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CompareOperation,
@@ -1521,8 +1707,15 @@ function revertDelta(obj, delta) {
   atomizeChangeset,
   buildDeltaPath,
   compare,
+  comparisonToDict,
+  comparisonToFlatList,
   createContainer,
   createValue,
+  deltaExtensions,
+  deltaGroupBy,
+  deltaMap,
+  deltaSpecDict,
+  deltaStamp,
   diff,
   diffDelta,
   enrich,
@@ -1530,10 +1723,14 @@ function revertDelta(obj, delta) {
   fromDelta,
   getTypeOfObj,
   invertDelta,
+  leafProperty,
+  operationExtensions,
+  operationSpecDict,
   parseDeltaPath,
   parseFilterLiteral,
   revertChangeset,
   revertDelta,
+  squashDeltas,
   toDelta,
   unatomizeChangeset,
   validateDelta