deep-diff

name	deep-diff
description	Compute structural differences between two JSON-compatible JavaScript values. Use this skill when you need to programmatically diff objects, check if two data structures are equivalent, or find what paths changed. Triggers include "diff two objects in code", "find changed keys", "compute JSON diff", "deep equality check with diff output".

deep-diff

Programmatic deep diff between two JSON-compatible values. Used internally by json-differ.

API

import { computeDiff } from './src/lib/diff';

const left  = { name: "Alice", age: 30 };
const right = { name: "Alicia", age: 30, role: "admin" };

const nodes = computeDiff(left, right, []);
// Returns DiffNode[]

DiffNode shape

interface DiffNode {
  kind: "unchanged" | "added" | "removed" | "changed" | "structural";
  path: string[];           // e.g. ["user", "address", "city"]
  leftValue: unknown;
  rightValue: unknown;
  children?: DiffNode[];
}

Ignore rules

import { applyIgnoreRules } from './src/lib/ignoreRules';

const rules = [
  { type: "key_name", value: "updatedAt" },
  { type: "exact_path", value: "user.id" }
];

const filteredNodes = applyIgnoreRules(nodes, rules);

Use cases

• Assertion in tests: "what changed between these two API responses?"
• Change detection in data pipelines
• Generating JSON Patch (RFC 6902) documents from a diff result

Limitations

• Arrays are compared by index (positional), not by element identity
• Type mismatches (object vs primitive) produce a single "changed" node, not a structural diff
• Circular references: not supported (will overflow the stack)