@peter.naydenov/walk-async 7.0.0 → 7.0.2

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

@@ -0,0 +1,60 @@
+# Paths, settings, and cycles
+
+## Defaults and speed tuning
+
+All settings are enabled unless explicitly set to literal `false`:
+
+| Setting | With `false` |
+| --- | --- |
+| `copy` | Skip result-container allocation and insertion; resolve `undefined` |
+| `breadcrumbs` | Skip breadcrumb preparation; omit the callback field |
+| `parentPath` | Skip parent-array preparation; omit the callback field |
+| `detectCycles` | Skip ancestor bookkeeping and circular-reference checks |
+
+Settings are independent. `copy:false` alone does not disable path
+preparation. Without callbacks, neither path is prepared automatically.
+Omitted settings and values other than literal `false` remain enabled.
+
+Explain optimisation in terms of unnecessary work avoided. Do not disable
+paths the callback uses. Disable cycle detection only when visited input
+and callback replacements are acyclic, or callbacks prune cyclic branches
+before revisiting them. Otherwise traversal may continue indefinitely.
+
+## Paths
+
+`breadcrumbs` is a slash-delimited string including the current key, such
+as `'root/profile/age'`. The root object callback receives `'root'`.
+
+`parentPath` is a frozen, shared array excluding the current key:
+
+| Location | `key` | `parentPath` |
+| --- | --- | --- |
+| Root object callback | `'root'` | `[]` |
+| Immediate root property | Property name | `['root']` |
+| `data.profile.age` | `'age'` | `['root','profile']` |
+| `data.items[0].score` | `'score'` | `['root','items','0']` |
+
+Create a full path with `[ ...parentPath, key ]`, or a breadcrumb string
+with `[ ...parentPath, key ].join ( '/' )`. Never mutate `parentPath`.
+Do not reconstruct property boundaries by splitting breadcrumbs: keys may
+contain `/`. Paths use input array indexes, even when output is compacted.
+
+Disabled fields are absent. Destructuring one gives `undefined`; check its
+setting before using it. TypeScript declares both path fields as optional.
+
+## Cycles and shared containers
+
+With detection enabled, a reference back to an ancestor points to that
+ancestor's copy, without revisiting its contents. For `data.self === data`,
+the copied result satisfies `result.self === result`. In no-copy mode,
+traversal stops at the circular edge.
+
+Object callbacks still see circular properties and may remove or replace
+them. Ancestor checks happen after callback and replacement promises settle, and
+also apply to
+containers returned by key callbacks. Detection works with both paths off.
+
+Shared containers encountered on separate non-ancestor branches are copied
+independently. For `{ a:shared, b:shared }`, `result.a !== result.b`.
+Walk therefore preserves circular ancestor links, not general shared graph
+identity. Choose a graph clone when preserved shared identity is required.

package/src/copyObject.js

@@ -8,10 +8,13 @@ import PASS, { isPass } from "./pass.js";
 import IGNORE, { isIgnore } from "./ignore.js";
 import { isFinish } from "./finish.js";
 import runCallback from "./runCallback.js";
+import runTask from "./runTask.js";
 
 
 
-async function copyObject ( resource, result, extend, cb, breadcrumbs, settings, control, parentPath, pass, parent, ancestors, pending, ...args ) {
+function copyObject ( resource, result, extend, cb, breadcrumbs, settings, control, parentPath, pass, parent, ancestors, pending, ...args ) {
+    return runTask ( copy() )
+    function* copy () {
     let
           [ keyCallback, objectCallback ] = cb
         , keys = Object.keys ( resource )
@@ -34,7 +37,7 @@ async function copyObject ( resource, result, extend, cb, breadcrumbs, settings,
                     if ( type !== 'simple' && objectCallback && !control.isFinished ) {
                                         const callbackArgs = createCallbackArgs ( item, k, IGNORE, br, parentPath, settings )
                                         callbackArgs.PASS = PASS
-                                        const replacement = await runCallback ( objectCallback, callbackArgs, pending, 'objectCallback', ...args )
+                                        const replacement = yield runCallback ( objectCallback, callbackArgs, pending, 'objectCallback', ...args )
                                         if ( isFinish ( replacement ) ) {
                                                 if ( !replacement.hasValue || !keyCallback ) {
                                                         finish ( replacement, result, k, canInsert, settings, control )
@@ -66,7 +69,7 @@ async function copyObject ( resource, result, extend, cb, breadcrumbs, settings,
                                         }
                                     const callbackArgs = createCallbackArgs ( item, k, IGNORE, br, parentPath, settings );
                                     callbackArgs.isFinished = control.isFinished
-                                    let keyRes = await runCallback ( keyCallback, callbackArgs, pending, 'keyCallback', ...args );
+                                    let keyRes = yield runCallback ( keyCallback, callbackArgs, pending, 'keyCallback', ...args );
                                     if ( isFinish ( keyRes ) ) {
                                             finish ( keyRes, result, k, canInsert, settings, control )
                                             return parents
@@ -114,6 +117,7 @@ async function copyObject ( resource, result, extend, cb, breadcrumbs, settings,
                         }
             }
     return parents
+    }
 } // copyObject func.
 
 

package/src/main.js

@@ -20,6 +20,8 @@ import createCallbackArgs from "./createCallbackArgs.js";
 import PASS, { isPass } from "./pass.js";
 import IGNORE, { isIgnore } from "./ignore.js";
 import runCallback from "./runCallback.js";
+import askForPromise from "ask-for-promise";
+import runTask from "./runTask.js";
 import { isFinish } from "./finish.js";
 
 
@@ -179,29 +181,34 @@ import { isFinish } from "./finish.js";
  *  // If you modify an object with objectCallback, keyCallback will be
  *  // executed on the result of objectCallback.
  */
-async function walk (options,...args) {
+function walk (options,...args) {
+    return runTask ( start() )
+
+    function* start () {
     const pending = new Set ();
     const task = traverse ( options, pending, ...args );
-    if ( options.timeout == null )   return task
+    if ( options.timeout == null )   return yield task
 
-    let timer;
-    const guard = new Promise ( ( resolve, reject ) => {
-            timer = setTimeout ( () => {
+    const guard = askForPromise();
+    const timer = setTimeout ( () => {
                     const stuck = [...pending].map ( name => `\n  - ${name}` ).join ( '' );
-                    reject ( new Error ( `walk-async: timed out after ${options.timeout}ms; callbacks still pending:${stuck}` ) )
+                    guard.cancel ( new Error ( `walk-async: timed out after ${options.timeout}ms; callbacks still pending:${stuck}` ) )
                 }, options.timeout )
-        })
+    task.then ( guard.done, guard.cancel )
     try {
-            return await Promise.race ([ task, guard ])
+            return yield guard.promise
         }
     finally {
             clearTimeout ( timer )
         }
+    }
 } // walk func.
 
 
 
-async function traverse ( options, pending, ...args ) {
+function traverse ( options, pending, ...args ) {
+    return runTask ( visit() )
+    function* visit () {
     let
           { data:origin, keyCallback, objectCallback, settings:config } = options
         , type = findType ( origin )
@@ -227,7 +234,7 @@ async function traverse ( options, pending, ...args ) {
             const rootParent = settings.parentPath ? Object.freeze ( [] ) : undefined
             const callbackArgs = createCallbackArgs ( origin, 'root', IGNORE, breadcrumbs, rootParent, settings )
             callbackArgs.PASS = PASS
-            const replacement = await runCallback ( objectCallback, callbackArgs, pending, 'objectCallback', ...args )
+            const replacement = yield runCallback ( objectCallback, callbackArgs, pending, 'objectCallback', ...args )
             if ( isFinish ( replacement ) ) {
                     if ( !replacement.hasValue ) {
                             if ( !settings.copy )   return
@@ -252,11 +259,11 @@ async function traverse ( options, pending, ...args ) {
     switch ( type ) {
             case 'array'  :
                                 result = settings.copy ? [] : undefined
-                                parent = await copyObject ( origin, result, extend, cb, breadcrumbs, settings, control, parentPath, pass, undefined, ancestors, pending, ...args )
+                                parent = yield copyObject ( origin, result, extend, cb, breadcrumbs, settings, control, parentPath, pass, undefined, ancestors, pending, ...args )
                                 break
             case 'object' :
                                 result = settings.copy ? {} : undefined
-                                parent = await copyObject ( origin, result, extend, cb, breadcrumbs, settings, control, parentPath, pass, undefined, ancestors, pending, ...args )
+                                parent = yield copyObject ( origin, result, extend, cb, breadcrumbs, settings, control, parentPath, pass, undefined, ancestors, pending, ...args )
                                 break
             case 'simple' :
                                 return settings.copy ? origin : undefined
@@ -268,10 +275,11 @@ async function traverse ( options, pending, ...args ) {
             control.restart = false
             if ( settings.detectCycles )   ancestors = moveParents ( parent, job.parent, ancestors )
             const path = settings.parentPath ? Object.freeze ([ ...job.parentPath, job.key ]) : undefined;
-            parent = await copyObject ( job.data, job.location, extend, cb, job.breadcrumbs, settings, control, path, job.pass, job.parent, ancestors, pending, ...args )
+            parent = yield copyObject ( job.data, job.location, extend, cb, job.breadcrumbs, settings, control, path, job.pass, job.parent, ancestors, pending, ...args )
             index = control.restart ? 0 : index + 1
         }
     return result
+    }
 } // traverse func.
 
 

package/src/runCallback.js

@@ -3,10 +3,15 @@
 import IGNORE from "./ignore.js";
 import PASS, { isPass } from "./pass.js";
 import FINISH, { isFinish } from "./finish.js";
+import askForPromise from "ask-for-promise";
+import runTask from "./runTask.js";
 
 
 
-async function runCallback ( callback, context, pending, name, ...args ) {
+function runCallback ( callback, context, pending, name, ...args ) {
+    return runTask ( run() )
+
+    function* run () {
     let
           task
         , done
@@ -17,11 +22,12 @@ async function runCallback ( callback, context, pending, name, ...args ) {
     // Return-based callbacks need no extra settlement promise.
     function explicit () {
         if ( !task ) {
-                task = new Promise ( resolve => { done = resolve } )
+                task = askForPromise()
+                done = task.done
                 // Observe rejected values immediately, even while the callback
                 // is still awaiting other work. The original rejection is
                 // propagated when task is awaited below.
-                task.catch ( () => {} )
+                task.promise.catch ( () => {} )
             }
     } // explicit func.
 
@@ -38,16 +44,17 @@ async function runCallback ( callback, context, pending, name, ...args ) {
 
     pending.add ( tag )
     try {
-            const returned = await callback ( context, ...args );
-            const value = task ? await task : returned;
+            const returned = yield callback ( context, ...args );
+            const value = task ? yield task.promise : returned;
             // Keep the callback pending while an instruction replacement settles too.
-            if ( name === 'objectCallback' && isPass ( value ) && value.hasValue )   return PASS ( await value.value )
-            if ( isFinish ( value ) && value.hasValue )   return FINISH ( await value.value )
+            if ( name === 'objectCallback' && isPass ( value ) && value.hasValue )   return PASS ( yield value.value )
+            if ( isFinish ( value ) && value.hasValue )   return FINISH ( yield value.value )
             return value
         }
     finally {
             pending.delete ( tag )
         }
+    }
 } // runCallback func.
 
 

package/src/runTask.js

@@ -0,0 +1,34 @@
+"use strict"
+
+import askForPromise from "ask-for-promise";
+
+
+// Drive the traversal one step at a time, including promised callback values.
+// Each task uses ask-for-promise for settlement and error propagation.
+function runTask ( iterator ) {
+    const task = askForPromise();
+
+    function step ( method, value ) {
+        let next;
+        try {
+                next = iterator[method] ( value )
+            }
+        catch ( error ) {
+                task.cancel ( error )
+                return
+            }
+        if ( next.done ) {
+                task.done ( next.value )
+                return
+            }
+        const pending = askForPromise();
+        pending.done ( next.value )
+        pending.promise.then ( value => step ( 'next', value ), error => step ( 'throw', error ) )
+    }
+
+    step ( 'next' )
+    return task.promise
+} // runTask func.
+
+
+export default runTask

package/types/copyObject.d.ts

@@ -1,8 +1,3 @@
-declare function copyObject(resource: any, result: any, extend: any, cb: any, breadcrumbs: any, settings: any, control: any, parentPath: any, pass: any, parent: any, ancestors: any, pending: any, ...args: any[]): Promise<{
-    data: any;
-    location: any;
-    parent: any;
-    depth: any;
-} | undefined>;
+declare function copyObject(resource: any, result: any, extend: any, cb: any, breadcrumbs: any, settings: any, control: any, parentPath: any, pass: any, parent: any, ancestors: any, pending: any, ...args: any[]): Promise<any>;
 export default copyObject;
 //# sourceMappingURL=copyObject.d.ts.map

package/types/copyObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copyObject.d.ts","sourceRoot":"","sources":["../src/copyObject.js"],"names":[],"mappings":"AAaA,iBAAe,UAAU,CAAG,QAAQ,KAAA,EAAE,MAAM,KAAA,EAAE,MAAM,KAAA,EAAE,EAAE,KAAA,EAAE,WAAW,KAAA,EAAE,QAAQ,KAAA,EAAE,OAAO,KAAA,EAAE,UAAU,KAAA,EAAE,IAAI,KAAA,EAAE,MAAM,KAAA,EAAE,SAAS,KAAA,EAAE,OAAO,KAAA,EAAE,GAAG,IAAI,OAAA;;;;;eAuG9I;eA4Bc,UAAU"}
+{"version":3,"file":"copyObject.d.ts","sourceRoot":"","sources":["../src/copyObject.js"],"names":[],"mappings":"AAcA,iBAAS,UAAU,CAAG,QAAQ,KAAA,EAAE,MAAM,KAAA,EAAE,MAAM,KAAA,EAAE,EAAE,KAAA,EAAE,WAAW,KAAA,EAAE,QAAQ,KAAA,EAAE,OAAO,KAAA,EAAE,UAAU,KAAA,EAAE,IAAI,KAAA,EAAE,MAAM,KAAA,EAAE,SAAS,KAAA,EAAE,OAAO,KAAA,EAAE,GAAG,IAAI,OAAA,gBA0GxI;eA4Bc,UAAU"}

package/types/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.js"],"names":[],"mappings":"AA6BI,YAAU,OAAO,GACjB,CAAW,KAAK,EAAR,GACR,KAAU,IACb,CAAA;AAMG,YAAU,MAAM,GAChB,CAAY,MAAM,AAAlB,CACA,EADQ,GACR,KAAU,IACb,CAAA;AAKG,YAAkB,WAAW,GAAnB,MAAM,CAAa;AAM7B,YAAU,cAAc,GACxB,MAAU,WACb,CAAA;AAQG,YAAU,YAAY,GACtB,CAAY,KAAK,AAAjB,CACA,EADQ,GACR,KAAU,OAAO,WAAW,EAAE,eACjC,CAAA;AAMG,YAAU,cAAc,GACxB,CAAY,KAAK,AAAjB,CACA,EADQ,GACR,KAAU,OAAO,aAAa,EAAE,iBACnC,CAAA;AAKG,YAAkB,YAAY,GAC9B;;;;IAAuB,KAAK,EAAjB,GAAC,CACZ;;;;IAAuB,GAAG,EAAf,MAAM,CACjB;;;;IAAwB,WAAW,AAAnC,CACA,EADW,MAAM,CACjB;;;;IAAmC,UAAU,AAA7C,CACA,EADW,aAAa,CAAC,MAAM,CAAC,CAChC;;;;IAAoB,OAAO,EAAhB,OAAO,CAClB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAA2B,MAAM,EAAtB,cAAc,CACzB;;;;IAA2B,MAAM,EAAtB,cAAc,CAC5B;CAAA,CAAA;AAGG,YAAkD,eAAe,GAAvD,YAAY,GAAG;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,CAAiB;AAIjE,YAAiD,kBAAkB,GAAzD,YAAY,GAAG;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAoB;AAmBnE,YAAU,WAAW,GACrB,CAAyB,IAAI,EAArB,eACR,EAAA,GACA,AADsB,IAAI,EAAf,GACX,KAAU,MAAI,OAAO,KACxB,CAAA;AAeG,YAAU,cAAc,GACxB,CAA4B,IAAI,EAAxB,kBACR,EAAA,GACA,AADsB,IAAI,EAAf,GACX,KAAU,MAAI,OAAO,KACxB,CAAA;AAGG,YAAkB,QAAQ,GAC1B;;;;IAAqB,IAAI,AAAzB,CACA,EADW,OAAO,CAClB;;;;IAAqB,WAAW,AAAhC,CACA,EADW,OAAO,CAClB;;;;IAAqB,UAAU,AAA/B,CACA,EADW,OAAO,CAClB;;;;IAAqB,YAAY,AAAjC,CACH,EADc,OAAO,CACrB;CAAA,CAAA;AAGG,YAAkB,OAAO,GACzB;;;;IAA0B,IAAI,EAAnB,GAAC,CACZ;;;;IAA4B,WAAW,AAAvC,CACA,EADW,WAAW,CACtB;;;;IAA4B,cAAc,AAA1C,CACA,EADW,cAAc,CACzB;;;;IAA4B,OAAO,AAAnC,CACA,EADW,MAAM,CACjB;;;;IAA4B,QAAQ,AAApC,CACH,EADc,QAAQ,CACtB;CAAA,CAAA;AAjID;;;;;;;GAOG;AAEH;;;;;;;GAOG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AAEH;;GAEG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AAEH;;;;;;;GAOG;AAGH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iBAAe,IAAI,CAAE,OAAO,EAdhB,OAcgB,EAAC,GAAG,IAAI,EAbrB,GAAC,EAaoB,GAZtB,OAAO,CAAC,GAAC,CAAC,CA8BvB;eAmHc,IAAI"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.js"],"names":[],"mappings":"AA+BI,YAAU,OAAO,GACjB,CAAW,KAAK,EAAR,GACR,KAAU,IACb,CAAA;AAMG,YAAU,MAAM,GAChB,CAAY,MAAM,AAAlB,CACA,EADQ,GACR,KAAU,IACb,CAAA;AAKG,YAAkB,WAAW,GAAnB,MAAM,CAAa;AAM7B,YAAU,cAAc,GACxB,MAAU,WACb,CAAA;AAQG,YAAU,YAAY,GACtB,CAAY,KAAK,AAAjB,CACA,EADQ,GACR,KAAU,OAAO,WAAW,EAAE,eACjC,CAAA;AAMG,YAAU,cAAc,GACxB,CAAY,KAAK,AAAjB,CACA,EADQ,GACR,KAAU,OAAO,aAAa,EAAE,iBACnC,CAAA;AAKG,YAAkB,YAAY,GAC9B;;;;IAAuB,KAAK,EAAjB,GAAC,CACZ;;;;IAAuB,GAAG,EAAf,MAAM,CACjB;;;;IAAwB,WAAW,AAAnC,CACA,EADW,MAAM,CACjB;;;;IAAmC,UAAU,AAA7C,CACA,EADW,aAAa,CAAC,MAAM,CAAC,CAChC;;;;IAAoB,OAAO,EAAhB,OAAO,CAClB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAA2B,MAAM,EAAtB,cAAc,CACzB;;;;IAA2B,MAAM,EAAtB,cAAc,CAC5B;CAAA,CAAA;AAGG,YAAkD,eAAe,GAAvD,YAAY,GAAG;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,CAAiB;AAIjE,YAAiD,kBAAkB,GAAzD,YAAY,GAAG;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAoB;AAmBnE,YAAU,WAAW,GACrB,CAAyB,IAAI,EAArB,eACR,EAAA,GACA,AADsB,IAAI,EAAf,GACX,KAAU,MAAI,OAAO,KACxB,CAAA;AAeG,YAAU,cAAc,GACxB,CAA4B,IAAI,EAAxB,kBACR,EAAA,GACA,AADsB,IAAI,EAAf,GACX,KAAU,MAAI,OAAO,KACxB,CAAA;AAGG,YAAkB,QAAQ,GAC1B;;;;IAAqB,IAAI,AAAzB,CACA,EADW,OAAO,CAClB;;;;IAAqB,WAAW,AAAhC,CACA,EADW,OAAO,CAClB;;;;IAAqB,UAAU,AAA/B,CACA,EADW,OAAO,CAClB;;;;IAAqB,YAAY,AAAjC,CACH,EADc,OAAO,CACrB;CAAA,CAAA;AAGG,YAAkB,OAAO,GACzB;;;;IAA0B,IAAI,EAAnB,GAAC,CACZ;;;;IAA4B,WAAW,AAAvC,CACA,EADW,WAAW,CACtB;;;;IAA4B,cAAc,AAA1C,CACA,EADW,cAAc,CACzB;;;;IAA4B,OAAO,AAAnC,CACA,EADW,MAAM,CACjB;;;;IAA4B,QAAQ,AAApC,CACH,EADc,QAAQ,CACtB;CAAA,CAAA;AAjID;;;;;;;GAOG;AAEH;;;;;;;GAOG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AAEH;;GAEG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AAEH;;;;;;;GAOG;AAGH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iBAAS,IAAI,CAAE,OAAO,EAdV,OAcU,EAAC,GAAG,IAAI,EAbf,GAAC,EAac,GAZhB,OAAO,CAAC,GAAC,CAAC,CAiCvB;eAsHc,IAAI"}

package/types/runCallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runCallback.d.ts","sourceRoot":"","sources":["../src/runCallback.js"],"names":[],"mappings":"AAQA,iBAAe,WAAW,CAAG,QAAQ,KAAA,EAAE,OAAO,KAAA,EAAE,OAAO,KAAA,EAAE,IAAI,KAAA,EAAE,GAAG,IAAI,OAAA,gBA0CrE;eAIc,WAAW"}
+{"version":3,"file":"runCallback.d.ts","sourceRoot":"","sources":["../src/runCallback.js"],"names":[],"mappings":"AAUA,iBAAS,WAAW,CAAG,QAAQ,KAAA,EAAE,OAAO,KAAA,EAAE,OAAO,KAAA,EAAE,IAAI,KAAA,EAAE,GAAG,IAAI,OAAA,gBA+C/D;eAIc,WAAW"}

package/types/runTask.d.ts

@@ -0,0 +1,3 @@
+declare function runTask(iterator: any): Promise<any>;
+export default runTask;
+//# sourceMappingURL=runTask.d.ts.map

package/types/runTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTask.d.ts","sourceRoot":"","sources":["../src/runTask.js"],"names":[],"mappings":"AAOA,iBAAS,OAAO,CAAG,QAAQ,KAAA,gBAuB1B;eAGc,OAAO"}