objwalk 1.5.0 → 1.6.0

package/README.md

@@ -15,7 +15,7 @@ npm install objwalk
 ## Usage
 
 ```ts
-import { each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
+import { diff, each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
 ```
 
 ## pick
@@ -143,6 +143,55 @@ equally({ a: 1 }, { a: 1, b: 2 })
 `equally` treats `NaN` as equal to `NaN`, compares `Date` by timestamp and `RegExp` by
 source and flags, and follows circular references without looping.
 
+## diff
+
+Describe changes from `first` to `last` as a list of `set` and `delete` operations.
+
+```ts
+import { diff, type DiffOperation } from 'objwalk'
+
+const operations: DiffOperation[] = diff(
+  { hp: 10, target: 'enemy', position: { x: 1, y: 2 } },
+  { hp: null, position: { x: 3, y: 2 } }
+)
+// [
+//   { type: 'set', path: ['hp'], value: null },
+//   { type: 'set', path: ['position', 'x'], value: 3 },
+//   { type: 'delete', path: ['target'] },
+// ]
+
+diff({}, { a: undefined })
+// [{ type: 'set', path: ['a'], value: undefined }]
+
+diff({ a: 1 }, {})
+// [{ type: 'delete', path: ['a'] }]
+
+diff(1, null)
+// [{ type: 'set', path: [], value: null }]
+
+diff({ a: 1 }, { a: 1 }) // []
+```
+
+- When both values are plain objects (with `Object.prototype` or a null prototype),
+  `diff` recursively compares own enumerable string keys. Symbol and non-enumerable
+  keys are ignored during that traversal, and prototype or descriptor changes are not reported.
+- Arrays and other values use `equally`; changed values are replaced as a whole.
+  Newly added properties also use a single `set`, including when their value is an empty object.
+- A `set` carries the new value, including `null` or `undefined`; a `delete` means
+  the key is absent from the final object's enumerable keys. Empty parents remain.
+- Paths are arrays of literal string keys, so dots, brackets, and empty keys are unambiguous.
+  An empty path `[]` means replacement of the root. These are not the string paths
+  accepted by `pick`, `set`, or `flush`; joining segments with `.` can lose information.
+- Operations follow the final object's key order, recursively, then report removed
+  keys in the first object's key order at each level. No changes return `[]`.
+
+`diff(first, last): DiffOperation[]` does not mutate or clone either input. Values in `set`
+operations retain references from `last`; this is not an independent snapshot.
+Getter and proxy errors propagate. Inputs must be acyclic; cycle detection is not performed.
+Shared references without cycles are supported. There is no options argument or patch applier.
+Native JSON serialization drops an `undefined` operation value, so these operations are not
+a lossless JSON transport format for arbitrary JavaScript values.
+
 ## merge
 
 Deeply merge plain objects into a target object.
@@ -216,16 +265,52 @@ extract(source, {
 Walk through an object and call a function for each value.
 
 ```ts
-each(data, (key, value, path) => {
-  console.log(key, value, path)
+each(data, (key, value, path, segments) => {
+  console.log(key, value, path, segments)
 })
 ```
 
 The callback receives:
 
-- `key`: the current object key or array index
+- `key`: the current object key or numeric array index; `undefined` for the root when enabled
 - `value`: the current value
-- `path`: the full path to the current value
+- `path`: the full string path to the current value
+- `segments`: literal path segments (`WalkKey[]`), with string object keys and numeric array indexes
+
+For example, a literal key `'user.name'` has segments `['user.name']`, while a nested
+`user.name` has `['user', 'name']`. `items[0].id` has `['items', 0, 'id']`.
+The first three callback arguments keep their existing meaning; old callbacks still work.
+Callback return values are ignored, including `false`.
+
+Pass options as the third argument:
+
+```ts
+each(data, (key, value, path, segments) => {
+  // The root is visited first with key undefined, path '', and segments [].
+}, {
+  root: true,
+  // Visit arrays themselves, but skip their contents.
+  descend: ({ value }) => Array.isArray(value) === false,
+})
+```
+
+| Option | Behavior | Default |
+| --- | --- | --- |
+| `root` | Visit the root, including primitive, nullish, or empty root values | `false` |
+| `descend` | Receive `{ key, value, path, segments }` and decide whether to visit a container's children | Visit all children |
+
+`descend` runs only for objects and arrays, after their callback. It also runs for the
+root container when `root` is false, allowing the entire traversal to be skipped.
+Returning `false` skips children, without evaluating their getters; the container itself
+is still visited when applicable. Errors from callbacks, getters, and `descend` propagate.
+Mutating the received `segments` arrays does not change traversal paths.
+
+`EachCallback`, `EachEntry`, and `EachOptions` are public named type exports.
+Without `root`, or with `root: false`, callback keys remain `WalkKey`. With `root: true`
+or a dynamic `root` option, keys are `WalkKey | undefined`. An explicitly typed callback
+can use `EachCallback<WalkKey | undefined>` when root visits are possible.
+Traversal does not detect cycles. `diff` uses `each` with `root: true` and a `descend`
+predicate that stops at arrays, non-plain objects, and branches replaced as a whole.
 
 ## map
 
@@ -358,10 +443,11 @@ pick(data, path)
 set(data, path, value)
 flush(data, path)
 extract(data, mapping)
-each(data, callback)
+each(data, callback, options?)
 map(data, callback)
 merge(target, ...sources)
 equally(a, b)
+diff(first, last) // DiffOperation[]
 parse(raw, options?) // unknown
 stringify(value, options?) // string | undefined
 ```

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   clone: () => clone,
+  diff: () => diff,
   each: () => each,
   equally: () => equally,
   extract: () => extract,
@@ -34,6 +35,40 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/helpers/createPath.ts
+var createPath = (parentPath, key, parentIsArray) => {
+  if (parentIsArray) {
+    return parentPath + "[" + key + "]";
+  }
+  return parentPath ? parentPath + "." + key : String(key);
+};
+
+// src/helpers/isWalkable.ts
+var isWalkable = (value) => {
+  return value !== null && typeof value === "object";
+};
+
+// src/each.ts
+var each = (data, callback, { root = false, descend } = {}) => {
+  const walk = (value, path, segments, key) => {
+    if (segments.length > 0 || root) {
+      callback(key, value, path, [...segments]);
+    }
+    if (isWalkable(value) && (descend === void 0 || descend({ key, value, path, segments: [...segments] }))) {
+      if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+          walk(item, createPath(path, index, true), [...segments, index], index);
+        });
+      } else {
+        Object.entries(value).forEach(([childKey, item]) => {
+          walk(item, createPath(path, childKey, false), [...segments, childKey], childKey);
+        });
+      }
+    }
+  };
+  walk(data, "", [], void 0);
+};
+
 // src/helpers/getValueByKey.ts
 var getValueByKey = (object, key, { inherited = true, ignore = [] } = {}) => {
   if (object === null || object === void 0 || ignore.includes(key) || !inherited && !Object.hasOwn(object, key)) {
@@ -85,51 +120,6 @@ var parsePathSelection = (path = "") => {
   };
 };
 
-// src/helpers/createPath.ts
-var createPath = (parentPath, key, parentIsArray) => {
-  if (parentIsArray) {
-    return parentPath + "[" + key + "]";
-  }
-  return parentPath ? parentPath + "." + key : String(key);
-};
-
-// src/helpers/isWalkable.ts
-var isWalkable = (value) => {
-  return value !== null && typeof value === "object";
-};
-
-// src/each.ts
-var each = (data, callback) => {
-  const walk = (value, path, key, parentIsArray) => {
-    const currentPath = path || createPath("", key, parentIsArray);
-    callback(key, value, currentPath);
-    if (!isWalkable(value)) {
-      return;
-    }
-    if (Array.isArray(value)) {
-      value.forEach((item, index) => {
-        walk(item, createPath(currentPath, index, true), index, true);
-      });
-      return;
-    }
-    Object.entries(value).forEach(([childKey, item]) => {
-      walk(item, createPath(currentPath, childKey, false), childKey, false);
-    });
-  };
-  if (!isWalkable(data)) {
-    return;
-  }
-  if (Array.isArray(data)) {
-    data.forEach((item, index) => {
-      walk(item, createPath("", index, true), index, true);
-    });
-    return;
-  }
-  Object.entries(data).forEach(([key, value]) => {
-    walk(value, createPath("", key, false), key, false);
-  });
-};
-
 // src/pick.ts
 var pick = (data = {}, path = "", options = {}) => {
   const { cleanPath, keys } = parsePathSelection(path);
@@ -245,15 +235,17 @@ var map = (data, callback, store = {}) => {
   return store;
 };
 
-// src/merge.ts
-var unsafeKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+// src/helpers/isPlainObject.ts
 var isPlainObject = (value) => {
-  if (value === null || typeof value !== "object") {
-    return false;
+  if (value !== null && typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
   }
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
+  return false;
 };
+
+// src/merge.ts
+var unsafeKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
 var merge = (target, ...sources) => {
   const targetRecord = target;
   for (const source of sources) {
@@ -353,6 +345,41 @@ var equalObjects = (x, y, store) => {
 // src/equally.ts
 var equally = (a, b) => deepEqual(a, b, /* @__PURE__ */ new WeakMap());
 
+// src/diff.ts
+var diff = (first, last) => {
+  const operations = [];
+  const frames = [];
+  const finish = (depth) => {
+    for (const { first: first2, last: last2, path } of frames.splice(depth).reverse()) {
+      for (const key of Object.keys(first2)) {
+        if (Object.prototype.propertyIsEnumerable.call(last2, key) === false) {
+          operations.push({ type: "delete", path: [...path, key] });
+        }
+      }
+    }
+    return frames.at(-1);
+  };
+  let descend = false;
+  each(last, (key, value, _path, segments) => {
+    const path = segments.map(String);
+    const frame = finish(segments.length);
+    const present = key === void 0 || frame !== void 0 && Object.prototype.propertyIsEnumerable.call(frame.first, key);
+    const previous = key === void 0 ? first : present ? frame?.first[key] : void 0;
+    descend = false;
+    if (present && isPlainObject(previous) && isPlainObject(value)) {
+      frames.push({ first: previous, last: value, path });
+      descend = true;
+    } else if (present === false || equally(previous, value) === false) {
+      operations.push({ type: "set", path, value });
+    }
+  }, {
+    root: true,
+    descend: () => descend
+  });
+  finish(0);
+  return operations;
+};
+
 // src/clone.ts
 var clone = (value) => {
   const store = /* @__PURE__ */ new WeakMap();
@@ -423,6 +450,7 @@ var stringify = (value, { fallback, onError, replacer, space } = {}) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   clone,
+  diff,
   each,
   equally,
   extract,

package/dist/index.d.cts

@@ -1,4 +1,12 @@
 type WalkKey = string | number;
+type DiffOperation = {
+    type: 'set';
+    path: string[];
+    value: unknown;
+} | {
+    type: 'delete';
+    path: string[];
+};
 type PickOptions = {
     inherited?: boolean;
     ignore?: readonly string[];
@@ -15,8 +23,24 @@ type StringifyOptions = {
     space?: string | number;
 };
 
-type EachCallback = (key: WalkKey, value: any, path: string) => void;
-declare const each: (data: any, callback: EachCallback) => void;
+type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (key: TKey, value: any, path: string, segments: WalkKey[]) => void;
+type EachEntry = {
+    key: WalkKey | undefined;
+    value: any;
+    path: string;
+    segments: WalkKey[];
+};
+type EachOptions = {
+    root?: boolean;
+    descend?: (entry: EachEntry) => boolean;
+};
+type Each = {
+    (data: any, callback: EachCallback, options?: EachOptions & {
+        root?: false;
+    }): void;
+    (data: any, callback: EachCallback<WalkKey | undefined>, options: EachOptions): void;
+};
+declare const each: Each;
 
 type ObjwalkObject$1 = Record<string, any>;
 declare const pick: (data?: ObjwalkObject$1, path?: string, options?: PickOptions) => any;
@@ -36,10 +60,12 @@ declare const flush: (data: ObjwalkObject$1 | undefined, path: string) => Objwal
 
 declare const equally: (a: unknown, b: unknown) => boolean;
 
+declare const diff: (first: unknown, last: unknown) => DiffOperation[];
+
 declare const clone: <T>(value: T) => T;
 
 declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOptions) => unknown;
 
 declare const stringify: (value: unknown, { fallback, onError, replacer, space }?: StringifyOptions) => string | undefined;
 
-export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, each, equally, extract, flush, map, merge, parse, pick, set, stringify };
+export { type DiffOperation, type EachCallback, type EachEntry, type EachOptions, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, diff, each, equally, extract, flush, map, merge, parse, pick, set, stringify };

package/dist/index.d.ts

@@ -1,4 +1,12 @@
 type WalkKey = string | number;
+type DiffOperation = {
+    type: 'set';
+    path: string[];
+    value: unknown;
+} | {
+    type: 'delete';
+    path: string[];
+};
 type PickOptions = {
     inherited?: boolean;
     ignore?: readonly string[];
@@ -15,8 +23,24 @@ type StringifyOptions = {
     space?: string | number;
 };
 
-type EachCallback = (key: WalkKey, value: any, path: string) => void;
-declare const each: (data: any, callback: EachCallback) => void;
+type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (key: TKey, value: any, path: string, segments: WalkKey[]) => void;
+type EachEntry = {
+    key: WalkKey | undefined;
+    value: any;
+    path: string;
+    segments: WalkKey[];
+};
+type EachOptions = {
+    root?: boolean;
+    descend?: (entry: EachEntry) => boolean;
+};
+type Each = {
+    (data: any, callback: EachCallback, options?: EachOptions & {
+        root?: false;
+    }): void;
+    (data: any, callback: EachCallback<WalkKey | undefined>, options: EachOptions): void;
+};
+declare const each: Each;
 
 type ObjwalkObject$1 = Record<string, any>;
 declare const pick: (data?: ObjwalkObject$1, path?: string, options?: PickOptions) => any;
@@ -36,10 +60,12 @@ declare const flush: (data: ObjwalkObject$1 | undefined, path: string) => Objwal
 
 declare const equally: (a: unknown, b: unknown) => boolean;
 
+declare const diff: (first: unknown, last: unknown) => DiffOperation[];
+
 declare const clone: <T>(value: T) => T;
 
 declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOptions) => unknown;
 
 declare const stringify: (value: unknown, { fallback, onError, replacer, space }?: StringifyOptions) => string | undefined;
 
-export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, each, equally, extract, flush, map, merge, parse, pick, set, stringify };
+export { type DiffOperation, type EachCallback, type EachEntry, type EachOptions, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, diff, each, equally, extract, flush, map, merge, parse, pick, set, stringify };

package/dist/index.js

@@ -1,3 +1,37 @@
+// src/helpers/createPath.ts
+var createPath = (parentPath, key, parentIsArray) => {
+  if (parentIsArray) {
+    return parentPath + "[" + key + "]";
+  }
+  return parentPath ? parentPath + "." + key : String(key);
+};
+
+// src/helpers/isWalkable.ts
+var isWalkable = (value) => {
+  return value !== null && typeof value === "object";
+};
+
+// src/each.ts
+var each = (data, callback, { root = false, descend } = {}) => {
+  const walk = (value, path, segments, key) => {
+    if (segments.length > 0 || root) {
+      callback(key, value, path, [...segments]);
+    }
+    if (isWalkable(value) && (descend === void 0 || descend({ key, value, path, segments: [...segments] }))) {
+      if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+          walk(item, createPath(path, index, true), [...segments, index], index);
+        });
+      } else {
+        Object.entries(value).forEach(([childKey, item]) => {
+          walk(item, createPath(path, childKey, false), [...segments, childKey], childKey);
+        });
+      }
+    }
+  };
+  walk(data, "", [], void 0);
+};
+
 // src/helpers/getValueByKey.ts
 var getValueByKey = (object, key, { inherited = true, ignore = [] } = {}) => {
   if (object === null || object === void 0 || ignore.includes(key) || !inherited && !Object.hasOwn(object, key)) {
@@ -49,51 +83,6 @@ var parsePathSelection = (path = "") => {
   };
 };
 
-// src/helpers/createPath.ts
-var createPath = (parentPath, key, parentIsArray) => {
-  if (parentIsArray) {
-    return parentPath + "[" + key + "]";
-  }
-  return parentPath ? parentPath + "." + key : String(key);
-};
-
-// src/helpers/isWalkable.ts
-var isWalkable = (value) => {
-  return value !== null && typeof value === "object";
-};
-
-// src/each.ts
-var each = (data, callback) => {
-  const walk = (value, path, key, parentIsArray) => {
-    const currentPath = path || createPath("", key, parentIsArray);
-    callback(key, value, currentPath);
-    if (!isWalkable(value)) {
-      return;
-    }
-    if (Array.isArray(value)) {
-      value.forEach((item, index) => {
-        walk(item, createPath(currentPath, index, true), index, true);
-      });
-      return;
-    }
-    Object.entries(value).forEach(([childKey, item]) => {
-      walk(item, createPath(currentPath, childKey, false), childKey, false);
-    });
-  };
-  if (!isWalkable(data)) {
-    return;
-  }
-  if (Array.isArray(data)) {
-    data.forEach((item, index) => {
-      walk(item, createPath("", index, true), index, true);
-    });
-    return;
-  }
-  Object.entries(data).forEach(([key, value]) => {
-    walk(value, createPath("", key, false), key, false);
-  });
-};
-
 // src/pick.ts
 var pick = (data = {}, path = "", options = {}) => {
   const { cleanPath, keys } = parsePathSelection(path);
@@ -209,15 +198,17 @@ var map = (data, callback, store = {}) => {
   return store;
 };
 
-// src/merge.ts
-var unsafeKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+// src/helpers/isPlainObject.ts
 var isPlainObject = (value) => {
-  if (value === null || typeof value !== "object") {
-    return false;
+  if (value !== null && typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
   }
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
+  return false;
 };
+
+// src/merge.ts
+var unsafeKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
 var merge = (target, ...sources) => {
   const targetRecord = target;
   for (const source of sources) {
@@ -317,6 +308,41 @@ var equalObjects = (x, y, store) => {
 // src/equally.ts
 var equally = (a, b) => deepEqual(a, b, /* @__PURE__ */ new WeakMap());
 
+// src/diff.ts
+var diff = (first, last) => {
+  const operations = [];
+  const frames = [];
+  const finish = (depth) => {
+    for (const { first: first2, last: last2, path } of frames.splice(depth).reverse()) {
+      for (const key of Object.keys(first2)) {
+        if (Object.prototype.propertyIsEnumerable.call(last2, key) === false) {
+          operations.push({ type: "delete", path: [...path, key] });
+        }
+      }
+    }
+    return frames.at(-1);
+  };
+  let descend = false;
+  each(last, (key, value, _path, segments) => {
+    const path = segments.map(String);
+    const frame = finish(segments.length);
+    const present = key === void 0 || frame !== void 0 && Object.prototype.propertyIsEnumerable.call(frame.first, key);
+    const previous = key === void 0 ? first : present ? frame?.first[key] : void 0;
+    descend = false;
+    if (present && isPlainObject(previous) && isPlainObject(value)) {
+      frames.push({ first: previous, last: value, path });
+      descend = true;
+    } else if (present === false || equally(previous, value) === false) {
+      operations.push({ type: "set", path, value });
+    }
+  }, {
+    root: true,
+    descend: () => descend
+  });
+  finish(0);
+  return operations;
+};
+
 // src/clone.ts
 var clone = (value) => {
   const store = /* @__PURE__ */ new WeakMap();
@@ -386,6 +412,7 @@ var stringify = (value, { fallback, onError, replacer, space } = {}) => {
 };
 export {
   clone,
+  diff,
   each,
   equally,
   extract,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objwalk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.",
   "keywords": [
     "object",

package/skills/objwalk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: objwalk
-description: Use when writing or editing JavaScript or TypeScript that imports `objwalk`, reads, writes, or deletes nested object paths, reshapes or walks objects, or uses objwalk JSON helpers.
+description: Use when writing or editing JavaScript or TypeScript that imports `objwalk`, reads, writes, or deletes nested object paths, computes differences, reshapes or walks objects, or uses objwalk JSON helpers.
 ---
 
 # objwalk
@@ -19,7 +19,7 @@ them with type assertions or assume every method accepts arbitrary `unknown`.
 Named imports only:
 
 ```ts
-import { clone, each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
+import { clone, diff, each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
 ```
 
 ## Choose the existing operation
@@ -30,14 +30,15 @@ import { clone, each, equally, extract, flush, map, merge, parse, pick, set, str
 | Write a nested value | `set(data, path, value)`; creates intermediate containers, mutates and returns `data`. |
 | Delete a nested property | `flush(data, path)`; deletes an own property, mutates and returns `data`; missing paths are left unchanged. |
 | Reshape an object | `extract(source, mapping)`; mapping keys are destination paths, values are source paths. |
-| Visit nested values | `each(data, (key, value, path) => { ... })`; visits containers and leaves, excluding the root. |
+| Visit nested values | `each(data, (key, value, path, segments) => { ... }, options?)`; root is excluded by default. |
 | Build a store while walking | `map(data, (key, value, store, path) => { ... }, store?)`; returns the store, ignores callback return values. |
 | Deep merge | `merge(target, ...sources)`; mutates and returns the target, merges plain objects, replaces arrays and non-plain values. |
 | Deep copy | `clone(value)`; preserves `Date`, `RegExp`, symbol keys, and circular references. |
 | Deep comparison | `equally(a, b)`; supports `NaN`, `Date`, `RegExp`, and circular references. |
+| Describe changes | `diff(first, last): DiffOperation[]`; returns `set`/`delete` operations, or `[]` when unchanged. |
 
 `set`, `flush`, and `merge` mutate their targets. Use `clone` first only when the task
-requires an independent copy. `each` and `map` do not support circular traversal;
+requires an independent copy. `each`, `map`, and `diff` do not support circular traversal;
 do not infer that capability from `clone` or `equally`.
 
 ## Paths and reshaping
@@ -72,6 +73,51 @@ pick(data, 'user.name', {
 })
 ```
 
+## Walking
+
+`each` passes literal `segments: WalkKey[]` as its fourth callback argument.
+Object keys are strings; array indexes are numbers. Prefer segments when keys may
+contain dots, brackets, or empty strings; the string `path` can be ambiguous.
+
+`EachOptions` accepts `root` (default `false`) and
+`descend: ({ key, value, path, segments }) => boolean`.
+With `root: true`, the root is visited first, including primitive/nullish values,
+with key `undefined`, path `''`, and segments `[]`. Callback keys are then typed
+`WalkKey | undefined`; legacy calls keep `WalkKey`. Use the public
+`EachCallback<WalkKey | undefined>` for an explicitly typed root-aware callback.
+`EachEntry` and `EachOptions` are also public named exports.
+
+`descend` is called only for containers, after their callback, and returning false
+skips their children. It also runs for a root container excluded from callbacks.
+For example, `descend: ({ value }) => Array.isArray(value) === false` visits arrays
+without traversing their elements. Callback return values remain ignored, including
+false. Mutating received segments does not affect traversal. Callback/getter/descend
+errors propagate. Cycles are not detected.
+
+## Differences
+
+`diff` recursively compares two plain objects by their own enumerable string keys;
+symbol/non-enumerable keys, prototypes, and descriptors are not reported during that traversal.
+Arrays and other values use `equally` and are replaced as a whole when changed.
+New properties are also set as whole values. The public `DiffOperation` type is:
+
+```ts
+type DiffOperation =
+  | { type: 'set'; path: string[]; value: unknown }
+  | { type: 'delete'; path: string[] }
+```
+
+Paths contain literal keys; `[]` replaces the root. Do not join them with `.` to
+call `set` or `flush`: keys may contain dots or brackets. `merge` does not apply
+these operations. There is no patch applier or options argument.
+
+Deletion is distinct from assigning `null` or `undefined`, including adding an own
+`undefined` property. Empty parent objects remain. Inputs are not mutated or cloned;
+`set.value` retains references from `last`. Native JSON serialization loses an
+`undefined` value, so do not assume lossless transport for arbitrary JS values.
+Getter/proxy errors propagate. Cycles are outside the contract, without detection;
+shared references without cycles work.
+
 ## JSON and ready values
 
 Call `parse(raw, options?)` directly with `raw: unknown`. The library chooses