@peter.naydenov/walk-async 3.0.7 → 3.1.1

package/Changelog.md

@@ -2,6 +2,19 @@
 
 
 
+### 3.1.1 (2026-07-12)
+- [x] Moving to typescript v.7.x.x;
+- [x] Changing 'mocha' testing library with vitest;
+- [x] Converting all tests to vitest;
+- [x] Changing coverage library from c8 to @vitest/coverage-v8;
+
+
+
+### 3.1.0 (2026-07-07)
+- [x] New option 'timeout'. Milliseconds. When set, the walk promise is rejected if callbacks do not resolve in time. Error message lists the breadcrumbs of the pending callbacks;
+
+
+
 ### 3.0.7 (2026-07-07)
 - [x] Fix: 'objectCallback' resolving the root object with a primitive value was crashing on null/undefined or producing broken results;
 - [x] Fix: Own '__proto__' property was replacing the prototype of the copy instead of being copied as a regular property;

package/README.md

@@ -13,6 +13,7 @@ Creates an immutable copies of javascript data structures(objects, arrays or mix
             data             // (required) Any JS object structure
           , objectCallback   // (optional) Function executed on each object property
           , keyCallback      // (optional) Function executed on each primitive property
+          , timeout          // (optional) Milliseconds. Reject the promise if callbacks do not resolve in time
       })
     .then ( result => {
                               // Result will become a exact deep copy of "data" 
@@ -55,7 +56,8 @@ function keyCallbackFn ({ value, key, breadcrumbs, resolve, reject }) {
     // breadcrumbs: location of the property;
     // resolve: function that will resolve the callback promise. Provide the result as argument;
     // reject: function that can cancel the copy of that property;
-    // Important: key callback should be resolved or rejected. 
+    // Important: key callback should be resolved or rejected on every code path,
+    // otherwise the walk promise never settles. See section "Timeout".
   }
 
 const result = await walk ({ data, keyCallback : keyCallbackFn });  // It's the short way to provide only key-callback. Callback functions are optional.
@@ -74,7 +76,8 @@ function objectCallbackFn ({ value, key, breadcrumbs, resolve, reject }) {
       // breadcrumbs: location of the object;
       // resolve: function that will resolve the callback promise. Provide the result as argument;
       // reject: function that can cancel the copy of that property;
-      // Important: Object callback should be resolved or rejected. 
+      // Important: Object callback should be resolved or rejected on every code path,
+      // otherwise the walk promise never settles. See section "Timeout".
 }
 
 walk ({ 
@@ -95,6 +98,32 @@ Skip key-callbacks by not providing a keyCallback function.
 ```
 
 
+## Timeout
+
+Every callback must call `resolve` or `reject` on every code path. If some path forgets to do it, the promise returned by `walk` will never settle — and by default there is no error and no hint which callback is the reason. The optional `timeout` property (milliseconds) turns that silent hang into a rejection with diagnostics:
+
+```js
+function objectCallbackFn ({ value, key, breadcrumbs, resolve, reject }) {
+        if ( breadcrumbs === 'root/props' )   return   // BUG: this path never resolves
+        resolve ( value )
+    }
+
+walk ({ data, objectCallback: objectCallbackFn, timeout: 5000 })
+    .catch ( err => {
+              console.error ( err.message )
+              // walk-async: timed out after 5000ms; callbacks still pending:
+              //   - objectCallback at 'root/props'
+        })
+```
+
+The error message lists the breadcrumbs of every callback that was started but never resolved or rejected, so the broken code path can be found directly.
+
+Notes:
+ - `timeout` is disabled by default. Without it the behavior is exactly as before;
+ - The limit applies to the whole walk, not to a single callback. Set it well above the worst-case duration of the legitimate async work inside the callbacks — it is a debugging safety net, not a scheduler;
+ - When callbacks finish in time, the timer is cleared and the result is delivered as usual.
+
+
 ## Installation
 
 Install for node.js projects by writing in your terminal:

package/dist/walk-async.cjs

@@ -1 +1 @@
-"use strict";var e=require("ask-for-promise");async function o(e,o,n){for await(const o of e)await o.next();n.done(o)}function n(e){return null==e||e.nodeType?"simple":e instanceof Array?"array":"object"==typeof e?"object":"simple"}async function*r(e,o,n,r,s,a){yield await t(e,o,n,r,s,...a)}function t(o,t,s,a,i,...c){let[l,d]=a,p=Object.keys(o),u=e(p),f=e();return p.forEach((p,f)=>{let m=n(o[p]),y=o[p],$="simple"!==m&&null!=d,b=e(),k=e(),h=e(),j="array"===n(t),v=!isNaN(p),C=Symbol("ignore___"),w="root"===i&&"root"===p,N=w?"root":`${i}/${p}`;$?d({resolve:b.done,reject:()=>b.done(C),value:y,key:p,breadcrumbs:N},...c):b.done("$$cancel"),b.onComplete(e=>{if("$$cancel"!==e||l)if("$$cancel"!==e&&(y=e,m=n(y)),y!=C)if("simple"===m){if(!l)return void k.done("$$noUpdates");l({resolve:k.done,reject:()=>k.done(C),value:y,key:p,breadcrumbs:N},...c)}else k.done("$$cancel");else u.promises[f].done("ignore object");else k.done("$$noUpdates")}),k.onComplete(e=>{if(w)return s.push(r(y,t,s,a,"root",c)),void u.promises[f].done("root");if(e!=C)if("$$cancel"!==e){if("$$noUpdates"!==e&&(y=e,m=n(y)),"simple"===m){const e=function(e,o){return o instanceof Array&&!isNaN(e)}(p,t);return e?t.push(y):t[p]=y,void u.promises[f].done("key")}h.done()}else h.done();else u.promises[f].done("ignore key")}),h.onComplete(()=>{if("object"===m){const e={};j&&v?t.push(e):t[p]=e,s.push(r(y,e,s,a,N,c)),u.promises[f].done("object")}if("array"===m){const e=[];j&&v?t.push(e):t[p]=e,s.push(r(y,e,s,a,N,c)),u.promises[f].done("array")}})}),u.onComplete(e=>f.done()),f.promise}module.exports=function({data:r,objectCallback:s=null,keyCallback:a=null},...i){let c,l=n(r),d=[],p="root",u=[a,s],f=e();switch(l){case"array":c=[],t({root:r},c,d,u,p,...i).then(()=>o(d,c,f));break;case"object":c={},t({root:r},c,d,u,p,...i).then(()=>{o(d,c,f)});break;case"simple":f.done(r)}return f.promise};
+"use strict";var e=require("ask-for-promise");async function o(e,o,n){for await(const o of e)await o.next();n.done(o)}function n(e){return null==e||e.nodeType?"simple":e instanceof Array?"array":"object"==typeof e?"object":"simple"}async function*t(e,o,n,t,r,l){yield await a(e,o,n,t,r,...l)}function r(e,o,n){"__proto__"===o?Object.defineProperty(e,o,{value:n,enumerable:!0,writable:!0,configurable:!0}):e[o]=n}function a(o,a,l,s,c,...i){let[d,u,p]=s,m=Object.keys(o),b=e(m),f=e();return m.forEach((m,f)=>{let y=n(o[m]),$=o[m],k="simple"!==y&&null!=u,j=e(),_=e(),C=e(),v="array"===n(a),h=!isNaN(m),w=Symbol("ignore___"),g=`${c}/${m}`,N=`objectCallback at '${g}'`,S=`keyCallback at '${g}'`;k?(p.add(N),u({resolve:j.done,reject:()=>j.done(w),value:$,key:m,breadcrumbs:g},...i)):j.done("$$cancel"),j.onComplete(e=>{if(p.delete(N),"$$cancel"!==e||d)if("$$cancel"!==e&&($=e,y=n($)),$!=w)if("simple"===y){if(!d)return void _.done("$$noUpdates");p.add(S),d({resolve:_.done,reject:()=>_.done(w),value:$,key:m,breadcrumbs:g},...i)}else _.done("$$cancel");else b.promises[f].done("ignore object");else _.done("$$noUpdates")}),_.onComplete(e=>{if(p.delete(S),e!=w)if("$$cancel"!==e){if("$$noUpdates"!==e&&($=e,y=n($)),"simple"===y){const e=function(e,o){return o instanceof Array&&!isNaN(e)}(m,a);return e?a.push($):r(a,m,$),void b.promises[f].done("key")}C.done()}else C.done();else b.promises[f].done("ignore key")}),C.onComplete(()=>{if("object"===y){const e={};v&&h?a.push(e):r(a,m,e),l.push(t($,e,l,s,g,i)),b.promises[f].done("object")}if("array"===y){const e=[];v&&h?a.push(e):r(a,m,e),l.push(t($,e,l,s,g,i)),b.promises[f].done("array")}})}),b.onComplete(e=>f.done()),f.promise}module.exports=function({data:t,objectCallback:r=null,keyCallback:l=null,timeout:s=null},...c){let i,d=n(t),u=[],p="root",m=new Set,b=[l,r,m],f=e(),y=e(),$=Symbol("ignore___");if("simple"!==d&&r?(m.add("objectCallback at 'root'"),r({resolve:y.done,reject:()=>y.done($),value:t,key:"root",breadcrumbs:p},...c)):y.done(t),y.onComplete(e=>{if(m.delete("objectCallback at 'root'"),e!==$)switch(n(e)){case"array":i=[],a(e,i,u,b,p,...c).then(()=>o(u,i,f));break;case"object":i={},a(e,i,u,b,p,...c).then(()=>{o(u,i,f)});break;case"simple":f.done(e)}else f.done("array"===d?[]:{})}),null==s)return f.promise;const k=Symbol("expired___"),j=e();return f.timeout(s,k),f.onComplete(e=>{if(e!==k)return void j.done(e);const o=[...m].map(e=>`\n  - ${e}`).join("");j.cancel(new Error(`walk-async: timed out after ${s}ms; callbacks still pending:${o}`))}),j.promise};

package/dist/walk-async.esm.mjs

@@ -1 +1 @@
-import e from"ask-for-promise";function o({data:o,objectCallback:t=null,keyCallback:a=null},...i){let c,l=r(o),p=[],d="root",u=[a,t],f=e();switch(l){case"array":c=[],s({root:o},c,p,u,d,...i).then(()=>n(p,c,f));break;case"object":c={},s({root:o},c,p,u,d,...i).then(()=>{n(p,c,f)});break;case"simple":f.done(o)}return f.promise}async function n(e,o,n){for await(const o of e)await o.next();n.done(o)}function r(e){return null==e||e.nodeType?"simple":e instanceof Array?"array":"object"==typeof e?"object":"simple"}async function*t(e,o,n,r,t,a){yield await s(e,o,n,r,t,...a)}function s(o,n,s,a,i,...c){let[l,p]=a,d=Object.keys(o),u=e(d),f=e();return d.forEach((d,f)=>{let m=r(o[d]),y=o[d],$="simple"!==m&&null!=p,b=e(),k=e(),h=e(),j="array"===r(n),v=!isNaN(d),C=Symbol("ignore___"),w="root"===i&&"root"===d,N=w?"root":`${i}/${d}`;$?p({resolve:b.done,reject:()=>b.done(C),value:y,key:d,breadcrumbs:N},...c):b.done("$$cancel"),b.onComplete(e=>{if("$$cancel"!==e||l)if("$$cancel"!==e&&(y=e,m=r(y)),y!=C)if("simple"===m){if(!l)return void k.done("$$noUpdates");l({resolve:k.done,reject:()=>k.done(C),value:y,key:d,breadcrumbs:N},...c)}else k.done("$$cancel");else u.promises[f].done("ignore object");else k.done("$$noUpdates")}),k.onComplete(e=>{if(w)return s.push(t(y,n,s,a,"root",c)),void u.promises[f].done("root");if(e!=C)if("$$cancel"!==e){if("$$noUpdates"!==e&&(y=e,m=r(y)),"simple"===m){const e=function(e,o){return o instanceof Array&&!isNaN(e)}(d,n);return e?n.push(y):n[d]=y,void u.promises[f].done("key")}h.done()}else h.done();else u.promises[f].done("ignore key")}),h.onComplete(()=>{if("object"===m){const e={};j&&v?n.push(e):n[d]=e,s.push(t(y,e,s,a,N,c)),u.promises[f].done("object")}if("array"===m){const e=[];j&&v?n.push(e):n[d]=e,s.push(t(y,e,s,a,N,c)),u.promises[f].done("array")}})}),u.onComplete(e=>f.done()),f.promise}export{o as default};
+import e from"ask-for-promise";function o({data:o,objectCallback:a=null,keyCallback:r=null,timeout:s=null},...c){let i,d=t(o),p=[],u="root",m=new Set,b=[r,a,m],f=e(),y=e(),$=Symbol("ignore___");if("simple"!==d&&a?(m.add("objectCallback at 'root'"),a({resolve:y.done,reject:()=>y.done($),value:o,key:"root",breadcrumbs:u},...c)):y.done(o),y.onComplete(e=>{if(m.delete("objectCallback at 'root'"),e!==$)switch(t(e)){case"array":i=[],l(e,i,p,b,u,...c).then(()=>n(p,i,f));break;case"object":i={},l(e,i,p,b,u,...c).then(()=>{n(p,i,f)});break;case"simple":f.done(e)}else f.done("array"===d?[]:{})}),null==s)return f.promise;const k=Symbol("expired___"),j=e();return f.timeout(s,k),f.onComplete(e=>{if(e!==k)return void j.done(e);const o=[...m].map(e=>`\n  - ${e}`).join("");j.cancel(new Error(`walk-async: timed out after ${s}ms; callbacks still pending:${o}`))}),j.promise}async function n(e,o,n){for await(const o of e)await o.next();n.done(o)}function t(e){return null==e||e.nodeType?"simple":e instanceof Array?"array":"object"==typeof e?"object":"simple"}async function*a(e,o,n,t,a,r){yield await l(e,o,n,t,a,...r)}function r(e,o,n){"__proto__"===o?Object.defineProperty(e,o,{value:n,enumerable:!0,writable:!0,configurable:!0}):e[o]=n}function l(o,n,l,s,c,...i){let[d,p,u]=s,m=Object.keys(o),b=e(m),f=e();return m.forEach((m,f)=>{let y=t(o[m]),$=o[m],k="simple"!==y&&null!=p,j=e(),_=e(),C=e(),v="array"===t(n),h=!isNaN(m),w=Symbol("ignore___"),g=`${c}/${m}`,N=`objectCallback at '${g}'`,S=`keyCallback at '${g}'`;k?(u.add(N),p({resolve:j.done,reject:()=>j.done(w),value:$,key:m,breadcrumbs:g},...i)):j.done("$$cancel"),j.onComplete(e=>{if(u.delete(N),"$$cancel"!==e||d)if("$$cancel"!==e&&($=e,y=t($)),$!=w)if("simple"===y){if(!d)return void _.done("$$noUpdates");u.add(S),d({resolve:_.done,reject:()=>_.done(w),value:$,key:m,breadcrumbs:g},...i)}else _.done("$$cancel");else b.promises[f].done("ignore object");else _.done("$$noUpdates")}),_.onComplete(e=>{if(u.delete(S),e!=w)if("$$cancel"!==e){if("$$noUpdates"!==e&&($=e,y=t($)),"simple"===y){const e=function(e,o){return o instanceof Array&&!isNaN(e)}(m,n);return e?n.push($):r(n,m,$),void b.promises[f].done("key")}C.done()}else C.done();else b.promises[f].done("ignore key")}),C.onComplete(()=>{if("object"===y){const e={};v&&h?n.push(e):r(n,m,e),l.push(a($,e,l,s,g,i)),b.promises[f].done("object")}if("array"===y){const e=[];v&&h?n.push(e):r(n,m,e),l.push(a($,e,l,s,g,i)),b.promises[f].done("array")}})}),b.onComplete(e=>f.done()),f.promise}export{o as default};

package/dist/walk-async.umd.js

@@ -1 +1 @@
-!function(e,o){"object"==typeof exports&&"undefined"!=typeof module?module.exports=o(require("ask-for-promise")):"function"==typeof define&&define.amd?define(["ask-for-promise"],o):(e="undefined"!=typeof globalThis?globalThis:e||self).walkAsync=o(e.askForPromise)}(this,function(e){"use strict";async function o(e,o,n){for await(const o of e)await o.next();n.done(o)}function n(e){return null==e||e.nodeType?"simple":e instanceof Array?"array":"object"==typeof e?"object":"simple"}async function*r(e,o,n,r,s,i){yield await t(e,o,n,r,s,...i)}function t(o,t,s,i,a,...c){let[l,d]=i,f=Object.keys(o),p=e(f),u=e();return f.forEach((f,u)=>{let m=n(o[f]),y=o[f],b="simple"!==m&&null!=d,$=e(),k=e(),h=e(),j="array"===n(t),v=!isNaN(f),C=Symbol("ignore___"),g="root"===a&&"root"===f,w=g?"root":`${a}/${f}`;b?d({resolve:$.done,reject:()=>$.done(C),value:y,key:f,breadcrumbs:w},...c):$.done("$$cancel"),$.onComplete(e=>{if("$$cancel"!==e||l)if("$$cancel"!==e&&(y=e,m=n(y)),y!=C)if("simple"===m){if(!l)return void k.done("$$noUpdates");l({resolve:k.done,reject:()=>k.done(C),value:y,key:f,breadcrumbs:w},...c)}else k.done("$$cancel");else p.promises[u].done("ignore object");else k.done("$$noUpdates")}),k.onComplete(e=>{if(g)return s.push(r(y,t,s,i,"root",c)),void p.promises[u].done("root");if(e!=C)if("$$cancel"!==e){if("$$noUpdates"!==e&&(y=e,m=n(y)),"simple"===m){const e=function(e,o){return o instanceof Array&&!isNaN(e)}(f,t);return e?t.push(y):t[f]=y,void p.promises[u].done("key")}h.done()}else h.done();else p.promises[u].done("ignore key")}),h.onComplete(()=>{if("object"===m){const e={};j&&v?t.push(e):t[f]=e,s.push(r(y,e,s,i,w,c)),p.promises[u].done("object")}if("array"===m){const e=[];j&&v?t.push(e):t[f]=e,s.push(r(y,e,s,i,w,c)),p.promises[u].done("array")}})}),p.onComplete(e=>u.done()),u.promise}return function({data:r,objectCallback:s=null,keyCallback:i=null},...a){let c,l=n(r),d=[],f="root",p=[i,s],u=e();switch(l){case"array":c=[],t({root:r},c,d,p,f,...a).then(()=>o(d,c,u));break;case"object":c={},t({root:r},c,d,p,f,...a).then(()=>{o(d,c,u)});break;case"simple":u.done(r)}return u.promise}});
+!function(e,o){"object"==typeof exports&&"undefined"!=typeof module?module.exports=o(require("ask-for-promise")):"function"==typeof define&&define.amd?define(["ask-for-promise"],o):(e="undefined"!=typeof globalThis?globalThis:e||self).walkAsync=o(e.askForPromise)}(this,function(e){"use strict";async function o(e,o,n){for await(const o of e)await o.next();n.done(o)}function n(e){return null==e||e.nodeType?"simple":e instanceof Array?"array":"object"==typeof e?"object":"simple"}async function*t(e,o,n,t,r,l){yield await a(e,o,n,t,r,...l)}function r(e,o,n){"__proto__"===o?Object.defineProperty(e,o,{value:n,enumerable:!0,writable:!0,configurable:!0}):e[o]=n}function a(o,a,l,i,s,...c){let[d,u,p]=i,f=Object.keys(o),m=e(f),b=e();return f.forEach((f,b)=>{let y=n(o[f]),$=o[f],k="simple"!==y&&null!=u,j=e(),_=e(),h=e(),C="array"===n(a),v=!isNaN(f),w=Symbol("ignore___"),g=`${s}/${f}`,x=`objectCallback at '${g}'`,N=`keyCallback at '${g}'`;k?(p.add(x),u({resolve:j.done,reject:()=>j.done(w),value:$,key:f,breadcrumbs:g},...c)):j.done("$$cancel"),j.onComplete(e=>{if(p.delete(x),"$$cancel"!==e||d)if("$$cancel"!==e&&($=e,y=n($)),$!=w)if("simple"===y){if(!d)return void _.done("$$noUpdates");p.add(N),d({resolve:_.done,reject:()=>_.done(w),value:$,key:f,breadcrumbs:g},...c)}else _.done("$$cancel");else m.promises[b].done("ignore object");else _.done("$$noUpdates")}),_.onComplete(e=>{if(p.delete(N),e!=w)if("$$cancel"!==e){if("$$noUpdates"!==e&&($=e,y=n($)),"simple"===y){const e=function(e,o){return o instanceof Array&&!isNaN(e)}(f,a);return e?a.push($):r(a,f,$),void m.promises[b].done("key")}h.done()}else h.done();else m.promises[b].done("ignore key")}),h.onComplete(()=>{if("object"===y){const e={};C&&v?a.push(e):r(a,f,e),l.push(t($,e,l,i,g,c)),m.promises[b].done("object")}if("array"===y){const e=[];C&&v?a.push(e):r(a,f,e),l.push(t($,e,l,i,g,c)),m.promises[b].done("array")}})}),m.onComplete(e=>b.done()),b.promise}return function({data:t,objectCallback:r=null,keyCallback:l=null,timeout:i=null},...s){let c,d=n(t),u=[],p="root",f=new Set,m=[l,r,f],b=e(),y=e(),$=Symbol("ignore___");if("simple"!==d&&r?(f.add("objectCallback at 'root'"),r({resolve:y.done,reject:()=>y.done($),value:t,key:"root",breadcrumbs:p},...s)):y.done(t),y.onComplete(e=>{if(f.delete("objectCallback at 'root'"),e!==$)switch(n(e)){case"array":c=[],a(e,c,u,m,p,...s).then(()=>o(u,c,b));break;case"object":c={},a(e,c,u,m,p,...s).then(()=>{o(u,c,b)});break;case"simple":b.done(e)}else b.done("array"===d?[]:{})}),null==i)return b.promise;const k=Symbol("expired___"),j=e();return b.timeout(i,k),b.onComplete(e=>{if(e!==k)return void j.done(e);const o=[...f].map(e=>`\n  - ${e}`).join("");j.cancel(new Error(`walk-async: timed out after ${i}ms; callbacks still pending:${o}`))}),j.promise}});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.naydenov/walk-async",
-  "version": "3.0.7",
+  "version": "3.1.1",
   "description": "Deep copy with fine control during the process. Can be used also as a deep forEach function",
   "main": ".dist/walk-async.umd.js",
   "type": "module",
@@ -16,8 +16,9 @@
     "./src/*": "./src/*"
   },
   "scripts": {
-    "test": "mocha test",
-    "cover": "c8 mocha test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "cover": "vitest run --coverage",
     "build": "rollup -c",
     "postbuild": "tsc -p tsconfig.json"
   },
@@ -34,29 +35,27 @@
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
-    "c8": "^11.0.0",
-    "chai": "^6.2.2",
-    "mocha": "^11.7.6",
+    "@vitest/coverage-v8": "3.2.4",
     "rollup": "^4.62.2",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4",
+    "vitest": "3.2.4"
   },
-  "overrides": {
-    "diff": "^8.0.2",
-    "serialize-javascript": "^7.0.0"
-  },
-  "c8": {
-    "include": [
-      "src/**/*.js"
-    ],
-    "exclude": [
-      "node_modules",
-      "test",
-      "test-data"
-    ],
-    "reporter": [
-      "lcov",
-      "text-summary"
-    ]
+  "vitest": {
+    "coverage": {
+      "include": [
+        "src/**/*.js"
+      ],
+      "exclude": [
+        "node_modules",
+        "test",
+        "test-data"
+      ],
+      "reporter": [
+        "lcov",
+        "text-summary"
+      ]
+    }
   },
   "browserslist": "> 2%, not dead",
   "allowScripts": {

package/src/main.js

@@ -21,40 +21,45 @@ import askForPromise from "ask-for-promise"
  * @property {Object} data - The data structure to be copied.
  * @property {Function|null} objectCallback - A function called for every object in the data structure.
  * @property {Function|null} keyCallback - A function called for every property in the data structure.
+ * @property {number|null} [timeout] - Milliseconds. When set, the promise is rejected if callbacks do not resolve in time. Error lists the pending callbacks.
  */
 
 
 
 
 /**
- * Walk-async is a deep copy function that executes callback functions on every object and property. 
- * Callbacks are async functions. 
- * 
+ * Walk-async is a deep copy function that executes callback functions on every object and property.
+ * Callbacks are async functions.
+ *
  * @param {Options} options - Object with following properties:
  *                          - data - The data structure to be copied.
  *                          - objectCallback - A function that will be called for every object in the data structure.
  *                          - keyCallback - A function that will be called for every property in the data structure.
+ *                          - timeout - Milliseconds. When set, the promise is rejected if callbacks do not resolve in time.
  * @param {...any} args - Any additional arguments will be passed to the callback functions.
- * 
+ *
  * @returns {Promise} - A promise that resolves to the immutable copy of the data structure.
  */
-function walk ({ 
+function walk ({
                   data:origin
                 , objectCallback = null
                 , keyCallback = null
+                , timeout = null
             }, ...args ) {
     let
           type = findType ( origin )
         , result
         , extend = []
         , breadcrumbs = 'root'
-        , cb = [ keyCallback, objectCallback ]
+        , pending = new Set ()   // Callbacks in flight. Read on timeout to report which ones never resolved.
+        , cb = [ keyCallback, objectCallback, pending ]
         , end = askForPromise ()
         , rootTask = askForPromise ()
         , IGNORE = Symbol ( 'ignore___' )
         ;
 
     if ( type !== 'simple' && objectCallback ) {   // Root object callback. Executed before the result is allocated, so it can replace the root with anything.
+            pending.add ( `objectCallback at 'root'` )
             objectCallback ({
                           resolve : rootTask.done
                         , reject  : () => rootTask.done ( IGNORE )
@@ -66,6 +71,7 @@ function walk ({
     else    rootTask.done ( origin )
 
     rootTask.onComplete ( item => {
+            pending.delete ( `objectCallback at 'root'` )
             if ( item === IGNORE ) {
                     end.done ( ( type === 'array' ) ? [] : {} )
                     return
@@ -87,7 +93,20 @@ function walk ({
                                         end.done ( item )
                 } // switch type
         })
-    return end.promise
+
+    if ( timeout == null )   return end.promise
+
+    const   // Watchdog. 'end.timeout' races 'end.onComplete' against a timer, but leaves 'end.promise' untouched — so return a guard promise fed from the race instead.
+          EXPIRED = Symbol ( 'expired___' )
+        , guard = askForPromise ()
+        ;
+    end.timeout ( timeout, EXPIRED )
+    end.onComplete ( res => {
+            if ( res !== EXPIRED ) {   guard.done ( res );   return   }
+            const stuck = [...pending].map ( name => `\n  - ${name}` ).join ( '' )
+            guard.cancel ( new Error ( `walk-async: timed out after ${timeout}ms; callbacks still pending:${stuck}` ) )
+        })
+    return guard.promise
 } // walk func.
 
 
@@ -136,8 +155,8 @@ function setKey ( target, k, value ) {
 
 
 function copyObject ( origin, result, extend, cb, breadcrumbs, ...args ) {
-    let 
-          [ keyCallback, objectCallback ] = cb
+    let
+          [ keyCallback, objectCallback, pending ] = cb
         , keys = Object.keys ( origin )
         , executeCallback = askForPromise ( keys )
         , finish = askForPromise ()
@@ -155,9 +174,12 @@ function copyObject ( origin, result, extend, cb, breadcrumbs, ...args ) {
                         , keyNumber = !isNaN ( k )
                         , IGNORE = Symbol ( 'ignore___' )
                         , br = `${breadcrumbs}/${k}`
+                        , objectTag = `objectCallback at '${br}'`
+                        , keyTag    = `keyCallback at '${br}'`
                         ;
 
                     if ( hasObjectCallback ) {
+                                        pending.add ( objectTag )
                                         objectCallback  ({
                                                               resolve : objectCallbackTask.done
                                                             , reject  : () => objectCallbackTask.done ( IGNORE )
@@ -171,6 +193,7 @@ function copyObject ( origin, result, extend, cb, breadcrumbs, ...args ) {
                         }
 
                     objectCallbackTask.onComplete ( res => {
+                                        pending.delete ( objectTag )
                                         if ( res === '$$cancel' && !keyCallback ) {   // deep copy, no callbacks
                                                  keyCallbackTask.done ( '$$noUpdates' )
                                                  return
@@ -188,9 +211,10 @@ function copyObject ( origin, result, extend, cb, breadcrumbs, ...args ) {
                                                             keyCallbackTask.done ( '$$noUpdates' )
                                                             return
                                                         }
+                                                    pending.add ( keyTag )
                                                     keyCallback ({
                                                                   resolve  : keyCallbackTask.done
-                                                                , reject   : () => keyCallbackTask.done ( IGNORE ) 
+                                                                , reject   : () => keyCallbackTask.done ( IGNORE )
                                                                 , value : item
                                                                 , key   : k
                                                                 , breadcrumbs : br
@@ -202,6 +226,7 @@ function copyObject ( origin, result, extend, cb, breadcrumbs, ...args ) {
                         }) // objectCallbackTask complete
 
                     keyCallbackTask.onComplete ( value => {
+                                        pending.delete ( keyTag )
                                         if ( value == IGNORE ) {
                                                     executeCallback.promises[i].done ( 'ignore key' )
                                                     return

package/types/main.d.ts

@@ -1,4 +1,16 @@
-export default walk;
+/**
+ *     walk-async
+ *
+ *     Alternative of deep-copy that provides much better control during creation of immutable
+ *     copies of javascript data structures.
+ *     Library is using 'generator functions'. If support for old browsers is required,
+ *     add a polyfill for 'generators'.
+ *
+ *     History notes:
+ *        - Walk-async was born on September 18th, 2022
+ *        - Converted to ES module on January 1st, 2024
+ *
+ */
 export type Options = {
     /**
      * - The data structure to be copied.
@@ -12,12 +24,17 @@ export type Options = {
      * - A function called for every property in the data structure.
      */
     keyCallback: Function | null;
+    /**
+     * - Milliseconds. When set, the promise is rejected if callbacks do not resolve in time. Error lists the pending callbacks.
+     */
+    timeout?: number | null;
 };
 /**
  * @typedef {Object} Options
  * @property {Object} data - The data structure to be copied.
  * @property {Function|null} objectCallback - A function called for every object in the data structure.
  * @property {Function|null} keyCallback - A function called for every property in the data structure.
+ * @property {number|null} [timeout] - Milliseconds. When set, the promise is rejected if callbacks do not resolve in time. Error lists the pending callbacks.
  */
 /**
  * Walk-async is a deep copy function that executes callback functions on every object and property.
@@ -27,9 +44,11 @@ export type Options = {
  *                          - data - The data structure to be copied.
  *                          - objectCallback - A function that will be called for every object in the data structure.
  *                          - keyCallback - A function that will be called for every property in the data structure.
+ *                          - timeout - Milliseconds. When set, the promise is rejected if callbacks do not resolve in time.
  * @param {...any} args - Any additional arguments will be passed to the callback functions.
  *
  * @returns {Promise} - A promise that resolves to the immutable copy of the data structure.
  */
-declare function walk({ data: origin, objectCallback, keyCallback }: Options, ...args: any[]): Promise<any>;
+declare function walk({ data: origin, objectCallback, keyCallback, timeout }: Options, ...args: any[]): Promise<any>;
+export default walk;
 //# sourceMappingURL=main.d.ts.map

package/types/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.js"],"names":[],"mappings":";;;;;UAoBc,MAAM;;;;oBACN,WAAS,IAAI;;;;iBACb,WAAS,IAAI;;AAJ3B;;;;;GAKG;AAKH;;;;;;;;;;;GAWG;AACH,qEARW,OAAO,WAIJ,GAAG,EAAA,gBAmChB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.js"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAMA,YAAkB,OAAO,GACzB;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAA0B,cAAc,EAA7B,WAAS,IAAI,CACxB;;;;IAA0B,WAAW,EAA1B,WAAS,IAAI,CACxB;;;;IAAyB,OAAO,AAAhC,CACF,EADa,MAAM,GAAC,IAAI,CACxB;CAAA,CAAA;AAND;;;;;;GAMG;AAKH;;;;;;;;;;;;GAYG;AACH,iBAAS,IAAI,CAAE,EACG,IAAI,EAAC,MAAM,EACX,cAAqB,EACrB,WAAkB,EAClB,OAAc,EACnB,EAdF,OAcE,EAAE,GAAG,IAAI,EATR,GAAG,EASK,gBA8DrB;eAsKc,IAAI"}

package/vitest.config.js

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