@peter.naydenov/walk-async 7.0.0 → 7.0.2

package/skills/README.md

@@ -0,0 +1,108 @@
+# Walk Async skill
+
+The distributable skill is [walk-async/SKILL.md](walk-async/SKILL.md). Its name is
+`walk-async`, matching the library. Install the entire `walk-async` folder, including
+`references`; installing only `SKILL.md` loses the detailed guidance.
+
+## Agent integration
+
+Keep the canonical skill in `skills/walk-async/`, independent of any agent vendor.
+Agents can read it at that path or install the same folder using their skill
+installer. Discovery locations differ between agents; top-level `skills/`
+does not imply automatic discovery by every tool. For example, Claude Code
+documents separate project, personal, and plugin locations in its
+[skill documentation](https://code.claude.com/docs/en/skills).
+
+Do not duplicate the skill under `.claude` or change personal agent
+configuration as part of maintaining this directory.
+
+## Authoring sources
+
+Guidance checked on October 4, 2026:
+
+- [Anthropic skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): concise instructions, precise descriptions, progressive disclosure, direct references, and evaluation-driven iteration.
+- [Claude Code skills](https://code.claude.com/docs/en/skills): discovery locations, invocation, frontmatter, and supporting files.
+
+Follow Anthropic's recommendation to keep the `SKILL.md` body under 500
+lines. This is an upper limit, not a target. Keep essential rules and routing
+in the entrypoint, with conditional details in references. All consumer
+references are linked directly from it; references longer than 100 lines
+have a contents list. Read supporting files only as needed.
+
+Keep the skill focused on using Walk Async. Generic programming lessons, copied
+manuals, promotional claims, and maintainer procedures do not belong in the
+consumer entrypoint. Keep examples consistent with the library's code style.
+
+## Quality checks
+
+After API changes, verify the skill against `src/main.js`, `src/runCallback.js`,
+the instruction helpers, callback creation, and traversal loop. Run the
+runnable examples with return, promise, and explicit-settlement callbacks
+against the implementation, checking outputs, source preservation, callback
+visits, and reference identity rather than only matching text.
+
+Evaluate selection and answers separately. Use these realistic prompts:
+
+| Prompt | Expected selection and behaviour |
+| --- | --- |
+| “Use Walk Async to copy an API response and remove passwords at every depth.” | Select `walk-async`; await the walk; leaf callback returns `IGNORE()`; preserve source |
+| “Skip every metadata branch while scanning; I don't need a copy.” | Select `walk-async`; await the walk; `copy:false`; object callback returns `IGNORE()` for metadata and `value` otherwise |
+| “Keep a branch's immediate values unchanged but transform nested values.” | Read control-flow reference; await the walk; local `PASS()`; nested callbacks continue |
+| “Replace a branch, skipping only its immediate key callbacks.” | Return `PASS(replacement)`; replacement remains data, not an instruction in the output |
+| “Find the first matching leaf and stop without cloning.” | Collect externally with `copy:false`; return `FINISH()`; walk resolves `undefined` |
+| “Finish on one object, then choose its final leaves.” | Read final-branch rules; `FINISH(value)` plus key callback's `isFinished`; no further object callbacks |
+| “A key contains a slash; give me its full path as an array.” | Use `[ ...parentPath, key ]`; never split breadcrumbs |
+| “Copy a self-referencing object and two shared branches.” | Ancestor cycle closes inside copy; separate shared branches become distinct copies |
+| “Deep-copy nested data while awaiting a lookup for every userId.” | Select `walk-async`; await the walk and lookup; returned containers are visited |
+| “Await an HTTP request for each leaf.” | Select `walk-async`; return or await callback promises; process siblings sequentially |
+| “Use resolve/reject callbacks to drop failed values.” | Settle every path; `reject()` prunes; a throw or rejected promise fails the walk |
+| “Resolve FINISH early, then await more work in that callback.” | Await callback completion and the supplied payload before processing the instruction |
+| “A callback never settles; limit the walk to one second.” | Use top-level `timeout:1000`; explain diagnostics and that timeout does not cancel I/O |
+| “Transform a JSON object using only immediate arithmetic.” | Route to `@peter.naydenov/walk` when a synchronous API meets the request |
+| “Independently clone the contents of a Map.” | Do not select this skill for built-in cloning; explain Walk's reference contract if asked |
+
+For selection evaluation, expose only the skill name and description first.
+For answer evaluation, expose the skill and let the agent choose references.
+Record which files it reads and check the generated code's observable result.
+Run these prompts with the target agents/models when available. Executable
+examples verify API accuracy but do not prove automatic selection quality.
+
+Do not change `package.json`, commit, or publish as part of maintaining the
+skill unless separately requested.
+
+## Package integration
+
+The canonical folder is available from this repository. The current npm
+`files` whitelist still names `.agents/skills` and excludes the top-level
+`skills` folder.
+The manifest is intentionally unchanged for this documentation update.
+To ship the portable skill, manually replace the obsolete `.agents/skills`
+entry in the `package.json` `files` array with this exact entry:
+
+```json
+"skills"
+```
+
+This includes `skills/README.md`, `walk-async/SKILL.md`, and all four reference
+files. Listing only the skill subfolder would omit the integration README
+linked from the package documentation.
+Verify the complete folder with `npm pack --dry-run --json` after changing
+the manifest. Local `/.claude` and `/.agents` settings are listed in
+`.npmignore`. An explicit `files` entry can override that exclusion, so the
+obsolete `.agents/skills` entry also needs replacing. Neither location
+contains a maintained duplicate of this skill.
+
+## Validation scope
+
+Run `npx vitest run test/14-skill.test.js` to verify entrypoint structure,
+relative links, portable references, and examples against the async source.
+The cases check outputs, source preservation, reference identity, sequential
+callback order, and final-branch flags across return, promise, and resolve
+modes. They also execute the explicit-settlement examples as written.
+
+The built-in Python skill validator requires PyYAML, which is unavailable in
+this environment. Frontmatter can instead be parsed with the available Ruby
+YAML parser and checked against the same name, description, and scaffold
+rules. Do not install dependencies solely for this documentation update.
+No automatic skill-selection or target-agent answer evaluation has been run;
+the prompts above are evaluation scenarios, not evidence of agent selection.

package/skills/walk-async/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: walk-async
+description: >-
+  Uses @peter.naydenov/walk-async to copy, transform, filter, or inspect nested
+  JavaScript data with awaited callbacks. Use for deep copies with transformations,
+  masking or removing nested fields, pruning branches, deep forEach, and
+  early-stop searches. Applies to the async Walk API, not synchronous
+  traversal or independent cloning of built-in objects such as Map and Date.
+---
+
+# Walk Async
+
+Write traversal rules with `@peter.naydenov/walk-async`. Walk handles the nesting
+and builds an editable copy by default. This skill covers the upcoming version
+7 API in this repository.
+Await the walk to obtain the result or finish its side effects.
+
+## Choose the call
+
+| Intent | Use |
+| --- | --- |
+| Copy nested objects and arrays | `await walk ({ data })` |
+| Transform, mask, or remove leaves | `keyCallback` |
+| Await a lookup while copying | An async callback that returns its awaited result |
+| Replace a container or remove a branch | `objectCallback` |
+| Inspect without building a copy | `settings:{ copy:false }` |
+| Skip immediate key callbacks but visit nested containers | Return `PASS()` or `PASS(value)` from `objectCallback` |
+| Stop at a match | Return `FINISH()` or `FINISH(value)` |
+
+For example, mask passwords at any depth:
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { user:{ password:'secret', name:'Peter' } };
+let result = await walk ({
+                          data
+                        , keyCallback : ({ key, value }) => key === 'password' ? '[hidden]' : value
+                    })
+// { user:{ password:'[hidden]', name:'Peter' } }
+```
+
+## Essential rules
+
+- Return the intended value when copying. `null` and `undefined` are values,
+  not instructions to remove a property.
+- Call and return helper instructions: `return IGNORE()`, `return PASS()`,
+  or `return FINISH()`, or pass the instruction to `resolve`. Merely calling
+  a helper has no traversal effect. Promised replacement payloads are awaited.
+- An object callback must return or resolve a container to continue into it,
+  including when `copy:false`. A leaf callback used only for side effects
+  may omit its return in that mode. Walk then resolves `undefined`.
+- Return new containers to avoid mutating source data. Built-in objects and
+  functions are leaves preserved by reference; this is not a full graph clone.
+- Each callback completes before the next starts; sibling callbacks do not
+  run concurrently. Throws and rejected promises reject the walk.
+- Existing `resolve`/`reject` callbacks remain supported. Reading either field
+  selects explicit settlement; settle every path and leave unused fields alone.
+  `reject()` prunes the current value; throw to fail the walk.
+- Use `@peter.naydenov/walk` for work that completes synchronously.
+  Do not invent methods such as `walk.pick()`.
+
+## Read the relevant reference
+
+Read only the files needed for the request. Resolve these links relative to
+this skill folder; they remain usable when the folder is installed elsewhere.
+
+- [Callbacks and copying](references/callbacks.md): callback arguments,
+  return values, explicit settlement, errors, timeout, and queued visit order.
+- [Traversal controls](references/control-flow.md): `IGNORE`, local `PASS`,
+  both `FINISH` forms, `isFinished`, and partially completed results.
+- [Paths, settings, and cycles](references/settings.md): `parentPath`,
+  breadcrumbs, performance switches, circular links, and shared references.
+- [Runnable examples](references/examples.md): input and output examples
+  for filtering, pruning, local skipping, searching, and final branches.
+
+## Deliver the solution
+
+Provide focused code in the developer's existing style, using ESM by default.
+Explain the selected callback or setting and any limitation relevant to the
+task. Prefer one walk with combined rules when it satisfies the request;
+finite awaited nested walks are supported when needed. Explain speed through
+work avoided, without claiming a universal advantage over other libraries.

package/skills/walk-async/references/callbacks.md

@@ -0,0 +1,135 @@
+# Callbacks and copying
+
+## Contents
+
+- [Import and signature](#import-and-signature)
+- [Return values](#return-values)
+- [What is copied](#what-is-copied)
+- [Visit order](#visit-order)
+- [Explicit settlement](#explicit-settlement)
+- [Errors and timeout](#errors-and-timeout)
+
+## Import and signature
+
+```js
+import walk from '@peter.naydenov/walk-async'
+// CommonJS: const walk = require ( '@peter.naydenov/walk-async' )
+
+let result = await walk ({ data, keyCallback, objectCallback, settings, timeout }, ...args)
+```
+
+The signature is `walk(options, ...args)` and it returns a Promise. Only
+`data` is required. Await the call to obtain the copy or finish side effects.
+Extra positional arguments are forwarded to both callbacks after their
+arguments object, in the same order.
+
+| Callback | Receives | Additional fields |
+| --- | --- | --- |
+| `keyCallback` | Leaves: primitives, functions, and supported built-in values | `isFinished` |
+| `objectCallback` | Object and array containers, including the root | `PASS` |
+
+Both receive `value`, string `key`, `IGNORE`, `FINISH`, and the async-only
+`resolve` and `reject` settlement fields. `breadcrumbs` and read-only
+`parentPath` are present unless disabled. The root object
+callback's key is `'root'`. Helpers are supplied to callbacks, not imported
+as named exports. `isFinished` is normally `false` in key callbacks.
+
+## Return values
+
+Both plain returns and returned promises are awaited before interpretation.
+When copying, return the value to keep. Returning `null` or `undefined`
+stores it. Return `IGNORE()` to remove the current property or branch.
+
+- A plain object or array returned by either callback is traversed and
+  copied. Its children receive callbacks. A container returned by
+  `keyCallback` does not itself receive another `objectCallback` call.
+- A simple replacement returned by `objectCallback` goes to `keyCallback`
+  when key callbacks are active for its parent. A `PASS` instruction skips
+  that call. Simple root replacements resolve directly.
+- Built-in replacements remain leaves and are stored by reference.
+- In no-copy mode, returns still control traversal but are never assigned
+  to the source. Leaf callbacks used for side effects may omit their return.
+  Object callbacks must return a container to continue into it.
+- A primitive or built-in root resolves directly without callbacks;
+  with `copy:false`, the walk always resolves `undefined`.
+- Root `IGNORE()` produces an empty object or array matching the input
+  root when copying, or `undefined` without copying.
+
+`IGNORE`, `PASS`, and `FINISH` must be called and their results returned or
+passed to `resolve`.
+Returning the function itself is an ordinary function value. When moving
+from synchronous v6, change `return IGNORE` to `return IGNORE()`; async v6
+used `reject()`, which remains supported.
+
+## What is copied
+
+Walk copies own enumerable string-keyed properties into new editable object
+and array containers. It does not preserve prototypes, property descriptors,
+non-enumerable properties, or symbol-keyed properties. Enumerable getters
+are read once per visited property.
+
+`Date`, `RegExp`, `Map`, `Set`, `WeakMap`, `WeakSet`, `ArrayBuffer`,
+`DataView`, typed arrays, DOM nodes, and functions remain the same references.
+Their internal contents are not visited. Use an appropriate independent
+clone operation when the task requires cloning those built-in contents.
+
+Callbacks receive source or replacement values. Mutating them may mutate
+the original data; return a replacement instead when preservation matters.
+Walk does not freeze the result.
+
+Array traversal uses input index strings. Removed items and sparse holes
+are compacted in the result; non-index enumerable properties keep their
+names. Own `__proto__` keys are copied as data properties.
+
+## Visit order
+
+Within a container, properties follow `Object.keys` order. Object callbacks
+run before the corresponding container's contents. Contents are queued and
+processed later in scheduling order; this is not recursive depth-first order.
+
+For `{ first:{ a:1 }, second:{ b:2 } }`, ordinary callback order is:
+
+```text
+object root
+object first
+object second
+key a
+key b
+```
+
+Do not treat the next object callback as a signal that the previous
+container's keys are complete. Callback values are input or replacement
+values, not completed transformed subtrees. Walk has no post-order callback.
+
+Await each callback before starting the next; siblings do not overlap.
+Returned containers follow the same queue order. Finite awaited nested walks
+have their own queue, ancestors, and finish state. Walk has no exit callback.
+Use `@peter.naydenov/walk` when callbacks do not need asynchronous work.
+
+## Explicit settlement
+
+Version 6 callbacks can still use `resolve(value)` or `reject()`. Reading or
+destructuring either field selects explicit settlement for that invocation.
+Settle every path with one of them; the callback's normal return is then
+ignored. Spreading the entire arguments object also reads these getters and
+selects explicit settlement. Do not read unused fields in return-based code.
+
+`resolve` awaits supplied promises and consumes helper instructions, including
+`resolve ( IGNORE() )`, `resolve ( PASS(value) )` in object callbacks, and
+`resolve ( FINISH(value) )`. Callback completion is still awaited when an async
+callback calls `resolve` early. `reject()` drops the current key or branch,
+equivalent to `IGNORE()`; its optional reason does not reject the walk.
+
+## Errors and timeout
+
+Throwing or returning a rejected promise rejects the walk, including failures
+from awaited nested walks or promised instruction payloads. Catch only when
+recovery or pruning is intended; `reject()` is traversal control, not failure.
+
+`timeout` is an optional number of milliseconds for the whole walk, supplied
+beside `data`, not inside `settings`. If time expires, the walk rejects with
+pending callback paths, or keys when breadcrumbs are disabled. It covers
+forgotten explicit settlement, unresolved callback returns, and unresolved
+PASS or FINISH payloads. The timer is cleared after success or failure.
+Timeout does not cancel callback I/O or stop the underlying traversal; arrange
+cancellation in application code when required. No timeout is set by default.

package/skills/walk-async/references/control-flow.md

@@ -0,0 +1,94 @@
+# Traversal controls
+
+All helpers produce instructions that must be returned from the callback
+or passed to `resolve`. Returned promises settle before interpretation.
+Calling a helper and then returning an ordinary value does not issue the
+instruction. Ordinary objects and arrays are data, not instructions.
+
+## IGNORE
+
+`IGNORE()` is available to both callbacks:
+
+- From `keyCallback`, remove this leaf and continue the walk.
+- From `objectCallback`, remove this container and skip its whole branch.
+- From the root object callback, stop without visiting children. Copying
+  resolves `{}` or `[]` matching the original root; no-copy resolves `undefined`.
+
+`IGNORE()` takes no arguments. Returning `undefined` is not removal.
+
+## PASS
+
+`PASS` is available only to `objectCallback`:
+
+- `PASS()` keeps the current value.
+- `PASS(replacement)` uses the supplied replacement.
+- Both skip `keyCallback` only for this container's immediate leaves.
+  Nested containers still run their object and key callbacks normally.
+- Simple replacements are stored directly without a key callback.
+- `PASS(undefined)` supplies an explicit replacement; it differs from
+  `PASS()`, which keeps the current value.
+
+This is local callback skipping, not pruning or retaining an entire branch
+by reference. Object and array containers are still traversed and copied
+when copying is enabled. In no-copy mode, `PASS` applies the same visit rules.
+
+## FINISH without a value
+
+Both callbacks receive `FINISH`. `return FINISH()` omits the current value
+or branch and immediately stops the entire walk, including pending work.
+It behaves like removal followed by stopping. Root `FINISH()` resolves an
+empty object or array matching the original root when copying.
+
+## FINISH with a value
+
+From `keyCallback`, `return FINISH(value)` includes the supplied value
+directly and immediately stops. Supplied containers are not traversed or
+copied; their references are retained.
+
+From `objectCallback`, `return FINISH(value)` selects the final branch:
+
+- Without `keyCallback`, include the supplied value directly and stop.
+  Supplied object and array references are retained.
+- With `keyCallback`, visit the final branch's leaves, including nested
+  containers and containers returned by key callbacks. Each key callback
+  receives `isFinished:true`. No further object callbacks run.
+- In that final branch, return `value` to keep a leaf, `IGNORE()` to drop
+  it and continue, or either `FINISH` form to stop immediately at that leaf.
+- Ordinary key callbacks receive `isFinished:false`. Earlier `PASS`
+  instructions do not suppress the selected branch's final key callbacks.
+- A simple replacement from the root object callback remains a direct
+  resolution, without a key callback, as in ordinary root replacement.
+
+An explicit argument counts even if it is `undefined`:
+`FINISH(undefined)` includes an undefined value; `FINISH()` omits it.
+An object callback that wants to finish with its current value must return
+`FINISH(value)`, not the zero-argument form.
+
+## Results and search side effects
+
+Copying resolves to the work completed before stopping. Unrelated containers
+allocated earlier but still awaiting traversal can remain empty or partially
+populated. Dropping all final leaves may leave empty nested containers.
+Final-branch traversal uses the normal leaf return rules and cycle detection.
+
+With `settings.copy:false`, every walk resolves `undefined`, including a
+walk that returns `FINISH(value)` from a callback. Store a search result in
+external state before returning the instruction. Replacements are visited
+without being assigned to the source.
+
+## Awaited instructions
+
+Walk awaits promises supplied to `PASS(replacement)` or `FINISH(value)` before
+classifying the payload and checking ancestors. This applies to ordinary
+returns and explicit `resolve` settlement. Rejected payloads reject the walk;
+unresolved payloads stay in timeout diagnostics. An explicit promised
+undefined counts as a supplied value, unlike a zero-argument instruction.
+
+A key callback's FINISH container payload is included by reference after it
+settles. An object callback's FINISH payload with a key callback selects a
+copied final branch with the same cycle and leaf-return rules. `isFinished`
+is provided only to key callbacks; object callbacks do not receive it.
+
+Finishing is local to each walk; a finite awaited nested walk has its own
+control state. A FINISH instruction issued through early `resolve` is
+interpreted only after the callback's own returned promise completes.

package/skills/walk-async/references/examples.md

@@ -0,0 +1,252 @@
+# Runnable examples
+
+## Contents
+
+- [Remove leaf keys](#remove-leaf-keys)
+- [Prune a whole branch](#prune-a-whole-branch)
+- [PASS with a replacement](#pass-with-a-replacement)
+- [Inspect with a parent path](#inspect-with-a-parent-path)
+- [Stop at a matching leaf](#stop-at-a-matching-leaf)
+- [Search without copying](#search-without-copying)
+- [Process a final branch](#process-a-final-branch)
+- [Copy circular and shared references](#copy-circular-and-shared-references)
+- [Await a lookup](#await-a-lookup)
+- [Use resolve and reject](#use-resolve-and-reject)
+- [Settle a final branch payload](#settle-a-final-branch-payload)
+- [Observe sequential callbacks](#observe-sequential-callbacks)
+
+Each block is independent and uses the version 7 API. Expected results are
+shown below the calls. Preserve the developer's style when adapting them.
+
+## Remove leaf keys
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { name:'Peter', password:'secret', nested:{ token:'abc', count:2 } };
+let result = await walk ({
+                          data
+                        , keyCallback : ({ key, value, IGNORE }) => {
+                                              if ( key === 'password' || key === 'token' )   return IGNORE()
+                                              return value
+                                          }
+                    })
+// { name:'Peter', nested:{ count:2 } }
+// data still contains password and nested.token.
+```
+
+## Prune a whole branch
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { profile:{ name:'Peter' }, metadata:{ events:[1,2,3] } };
+let result = await walk ({
+                          data
+                        , objectCallback : ({ key, value, IGNORE }) => key === 'metadata' ? IGNORE() : value
+                    })
+// { profile:{ name:'Peter' } }
+// Nothing inside metadata is visited.
+```
+
+## PASS with a replacement
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { branch:{ count:2, nested:{ count:3 } } };
+let result = await walk ({
+                          data
+                        , objectCallback : ({ key, value, PASS }) => {
+                                              if ( key === 'branch' )   return PASS ({ ...value, count:100 })
+                                              return value
+                                          }
+                        , keyCallback : ({ value }) => typeof value === 'number' ? value * 2 : value
+                    })
+// { branch:{ count:100, nested:{ count:6 } } }
+// PASS() instead keeps branch.count at 2; nested.count still becomes 6.
+```
+
+## Inspect with a parent path
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { profile:{ age:42 } };
+let paths = [];
+let result = await walk ({
+                          data
+                        , settings : { copy:false, breadcrumbs:false }
+                        , objectCallback : ({ value }) => value
+                        , keyCallback : ({ parentPath, key }) => {
+                                              paths.push ([ ...parentPath, key ])
+                                          }
+                    })
+// paths: [['root','profile','age']]
+// result: undefined
+```
+
+## Stop at a matching leaf
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = [12,22,33,44,55,66];
+let result = await walk ({
+                          data
+                        , keyCallback : ({ value, FINISH }) => {
+                                              if ( value === 33 )   return FINISH ( value )
+                                              return value
+                                          }
+                    })
+// [12,22,33]
+// Return FINISH() instead to produce [12,22].
+```
+
+## Search without copying
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { a:12, nested:{ b:33, c:44 } };
+let found;
+let result = await walk ({
+                          data
+                        , settings : { copy:false, breadcrumbs:false, parentPath:false }
+                        , keyCallback : ({ value, FINISH }) => {
+                                              if ( value !== 33 )   return
+                                              found = value
+                                              return FINISH()
+                                          }
+                    })
+// found: 33
+// result: undefined
+```
+
+## Process a final branch
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { a:12, c:{ internal:44, in1:'bbb', in2:'ccc' }, later:99 };
+let result = await walk ({
+                          data
+                        , objectCallback : ({ key, value, FINISH }) => key === 'c' ? FINISH ( value ) : value
+                        , keyCallback : ({ key, value, isFinished, IGNORE }) => {
+                                              if ( isFinished && key !== 'internal' )   return IGNORE()
+                                              return value
+                                          }
+                    })
+// { a:12, c:{ internal:44 } }
+// Key callbacks in c receive isFinished:true; later is not visited.
+```
+
+To select just the first final leaf and stop, return `FINISH(value)` from
+that final key callback. Its order follows `Object.keys`, so select by key
+when a particular property is required. Nested containers in the selected
+branch still have their leaves visited, without further object callbacks.
+
+## Copy circular and shared references
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let shared = { count:1 };
+let data = { a:shared, b:shared };
+data.self = data
+
+let result = await walk ({ data })
+// result !== data
+// result.self === result
+// result.a !== result.b
+// result.a and result.b both contain { count:1 }.
+```
+
+## Await a lookup
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+async function lookupUser ( id ) {
+    return await Promise.resolve ({ id, active:true })
+} // lookupUser func.
+
+let data = { userId:42, nested:{ userId:7 } };
+let result = await walk ({
+                          data
+                        , keyCallback : async ({ key, value }) => {
+                                              if ( key === 'userId' )   return await lookupUser ( value )
+                                              return value
+                                          }
+                    })
+// { userId:{ id:42, active:true }, nested:{ userId:{ id:7, active:true } } }
+```
+
+The local lookup stands in for an awaited service call. Returned containers
+are visited; only keys named userId start lookups, so their generated leaves
+do not trigger the lookup again. Errors propagate to the caller.
+
+## Use resolve and reject
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { number:2, password:'secret', nested:{ number:3 } };
+let result = await walk ({
+                          data
+                        , keyCallback : ({ key, value, resolve, reject }) => {
+                                              if ( key === 'password' )   reject()
+                                              else                       resolve ( Promise.resolve ( value * 2 ) )
+                                          }
+                    })
+// { number:4, nested:{ number:6 } }
+```
+
+These fields select explicit settlement, so every callback path settles.
+`reject()` prunes a leaf. Throw or return a rejected promise to fail the walk.
+Return-based callbacks should leave these fields unread.
+
+## Settle a final branch payload
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { final:{ original:1 }, later:99 };
+let flags = [];
+let result = await walk ({
+                          data
+                        , objectCallback : ({ key, value, FINISH, resolve }) => {
+                                              resolve ( key === 'final' ? FINISH ( Promise.resolve ({ first:2, nested:{ number:3 } }) ) : value )
+                                          }
+                        , keyCallback : async ({ value, isFinished }) => {
+                                              flags.push ( isFinished )
+                                              return await Promise.resolve ( value * 10 )
+                                          }
+                    })
+// { final:{ first:20, nested:{ number:30 } } }
+// flags: [true,true]; later and final-branch object callbacks do not run.
+```
+
+## Observe sequential callbacks
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+let data = { first:{ a:1 }, second:{ b:2 } };
+let visits = [];
+let result = await walk ({
+                          data
+                        , objectCallback : async ({ key, value }) => {
+                                              visits.push ( 'object ' + key )
+                                              await Promise.resolve()
+                                              return value
+                                          }
+                        , keyCallback : async ({ key, value }) => {
+                                              visits.push ( 'key ' + key )
+                                              await Promise.resolve()
+                                              return value
+                                          }
+                    })
+// visits: ['object root','object first','object second','key a','key b']
+// result: { first:{ a:1 }, second:{ b:2 } }
+```