objwalk 1.7.0 → 1.9.0

package/README.md

@@ -125,21 +125,53 @@ Return `false` to stop the entire walk. For more control, `each` also accepts
 `root` and `descend` options and provides literal path segments as a fourth
 callback argument. [Traversal details](SPEC.md#each).
 
-Use `map` when the walk should build a result:
+Use `{ shallow: true }` to visit dictionary entries as whole values:
 
 ```ts
-import { map, set } from 'objwalk'
+import { each } from 'objwalk'
 
-const cleaned = map({ name: ' Natalia ', tags: [' ts '] }, (_key, value, store, path) => {
-  if (typeof value === 'string') {
-    set(store, path, value.trim())
-  }
-})
+each({ first: { count: 1 }, second: { count: 2 } }, (key, value) => {
+  console.log(key, value.count)
+}, { shallow: true })
+// first 1
+// second 2
+```
+
+Here, `key` is inferred as `string` and `value` as `{ count: number }`.
+Shallow array visits infer a numeric index and the array's element type.
+
+Use `map` to transform values while keeping the object and array structure:
+
+```ts
+import { map } from 'objwalk'
+
+const cleaned = map({ name: ' Natalia ', tags: [' ts '] }, (_key, value) =>
+  typeof value === 'string' ? value.trim() : value
+)
 // { name: 'Natalia', tags: ['ts'] }
 ```
 
-`map` returns its store and ignores callback return values. Both walkers expect
-acyclic data.
+Each callback return becomes the value at that key or index in the new result.
+The input is not modified by `map`. Both walkers expect acyclic data unless
+traversal options prune the cycles.
+
+When your callback handles each entry as a whole, use a shallow walk:
+
+```ts
+import { map } from 'objwalk'
+
+const counts = map(
+  { editors: ['Natalia'], readers: ['Ada', 'Grace'] },
+  (_key, value) => value.length,
+  { shallow: true }
+)
+// { editors: 1, readers: 2 }
+```
+
+Shallow dictionary keys are typed as `string`; shallow array indexes are `number`.
+Both `each` and `map` also infer the original value type in shallow mode.
+For selective traversal, pass `descend` in the third argument.
+[Mapping options](SPEC.md#map).
 
 ## Merge defaults or make a copy
 
@@ -188,7 +220,7 @@ formatting, and an `onError` callback are available through options.
 | Delete one or several paths | [`flush(data, path)`](SPEC.md#flush) |
 | Reshape data with a mapping | [`extract(source, mapping)`](SPEC.md#extract) |
 | Visit nested values | [`each(data, callback, options?)`](SPEC.md#each) |
-| Build a result while walking | [`map(data, callback, store?)`](SPEC.md#map) |
+| Transform values while keeping keys | [`map(data, callback, options?)`](SPEC.md#map) |
 | Merge plain objects | [`merge(target, ...sources)`](SPEC.md#merge) |
 | Copy supported values | [`clone(value)`](SPEC.md#clone) |
 | Compare values or selected paths | [`equally(a, b, paths?)`](SPEC.md#equally) |

package/SPEC.md

@@ -30,7 +30,7 @@ type DiffOperation =
 | `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 |
+| `map(data, callback, options?)` | New array or dictionary | Callback returns each replacement value; pruned and returned values can retain references |
 | `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 |
@@ -41,8 +41,8 @@ type DiffOperation =
 `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.
+functions accept every possible JavaScript value. `each` accepts `any`; `map`
+accepts dictionaries and readonly arrays; `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,
@@ -163,9 +163,9 @@ does not provide an independent deep snapshot.
 ## each
 
 ```ts
-type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (
+type EachCallback<TKey extends WalkKey | undefined = WalkKey, TValue = any> = (
   key: TKey,
-  value: any,
+  value: TValue,
   path: string,
   segments: WalkKey[]
 ) => unknown
@@ -180,6 +180,7 @@ type EachEntry = {
 type EachOptions = {
   root?: boolean
   descend?: (entry: EachEntry) => boolean
+  shallow?: boolean
 }
 ```
 
@@ -194,8 +195,9 @@ 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`.
+strings and array indexes are numbers. In the default deep mode, callback keys
+are typed as `WalkKey` without root visits; enabled or dynamic root options use
+`WalkKey | undefined`. Shallow key and value types are described below.
 
 Returning exactly `false` from the callback stops the entire traversal, including
 siblings and remaining ancestor branches. Other return values, including other
@@ -207,6 +209,28 @@ both completion and early stopping.
 an excluded root container. Returning `false` skips that container's children and
 continues with siblings. It does not stop the entire traversal.
 
+`shallow` defaults to `false`. With `shallow: true`, only immediate root children
+are visited, plus the root when requested. Child values are passed by reference;
+their contents are not read. `descend` is evaluated only for the root because
+child containers are already at the shallow limit. Root pruning and stopping via
+callback `false` keep their existing meanings. Cyclic child values are safe when
+the shallow limit prevents following them.
+
+With literal `shallow: true` and root visits disabled, dictionary keys are typed
+as `string` and values as the dictionary's value type; readonly array keys are
+`number` and values are the element type. Heterogeneous inputs produce the union
+of their immediate value types. With root visits enabled or a dynamic root flag,
+the key type additionally includes `undefined`, and the value type additionally
+includes the root container's type. These key/value unions are not correlated
+for control-flow narrowing; narrow a union value before accessing its fields.
+
+Deep traversal, dynamic shallow flags, and unknown or mixed array/dictionary inputs retain the
+general key and value types. An arbitrary `descend` predicate does not narrow
+them. `EachCallback<TKey, TValue>` supports explicitly typed callbacks; `TValue`
+defaults to `any` to preserve existing callback type declarations.
+`EachEntry.value` in `descend` remains general because the predicate can see
+different container levels, including the root.
+
 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
@@ -217,22 +241,88 @@ not share stop state.
 ## map
 
 ```ts
-type MapCallback<TStore extends Record<string, any> = Record<string, any>> = (
-  key: WalkKey,
-  value: any,
-  store: TStore,
+type MapCallback<TResult = unknown, TKey extends WalkKey = WalkKey, TValue = any> = (
+  key: TKey,
+  value: TValue,
   path: string
-) => void
-```
+) => TResult
 
-`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.
+type MapOptions = {
+  descend?: EachOptions['descend']
+  shallow?: boolean
+}
+```
 
-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.
+`map(data, callback, options?)` transforms a dictionary or array without assigning
+into the input. An array root produces a new array; a dictionary root produces a
+new ordinary object. The root is excluded from callback visits. Every visited
+property or array index retains its literal key; its value becomes the callback's
+return value. `false`, `null`, and `undefined` are stored as ordinary results;
+there is no callback return value for stopping, filtering, or deleting entries.
+Callback replacements are not traversed again, including returned objects and arrays.
+
+The callback receives `(key, value, path)`. Object keys are strings, array indexes
+are numbers, and paths follow `each`'s descriptive string format. No accumulator or
+store argument exists. `MapCallback`'s first generic argument is the return value
+rather than the former store type; the optional second argument is the key type,
+and the optional third argument is the input value type (default `any`).
+Array results are typed as `TResult[]`; dictionary results as
+`Record<string, TResult>`. A dictionary-or-array union input produces the matching
+union result type. Readonly input arrays are accepted and produce mutable new arrays.
+Deep callback values are typed as `any`, since earlier child transformations can
+change their contents.
+
+Deep traversal is the default. Plain objects and arrays are recursively mapped
+before their containing value is passed to the callback. Thus callbacks run in
+postorder: children first, then their parent, with the root still excluded.
+A container callback receives a newly built container containing its already
+mapped children. A pruned container callback instead receives the original value
+by reference. `Date`, `RegExp`, other non-plain objects, and functions are leaves:
+they are passed directly to the callback without rebuilding their internal state.
+The root dictionary's own entries are enumerated regardless of its prototype;
+the plain-object restriction applies to nested traversal.
+
+Objects enumerate own enumerable string keys; inherited, symbol, and non-enumerable
+properties are excluded. Literal dots, brackets, empty keys, and `__proto__` are
+preserved as own data properties rather than parsed as paths. Result objects use
+`Object.prototype`; source prototypes and descriptors are not copied. Array indexes
+follow `each` iteration, preserving length and absent slots. An explicitly returned
+`undefined` is an own slot, whereas an unvisited hole remains absent. Inherited
+indexed values can be visited; extra array properties are excluded.
+
+`descend` runs on each original traversable container before visiting children,
+including the excluded root. It receives `EachEntry` with literal `segments`;
+modifying these segments does not alter traversal paths. Returning `false` prunes
+children, then the container's callback processes the original value as a whole.
+Pruning the root produces an empty container of the same kind, with no callback
+visits. This timing differs from `each`, which calls its callback before `descend`.
+
+`shallow` defaults to `false`. With literal `shallow: true`, only immediate root
+children are mapped: dictionary callback keys are typed as `string`, and statically
+known array keys as `number`. The input value type is inferred from the dictionary
+values or array elements, including readonly and heterogeneous inputs. A shallow
+`Record<string, T>` or readonly `T[]` passes `T` to its callback. Deep calls, dynamic
+shallow flags, and union inputs keep `WalkKey` and general callback values. An
+arbitrary `descend` predicate does not narrow these types. The shallow overloads
+use `<TResult, TValue = any>`: calls that explicitly provide only `TResult` retain
+the default `any` value type for compatibility. Omit explicit type arguments for
+full inference, or provide both result and value types. When both
+options are present, `descend` is evaluated only for the root, because child
+containers are already at the shallow limit.
+
+Traversed containers are new. Pruned containers, special objects, and values
+returned by the callback may share references with the input. Each occurrence of
+a shared traversable container is mapped separately. Cycles are not detected;
+pruning can prevent descent into a cyclic branch. Exceptions from callbacks,
+getters, and `descend` propagate. The function does not roll back callback side
+effects or await promises returned by callbacks.
+
+This replaces the published accumulator-based contract. Migrate
+`map(data, (key, value, store, path) => { store[key] = transform(value) }, store)`
+to `map(data, (key, value, path) => transform(value), options)` when the result
+retains input keys. Callers that build a different structure should use `each`
+and manage their accumulator explicitly. Old stores are not accepted as options,
+and there is no compatibility overload or `undefined` placeholder.
 
 ## merge
 

package/dist/index.cjs

@@ -49,10 +49,10 @@ var isWalkable = (value) => {
 };
 
 // src/each.ts
-var each = (data, callback, { root = false, descend } = {}) => {
+var each = (data, callback, { root = false, descend, shallow = false } = {}) => {
   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 (proceed && (segments.length === 0 || shallow === false) && 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)
@@ -225,14 +225,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") {
@@ -242,6 +234,30 @@ 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
+        });
+      }, { shallow: true });
+    }
+    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) => {

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[]) => unknown;
+type EachCallback<TKey extends WalkKey | undefined = WalkKey, TValue = any> = (key: TKey, value: TValue, path: string, segments: WalkKey[]) => unknown;
 type EachEntry = {
     key: WalkKey | undefined;
     value: any;
@@ -33,8 +33,24 @@ type EachEntry = {
 type EachOptions = {
     root?: boolean;
     descend?: (entry: EachEntry) => boolean;
+    shallow?: boolean;
 };
+type DictionaryValue<TData> = TData extends unknown ? TData[keyof TData] : never;
 type Each = {
+    <TData extends readonly unknown[]>(data: TData, callback: EachCallback<number, TData[number]>, options: EachOptions & {
+        shallow: true;
+        root?: false;
+    }): void;
+    <TData extends Record<string, unknown>>(data: TData, callback: EachCallback<string, DictionaryValue<TData>>, options: EachOptions & {
+        shallow: true;
+        root?: false;
+    }): void;
+    <TData extends readonly unknown[]>(data: TData, callback: EachCallback<number | undefined, TData[number] | TData>, options: EachOptions & {
+        shallow: true;
+    }): void;
+    <TData extends Record<string, unknown>>(data: TData, callback: EachCallback<string | undefined, DictionaryValue<TData> | TData>, options: EachOptions & {
+        shallow: true;
+    }): void;
     (data: any, callback: EachCallback, options?: EachOptions & {
         root?: false;
     }): void;
@@ -48,8 +64,23 @@ declare const pick: (data?: ObjwalkObject$1, path?: string, options?: PickOption
 type ExtractMapping = Record<string, string | string[]>;
 declare const extract: (source: ObjwalkObject$1, mapping: ExtractMapping) => ObjwalkObject$1;
 
-type MapCallback<TStore extends Record<string, any> = Record<string, any>> = (key: WalkKey, value: any, store: TStore, path: string) => void;
-declare const map: <TStore extends Record<string, any> = Record<string, any>>(data: any, callback: MapCallback<TStore>, store?: TStore) => TStore;
+type MapCallback<TResult = unknown, TKey extends WalkKey = WalkKey, TValue = any> = (key: TKey, value: TValue, path: string) => TResult;
+type MapOptions = {
+    descend?: EachOptions['descend'];
+    shallow?: boolean;
+};
+type Map = {
+    <TResult, TValue = any>(data: readonly TValue[], callback: MapCallback<TResult, number, TValue>, options: MapOptions & {
+        shallow: true;
+    }): TResult[];
+    <TResult, TValue = any>(data: Record<string, TValue>, callback: MapCallback<TResult, string, TValue>, options: MapOptions & {
+        shallow: true;
+    }): Record<string, TResult>;
+    <TResult>(data: readonly unknown[], callback: MapCallback<TResult>, options?: MapOptions): TResult[];
+    <TResult>(data: Record<string, unknown>, callback: MapCallback<TResult>, options?: MapOptions): Record<string, TResult>;
+    <TResult>(data: Record<string, unknown> | readonly unknown[], callback: MapCallback<TResult>, options?: MapOptions): Record<string, TResult> | TResult[];
+};
+declare const map: Map;
 
 declare const merge: <T extends ObjwalkObject$1>(target: T, ...sources: unknown[]) => T;
 
@@ -68,4 +99,4 @@ declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOption
 
 declare const stringify: (value: unknown, { fallback, onError, replacer, space }?: StringifyOptions) => string | undefined;
 
-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 };
+export { type DiffOperation, type EachCallback, type EachEntry, type EachOptions, type ExtractMapping, type MapCallback, type MapOptions, 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

@@ -23,7 +23,7 @@ type StringifyOptions = {
     space?: string | number;
 };
 
-type EachCallback<TKey extends WalkKey | undefined = WalkKey> = (key: TKey, value: any, path: string, segments: WalkKey[]) => unknown;
+type EachCallback<TKey extends WalkKey | undefined = WalkKey, TValue = any> = (key: TKey, value: TValue, path: string, segments: WalkKey[]) => unknown;
 type EachEntry = {
     key: WalkKey | undefined;
     value: any;
@@ -33,8 +33,24 @@ type EachEntry = {
 type EachOptions = {
     root?: boolean;
     descend?: (entry: EachEntry) => boolean;
+    shallow?: boolean;
 };
+type DictionaryValue<TData> = TData extends unknown ? TData[keyof TData] : never;
 type Each = {
+    <TData extends readonly unknown[]>(data: TData, callback: EachCallback<number, TData[number]>, options: EachOptions & {
+        shallow: true;
+        root?: false;
+    }): void;
+    <TData extends Record<string, unknown>>(data: TData, callback: EachCallback<string, DictionaryValue<TData>>, options: EachOptions & {
+        shallow: true;
+        root?: false;
+    }): void;
+    <TData extends readonly unknown[]>(data: TData, callback: EachCallback<number | undefined, TData[number] | TData>, options: EachOptions & {
+        shallow: true;
+    }): void;
+    <TData extends Record<string, unknown>>(data: TData, callback: EachCallback<string | undefined, DictionaryValue<TData> | TData>, options: EachOptions & {
+        shallow: true;
+    }): void;
     (data: any, callback: EachCallback, options?: EachOptions & {
         root?: false;
     }): void;
@@ -48,8 +64,23 @@ declare const pick: (data?: ObjwalkObject$1, path?: string, options?: PickOption
 type ExtractMapping = Record<string, string | string[]>;
 declare const extract: (source: ObjwalkObject$1, mapping: ExtractMapping) => ObjwalkObject$1;
 
-type MapCallback<TStore extends Record<string, any> = Record<string, any>> = (key: WalkKey, value: any, store: TStore, path: string) => void;
-declare const map: <TStore extends Record<string, any> = Record<string, any>>(data: any, callback: MapCallback<TStore>, store?: TStore) => TStore;
+type MapCallback<TResult = unknown, TKey extends WalkKey = WalkKey, TValue = any> = (key: TKey, value: TValue, path: string) => TResult;
+type MapOptions = {
+    descend?: EachOptions['descend'];
+    shallow?: boolean;
+};
+type Map = {
+    <TResult, TValue = any>(data: readonly TValue[], callback: MapCallback<TResult, number, TValue>, options: MapOptions & {
+        shallow: true;
+    }): TResult[];
+    <TResult, TValue = any>(data: Record<string, TValue>, callback: MapCallback<TResult, string, TValue>, options: MapOptions & {
+        shallow: true;
+    }): Record<string, TResult>;
+    <TResult>(data: readonly unknown[], callback: MapCallback<TResult>, options?: MapOptions): TResult[];
+    <TResult>(data: Record<string, unknown>, callback: MapCallback<TResult>, options?: MapOptions): Record<string, TResult>;
+    <TResult>(data: Record<string, unknown> | readonly unknown[], callback: MapCallback<TResult>, options?: MapOptions): Record<string, TResult> | TResult[];
+};
+declare const map: Map;
 
 declare const merge: <T extends ObjwalkObject$1>(target: T, ...sources: unknown[]) => T;
 
@@ -68,4 +99,4 @@ declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOption
 
 declare const stringify: (value: unknown, { fallback, onError, replacer, space }?: StringifyOptions) => string | undefined;
 
-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 };
+export { type DiffOperation, type EachCallback, type EachEntry, type EachOptions, type ExtractMapping, type MapCallback, type MapOptions, 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

@@ -12,10 +12,10 @@ var isWalkable = (value) => {
 };
 
 // src/each.ts
-var each = (data, callback, { root = false, descend } = {}) => {
+var each = (data, callback, { root = false, descend, shallow = false } = {}) => {
   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 (proceed && (segments.length === 0 || shallow === false) && 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)
@@ -188,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") {
@@ -205,6 +197,30 @@ 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
+        });
+      }, { shallow: true });
+    }
+    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) => {

package/package.json

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

package/skills/objwalk/SKILL.md

@@ -31,7 +31,7 @@ import { clone, diff, each, equally, extract, flush, map, merge, parse, pick, se
 | 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?)`; 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. |
+| 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, paths?)`; supports `NaN`, `Date`, `RegExp`, and circular references; optional `string[]` compares only selected paths. |
@@ -92,7 +92,7 @@ pick(data, 'user.name', {
 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
+`EachOptions` accepts `root` and `shallow` (both 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
@@ -100,6 +100,16 @@ with key `undefined`, path `''`, and segments `[]`. Callback keys are then typed
 `EachCallback<WalkKey | undefined>` for an explicitly typed root-aware callback.
 `EachEntry` and `EachOptions` are also public named exports.
 
+Use `each(data, callback, { shallow: true })` to visit only immediate entries.
+Literal shallow mode infers string dictionary keys, numeric array indexes, and
+the input value type. With root visits enabled or a dynamic root flag, key types
+also include `undefined` and value types include the root container. Narrow the
+value union explicitly; key/value parameters are not correlated. `descend` runs
+only at the shallow root. Callback `false` still stops the entire traversal.
+`EachCallback<TKey, TValue>` adds an optional value type parameter, defaulting
+to `any` for existing explicit callback declarations. Dynamic shallow flags and
+unknown inputs retain general callback types.
+
 `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
@@ -108,11 +118,36 @@ the entire traversal, including siblings and ancestor branches; other return val
 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
+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.
+Shallow map also infers the input value type; deep/dynamic callback values stay
+general. `MapCallback<TResult, TKey, TValue>` describes the callback's result,
+key, and input value types. Calls that specify only `map<TResult>` retain the
+default `any` input value type; omit explicit generics for full inference or
+provide both result and value types.
+This is a breaking replacement of the old store-based map, not an overload.
+
 ## Differences
 
 `diff` recursively compares two plain objects by their own enumerable string keys;