objwalk 1.7.0 → 1.8.0

package/README.md

@@ -125,21 +125,37 @@ 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 `map` to transform values while keeping the object and array structure:
 
 ```ts
-import { map, set } from 'objwalk'
+import { map } from 'objwalk'
 
-const cleaned = map({ name: ' Natalia ', tags: [' ts '] }, (_key, value, store, path) => {
-  if (typeof value === 'string') {
-    set(store, path, value.trim())
-  }
-})
+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`.
+For selective traversal, pass `descend` in the third argument.
+[Mapping options](SPEC.md#map).
 
 ## Merge defaults or make a copy
 
@@ -188,7 +204,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,
@@ -217,22 +217,81 @@ not share stop state.
 ## map
 
 ```ts
-type MapCallback<TStore extends Record<string, any> = Record<string, any>> = (
-  key: WalkKey,
+type MapCallback<TResult = unknown, TKey extends WalkKey = WalkKey> = (
+  key: TKey,
   value: any,
-  store: TStore,
   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.
+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`. Deep calls, dynamic shallow flags, and union inputs
+keep `WalkKey`. An arbitrary `descend` predicate does not narrow keys. 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

@@ -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
+        });
+      }, { 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) => {

package/dist/index.d.cts

@@ -48,8 +48,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> = (key: TKey, value: any, path: string) => TResult;
+type MapOptions = {
+    descend?: EachOptions['descend'];
+    shallow?: boolean;
+};
+type Map = {
+    <TResult>(data: readonly unknown[], callback: MapCallback<TResult, number>, options: MapOptions & {
+        shallow: true;
+    }): TResult[];
+    <TResult>(data: Record<string, unknown>, callback: MapCallback<TResult, string>, 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 +83,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

@@ -48,8 +48,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> = (key: TKey, value: any, path: string) => TResult;
+type MapOptions = {
+    descend?: EachOptions['descend'];
+    shallow?: boolean;
+};
+type Map = {
+    <TResult>(data: readonly unknown[], callback: MapCallback<TResult, number>, options: MapOptions & {
+        shallow: true;
+    }): TResult[];
+    <TResult>(data: Record<string, unknown>, callback: MapCallback<TResult, string>, 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 +83,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

@@ -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
+        });
+      }, { 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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objwalk",
-  "version": "1.7.0",
+  "version": "1.8.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. |
@@ -108,11 +108,32 @@ 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.
+`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
 
 `diff` recursively compares two plain objects by their own enumerable string keys;