objwalk 1.8.0 → 1.9.0

package/README.md

@@ -125,6 +125,21 @@ 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 `{ shallow: true }` to visit dictionary entries as whole values:
+
+```ts
+import { each } from 'objwalk'
+
+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
@@ -154,6 +169,7 @@ const counts = map(
 ```
 
 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).
 

package/SPEC.md

@@ -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,9 +241,9 @@ not share stop state.
 ## map
 
 ```ts
-type MapCallback<TResult = unknown, TKey extends WalkKey = WalkKey> = (
+type MapCallback<TResult = unknown, TKey extends WalkKey = WalkKey, TValue = any> = (
   key: TKey,
-  value: any,
+  value: TValue,
   path: string
 ) => TResult
 
@@ -240,7 +264,8 @@ Callback replacements are not traversed again, including returned objects and ar
 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.
+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.
@@ -274,8 +299,14 @@ visits. This timing differs from `each`, which calls its callback before `descen
 
 `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
+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.
 

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)
@@ -251,7 +251,7 @@ var map = (data, callback, { descend, shallow = false } = {}) => {
           enumerable: true,
           configurable: true
         });
-      }, { descend: ({ segments: segments2 }) => segments2.length === 0 });
+      }, { shallow: true });
     }
     return key !== void 0 ? callback(key, mapped, path) : mapped;
   };

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,16 +64,16 @@ 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<TResult = unknown, TKey extends WalkKey = WalkKey> = (key: TKey, value: any, path: string) => TResult;
+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>(data: readonly unknown[], callback: MapCallback<TResult, number>, options: MapOptions & {
+    <TResult, TValue = any>(data: readonly TValue[], callback: MapCallback<TResult, number, TValue>, options: MapOptions & {
         shallow: true;
     }): TResult[];
-    <TResult>(data: Record<string, unknown>, callback: MapCallback<TResult, string>, options: MapOptions & {
+    <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[];

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,16 +64,16 @@ 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<TResult = unknown, TKey extends WalkKey = WalkKey> = (key: TKey, value: any, path: string) => TResult;
+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>(data: readonly unknown[], callback: MapCallback<TResult, number>, options: MapOptions & {
+    <TResult, TValue = any>(data: readonly TValue[], callback: MapCallback<TResult, number, TValue>, options: MapOptions & {
         shallow: true;
     }): TResult[];
-    <TResult>(data: Record<string, unknown>, callback: MapCallback<TResult, string>, options: MapOptions & {
+    <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[];

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)
@@ -214,7 +214,7 @@ var map = (data, callback, { descend, shallow = false } = {}) => {
           enumerable: true,
           configurable: true
         });
-      }, { descend: ({ segments: segments2 }) => segments2.length === 0 });
+      }, { shallow: true });
     }
     return key !== void 0 ? callback(key, mapped, path) : mapped;
   };

package/package.json

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

package/skills/objwalk/SKILL.md

@@ -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
@@ -131,7 +141,11 @@ 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.
+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