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

package/dist/index.d.cts

@@ -121,6 +121,35 @@ declare const createContainer: (value: object | []) => IComparisonEnrichedNode;
 declare const enrich: (object: any) => IComparisonEnrichedNode;
 declare const applyChangelist: (object: IComparisonEnrichedNode, changelist: IAtomicChange[]) => IComparisonEnrichedNode;
 declare const compare: (oldObject: any, newObject: any) => IComparisonEnrichedNode;
+interface IComparisonDict {
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+interface IFlatChange {
+    path: string;
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+/**
+ * Recursively serializes an enriched comparison tree to a plain JS object.
+ * The result is JSON-serializable when contained `value`/`oldValue` are
+ * themselves JSON-serializable. Includes `value`/`oldValue` based on change
+ * type, not truthiness — `null` is preserved as a valid JSON value.
+ */
+declare const comparisonToDict: (node: IComparisonEnrichedNode) => IComparisonDict;
+/**
+ * Flattens an enriched comparison tree to a list of leaf changes with paths.
+ * Uses dot notation for identifier keys and bracket-quote notation for
+ * non-identifier keys (per spec Section 5.5).
+ *
+ * By default, `UNCHANGED` entries are excluded. Set `includeUnchanged: true`
+ * to include them.
+ */
+declare const comparisonToFlatList: (node: IComparisonEnrichedNode, options?: {
+    includeUnchanged?: boolean;
+}) => IFlatChange[];
 
 type DeltaPathSegment = {
     type: 'root';
@@ -217,4 +246,60 @@ declare function applyDelta(obj: any, delta: IJsonDelta): any;
  */
 declare function revertDelta(obj: any, delta: IJsonDelta): any;
 
-export { type Changeset, CompareOperation, type DeltaOp, type DeltaOptions, type DeltaPathSegment, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonEnrichedNode, type IDeltaOperation, type IJsonDelta, Operation, type Options, applyChangelist, applyChangeset, applyDelta, atomizeChangeset, buildDeltaPath, compare, createContainer, createValue, diff, diffDelta, enrich, formatFilterLiteral, fromDelta, getTypeOfObj, invertDelta, parseDeltaPath, parseFilterLiteral, revertChangeset, revertDelta, toDelta, unatomizeChangeset, validateDelta };
+/**
+ * Returns a copy of the operation containing only spec-defined keys
+ * (`op`, `path`, `value`, `oldValue`). Complement of `operationExtensions`.
+ */
+declare function operationSpecDict(op: IDeltaOperation): IDeltaOperation;
+/**
+ * Returns a record of non-spec keys from the operation (extension properties).
+ * Complement of `operationSpecDict`.
+ */
+declare function operationExtensions(op: IDeltaOperation): Record<string, any>;
+/**
+ * Returns the terminal property name from the operation's path, or `null`
+ * for root, index, and filter segments.
+ */
+declare function leafProperty(op: IDeltaOperation): string | null;
+/**
+ * Returns a copy of the delta with only spec-defined keys in the envelope
+ * and each operation. Strips all extension properties.
+ */
+declare function deltaSpecDict(delta: IJsonDelta): IJsonDelta;
+/**
+ * Returns a record of non-spec keys from the delta envelope.
+ * Complement of `deltaSpecDict`.
+ */
+declare function deltaExtensions(delta: IJsonDelta): Record<string, any>;
+/**
+ * Transforms each operation in the delta using the provided function.
+ * Returns a new delta (immutable). Preserves all envelope properties.
+ */
+declare function deltaMap(delta: IJsonDelta, fn: (op: IDeltaOperation, index: number) => IDeltaOperation): IJsonDelta;
+/**
+ * Returns a new delta with the given extension properties merged onto every
+ * operation. Immutable — the original delta is not modified.
+ */
+declare function deltaStamp(delta: IJsonDelta, extensions: Record<string, any>): IJsonDelta;
+/**
+ * Groups operations in the delta by the result of `keyFn`. Returns a record
+ * mapping each key to a sub-delta containing only the matching operations.
+ * Each sub-delta preserves all envelope properties.
+ */
+declare function deltaGroupBy(delta: IJsonDelta, keyFn: (op: IDeltaOperation) => string): Record<string, IJsonDelta>;
+interface SquashDeltasOptions extends DeltaOptions {
+    /** Pre-computed final state. When provided with deltas, used instead of computing. */
+    target?: any;
+    /** Verify that `target` matches sequential application of deltas. Default: true. */
+    verifyTarget?: boolean;
+}
+/**
+ * Compacts multiple deltas into a single net-effect delta. The result is
+ * equivalent to applying all deltas sequentially, but expressed as a single
+ * `source → final` diff.
+ *
+ * Envelope extensions from all input deltas are merged (last-wins on conflict).
+ */
+declare function squashDeltas(source: any, deltas: IJsonDelta[], options?: SquashDeltasOptions): IJsonDelta;
+
+export { type Changeset, CompareOperation, type DeltaOp, type DeltaOptions, type DeltaPathSegment, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonDict, type IComparisonEnrichedNode, type IDeltaOperation, type IFlatChange, type IJsonDelta, Operation, type Options, type SquashDeltasOptions, applyChangelist, applyChangeset, applyDelta, atomizeChangeset, buildDeltaPath, compare, comparisonToDict, comparisonToFlatList, createContainer, createValue, deltaExtensions, deltaGroupBy, deltaMap, deltaSpecDict, deltaStamp, diff, diffDelta, enrich, formatFilterLiteral, fromDelta, getTypeOfObj, invertDelta, leafProperty, operationExtensions, operationSpecDict, parseDeltaPath, parseFilterLiteral, revertChangeset, revertDelta, squashDeltas, toDelta, unatomizeChangeset, validateDelta };

package/dist/index.d.ts

@@ -121,6 +121,35 @@ declare const createContainer: (value: object | []) => IComparisonEnrichedNode;
 declare const enrich: (object: any) => IComparisonEnrichedNode;
 declare const applyChangelist: (object: IComparisonEnrichedNode, changelist: IAtomicChange[]) => IComparisonEnrichedNode;
 declare const compare: (oldObject: any, newObject: any) => IComparisonEnrichedNode;
+interface IComparisonDict {
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+interface IFlatChange {
+    path: string;
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+/**
+ * Recursively serializes an enriched comparison tree to a plain JS object.
+ * The result is JSON-serializable when contained `value`/`oldValue` are
+ * themselves JSON-serializable. Includes `value`/`oldValue` based on change
+ * type, not truthiness — `null` is preserved as a valid JSON value.
+ */
+declare const comparisonToDict: (node: IComparisonEnrichedNode) => IComparisonDict;
+/**
+ * Flattens an enriched comparison tree to a list of leaf changes with paths.
+ * Uses dot notation for identifier keys and bracket-quote notation for
+ * non-identifier keys (per spec Section 5.5).
+ *
+ * By default, `UNCHANGED` entries are excluded. Set `includeUnchanged: true`
+ * to include them.
+ */
+declare const comparisonToFlatList: (node: IComparisonEnrichedNode, options?: {
+    includeUnchanged?: boolean;
+}) => IFlatChange[];
 
 type DeltaPathSegment = {
     type: 'root';
@@ -217,4 +246,60 @@ declare function applyDelta(obj: any, delta: IJsonDelta): any;
  */
 declare function revertDelta(obj: any, delta: IJsonDelta): any;
 
-export { type Changeset, CompareOperation, type DeltaOp, type DeltaOptions, type DeltaPathSegment, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonEnrichedNode, type IDeltaOperation, type IJsonDelta, Operation, type Options, applyChangelist, applyChangeset, applyDelta, atomizeChangeset, buildDeltaPath, compare, createContainer, createValue, diff, diffDelta, enrich, formatFilterLiteral, fromDelta, getTypeOfObj, invertDelta, parseDeltaPath, parseFilterLiteral, revertChangeset, revertDelta, toDelta, unatomizeChangeset, validateDelta };
+/**
+ * Returns a copy of the operation containing only spec-defined keys
+ * (`op`, `path`, `value`, `oldValue`). Complement of `operationExtensions`.
+ */
+declare function operationSpecDict(op: IDeltaOperation): IDeltaOperation;
+/**
+ * Returns a record of non-spec keys from the operation (extension properties).
+ * Complement of `operationSpecDict`.
+ */
+declare function operationExtensions(op: IDeltaOperation): Record<string, any>;
+/**
+ * Returns the terminal property name from the operation's path, or `null`
+ * for root, index, and filter segments.
+ */
+declare function leafProperty(op: IDeltaOperation): string | null;
+/**
+ * Returns a copy of the delta with only spec-defined keys in the envelope
+ * and each operation. Strips all extension properties.
+ */
+declare function deltaSpecDict(delta: IJsonDelta): IJsonDelta;
+/**
+ * Returns a record of non-spec keys from the delta envelope.
+ * Complement of `deltaSpecDict`.
+ */
+declare function deltaExtensions(delta: IJsonDelta): Record<string, any>;
+/**
+ * Transforms each operation in the delta using the provided function.
+ * Returns a new delta (immutable). Preserves all envelope properties.
+ */
+declare function deltaMap(delta: IJsonDelta, fn: (op: IDeltaOperation, index: number) => IDeltaOperation): IJsonDelta;
+/**
+ * Returns a new delta with the given extension properties merged onto every
+ * operation. Immutable — the original delta is not modified.
+ */
+declare function deltaStamp(delta: IJsonDelta, extensions: Record<string, any>): IJsonDelta;
+/**
+ * Groups operations in the delta by the result of `keyFn`. Returns a record
+ * mapping each key to a sub-delta containing only the matching operations.
+ * Each sub-delta preserves all envelope properties.
+ */
+declare function deltaGroupBy(delta: IJsonDelta, keyFn: (op: IDeltaOperation) => string): Record<string, IJsonDelta>;
+interface SquashDeltasOptions extends DeltaOptions {
+    /** Pre-computed final state. When provided with deltas, used instead of computing. */
+    target?: any;
+    /** Verify that `target` matches sequential application of deltas. Default: true. */
+    verifyTarget?: boolean;
+}
+/**
+ * Compacts multiple deltas into a single net-effect delta. The result is
+ * equivalent to applying all deltas sequentially, but expressed as a single
+ * `source → final` diff.
+ *
+ * Envelope extensions from all input deltas are merged (last-wins on conflict).
+ */
+declare function squashDeltas(source: any, deltas: IJsonDelta[], options?: SquashDeltasOptions): IJsonDelta;
+
+export { type Changeset, CompareOperation, type DeltaOp, type DeltaOptions, type DeltaPathSegment, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonDict, type IComparisonEnrichedNode, type IDeltaOperation, type IFlatChange, type IJsonDelta, Operation, type Options, type SquashDeltasOptions, applyChangelist, applyChangeset, applyDelta, atomizeChangeset, buildDeltaPath, compare, comparisonToDict, comparisonToFlatList, createContainer, createValue, deltaExtensions, deltaGroupBy, deltaMap, deltaSpecDict, deltaStamp, diff, diffDelta, enrich, formatFilterLiteral, fromDelta, getTypeOfObj, invertDelta, leafProperty, operationExtensions, operationSpecDict, parseDeltaPath, parseFilterLiteral, revertChangeset, revertDelta, squashDeltas, toDelta, unatomizeChangeset, validateDelta };

package/dist/index.js

@@ -734,6 +734,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) {
@@ -1462,6 +1530,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;
+}
 export {
   CompareOperation,
   Operation,
@@ -1471,8 +1646,15 @@ export {
   atomizeChangeset,
   buildDeltaPath,
   compare2 as compare,
+  comparisonToDict,
+  comparisonToFlatList,
   createContainer,
   createValue,
+  deltaExtensions,
+  deltaGroupBy,
+  deltaMap,
+  deltaSpecDict,
+  deltaStamp,
   diff,
   diffDelta,
   enrich,
@@ -1480,10 +1662,14 @@ export {
   fromDelta,
   getTypeOfObj,
   invertDelta,
+  leafProperty,
+  operationExtensions,
+  operationSpecDict,
   parseDeltaPath,
   parseFilterLiteral,
   revertChangeset,
   revertDelta,
+  squashDeltas,
   toDelta,
   unatomizeChangeset,
   validateDelta