objwalk 1.4.0 → 1.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.
 
-`objwalk` is built around a compact path syntax, so the same mental model works for picking values, setting values, extracting a new object shape, and walking through nested data.
+`objwalk` is built around a compact path syntax, so the same mental model works for picking, setting, and deleting values, extracting a new object shape, and walking through nested data.
 
 > Coding agent? Load the [objwalk skill](skills/objwalk/SKILL.md).
 
@@ -15,7 +15,7 @@ npm install objwalk
 ## Usage
 
 ```ts
-import { each, equally, extract, map, merge, parse, pick, set, stringify } from 'objwalk'
+import { diff, each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
 ```
 
 ## pick
@@ -96,6 +96,38 @@ set(data, 'items[0].title', 'First')
 
 `set` mutates the object passed to it and returns the same object.
 
+## flush
+
+Delete a property by path using native `delete` semantics.
+
+```ts
+const data = { user: { name: 'Ada', role: 'admin' } }
+
+flush(data, 'user.name')
+// { user: { role: 'admin' } }
+
+flush({}, 'path.to.key') // {}
+flush({ user: null }, 'user.name') // { user: null }
+```
+
+`flush(data, path)` mutates and returns the same object. Missing paths, `null`,
+`undefined`, and primitive parents are left unchanged. It does not create intermediate
+containers or remove empty parents. An empty path leaves the object unchanged.
+Only own properties are traversed and deleted; inherited properties are left unchanged.
+
+Array indexes use the same explicit syntax as `pick` and `set`:
+
+```ts
+const data = { items: [{ title: 'First' }, { title: 'Second' }] }
+
+flush(data, 'items[0].title') // { items: [{}, { title: 'Second' }] }
+flush(data, 'items[1]') // { items: [{}, <empty item>] }
+```
+
+Deleting an array item leaves a hole, preserves its length, and does not shift later items.
+Selection syntax (`{name,email}`, `{*}`) and `[n]` mappings are not supported by `flush`.
+Errors from getters, proxies, or deleting non-configurable properties propagate to the caller.
+
 ## equally
 
 Deeply compare two values for structural equality.
@@ -111,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.
@@ -184,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
 
@@ -304,8 +421,8 @@ The wrappers do not mutate inputs, undo callback side effects, log errors, or re
 
 | Syntax | Description |
 | --- | --- |
-| `user.name` | Read or write a nested property. |
-| `items[0].title` | Read or write an array item by index. |
+| `user.name` | Read, write, or delete a nested property. |
+| `items[0].title` | Read, write, or delete an array item's property by index. |
 | `user.{name,email}` | Pick several keys from one object. |
 | `user.{*}` | List keys from one object. |
 | `items[n].title` | Map every item in an array during `extract`. |
@@ -324,11 +441,13 @@ them without redundant wrappers that only repeat object checks.
 ```ts
 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,9 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   clone: () => clone,
+  diff: () => diff,
   each: () => each,
   equally: () => equally,
   extract: () => extract,
+  flush: () => flush,
   map: () => map,
   merge: () => merge,
   parse: () => parse,
@@ -33,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)) {
@@ -84,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);
@@ -244,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) {
@@ -274,6 +267,27 @@ var merge = (target, ...sources) => {
   return target;
 };
 
+// src/flush.ts
+var flush = (data = {}, path) => {
+  if (path.length > 0) {
+    const keys = path.split(".");
+    const lastKey = keys.pop() ?? "";
+    const match = lastKey.match(/^(\w+)\[(\d+)\]$/);
+    let parent = getValueByPath(data, keys.join("."), { inherited: false });
+    let key = lastKey;
+    if (match) {
+      const [, arrayKey, index] = match;
+      const array = getValueByKey(parent, arrayKey, { inherited: false });
+      parent = Array.isArray(array) ? array : void 0;
+      key = index;
+    }
+    if (parent !== null && typeof parent === "object" && Object.hasOwn(parent, key)) {
+      delete parent[key];
+    }
+  }
+  return data;
+};
+
 // src/deepEqual.ts
 var deepEqual = (x, y, store) => {
   if (Number.isNaN(x) && Number.isNaN(y)) {
@@ -331,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();
@@ -401,9 +450,11 @@ 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,
+  flush,
   map,
   merge,
   parse,

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;
@@ -32,12 +56,16 @@ declare const merge: <T extends ObjwalkObject$1>(target: T, ...sources: unknown[
 type ObjwalkObject = Record<string, any>;
 declare const set: (data: ObjwalkObject | undefined, path: string, value: any) => ObjwalkObject;
 
+declare const flush: (data: ObjwalkObject$1 | undefined, path: string) => ObjwalkObject$1;
+
 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, 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;
@@ -32,12 +56,16 @@ declare const merge: <T extends ObjwalkObject$1>(target: T, ...sources: unknown[
 type ObjwalkObject = Record<string, any>;
 declare const set: (data: ObjwalkObject | undefined, path: string, value: any) => ObjwalkObject;
 
+declare const flush: (data: ObjwalkObject$1 | undefined, path: string) => ObjwalkObject$1;
+
 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, 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) {
@@ -239,6 +230,27 @@ var merge = (target, ...sources) => {
   return target;
 };
 
+// src/flush.ts
+var flush = (data = {}, path) => {
+  if (path.length > 0) {
+    const keys = path.split(".");
+    const lastKey = keys.pop() ?? "";
+    const match = lastKey.match(/^(\w+)\[(\d+)\]$/);
+    let parent = getValueByPath(data, keys.join("."), { inherited: false });
+    let key = lastKey;
+    if (match) {
+      const [, arrayKey, index] = match;
+      const array = getValueByKey(parent, arrayKey, { inherited: false });
+      parent = Array.isArray(array) ? array : void 0;
+      key = index;
+    }
+    if (parent !== null && typeof parent === "object" && Object.hasOwn(parent, key)) {
+      delete parent[key];
+    }
+  }
+  return data;
+};
+
 // src/deepEqual.ts
 var deepEqual = (x, y, store) => {
   if (Number.isNaN(x) && Number.isNaN(y)) {
@@ -296,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();
@@ -365,9 +412,11 @@ var stringify = (value, { fallback, onError, replacer, space } = {}) => {
 };
 export {
   clone,
+  diff,
   each,
   equally,
   extract,
+  flush,
   map,
   merge,
   parse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objwalk",
-  "version": "1.4.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 or writes 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, 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
@@ -28,15 +28,17 @@ import { clone, each, equally, extract, map, merge, parse, pick, set, stringify
 | --- | --- |
 | Read a nested value | `pick(data, path, options?)`; unresolved paths return `undefined`. |
 | 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` and `merge` mutate their targets. Use `clone` first only when the task
-requires an independent copy. `each` and `map` do not support circular traversal;
+`set`, `flush`, and `merge` mutate their targets. Use `clone` first only when the task
+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
@@ -49,10 +51,18 @@ do not infer that capability from `clone` or `equally`.
 | `user.{*}` | List object keys with `pick`. |
 | `items[n].title` | Map array items in `extract`, with `[n]` in both source and destination paths. |
 
-`[n]` is an `extract` mapping feature, not a general wildcard for `pick` or `set`.
+`[n]` is an `extract` mapping feature, not a general wildcard for `pick`, `set`, or `flush`.
 An array of source paths in `extract` selects the first result that is not
 `undefined`, preserving `null`, `false`, `0`, and empty strings.
 
+Use `flush` to remove a property rather than `set(data, path, undefined)`, which
+leaves the property present. `flush` traverses and deletes only own properties.
+Missing, nullish, or primitive parents and empty paths are left unchanged; no
+containers are created and empty parents remain. Explicit array indexes work,
+but deleting an item leaves a hole without shifting indexes or changing length.
+Selection syntax (`{name,email}`, `{*}`) is not supported. Errors from getters,
+proxies, or deleting non-configurable properties propagate.
+
 `pick` reads inherited properties by default. Use its existing options when own
 properties or ignored keys are required:
 
@@ -63,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