objwalk 1.6.0 → 1.8.0

package/dist/index.js

@@ -14,20 +14,18 @@ var isWalkable = (value) => {
 // 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] }))) {
+    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)) {
-        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);
-        });
+        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);
 };
@@ -176,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));
@@ -190,14 +188,6 @@ var extract = (source, mapping) => {
   return result;
 };
 
-// src/map.ts
-var map = (data, callback, store = {}) => {
-  each(data, (key, value, path) => {
-    callback(key, value, store, path);
-  });
-  return store;
-};
-
 // src/helpers/isPlainObject.ts
 var isPlainObject = (value) => {
   if (value !== null && typeof value === "object") {
@@ -207,119 +197,136 @@ var isPlainObject = (value) => {
   return false;
 };
 
+// src/map.ts
+var map = (data, callback, { descend, shallow = false } = {}) => {
+  const walk = (value, key, path, segments) => {
+    const root = key === void 0;
+    let mapped = root ? Array.isArray(value) ? [] : {} : value;
+    if ((root || Array.isArray(value) || isPlainObject(value)) && (root || shallow === false) && (descend === void 0 || descend({ key, value, path, segments: [...segments] }))) {
+      mapped = Array.isArray(value) ? Array(value.length) : {};
+      each(value, (key2, value2) => {
+        const childPath = createPath(path, key2, Array.isArray(mapped));
+        const childSegments = [...segments, key2];
+        const result = walk(value2, key2, childPath, childSegments);
+        Object.defineProperty(mapped, key2, {
+          value: result,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+      }, { descend: ({ segments: segments2 }) => segments2.length === 0 });
+    }
+    return key !== void 0 ? callback(key, mapped, path) : mapped;
+  };
+  return walk(data, void 0, "", []);
+};
+
 // 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)) {
-    return true;
-  }
-  if (x === y) {
+  if (x === y || Number.isNaN(x) && Number.isNaN(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);
-  }
-  return equalObjects(x, y, store);
-};
-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;
-  }
-  return keysX.every((key) => {
-    if (!Object.hasOwn(y, key)) {
-      return false;
+  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;
     }
-    return deepEqual(x[key], y[key], store);
-  });
+    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 false;
 };
 
 // src/equally.ts
-var equally = (a, b) => deepEqual(a, b, /* @__PURE__ */ new WeakMap());
+var equally = (a, b, paths) => {
+  if (paths !== void 0) {
+    return paths.every((path) => equally(getValueByPath(a, path), getValueByPath(b, path)));
+  }
+  return 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)) {
+    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;
@@ -370,9 +377,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objwalk",
-  "version": "1.6.0",
+  "version": "1.8.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

@@ -28,13 +28,13 @@ import { clone, diff, each, equally, extract, flush, map, merge, parse, pick, se
 | --- | --- |
 | 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, 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. |
+| 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. |
+| Transform nested values | `map(data, (key, value, path) => replacement, options?)`; returns a new array or dictionary with the same keys. |
 | 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
@@ -53,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.
@@ -63,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:
 
@@ -90,9 +103,36 @@ with key `undefined`, path `''`, and segments `[]`. Callback keys are then typed
 `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.
+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. Mutating received
+segments does not affect traversal. Callback/getter/descend errors
+propagate. Cycles are not detected.
+
+`map(data, callback, options?)` returns a new array for an array root and a new
+ordinary dictionary for a dictionary root. Its callback is `(key, value, path)`;
+return the replacement value. There is no store argument. `false`, `null`, and
+`undefined` are ordinary output values, not traversal control. To accumulate a
+different structure, use `each` with an explicit accumulator.
+
+Deep map callbacks run children first, then their containing value; the root is
+excluded. Plain objects and arrays are rebuilt, while non-plain objects such as
+Date and RegExp are passed to the callback as leaves. Callback results are not
+traversed again. Source data is not assigned to, but returned or pruned values
+can retain references. Array holes and literal object keys are preserved.
+
+`MapOptions` is the third argument. `descend` receives original containers before
+children are mapped; false prunes their children and passes the original value to
+the callback. It also runs for the excluded root, where false produces an empty
+result of the same kind. Literal `shallow: true` visits only immediate children,
+typing dictionary keys as `string` and array keys as `number`. When both options
+are present, `descend` is evaluated only for the root. Deep/dynamic calls keep
+`WalkKey`; a custom descend predicate alone cannot narrow keys.
+`MapCallback<TResult, TKey>` describes the callback's returned value and key type.
+This is a breaking replacement of the old store-based map, not an overload.
 
 ## Differences
 
@@ -147,5 +187,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.