objwalk 1.5.0 → 1.7.0

package/dist/index.js

@@ -1,3 +1,35 @@
+// 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) => {
+    const proceed = segments.length > 0 || root ? callback(key, value, path, [...segments]) !== false : true;
+    if (proceed && isWalkable(value) && (descend === void 0 || descend({ key, value, path, segments: [...segments] }))) {
+      if (Array.isArray(value)) {
+        return value.every(
+          (item, index) => walk(item, createPath(path, index, true), [...segments, index], index)
+        );
+      }
+      return Object.keys(value).every(
+        (childKey) => walk(value[childKey], createPath(path, childKey, false), [...segments, childKey], childKey)
+      );
+    }
+    return proceed;
+  };
+  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 +81,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);
@@ -187,13 +174,13 @@ var extract = (source, mapping) => {
       return;
     }
     if (Array.isArray(sourcePath)) {
-      for (const item of sourcePath) {
+      each(sourcePath, (_key, item) => {
         const value = pick(source, item);
         if (value !== void 0) {
           set(result, destinationPath, value);
-          break;
+          return false;
         }
-      }
+      });
       return;
     }
     set(result, destinationPath, pick(source, sourcePath));
@@ -209,114 +196,144 @@ 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) {
-    if (!isPlainObject(source)) {
-      continue;
-    }
-    for (const [key, sourceValue] of Object.entries(source)) {
-      if (unsafeKeys.has(key)) {
-        continue;
-      }
-      const targetValue = targetRecord[key];
-      if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
-        merge(targetValue, sourceValue);
-      } else {
-        targetRecord[key] = sourceValue;
-      }
+  each(sources, (_index, source) => {
+    if (isPlainObject(source)) {
+      each(Object.entries(source), (_index2, [key, sourceValue]) => {
+        if (unsafeKeys.has(key) === false) {
+          const targetValue = targetRecord[key];
+          if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+            merge(targetValue, sourceValue);
+          } else {
+            targetRecord[key] = sourceValue;
+          }
+        }
+      }, { descend: ({ segments }) => segments.length === 0 });
     }
-  }
+  }, { descend: ({ segments }) => segments.length === 0 });
   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];
+  const paths = Array.isArray(path) ? path : [path];
+  each(paths, (_key, path2) => {
+    if (path2.length > 0) {
+      const keys = path2.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)) {
+  if (x === y || Number.isNaN(x) && Number.isNaN(y)) {
     return true;
   }
-  if (x === y) {
-    return true;
-  }
-  if (x == null || y == null) {
-    return false;
-  }
-  if (typeof x !== "object" || typeof y !== "object") {
-    return false;
-  }
-  let seen = store.get(x);
-  if (seen !== void 0 && seen.has(y)) {
-    return true;
-  }
-  if (seen === void 0) {
-    seen = /* @__PURE__ */ new WeakSet();
-    store.set(x, seen);
-  }
-  seen.add(y);
-  if (x instanceof Date && y instanceof Date) {
-    return x.getTime() === y.getTime();
-  }
-  if (x instanceof RegExp && y instanceof RegExp) {
-    return x.toString() === y.toString();
-  }
-  const isArrayX = Array.isArray(x);
-  const isArrayY = Array.isArray(y);
-  if (isArrayX !== isArrayY) {
-    return false;
-  }
-  if (isArrayX) {
-    return equalArrays(x, y, store);
+  if (x !== null && y !== null && typeof x === "object" && typeof y === "object") {
+    let seen = store.get(x);
+    if (seen !== void 0 && seen.has(y)) {
+      return true;
+    }
+    if (seen === void 0) {
+      seen = /* @__PURE__ */ new WeakSet();
+      store.set(x, seen);
+    }
+    seen.add(y);
+    if (x instanceof Date || y instanceof Date) {
+      return x instanceof Date && y instanceof Date && x.getTime() === y.getTime();
+    }
+    if (x instanceof RegExp || y instanceof RegExp) {
+      return x instanceof RegExp && y instanceof RegExp && x.toString() === y.toString();
+    }
+    if (Array.isArray(x) && Array.isArray(y)) {
+      const { length } = x;
+      let equal = length === y.length;
+      let index = 0;
+      while (equal && index < length) {
+        equal = deepEqual(x[index], y[index], store);
+        index += 1;
+      }
+      return equal;
+    } else if (Array.isArray(x) === false && Array.isArray(y) === false) {
+      const keysX = Reflect.ownKeys(x);
+      const keysY = Reflect.ownKeys(y);
+      return keysX.length === keysY.length && keysX.every(
+        (key) => Object.hasOwn(y, key) && deepEqual(x[key], y[key], store)
+      );
+    }
   }
-  return equalObjects(x, y, store);
+  return false;
 };
-var equalArrays = (x, y, store) => x.length === y.length && x.every((value, index) => deepEqual(value, y[index], store));
-var equalObjects = (x, y, store) => {
-  const keysX = Reflect.ownKeys(x);
-  const keysY = Reflect.ownKeys(y);
-  if (keysX.length !== keysY.length) {
-    return false;
+
+// src/equally.ts
+var equally = (a, b, paths) => {
+  if (paths !== void 0) {
+    return paths.every((path) => equally(getValueByPath(a, path), getValueByPath(b, path)));
   }
-  return keysX.every((key) => {
-    if (!Object.hasOwn(y, key)) {
-      return false;
+  return deepEqual(a, b, /* @__PURE__ */ new WeakMap());
+};
+
+// src/diff.ts
+var diff = (first, last) => {
+  const operations = [];
+  const frames = [];
+  const finish = (depth) => {
+    each(frames.splice(depth).reverse(), (_index, { first: first2, last: last2, path }) => {
+      each(Object.keys(first2), (_index2, key) => {
+        if (Object.prototype.propertyIsEnumerable.call(last2, key) === false) {
+          operations.push({ type: "delete", path: [...path, key] });
+        }
+      });
+    }, { descend: ({ segments }) => segments.length === 0 });
+    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 });
     }
-    return deepEqual(x[key], y[key], store);
+  }, {
+    root: true,
+    descend: () => descend
   });
+  finish(0);
+  return operations;
 };
 
-// src/equally.ts
-var equally = (a, b) => deepEqual(a, b, /* @__PURE__ */ new WeakMap());
-
 // src/clone.ts
 var clone = (value) => {
   const store = /* @__PURE__ */ new WeakMap();
@@ -344,9 +361,9 @@ var clone = (value) => {
     }
     const result = {};
     store.set(obj, result);
-    for (const key of Reflect.ownKeys(obj)) {
+    each(Reflect.ownKeys(obj), (_index, key) => {
       result[key] = cloneValue(obj[key]);
-    }
+    });
     return result;
   };
   return cloneValue(value);
@@ -386,6 +403,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.7.0",
   "description": "Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.",
   "keywords": [
     "object",
@@ -40,11 +40,12 @@
   "files": [
     "dist",
     "README.md",
+    "SPEC.md",
     "skills"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "test": "vitest run",
+    "test": "tsc --project tsconfig.test.json && vitest run",
     "pack:check": "npm pack --dry-run"
   },
   "prepublishOnly": "npm run build",

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
@@ -28,16 +28,17 @@ import { clone, each, equally, extract, flush, map, merge, parse, pick, set, str
 | --- | --- |
 | 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. |
+| Delete nested properties | `flush(data, path)`; accepts one path or `string[]`, deletes own properties, 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?)`; supports objects and arrays, root is excluded by default; returning `false` stops the entire traversal. |
 | 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. |
+| Deep comparison | `equally(a, b, paths?)`; supports `NaN`, `Date`, `RegExp`, and circular references; optional `string[]` compares only selected paths. |
+| 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
@@ -52,7 +53,8 @@ do not infer that capability from `clone` or `equally`.
 
 `[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.
+`undefined`, preserving `null`, `false`, `0`, and empty strings; later paths are
+not read. Sparse path arrays in `flush` and fallback arrays in `extract` skip holes.
 
 Use `flush` to remove a property rather than `set(data, path, undefined)`, which
 leaves the property present. `flush` traverses and deletes only own properties.
@@ -62,6 +64,18 @@ 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.
 
+`flush` processes a path array in order; `[]` leaves the target unchanged.
+`equally` without `paths` (or with `undefined`) compares whole values. With `paths`,
+every selected value must match; `[]` returns true and `''` selects the whole input.
+It uses dot notation and explicit array indexes, reading inherited properties like
+`pick`; unresolved paths compare as `undefined`, including against an explicit
+`undefined` value. Selection syntax and `[n]` mappings are not supported.
+Getter/proxy errors propagate.
+
+`equally` compares `Date` and `RegExp` only with their respective types. Arrays
+compare every index, including holes, which read as `undefined`; holes match
+explicit `undefined` slots but not other values.
+
 `pick` reads inherited properties by default. Use its existing options when own
 properties or ignored keys are required:
 
@@ -72,6 +86,57 @@ 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. Returning exactly `false` from the callback stops
+the entire traversal, including siblings and ancestor branches; other return values
+are ignored. The stopped container's `descend` is not called, and its children and
+subsequent values are not read. Object keys are collected on entering a container;
+values are read as visited. `each` still returns `undefined`. Existing callbacks
+that returned `false` must omit that return to keep walking. `map` continues to
+ignore callback return values for both objects and arrays.
+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
@@ -101,5 +166,6 @@ Fallback applies only to exceptions. Preserve valid falsy results and native
 `undefined`. Neither fallback nor a throwing `onError` changes stringify's
 return type of `string | undefined`.
 
-Full usage: [README](../../README.md). In a consumer project, read the installed
+Full usage: [README](../../README.md). Edge cases: [specification](../../SPEC.md).
+In a consumer project, read the installed
 package's README and declarations when checking the available version's API.