objwalk 1.6.0 → 1.7.0

package/SPEC.md

@@ -0,0 +1,383 @@
+# objwalk specification
+
+This document describes the public API in the current source tree, including changes
+not yet released. [README.md](README.md) provides examples; [tests](tests/) exercise
+the contracts.
+
+## Public API and shared types
+
+All functions and types below are named exports from `objwalk`.
+
+```ts
+type ObjwalkObject = Record<string, any>
+type WalkKey = string | number
+type ExtractMapping = Record<string, string | string[]>
+
+type PickOptions = {
+  inherited?: boolean
+  ignore?: readonly string[]
+}
+
+type DiffOperation =
+  | { type: 'set'; path: string[]; value: unknown }
+  | { type: 'delete'; path: string[] }
+```
+
+| Function | Return value | Mutation and identity |
+| --- | --- | --- |
+| `pick(data, path?, options?)` | Selected value, selection object, key list, or `undefined` | Selected values retain their references |
+| `set(data, path, value)` | Input object | Mutates the input; assigned values are not cloned |
+| `flush(data, path)` | Input object | Mutates the input |
+| `extract(source, mapping)` | New result object | Selected values are not cloned |
+| `each(data, callback, options?)` | `undefined` | Passes original values to callbacks |
+| `map(data, callback, store?)` | Supplied store or a new object | Callback builds or mutates the store |
+| `merge(target, ...sources)` | Target object | Mutates the target; replacement values are not cloned |
+| `clone(value)` | Value of the same declared generic type | Recursively copies supported objects and arrays |
+| `equally(a, b, paths?)` | `boolean` | Does not assign to the inputs |
+| `diff(first, last)` | `DiffOperation[]` | Does not assign to inputs; operation values retain references |
+| `parse(raw, options?)` | `unknown` | Ready objects and arrays retain their references |
+| `stringify(value, options?)` | `string \| undefined` | Uses native JSON serialization |
+
+`pick`, `set`, and `flush` use `{}` when their `data` argument is `undefined`.
+`set` and `flush` still require the path argument. `pick` defaults its path to `''`.
+Their declared data contract is `ObjwalkObject`; this is not a guarantee that all
+functions accept every possible JavaScript value. `each` and `map` accept `any`;
+`clone` is generic; `equally`, `diff`, `parse`, and `stringify` accept `unknown` inputs.
+`extract` requires an object and a mapping; `merge` requires an object target.
+
+Except for the documented JSON error handling, exceptions from callbacks, getters,
+setters, proxies, or native property operations propagate. Mutations already made
+before an exception are not rolled back. Functions are synchronous and do not await
+callback results. User callbacks and property accessors can have their own side effects.
+
+## Paths
+
+Paths are strings, not arrays of literal segments. A dot separates object properties.
+An explicit array segment has the form `items[0]`; its parser matches
+`^(\w+)\[(\d+)\]$`. Use canonical non-negative decimal indexes and a word-character
+property name for this syntax. A bracket segment resolves only when its named value
+is an array. Ordinary segments use property lookup.
+
+Supported examples are `user.name`, `items[0].title`, and
+`groups[0].items[1].id`. Quoted brackets, escaping dots, negative indexes, and nested
+brackets such as `matrix[0][1]` are not supported path operators. Unsupported syntax
+is not automatically rejected: a segment can instead be treated as a literal key.
+There is no general path validator.
+
+| Syntax | Interpretation |
+| --- | --- |
+| `user.name` | Property traversal |
+| `items[0].title` | Explicit array index followed by property traversal |
+| `user.{name,email}` | Terminal key selection in `pick` |
+| `user.{*}` | Terminal key listing in `pick` |
+| `items[n].title` | Array mapping in `extract`, paired with a source mapping |
+
+Key selection is interpreted by `pick`, including source paths passed through
+`pick` by `extract`. It is not interpreted by `set`, `flush`, or `equally`.
+`[n]` is not a wildcard for the other functions.
+
+Empty paths have operation-specific meanings:
+
+- `pick(data, '')` returns the root value.
+- `equally(a, b, [''])` compares the whole input values.
+- `flush(data, '')` does nothing.
+- `set(data, '', value)` assigns the property whose key is the empty string.
+
+Traversal paths from `each` and `map` are descriptive strings, not a lossless encoding
+of arbitrary keys. Literal dots, brackets, and empty keys can make them ambiguous.
+A root array produces paths such as `[0]`, which do not have the named-array-segment
+form above. Use `each`'s literal `segments` or `diff`'s operation paths when exact keys matter.
+
+## pick
+
+`pick(data, path?, options?)` reads a path without creating intermediate containers.
+Missing or nullish intermediate values produce `undefined`. Valid falsy values are
+preserved. An explicit array index outside the array resolves to `undefined`, unless
+a value is available through the configured property lookup.
+
+`PickOptions` defaults to `{ inherited: true, ignore: [] }`. `inherited: false`
+restricts every property and array-index lookup to own properties. `ignore` matches
+exact string keys, including array indexes represented as strings, at every lookup.
+
+Terminal selection trims whitespace around comma-separated keys and removes empty
+entries. One selected key returns its value. Multiple selected keys return a new
+object containing every selected key, including keys whose values are `undefined`.
+Selection requires an object value; an unresolved or primitive selection base returns
+`undefined`. The selection operation does not clone selected values.
+
+`{*}` returns own enumerable string keys, filtered by `ignore`, in `Object.keys`
+order. It returns `[]` for arrays, primitives, nullish values, or unresolved paths;
+it does not list inherited keys even when inherited lookup is enabled.
+
+## set
+
+`set(data, path, value)` mutates and returns the same input object. It uses direct
+property lookup and assignment, without `PickOptions` or the key filter from `merge`.
+
+For an ordinary intermediate segment, missing, nullish, and primitive values are
+replaced with `{}`. Existing object values, including arrays, are reused.
+For an array segment, a non-array named value is replaced with `[]`. A later index
+extends the array, leaving holes before that index. An intermediate indexed value
+is initialized to `{}` only when it is `undefined`; existing null or primitive
+indexed values are not normalized into objects for further traversal.
+
+The final property or array slot is assigned even when `value` is `undefined`.
+Assignment is distinct from deletion. No empty-parent pruning or rollback occurs.
+
+## flush
+
+`flush(data, path)` accepts `path: string | string[]`. Each path deletes an own
+property using native `delete`, and the function returns the same input object.
+
+- Path arrays are processed in order and are not modified. Holes are skipped.
+- Empty lists, empty paths, missing paths, and nullish or primitive parents are no-ops.
+- Traversal and deletion use only own properties, including explicit array indexes.
+- Missing containers are not created; empty parents are not removed.
+- Overlapping and repeated paths are processed against the state left by earlier paths.
+- Deleting an array slot leaves a hole; length and later indexes are unchanged.
+- An exception stops processing immediately. Earlier deletions remain applied and
+  later paths are not processed.
+
+## extract
+
+`extract(source, mapping)` creates a result root. Mapping keys are destination paths;
+values are source paths or ordered arrays of fallback source paths.
+
+Mappings are processed in `Object.entries(mapping)` order. A direct source path is
+read with `pick` and written with `set`, even when its value is `undefined`.
+A fallback array selects the first value that is not `undefined`; `null`, `false`,
+`0`, and `''` all count as resolved. Holes are skipped and later paths are not read
+after a match. If none resolve, that mapping performs no assignment.
+
+For array mapping, use one `[n].` marker in both the destination path and its string
+source path, for example `'items[n].title': 'products[n].name'`. The source prefix
+must resolve to an array. Each present source item is read using the source suffix
+and assigned at the corresponding destination index. A non-array source produces
+no assignments. Multiple mapping markers and fallback arrays of array mappings
+are outside this mapping contract.
+
+The result root is new, but selected objects are assigned by reference. Overlapping
+destination writes can therefore modify objects shared with the source. `extract`
+does not provide an independent deep snapshot.
+
+## each
+
+```ts
+type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (
+  key: TKey,
+  value: any,
+  path: string,
+  segments: WalkKey[]
+) => unknown
+
+type EachEntry = {
+  key: WalkKey | undefined
+  value: any
+  path: string
+  segments: WalkKey[]
+}
+
+type EachOptions = {
+  root?: boolean
+  descend?: (entry: EachEntry) => boolean
+}
+```
+
+`each(data, callback, options?)` walks objects and arrays depth first, visiting a
+value before its children. Objects enumerate own enumerable string keys in
+`Object.keys` order; symbols and non-enumerable properties are not enumerated.
+Arrays visit numeric indexes in ascending order, using native `every` iteration:
+absent slots are skipped, inherited indexed values can be visited, and non-index
+properties are not traversed. Any non-null object can be a container; functions
+are leaves, and built-in collection internals are not traversed.
+
+`root` defaults to `false`. When enabled, the root is visited first with key
+`undefined`, path `''`, and segments `[]`, even for primitive, nullish, or empty
+inputs. Otherwise a primitive or nullish root has no visits. Object keys are
+strings and array indexes are numbers. Without root visits, callback keys are
+typed as `WalkKey`; enabled or dynamic root options use `WalkKey | undefined`.
+
+Returning exactly `false` from the callback stops the entire traversal, including
+siblings and remaining ancestor branches. Other return values, including other
+falsy values, are ignored. A stopped container does not invoke `descend` or visit
+children; subsequent values are not read. The function returns `undefined` after
+both completion and early stopping.
+
+`descend` is evaluated only for containers, after their callback. It also runs for
+an excluded root container. Returning `false` skips that container's children and
+continues with siblings. It does not stop the entire traversal.
+
+Object keys are collected when entering a container; values are read as visited.
+For arrays, native iteration captures the starting length: appended slots beyond
+that length are not visited. Callback and `descend` receive separate copies of
+`segments`; modifying those copies does not change traversal paths. `value` remains
+the original value. Cycles are not detected. Separate and nested invocations do
+not share stop state.
+
+## map
+
+```ts
+type MapCallback<TStore extends Record<string, any> = Record<string, any>> = (
+  key: WalkKey,
+  value: any,
+  store: TStore,
+  path: string
+) => void
+```
+
+`map(data, callback, store?)` uses the default `each` traversal for objects and arrays,
+excluding the root. The callback receives the original value and the same store
+on every visit. A supplied store is returned by identity; otherwise the store is
+a new `{}`. The generic store type is preserved in the return type.
+
+All callback return values, including `false`, are ignored. `map` exposes neither
+root/descend options nor literal segments. Errors propagate and completed store
+mutations remain applied. Cycles are not detected.
+
+## merge
+
+`merge<T extends ObjwalkObject>(target: T, ...sources: unknown[]): T` mutates and
+returns the target. Sources are applied left to right. A source is processed only
+when its prototype is `Object.prototype` or `null`; other root sources are ignored.
+
+Each source uses its own enumerable string entries. Entry values are read by
+`Object.entries` before that source's assignments begin. Keys `__proto__`,
+`constructor`, and `prototype` are skipped at every recursive merge level.
+Symbols and non-enumerable source keys are not merged.
+
+When the current target value and source value are both plain objects, they are
+merged recursively. Otherwise the source value replaces the target value by
+reference, including arrays, `Date`, `null`, and `undefined`. Replacement objects
+are not traversed just because they have been assigned. The operation does not
+guarantee cycle handling or preserve a snapshot of source values beyond each
+source's entry collection.
+
+## clone
+
+`clone<T>(value: T): T` returns primitive values and functions unchanged. Arrays
+and ordinary object properties are recursively copied with a reference store,
+preserving their shared references and circular links within the copied graph.
+
+- Arrays copy indexed values up to their length into a new array. Holes become
+  explicit `undefined` entries; extra properties and symbol keys are not copied.
+- Other objects use `Reflect.ownKeys`, including symbols and non-enumerable keys,
+  to read values and assign them to a new ordinary object. Custom prototypes and
+  property descriptors are not preserved; accessors are evaluated rather than copied.
+- `Date` uses a new instance with the same timestamp; `RegExp` uses its source and
+  flags. Their custom properties are not copied, `lastIndex` is not retained, and
+  repeated references to these special values are not deduplicated by the store.
+- There is no specialized copying of `Map`, `Set`, typed-array internal state, or
+  class invariants. The generic return type does not guarantee preservation of
+  those runtime capabilities.
+
+Property access errors propagate. The implementation does not assign to the source.
+
+## equally
+
+`equally(a: unknown, b: unknown, paths?: string[]): boolean` performs deep comparison.
+Omitting `paths`, or passing `undefined`, compares the whole values. Providing a
+path list compares only the selected values; all must match. An empty list returns
+`true`, holes are skipped, and comparison stops at the first mismatch. Unselected
+properties and later paths are not read.
+
+Path reads use ordinary dot and explicit array-index lookup with inherited
+properties enabled. Missing paths resolve to `undefined`, so a missing value and
+an explicit `undefined` value compare equally. `''` selects the root. Selection
+syntax and `[n]` mappings are not interpreted.
+
+For whole values or each selected value:
+
+- Strictly identical values compare equal, including `0` and `-0`.
+- `NaN` compares equal to `NaN`. Other primitive values use strict equality.
+- Two `Date` instances compare timestamps; two `RegExp` instances compare source
+  and flags. Distinct invalid dates have unequal timestamps under strict equality.
+  A `Date` or `RegExp` cannot equal a value of the other type or an ordinary object.
+- An array and a non-array compare unequal. Arrays compare lengths and indexed
+  values in both dense and sparse arrays. A hole reads as `undefined`, including
+  when compared against an explicit `undefined` slot. Inherited indexed values
+  follow ordinary property lookup. Comparison is independent of argument order
+  for inputs without access side effects. Values are read once per compared index,
+  and reading stops at the first mismatch. Extra string and symbol properties
+  are not compared.
+- Other objects compare all own string and symbol keys, including non-enumerable
+  keys, then recursively compare values. Key order, prototypes, and descriptors
+  are not compared. Accessors are evaluated.
+- Previously visited object pairs allow circular graphs to terminate; alias
+  identity across otherwise equal object graphs is not required.
+
+There is no specialized comparison of collection internal state such as `Map`
+or `Set` entries. The same rules apply to whole-value and selected-path comparisons.
+
+## diff
+
+`diff(first: unknown, last: unknown): DiffOperation[]` describes changes from the
+first value to the last. Equal inputs produce `[]`.
+
+When both values at a location are plain objects, comparison recurses through own
+enumerable string keys. Inherited, symbol, and non-enumerable properties are not
+part of that recursion. Other values, including arrays, use `equally` and are
+replaced as a whole when unequal. Newly added values are also set as a whole.
+
+Paths are arrays of literal string keys. `[]` identifies a root replacement.
+They are not string-path arguments for `pick`, `set`, or `flush`, and must not be
+joined with dots when keys can contain path punctuation.
+
+Changed and added values are visited in the last object's key order. Removals
+are emitted when leaving their containing branch, in the first object's key
+order, before moving to the next branch. An own `undefined` value is distinct
+from deletion. Empty parents remain; prototype and descriptor changes are not
+reported during plain-object recursion.
+
+Operations contain original references from `last`, without cloning. No patch
+applier, options argument, or cycle detection is provided. Acyclic shared references
+are supported. JSON serialization can drop an `undefined` operation value, so the
+operation list is not a lossless JSON transport for every JavaScript value.
+
+## parse and stringify
+
+```ts
+type ParseOptions = {
+  fallback?: unknown
+  onError?: (error: unknown) => void
+  reviver?: Parameters<typeof JSON.parse>[1]
+}
+
+type StringifyOptions = {
+  fallback?: string
+  onError?: (error: unknown) => void
+  replacer?: ParseOptions['reviver'] | Parameters<typeof JSON.stringify>[1]
+  space?: string | number
+}
+```
+
+`parse(raw: unknown, options?): unknown` returns ready arrays and plain objects
+by reference without walking them or calling `reviver`. Plain objects include
+null-prototype objects. Other values use
+`JSON.parse(typeof raw === 'string' ? raw : String(raw), reviver)`.
+`ArrayBuffer` and array-buffer views always use the text path; there is no binary
+decoder. The result can be any JSON root type, or the arbitrary result of a
+reviver. There is no generic `parse<T>()` or object-only mode.
+
+`stringify(value: unknown, options?): string | undefined` always calls native
+`JSON.stringify` with `replacer` and `space`. Strings are serialized as strings,
+not treated as already serialized JSON. Native omission, array-null replacement,
+formatting, `toJSON`, and callback `this` binding are preserved.
+
+Both functions catch exceptions from their normal operation, including recognition,
+conversion, getters, proxies, and JSON callbacks. On an exception, `onError`, when
+provided, receives the original thrown value once, then the function returns
+`fallback`, which defaults to `undefined`. A throwing `onError` propagates its
+exception without being called again. Its return value is ignored.
+
+Fallback applies only to exceptions. Valid `null`, `false`, `0`, and `''` are
+preserved. A root reviver result of `undefined`, or native `stringify(undefined)`,
+does not invoke error handling or use the fallback. A string fallback or throwing
+handler does not narrow stringify's public `string | undefined` return type.
+Callback side effects are not rolled back. There is no logging, JSON repair, or
+domain-shape validation.
+
+## Verification
+
+`npm test` type-checks source and tests through `tsconfig.test.json`, then runs
+Vitest. This includes compile-time `expectTypeOf` assertions. `npm run build` generates ESM,
+CommonJS, and declarations; `npm run pack:check` inspects the npm package contents.

package/dist/index.cjs

@@ -51,20 +51,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);
 };
@@ -213,13 +211,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));
@@ -248,115 +246,108 @@ var isPlainObject = (value) => {
 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;
@@ -407,9 +398,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/dist/index.d.cts

@@ -23,7 +23,7 @@ type StringifyOptions = {
     space?: string | number;
 };
 
-type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (key: TKey, value: any, path: string, segments: WalkKey[]) => void;
+type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (key: TKey, value: any, path: string, segments: WalkKey[]) => unknown;
 type EachEntry = {
     key: WalkKey | undefined;
     value: any;
@@ -56,9 +56,9 @@ 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 flush: (data: ObjwalkObject$1 | undefined, path: string | string[]) => ObjwalkObject$1;
 
-declare const equally: (a: unknown, b: unknown) => boolean;
+declare const equally: (a: unknown, b: unknown, paths?: string[]) => boolean;
 
 declare const diff: (first: unknown, last: unknown) => DiffOperation[];
 

package/dist/index.d.ts

@@ -23,7 +23,7 @@ type StringifyOptions = {
     space?: string | number;
 };
 
-type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (key: TKey, value: any, path: string, segments: WalkKey[]) => void;
+type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (key: TKey, value: any, path: string, segments: WalkKey[]) => unknown;
 type EachEntry = {
     key: WalkKey | undefined;
     value: any;
@@ -56,9 +56,9 @@ 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 flush: (data: ObjwalkObject$1 | undefined, path: string | string[]) => ObjwalkObject$1;
 
-declare const equally: (a: unknown, b: unknown) => boolean;
+declare const equally: (a: unknown, b: unknown, paths?: string[]) => boolean;
 
 declare const diff: (first: unknown, last: unknown) => DiffOperation[];