@peter.naydenov/walk-async 6.0.0 → 6.1.0

package/.agents/skills/git-walk-async/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: git-walk-async
+description: |
+  Help developers use `@peter.naydenov/walk-async` (the async `walk` from
+  the git-walk-async project, v6.0.0): write a deep copy with `await
+  walk({ data, keyCallback?, objectCallback?, timeout? })`, use the
+  `resolve` / `reject` pair inside callbacks to store or drop values, and
+  leverage the `timeout` option as a debugging safety net. Use when the
+  developer asks for a deep copy with simultaneous async transforms, a
+  deep `forEach` that can `await` work and drop or rewrite values, a
+  single-pass async clone that filters keys by name, or anything phrased
+  as "async deep copy / async deep clone / async deep walk / async deep
+  forEach" where the transforms do real async I/O. Do NOT use for: sync
+  walks (point to the sibling `@peter.naydenov/walk` instead),
+  deep-copying a `Map` / `Set` / `Date` / typed array (use
+  `structuredClone` for those), retry / abort semantics, or fixing bugs
+  in the library itself.
+---
+
+# git-walk-async helper
+
+A single-pass deep walk over a JavaScript data structure that runs two
+optional async callbacks during the visit. Each callback can `await`
+work and reports back via `resolve(value)` or `reject()`. A plain deep
+copy is the no-callback case.
+
+This is the **async sibling** of `@peter.naydenov/walk`. If your
+callbacks don't actually need `await`, prefer the sync version — it's
+noticeably faster because it avoids the promise machinery.
+
+Source of truth:
+- `src/main.js` — JSDoc on every public function and typedef (`walk`, `keyCallback`, `objectCallback`, `CallbackArgs`, `Resolve`, `Reject`, `Options`)
+- `test/01-deepCopy.test.js` — plain deep copy
+- `test/02-keyCallback.test.js` — primitive transforms
+- `test/03-objectCallback.test.js` — object/array transforms
+- `test/04-async.test.js` — real async work in callbacks
+- `test/05-bothCallbacks.test.js` — interaction between the two
+- `test/06-builtins.test.js` — Date / Map / Set / typed arrays / DOM nodes
+- `README.md` — narrative docs (lead paragraph, "When to use `walk-async` vs `structuredClone`" callout, "Migrating from `@peter.naydenov/walk`" table, "Timeout" section, "Limitations")
+
+## Procedure
+
+1. **Map the developer's intent to the right shape of `await walk({ data, ... })` call**:
+   - "Just deep-copy this" / "give me an immutable copy" → `await walk({ data })` (no callbacks)
+   - "Drop a few keys while copying" → `await walk({ data, keyCallback })`; call `reject()` for the keys to drop
+   - "Mask a value" / "rewrite a value" → `await walk({ data, keyCallback })`; call `resolve(newValue)`
+   - "Skip a whole subtree" → `await walk({ data, objectCallback })`; call `reject()` at the right key
+   - "Await something inside the walk" (DB lookup, fetch, fs.readFile) → `await walk({ data, keyCallback: async ({ resolve, value, key }) => { const fresh = await fetch(value); resolve(fresh) } })`
+   - "Run a function on every leaf" (deep `forEach` with side effects) → `await walk({ data, keyCallback })`; the callback must still call `resolve(value)` (see gotcha below)
+
+2. **Generate code that follows the real API contract**:
+   - ESM import: `import walk from '@peter.naydenov/walk-async'` (CJS: `require('@peter.naydenov/walk-async')`)
+   - **The call returns a Promise** — `await` it, or chain `.then`. Forgetting this is the #1 mistake.
+   - Options shape: `{ data, keyCallback?, objectCallback?, timeout? }`. Same names as the sync `walk`, plus `timeout`.
+   - Callback signature is `({ value, key, breadcrumbs, resolve, reject }, ...args)`. Always destructure the five fields from the first arg.
+   - Extra positional args passed to `walk` are forwarded to both callbacks as `...args`. Use this for context the callbacks need but you don't want to close over.
+   - **There is no `IGNORE` symbol.** The way to drop a key is `reject()` — that's it. The internal `IGNORE = Symbol('ignore___')` is private implementation detail; do not import, construct, or return it from user code. Returning it from a callback is a bug (it would be treated as a value to store, not a drop signal).
+   - The callback MUST call `resolve(...)` or `reject()` on every code path. If it doesn't, the walk promise never settles. The `timeout` option is the recommended way to catch this in development.
+   - `resolve` accepts anything a sync `walk` would accept: a primitive, a built-in like `Date` / `Map` / `Set`, or a plain object/array. A plain object/array is walked into (deferred). A `Date` / `Map` / `Set` is stored by reference.
+
+3. **Apply the order-of-execution rules**:
+   - Within one level, keys are visited in `Object.keys` order on the current object/array.
+   - A level finishes before any nested walk starts. The new walk into a returned object/array is deferred.
+   - For the same value, `objectCallback` runs before `keyCallback`. If `objectCallback` resolves a new object, that object is what `keyCallback` sees when it processes the children.
+   - The root goes through `objectCallback` first (if defined), then its children are walked. Rejecting from the root `objectCallback` short-circuits the whole walk to `[]` (for array roots) or `{}` (for object roots).
+   - **Within a level, all keys are started concurrently** — they don't wait for each other to resolve before the next one is fired. They just have to finish before the next level begins. (This is the part where the async version earns its keep — `await` work in callbacks runs in parallel for free.)
+
+4. **Surface only the relevant gotcha proactively** — pick at most one from the list below that applies to the current example, and only if the user is unlikely to know it:
+   - **The biggest trap: `walk-async` is `await`able.** A no-`await` call silently drops the result. `walk(...)` alone returns a Promise, not the copy.
+   - **Don't return values from callbacks.** Returning `value` or `IGNORE` from a callback is a sync-API leak — the walk ignores the return. The right call is `resolve(value)` or `reject()`. If a user just ported from sync `walk` and writes `return value` in their callback, their result will be `{}` (the empty container, because nothing was ever stored).
+   - **Callbacks must call `resolve` or `reject` on every code path.** A path that returns early or `throw`s without calling either will leave the walk promise pending forever. Either wire every path explicitly, or set `timeout` during development to surface these as a clear rejection with breadcrumbs of the stuck callbacks.
+   - **Don't `await walk-async` from inside a callback.** That's the first item on the Limitations list in the README — it corrupts the in-progress walk. If you need recursion, let the library handle it by `resolve`-ing a plain object/array from the callback.
+   - **Built-in types are not walked.** `Date`, `RegExp`, `Map`, `Set`, `WeakMap`, `WeakSet`, `ArrayBuffer`, `DataView`, typed arrays, DOM nodes, and functions are passed by reference. If the user wants a deep clone of a `Map`/`Set`/typed array, recommend `structuredClone` for that subtree, or do it themselves before calling `walk-async`.
+   - **`'simple'` is the storage type, not the return type.** A plain object or array resolved from `keyCallback` is re-typed and walked into (deferred). A `Date` resolved from `keyCallback` is `'simple'` and stored by reference. This is the v6.0.0 contract.
+
+5. **If the request is "I just need a deep clone with no transforms"** (or the user doesn't actually need async), point them at `structuredClone` first (built into the platform, no dependency, no promise), and mention the sync `walk` as a fallback. Only use `walk-async` when real async I/O is happening inside the callbacks.
+
+6. **If the request is for a sync walk**, route to `@peter.naydenov/walk` (separate package, similar interface, no promise machinery). The two are kept in sync semantically — same callback args, same three-outcome contract — but the sync version is faster when you don't need `await`.
+
+## Output contract
+
+- One focused code snippet, ESM by default (CJS if asked)
+- The snippet must `await` the `walk` call (or chain `.then`); never produce a snippet that calls `walk` and ignores the returned Promise
+- One line of context explaining which option(s) are used and why
+- A pointer to the relevant source/test section if the developer wants to dig deeper
+- Surface at most one relevant gotcha proactively, only if it applies to the example
+- Never include a code example that uses `return value` / `return IGNORE` from a callback (those are the sync API)
+- Never include a code example that `await`s `walk-async` from inside one of its own callbacks
+
+## Failure handling
+
+- The developer's use case genuinely ambiguous (e.g., "deep clone this") → point them at `structuredClone` for the no-deps no-callback case, then `walk-async` only if they want callbacks that `await`
+- Developer reports a bug or unexpected behavior in `walk-async` itself → do NOT try to fix from this skill; route to the project source or maintainer
+- Developer wants a walk that never settles, or hits the timeout, or sees the "callbacks still pending" error → point at the `Timeout` section in the README and the callback "every code path resolves" rule
+- Developer asks for an API `walk-async` doesn't have (e.g., `walk.pick(...)`, `walk.omit(...)`) → do not invent it; point at the callback-factory pattern in the README ("Why one callback, not a list of methods" section) where such helpers belong outside the library
+
+## Examples
+
+**"Fetch fresh data for every URL string in the object, drop the rest"**
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+const result = await walk({
+  data: source,
+  keyCallback: async ({ value, resolve, reject }) => {
+    if (typeof value !== 'string' || !/^https?:\/\//.test(value)) {
+      reject()                                          // drop non-URL primitives
+      return
+    }
+    try {
+      const r = await fetch(value)
+      resolve(await r.json())
+    } catch (e) {
+      reject()                                          // drop on network failure
+    }
+  },
+  timeout: 5000,    // surfaces forgotten resolve/reject with breadcrumbs
+})
+```
+
+`await` is mandatory — without it you have a Promise, not a result. `reject()` (no argument) is the only way to drop a key. The `timeout` is a debugging safety net; remove or raise it for production. See `test/04-async.test.js` for the executable pattern.
+
+**"Drop a whole `metadata` subtree"**
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+const result = await walk({
+  data: user,
+  objectCallback: ({ key, value, resolve, reject }) =>
+    key === 'metadata' ? reject() : resolve(value)
+})
+```
+
+Rejecting from `objectCallback` drops the entire subtree (not just the immediate property). `keyCallback` is not used here, so primitive keys inside `metadata` are never visited. See `test/03-objectCallback.test.js`.
+
+**"Deep `forEach` — log every leaf"**
+
+```js
+import walk from '@peter.naydenov/walk-async'
+
+await walk({
+  data: tree,
+  keyCallback: ({ value, key, breadcrumbs, resolve }) => {
+    console.log(`${breadcrumbs}/${key} = ${value}`)
+    resolve(value)   // pass-through — required, otherwise this key is dropped
+  }
+})
+```
+
+The callback MUST call `resolve` or `reject` on every code path. A missing call leaves the walk pending — if you suspect this in your own code, set `timeout: 1000` during dev and look at which callback the rejection names. The `breadcrumbs` argument is a slash-delimited path starting with `'root'`, e.g. `'root/props/age'`. See "Deep 'forEach'" in `README.md`.
+
+**"Port a sync `walk` call to `walk-async`"**
+
+```js
+// walk (sync)
+const result = walk ({
+  data: user,
+  keyCallback: ({ value, key, IGNORE }) => key === 'password' ? IGNORE : value
+})
+
+// walk-async — same shape, just promise-based
+const result = await walk ({
+  data: user,
+  keyCallback: ({ value, key, resolve, reject }) => {
+    if ( key === 'password' )   reject ()   // was: return IGNORE
+    else                       resolve ( value )  // was: return value
+  }
+})
+```
+
+The mechanical translation: `return X` → `resolve(X)`, `return IGNORE` → `reject()`. Add `await` to the call. Add `timeout` during dev to surface any path that forgets to resolve/reject. The "Migrating from `@peter.naydenov/walk`" section in `README.md` has the full table.

package/Changelog.md

@@ -2,6 +2,13 @@
 
 
 
+### 6.1.0 (2026-09-01)
+- [x] Feature: Added a skill at `.agents/skills/git-walk-async/SKILL.md`;
+- [x] Packaging: Added `.agents/skills` to the `"files"` allow-list in `package.json` so the Mavis skill ships with the npm package. AI-agent users can discover the walk-async skill from `node_modules` directly, without needing access to the source repo. The same allow-list also drops the dev-only `rollup.config.js`, `tsconfig.json`, and `vitest.config.js` that were leaking under the previous `.npmignore`-only packaging;
+- [x] Docs: Prefilled `Migration.guide.md` for every major release: sync-`@peter.naydenov/walk` → `walk-async` (the README's "Migrating from `@peter.naydenov/walk`" table, folded in), v3.x → v6.x (callback signatures tightened with exported `Resolve` / `Reject` typedefs), v3.0.x → v3.1.x (the `timeout` option, the built-in-type pass-by-reference fix from v3.1.2, and the v3.0.6/v3.0.7 root-callback bug fixes), the existing v2.x → v3.x root-callback entry, v1.x → v2.x (ES module + `dist` + `exports`), and v1.0.0 → v1.x (the early null/undefined, DOM-node, and collection-container fixes). The README still has a copy of the sync-`walk` → `walk-async` table — flag for a follow-up if you want the README trimmed to a one-liner pointer so the docs aren't split across two files;
+
+
+
 ### 6.0.0 (2026-08-08)
 - [x] Allign version numbers with `@peter.naydenov/walk`. We jumping from 3.1.3 to 6.0.0;
 - [x] Types: Tighten callback signatures in `types/main.d.ts`. `keyCallback` and `objectCallback` are now typed as `KeyCallback` / `ObjectCallback` over a `CallbackArgs` shape (`value`, `key`, `breadcrumbs`, `resolve`, `reject`); `resolve` and `reject` are exported as `Resolve` / `Reject` types so TypeScript users get autocomplete. Driven from JSDoc in `src/main.js`; regenerate with `npm run build`;

package/Migration.guide.md

@@ -1,8 +1,94 @@
 # Migration Guides
 
+Upgrade notes for non-trivial `walk-async` releases. For the full per-release list of changes, see the [Changelog](Changelog.md); this guide focuses on what *you* have to change in your code.
+
+Most common first, then version history newest-first.
+
+
+
+## From `@peter.naydenov/walk` (sync sibling)
+
+`walk-async` is the async sibling of [`@peter.naydenov/walk`](https://github.com/PeterNaydenov/walk). They share the same callback parameter names (`value`, `key`, `breadcrumbs`) and the same three-outcome contract. The only mechanical change is how you express the return value:
+
+| `walk` (sync)                    | `walk-async` (async)         |
+| -------------------------------- | ---------------------------- |
+| `return value`                   | `resolve(value)`             |
+| `return newObject`               | `resolve(newObject)`         |
+| `return IGNORE`                  | `reject()`                   |
+
+The options shape is identical: `{ data, keyCallback, objectCallback }`. `walk-async` adds an optional `timeout` (milliseconds). The walk call itself becomes an `await` (or `.then`).
+
+```js
+// walk
+const result = walk ({
+    data: user,
+    keyCallback: ({ value, key, IGNORE }) => key === 'password' ? IGNORE : value
+})
+
+// walk-async — same shape, just promise-based
+const result = await walk ({
+    data: user,
+    keyCallback: ({ value, key, resolve, reject }) => {
+        if ( key === 'password' )   reject ()
+        else                       resolve ( value )
+    }
+})
+```
+
+If your callbacks don't actually need async work, prefer the sync `walk` — it's noticeably faster because it avoids the promise machinery. Reach for `walk-async` only when you have real async work inside the callbacks (database lookups, network calls, file reads, etc.) and the cost of multiple `walk` calls would be unacceptable.
+
+
+
+## From v.3.x.x - v.6.x.x
+
+v6 is a version-alignment release with `@peter.naydenov/walk` (the sync sibling). **Behaviour is unchanged from v.3.1.3** — every v3.x callback that worked in v3.1.3 still works identically in v6.x. The only user-facing change is on the TypeScript side.
+
+### Callback signatures are now strictly typed
+
+`keyCallback` and `objectCallback` are now typed as `KeyCallback` / `ObjectCallback` over a `CallbackArgs` shape, and `resolve` / `reject` are exported as `Resolve` / `Reject` typedefs so TypeScript users get autocomplete. If your callbacks already called `resolve(value)` / `reject()` correctly, they keep working unchanged at runtime; TypeScript will now catch signature mistakes at compile time.
+
+```ts
+// v3.x.x  - call signatures inferred from usage; no Resolve/Reject typedefs
+function keyCallback ({ value, key, resolve, reject }) {
+    if (key === 'password') reject()
+    else resolve(value)
+}
+
+// v6.x.x  - same code, now type-checked against the exported Resolve / Reject
+import type { KeyCallback, Resolve, Reject } from '@peter.naydenov/walk-async'
+const keyCallback: KeyCallback = ({ value, key, resolve, reject }) => {
+    if (key === 'password') reject()
+    else (resolve as Resolve)(value)
+}
+```
+
+If you're on JavaScript (not TypeScript), there is nothing to change.
+
+
+
+## From v.3.0.x - v.3.1.x
+
+A new optional `timeout` (milliseconds) was added. When set, the walk promise is rejected if any callback has not called `resolve` or `reject` in time; the error message lists the breadcrumbs of every still-pending callback so the broken code path can be found directly.
+
+```js
+// v3.0.x
+const result = await walk ({ data, keyCallback })   // hangs forever if a callback forgets to resolve
+
+// v3.1.x
+const result = await walk ({ data, keyCallback, timeout: 5000 })
+// if a callback never settles, the walk promise is rejected with:
+//   walk-async: timed out after 5000ms; callbacks still pending:
+//     - keyCallback at 'root/props/age'
+```
+
+This is purely additive — the option is optional, off by default, and identical to v3.0.x when omitted. The pre-existing v3.0.6 and v3.0.7 bug fixes (`__proto__` no longer replacing the copy's prototype; top-level property named `root` no longer dropped; `objectCallback` resolving the root with a primitive no longer crashes) shipped in this window. Correct code gets more lenient, not more strict.
+
+This is also the window when `Date`, `RegExp`, `Map`, `Set`, `WeakMap`, `WeakSet`, `ArrayBuffer`, `DataView`, and typed arrays became passed by reference (v.3.1.2). They used to come out as empty `{}` — that was almost always a bug, so the fix is a no-op for working code, but if you were somehow relying on the broken behaviour, this is the release that changed it.
+
 
 
 ## From v.2.x.x - v.3.x.x
+
 Difference between v.2.x.x and v.3.x.x is that object callbacks are triggered on 'root' object as well. So if you have object callbacks that are not working as expected after upgrade, you need to add extra line of code for version 3.
 
 ```js
@@ -21,3 +107,37 @@ function oCallbackFn ({ value:o, key, IGNORE, breadcrumbs }) {
 Everything else works the same.
 
 
+
+## From v.1.x.x - v.2.x.x
+
+v2 converted the package to a proper ES module and added a built `dist/` (CommonJS, ESM, UMD) plus a `package.json` `exports` map and a Rollup build pipeline.
+
+**For most users the upgrade is automatic** — your bundler / runtime picks the right build from the `exports` map. The only breaking case is if you were reaching into the package by path:
+
+```js
+// v1.x.x - CommonJS; the package exports a function
+const walk = require ( '@peter.naydenov/walk-async' )
+
+// v2.x.x - ES module; the default export is the walk function
+import walk from '@peter.naydenov/walk-async'
+```
+
+If you were loading source directly (`require('@peter.naydenov/walk-async/src/main')` or similar), use the package's `exports` map (`@peter.naydenov/walk-async/src/main`) instead, or just import the default.
+
+
+
+## From v.1.0.0 - v.1.x.x
+
+v1.x added a series of small but important fixes. If you are still on v.1.0.0, the relevant ones are:
+
+### v.1.1.0 - `null` and `undefined` resolution
+
+Returning `null` or `undefined` from a callback is now stored as the literal value (not treated as "skip"). If you were relying on `null` to mean "drop this key", switch to `reject()` (in v6.x) or to whatever the v1.x equivalent was — the API has since changed.
+
+### v.1.2.0 - DOM nodes copied by reference
+
+`walk-async` no longer descends into HTML DOM nodes — they are passed through by reference. This is the same contract as functions, and (added later in v.3.1.2) `Date` / `Map` / `Set` / `RegExp` / typed arrays.
+
+### v.1.3.0 - `undefined`-valued keys preserved; collection containers
+
+Keys whose value is `undefined` are now copied (they were being dropped in v.1.0.0). Also, callbacks can now extract data into provided collection containers during iteration.

package/package.json

@@ -1,20 +1,30 @@
 {
   "name": "@peter.naydenov/walk-async",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Deep copy with fine control during the process. Can be used also as a deep forEach function",
-  "main": ".dist/walk-async.umd.js",
+  "main": "./dist/walk-async.umd.js",
   "type": "module",
   "types": "./types/main.d.ts",
   "exports": {
     ".": {
-      "import": "./.dist/walk-async.esm.mjs",
-      "require": "./.dist/walk-async.cjs",
+      "import": "./dist/walk-async.esm.mjs",
+      "require": "./dist/walk-async.cjs",
       "default": "./dist/walk-async.umd.js"
     },
     "./package.json": "./package.json",
     "./dist/*": "./dist/*",
     "./src/*": "./src/*"
   },
+  "files": [
+    "dist",
+    "src",
+    "types",
+    "README.md",
+    "Changelog.md",
+    "Migration.guide.md",
+    "LICENSE",
+    ".agents/skills"
+  ],
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
@@ -35,11 +45,11 @@
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
-    "@vitest/coverage-v8": "4.1.10",
-    "rollup": "^4.62.3",
+    "@vitest/coverage-v8": "4.1.11",
+    "rollup": "^4.63.1",
     "typescript": "^7.0.2",
-    "vite": "^8.2.0",
-    "vitest": "4.1.10"
+    "vite": "^8.2.2",
+    "vitest": "4.1.11"
   },
   "vitest": {
     "coverage": {

package/rollup.config.js

@@ -1,41 +0,0 @@
-import resolve    from '@rollup/plugin-node-resolve'
-import commonjs   from '@rollup/plugin-commonjs'
-import terser     from '@rollup/plugin-terser';
-
-
-export default [
-	// browser-friendly UMD build
-	{
-		input: 'src/main.js',
-		output: {
-			name: 'walkAsync',
-			file: 'dist/walk-async.umd.js',
-			format: 'umd',
-            globals: {
-                        'ask-for-promise': 'askForPromise'
-                    }
-		},
-        external : [ 'ask-for-promise' ],
-		plugins: [
-			resolve(), // so Rollup can find `ms`
-			commonjs() // so Rollup can convert `ms` to an ES module
-			, terser()
-		]
-	},
-
-	// CommonJS (for Node) and ES module (for bundlers) build.
-	// (We could have three entries in the configuration array
-	// instead of two, but it's quicker to generate multiple
-	// builds from a single configuration where possible, using
-	// an array for the `output` option, where we can specify
-	// `file` and `format` for each target)
-	{
-		input: 'src/main.js',
-		external: ['ask-for-promise'],
-		output: [
-			{ file: 'dist/walk-async.cjs'    , format: 'cjs' },
-			{ file: 'dist/walk-async.esm.mjs', format: 'es' }
-		],
-		plugins: [ terser() ]
-	}
-];

package/tsconfig.json

@@ -1,11 +0,0 @@
-{
-    "include": ["./src/**/*"],
-    "compilerOptions": {
-      "allowJs": true,
-      "declaration": true,
-      "emitDeclarationOnly": true,
-      "rootDir": "./src",
-      "outDir": "types",
-      "declarationMap": true
-    }
-}

package/vitest.config.js

@@ -1,8 +0,0 @@
-import { defineConfig } from 'vitest/config'
-
-
-export default defineConfig ({
-        test : {
-                globals : true
-            }
-    })