@peter.naydenov/walk-async 3.0.7 → 3.1.0

package/Changelog.md

@@ -2,6 +2,11 @@
 
 
 
+### 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.naydenov/walk-async",
-  "version": "3.0.7",
+  "version": "3.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",
   "type": "module",

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