@peter.naydenov/walk-async 6.1.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Changelog.md +29 -4
- package/Migration.guide.md +179 -25
- package/README.md +501 -311
- package/dist/walk-async.cjs +1 -1
- package/dist/walk-async.esm.mjs +1 -1
- package/dist/walk-async.umd.js +1 -1
- package/package.json +6 -5
- package/src/copyObject.js +145 -0
- package/src/createCallbackArgs.js +15 -0
- package/src/findType.js +28 -0
- package/src/finish.js +38 -0
- package/src/ignore.js +24 -0
- package/src/main.js +230 -285
- package/src/pass.js +36 -0
- package/src/runCallback.js +55 -0
- package/src/setKey.js +12 -0
- package/src/validateForInsertion.js +12 -0
- package/types/copyObject.d.ts +8 -0
- package/types/copyObject.d.ts.map +1 -0
- package/types/createCallbackArgs.d.ts +32 -0
- package/types/createCallbackArgs.d.ts.map +1 -0
- package/types/findType.d.ts +3 -0
- package/types/findType.d.ts.map +1 -0
- package/types/finish.d.ts +25 -0
- package/types/finish.d.ts.map +1 -0
- package/types/ignore.d.ts +10 -0
- package/types/ignore.d.ts.map +1 -0
- package/types/main.d.ts +147 -61
- package/types/main.d.ts.map +1 -1
- package/types/pass.d.ts +23 -0
- package/types/pass.d.ts.map +1 -0
- package/types/runCallback.d.ts +3 -0
- package/types/runCallback.d.ts.map +1 -0
- package/types/setKey.d.ts +3 -0
- package/types/setKey.d.ts.map +1 -0
- package/types/validateForInsertion.d.ts +3 -0
- package/types/validateForInsertion.d.ts.map +1 -0
- package/.agents/skills/git-walk-async/SKILL.md +0 -173
- package/types/src/main.d.ts +0 -35
- package/types/src/main.d.ts.map +0 -1
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"use strict"
|
|
2
|
+
|
|
3
|
+
import IGNORE from "./ignore.js";
|
|
4
|
+
import PASS, { isPass } from "./pass.js";
|
|
5
|
+
import FINISH, { isFinish } from "./finish.js";
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
async function runCallback ( callback, context, pending, name, ...args ) {
|
|
10
|
+
let
|
|
11
|
+
task
|
|
12
|
+
, done
|
|
13
|
+
, tag = `${name} at '${context.breadcrumbs ?? context.key}'`
|
|
14
|
+
;
|
|
15
|
+
|
|
16
|
+
// Reading resolve or reject selects the v6 explicit-settlement API.
|
|
17
|
+
// Return-based callbacks need no extra settlement promise.
|
|
18
|
+
function explicit () {
|
|
19
|
+
if ( !task ) {
|
|
20
|
+
task = new Promise ( resolve => { done = resolve } )
|
|
21
|
+
// Observe rejected values immediately, even while the callback
|
|
22
|
+
// is still awaiting other work. The original rejection is
|
|
23
|
+
// propagated when task is awaited below.
|
|
24
|
+
task.catch ( () => {} )
|
|
25
|
+
}
|
|
26
|
+
} // explicit func.
|
|
27
|
+
|
|
28
|
+
Object.defineProperties ( context, {
|
|
29
|
+
resolve : {
|
|
30
|
+
enumerable : true
|
|
31
|
+
, get : () => { explicit (); return done }
|
|
32
|
+
}
|
|
33
|
+
, reject : {
|
|
34
|
+
enumerable : true
|
|
35
|
+
, get : () => { explicit (); return () => done ( IGNORE() ) }
|
|
36
|
+
}
|
|
37
|
+
})
|
|
38
|
+
|
|
39
|
+
pending.add ( tag )
|
|
40
|
+
try {
|
|
41
|
+
const returned = await callback ( context, ...args );
|
|
42
|
+
const value = task ? await task : returned;
|
|
43
|
+
// Keep the callback pending while an instruction replacement settles too.
|
|
44
|
+
if ( name === 'objectCallback' && isPass ( value ) && value.hasValue ) return PASS ( await value.value )
|
|
45
|
+
if ( isFinish ( value ) && value.hasValue ) return FINISH ( await value.value )
|
|
46
|
+
return value
|
|
47
|
+
}
|
|
48
|
+
finally {
|
|
49
|
+
pending.delete ( tag )
|
|
50
|
+
}
|
|
51
|
+
} // runCallback func.
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
export default runCallback
|
package/src/setKey.js
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// Plain assignment of a '__proto__' key triggers the inherited setter and
|
|
2
|
+
// replaces the prototype of 'target' instead of creating an own property.
|
|
3
|
+
function setKey ( target, k, value ) {
|
|
4
|
+
if ( k === '__proto__' ) Object.defineProperty ( target, k, { value, enumerable:true, writable:true, configurable:true })
|
|
5
|
+
else target[k] = value
|
|
6
|
+
} // setKey func.
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
export default setKey
|
|
11
|
+
|
|
12
|
+
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
function validateForInsertion ( k, result ) {
|
|
2
|
+
if ( !Array.isArray ( result ) ) return false
|
|
3
|
+
const index = Number ( k );
|
|
4
|
+
// Array indexes are canonical decimal strings from 0 through 2^32 - 2.
|
|
5
|
+
return Number.isInteger ( index ) && index >= 0 && index < 4294967295 && String ( index ) === k
|
|
6
|
+
} // validateForInsertion func.
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
export default validateForInsertion
|
|
11
|
+
|
|
12
|
+
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
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<{
|
|
2
|
+
data: any;
|
|
3
|
+
location: any;
|
|
4
|
+
parent: any;
|
|
5
|
+
depth: any;
|
|
6
|
+
} | undefined>;
|
|
7
|
+
export default copyObject;
|
|
8
|
+
//# sourceMappingURL=copyObject.d.ts.map
|
|
@@ -0,0 +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"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import FINISH from "./finish.js";
|
|
2
|
+
declare function createCallbackArgs(value: any, key: any, IGNORE: any, breadcrumbs: any, parentPath: any, settings: any): {
|
|
3
|
+
value: any;
|
|
4
|
+
key: any;
|
|
5
|
+
breadcrumbs: any;
|
|
6
|
+
parentPath: any;
|
|
7
|
+
IGNORE: any;
|
|
8
|
+
FINISH: typeof FINISH;
|
|
9
|
+
} | {
|
|
10
|
+
value: any;
|
|
11
|
+
key: any;
|
|
12
|
+
breadcrumbs: any;
|
|
13
|
+
IGNORE: any;
|
|
14
|
+
FINISH: typeof FINISH;
|
|
15
|
+
parentPath?: undefined;
|
|
16
|
+
} | {
|
|
17
|
+
breadcrumbs?: undefined;
|
|
18
|
+
value: any;
|
|
19
|
+
key: any;
|
|
20
|
+
parentPath: any;
|
|
21
|
+
IGNORE: any;
|
|
22
|
+
FINISH: typeof FINISH;
|
|
23
|
+
} | {
|
|
24
|
+
breadcrumbs?: undefined;
|
|
25
|
+
parentPath?: undefined;
|
|
26
|
+
value: any;
|
|
27
|
+
key: any;
|
|
28
|
+
IGNORE: any;
|
|
29
|
+
FINISH: typeof FINISH;
|
|
30
|
+
};
|
|
31
|
+
export default createCallbackArgs;
|
|
32
|
+
//# sourceMappingURL=createCallbackArgs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"createCallbackArgs.d.ts","sourceRoot":"","sources":["../src/createCallbackArgs.js"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAIjC,iBAAS,kBAAkB,CAAG,KAAK,KAAA,EAAE,GAAG,KAAA,EAAE,MAAM,KAAA,EAAE,WAAW,KAAA,EAAE,UAAU,KAAA,EAAE,QAAQ,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKlF;eAIc,kBAAkB"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"findType.d.ts","sourceRoot":"","sources":["../src/findType.js"],"names":[],"mappings":"AAAA,iBAAS,QAAQ,CAAG,CAAC,KAAA,iCAoBnB;eAIc,QAAQ"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export type FinishInstruction = {
|
|
2
|
+
value: any;
|
|
3
|
+
hasValue: boolean;
|
|
4
|
+
};
|
|
5
|
+
/**
|
|
6
|
+
* Private instruction created by the FINISH helper.
|
|
7
|
+
*
|
|
8
|
+
* @typedef {object} FinishInstruction
|
|
9
|
+
* @property {*} value
|
|
10
|
+
* @property {boolean} hasValue
|
|
11
|
+
*/
|
|
12
|
+
/**
|
|
13
|
+
* Stop the entire walk. Omit the current value when no argument is
|
|
14
|
+
* supplied. From objectCallback, a supplied value selects the final
|
|
15
|
+
* branch for key callbacks with isFinished true. From keyCallback,
|
|
16
|
+
* include the supplied value directly and stop immediately.
|
|
17
|
+
*
|
|
18
|
+
* @param {*} [value] - Final value or branch.
|
|
19
|
+
* @returns {FinishInstruction}
|
|
20
|
+
*/
|
|
21
|
+
declare function FINISH(value?: any): FinishInstruction;
|
|
22
|
+
declare function isFinish(value: any): boolean;
|
|
23
|
+
export { isFinish };
|
|
24
|
+
export default FINISH;
|
|
25
|
+
//# sourceMappingURL=finish.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"finish.d.ts","sourceRoot":"","sources":["../src/finish.js"],"names":[],"mappings":"AAQI,YAAkB,iBAAiB,GACnC;IAAc,KAAK,EAAR,GAAC,CACZ;IAAoB,QAAQ,EAAjB,OAAO,CACrB;CAAA,CAAA;AAND;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,iBAAS,MAAM,CAAG,KAAK,AAHnB,CACA,EADQ,GAGW,GAFT,iBAAiB,CAM9B;AAID,iBAAS,QAAQ,CAAG,KAAK,KAAA,WAExB;AAID,OAAO,EAAE,QAAQ,EAAE,CAAA;eACJ,MAAM"}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Remove the current key or the entire current object/array branch.
|
|
3
|
+
*
|
|
4
|
+
* @returns {symbol}
|
|
5
|
+
*/
|
|
6
|
+
declare function IGNORE(): symbol;
|
|
7
|
+
declare function isIgnore(value: any): boolean;
|
|
8
|
+
export { isIgnore };
|
|
9
|
+
export default IGNORE;
|
|
10
|
+
//# sourceMappingURL=ignore.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ignore.d.ts","sourceRoot":"","sources":["../src/ignore.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,iBAAS,MAAM,IAFD,MAAM,CAInB;AAID,iBAAS,QAAQ,CAAG,KAAK,KAAA,WAExB;AAID,OAAO,EAAE,QAAQ,EAAE,CAAA;eACJ,MAAM"}
|
package/types/main.d.ts
CHANGED
|
@@ -1,18 +1,9 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* walk-async
|
|
3
|
-
*
|
|
4
|
-
* Alternative of deep-copy that provides much better control during creation of immutable
|
|
5
|
-
* copies of javascript data structures.
|
|
6
|
-
* Library is using 'generator functions'. If support for old browsers is required,
|
|
7
|
-
* add a polyfill for 'generators'.
|
|
8
|
-
*
|
|
9
|
-
* History notes:
|
|
10
|
-
* - Walk-async was born on September 18th, 2022
|
|
11
|
-
* - Converted to ES module on January 1st, 2024
|
|
12
|
-
*
|
|
13
|
-
*/
|
|
14
1
|
export type Resolve = (value: any) => void;
|
|
15
2
|
export type Reject = (reason?: any) => void;
|
|
3
|
+
export type IgnoreToken = symbol;
|
|
4
|
+
export type IgnoreFunction = () => IgnoreToken;
|
|
5
|
+
export type PassFunction = (value?: any) => import('./pass.js').PassInstruction;
|
|
6
|
+
export type FinishFunction = (value?: any) => import('./finish.js').FinishInstruction;
|
|
16
7
|
export type CallbackArgs = {
|
|
17
8
|
/**
|
|
18
9
|
* - The current value being processed.
|
|
@@ -23,23 +14,59 @@ export type CallbackArgs = {
|
|
|
23
14
|
*/
|
|
24
15
|
key: string;
|
|
25
16
|
/**
|
|
26
|
-
* - Slash-delimited path
|
|
17
|
+
* - Slash-delimited path including the current key. Absent when `settings.breadcrumbs` is false.
|
|
18
|
+
*/
|
|
19
|
+
breadcrumbs?: string;
|
|
20
|
+
/**
|
|
21
|
+
* - Read-only path to the parent, excluding the current key. Absent when `settings.parentPath` is false.
|
|
27
22
|
*/
|
|
28
|
-
|
|
23
|
+
parentPath?: ReadonlyArray<string>;
|
|
29
24
|
/**
|
|
30
|
-
* -
|
|
25
|
+
* - Reading this field opts into explicit settlement with resolve(value) or reject().
|
|
31
26
|
*/
|
|
32
27
|
resolve: Resolve;
|
|
33
28
|
/**
|
|
34
|
-
* -
|
|
29
|
+
* - Drop the current key or branch; does not reject the walk promise.
|
|
35
30
|
*/
|
|
36
31
|
reject: Reject;
|
|
32
|
+
/**
|
|
33
|
+
* - Return FINISH() to omit the current value and stop, or FINISH(value) to include a final value or branch.
|
|
34
|
+
*/
|
|
35
|
+
FINISH: FinishFunction;
|
|
36
|
+
/**
|
|
37
|
+
* - Return IGNORE() from the callback to drop the current key from the result.
|
|
38
|
+
*/
|
|
39
|
+
IGNORE: IgnoreFunction;
|
|
40
|
+
};
|
|
41
|
+
export type KeyCallbackArgs = CallbackArgs & {
|
|
42
|
+
isFinished: boolean;
|
|
43
|
+
};
|
|
44
|
+
export type ObjectCallbackArgs = CallbackArgs & {
|
|
45
|
+
PASS: PassFunction;
|
|
46
|
+
};
|
|
47
|
+
export type KeyCallback = (args: KeyCallbackArgs, ...rest: any) => any | Promise<any>;
|
|
48
|
+
export type ObjectCallback = (args: ObjectCallbackArgs, ...rest: any) => any | Promise<any>;
|
|
49
|
+
export type Settings = {
|
|
50
|
+
/**
|
|
51
|
+
* - Defaults to true. Only false disables result creation; callbacks still run and walk resolves undefined.
|
|
52
|
+
*/
|
|
53
|
+
copy?: boolean;
|
|
54
|
+
/**
|
|
55
|
+
* - Defaults to true. Only false disables breadcrumbs preparation.
|
|
56
|
+
*/
|
|
57
|
+
breadcrumbs?: boolean;
|
|
58
|
+
/**
|
|
59
|
+
* - Defaults to true. Only false disables parent-path preparation.
|
|
60
|
+
*/
|
|
61
|
+
parentPath?: boolean;
|
|
62
|
+
/**
|
|
63
|
+
* - Defaults to true. Only false disables circular-reference checks and their bookkeeping; visited data and replacements must then be acyclic or callbacks must prune cyclic branches.
|
|
64
|
+
*/
|
|
65
|
+
detectCycles?: boolean;
|
|
37
66
|
};
|
|
38
|
-
export type KeyCallback = (args: CallbackArgs, ...rest: any) => void;
|
|
39
|
-
export type ObjectCallback = (args: CallbackArgs, ...rest: any) => void;
|
|
40
67
|
export type Options = {
|
|
41
68
|
/**
|
|
42
|
-
* - Required. Any JS data structure that will be
|
|
69
|
+
* - Required. Any JS data structure that will be walked.
|
|
43
70
|
*/
|
|
44
71
|
data: any;
|
|
45
72
|
/**
|
|
@@ -51,97 +78,156 @@ export type Options = {
|
|
|
51
78
|
*/
|
|
52
79
|
objectCallback?: ObjectCallback;
|
|
53
80
|
/**
|
|
54
|
-
* - Optional
|
|
81
|
+
* - Optional milliseconds. Reject the walk with pending-callback diagnostics when time expires.
|
|
55
82
|
*/
|
|
56
83
|
timeout?: number;
|
|
84
|
+
/**
|
|
85
|
+
* - Optional. Disable copying, unused callback metadata, or cycle detection with false.
|
|
86
|
+
*/
|
|
87
|
+
settings?: Settings;
|
|
57
88
|
};
|
|
58
89
|
/**
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
* - resolving a plain object or array → walk continues into it with the other callback applied to its children;
|
|
62
|
-
*
|
|
63
|
-
* You must call `resolve` or `reject` on every code path — otherwise the walk promise never settles
|
|
64
|
-
* (use the `timeout` option to turn that silent hang into a rejection with diagnostics).
|
|
90
|
+
* Explicitly settle a callback with its current value or a replacement.
|
|
91
|
+
* Promises supplied to resolve are awaited before traversal continues.
|
|
65
92
|
*
|
|
66
93
|
* @callback Resolve
|
|
67
94
|
* @param {*} value
|
|
68
95
|
* @returns {void}
|
|
69
96
|
*/
|
|
70
97
|
/**
|
|
71
|
-
*
|
|
98
|
+
* Drop the current key or entire branch. Retained for v6 callbacks.
|
|
99
|
+
* To reject the walk itself, throw or return a rejected promise.
|
|
72
100
|
*
|
|
73
101
|
* @callback Reject
|
|
74
102
|
* @param {*} [reason]
|
|
75
103
|
* @returns {void}
|
|
76
104
|
*/
|
|
77
105
|
/**
|
|
78
|
-
*
|
|
106
|
+
* Private sentinel returned by IGNORE().
|
|
107
|
+
*
|
|
108
|
+
* @typedef {symbol} IgnoreToken
|
|
109
|
+
*/
|
|
110
|
+
/**
|
|
111
|
+
* Call and return the result to drop the current key or entire branch.
|
|
112
|
+
*
|
|
113
|
+
* @callback IgnoreFunction
|
|
114
|
+
* @returns {IgnoreToken}
|
|
115
|
+
*/
|
|
116
|
+
/**
|
|
117
|
+
* Call with no arguments to keep the current value, or pass a replacement.
|
|
118
|
+
* Supplied replacement promises are awaited before traversal continues.
|
|
119
|
+
* Return the instruction from `objectCallback` to skip `keyCallback` on
|
|
120
|
+
* its immediate properties. Nested objects and arrays continue normally.
|
|
121
|
+
*
|
|
122
|
+
* @callback PassFunction
|
|
123
|
+
* @param {*} [value]
|
|
124
|
+
* @returns {import('./pass.js').PassInstruction}
|
|
125
|
+
*/
|
|
126
|
+
/**
|
|
127
|
+
* Stop the walk, optionally including a final value or branch.
|
|
128
|
+
* Supplied replacement promises are awaited before traversal continues.
|
|
129
|
+
*
|
|
130
|
+
* @callback FinishFunction
|
|
131
|
+
* @param {*} [value]
|
|
132
|
+
* @returns {import('./finish.js').FinishInstruction}
|
|
133
|
+
*/
|
|
134
|
+
/**
|
|
135
|
+
* Shared arguments received by `keyCallback` and `objectCallback`.
|
|
79
136
|
*
|
|
80
137
|
* @typedef {object} CallbackArgs
|
|
81
138
|
* @property {*} value - The current value being processed.
|
|
82
139
|
* @property {string} key - Property key as a string.
|
|
83
|
-
* @property {string} breadcrumbs
|
|
84
|
-
* @property {
|
|
85
|
-
* @property {
|
|
140
|
+
* @property {string} [breadcrumbs] - Slash-delimited path including the current key. Absent when `settings.breadcrumbs` is false.
|
|
141
|
+
* @property {ReadonlyArray<string>} [parentPath] - Read-only path to the parent, excluding the current key. Absent when `settings.parentPath` is false.
|
|
142
|
+
* @property {Resolve} resolve - Reading this field opts into explicit settlement with resolve(value) or reject().
|
|
143
|
+
* @property {Reject} reject - Drop the current key or branch; does not reject the walk promise.
|
|
144
|
+
* @property {FinishFunction} FINISH - Return FINISH() to omit the current value and stop, or FINISH(value) to include a final value or branch.
|
|
145
|
+
* @property {IgnoreFunction} IGNORE - Return IGNORE() from the callback to drop the current key from the result.
|
|
146
|
+
*/
|
|
147
|
+
/**
|
|
148
|
+
* @typedef {CallbackArgs & { isFinished: boolean }} KeyCallbackArgs
|
|
86
149
|
*/
|
|
87
150
|
/**
|
|
88
|
-
*
|
|
151
|
+
* @typedef {CallbackArgs & { PASS: PassFunction }} ObjectCallbackArgs
|
|
152
|
+
*/
|
|
153
|
+
/**
|
|
154
|
+
* Called once per primitive property unless its immediate parent returns
|
|
155
|
+
* `PASS()` or `PASS(value)` from `objectCallback`. Types: string, number, bigint, boolean,
|
|
89
156
|
* symbol, null, undefined, function, Date, RegExp, Map, Set, WeakMap,
|
|
90
|
-
* WeakSet, ArrayBuffer, DataView, typed arrays, DOM nodes
|
|
157
|
+
* WeakSet, ArrayBuffer, DataView, typed arrays, DOM nodes.
|
|
91
158
|
*
|
|
92
|
-
*
|
|
93
|
-
* -
|
|
94
|
-
* -
|
|
95
|
-
* -
|
|
159
|
+
* Return the new value to store, or `IGNORE()` to drop the key:
|
|
160
|
+
* - return a primitive (or a built-in like `Date`/`Map`/`Set`) → stored as-is by reference;
|
|
161
|
+
* - return a plain object or array → walk continues into it with the other callback applied to its children;
|
|
162
|
+
* - return `IGNORE()` → that key is dropped from the result;
|
|
163
|
+
* - return `FINISH()` → omit the current key and stop the entire walk;
|
|
164
|
+
* - return `FINISH(value)` → include the supplied value directly and stop, without descending into it.
|
|
165
|
+
* isFinished is true for keys in a final branch selected by objectCallback.
|
|
166
|
+
* With settings.copy false, no values are stored; returned containers
|
|
167
|
+
* still control what gets visited.
|
|
96
168
|
*
|
|
97
169
|
* @callback KeyCallback
|
|
98
|
-
* @param {
|
|
170
|
+
* @param {KeyCallbackArgs} args
|
|
99
171
|
* @param {...*} rest - Any extra arguments passed to `walk()` are forwarded to the callback.
|
|
100
|
-
* @returns {
|
|
172
|
+
* @returns {* | Promise<*>}
|
|
101
173
|
*/
|
|
102
174
|
/**
|
|
103
175
|
* Called once per object or array property, including the root.
|
|
104
|
-
* The
|
|
105
|
-
* -
|
|
106
|
-
* -
|
|
107
|
-
* -
|
|
176
|
+
* The returned value becomes the new value at that key:
|
|
177
|
+
* - return an object or array → walk continues into it with the other callbacks;
|
|
178
|
+
* - return a primitive → passed to `keyCallback` when active, otherwise stored as-is;
|
|
179
|
+
* - return `IGNORE()` → the key is dropped from the result.
|
|
180
|
+
* - return `PASS()` → keep the current object/array without its immediate key callbacks; nested callbacks continue normally.
|
|
181
|
+
* - return `PASS(value)` → use the replacement with the same rule; simple replacements are stored directly.
|
|
182
|
+
* - return `FINISH()` → omit the branch and stop the entire walk.
|
|
183
|
+
* - return `FINISH(value)` → process only the final branch with keyCallback and isFinished true, suppressing later object callbacks; without keyCallback, include it directly.
|
|
184
|
+
* With settings.copy false, returned values control traversal without
|
|
185
|
+
* being stored in a result or assigned to the source.
|
|
108
186
|
*
|
|
109
187
|
* @callback ObjectCallback
|
|
110
|
-
* @param {
|
|
188
|
+
* @param {ObjectCallbackArgs} args
|
|
111
189
|
* @param {...*} rest
|
|
112
|
-
* @returns {
|
|
190
|
+
* @returns {* | Promise<*>}
|
|
191
|
+
*/
|
|
192
|
+
/**
|
|
193
|
+
* @typedef {object} Settings
|
|
194
|
+
* @property {boolean} [copy] - Defaults to true. Only false disables result creation; callbacks still run and walk resolves undefined.
|
|
195
|
+
* @property {boolean} [breadcrumbs] - Defaults to true. Only false disables breadcrumbs preparation.
|
|
196
|
+
* @property {boolean} [parentPath] - Defaults to true. Only false disables parent-path preparation.
|
|
197
|
+
* @property {boolean} [detectCycles] - Defaults to true. Only false disables circular-reference checks and their bookkeeping; visited data and replacements must then be acyclic or callbacks must prune cyclic branches.
|
|
113
198
|
*/
|
|
114
199
|
/**
|
|
115
200
|
* @typedef {object} Options
|
|
116
|
-
* @property {*} data - Required. Any JS data structure that will be
|
|
201
|
+
* @property {*} data - Required. Any JS data structure that will be walked.
|
|
117
202
|
* @property {KeyCallback} [keyCallback] - Optional. Executed on each primitive property.
|
|
118
203
|
* @property {ObjectCallback} [objectCallback] - Optional. Executed on each object/array property, including the root.
|
|
119
|
-
* @property {number} [timeout]
|
|
204
|
+
* @property {number} [timeout] - Optional milliseconds. Reject the walk with pending-callback diagnostics when time expires.
|
|
205
|
+
* @property {Settings} [settings] - Optional. Disable copying, unused callback metadata, or cycle detection with false.
|
|
120
206
|
*/
|
|
121
207
|
/**
|
|
122
208
|
* Walk-async
|
|
123
209
|
*
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
* The deep copy of the original data is mostly a side-effect: the real
|
|
130
|
-
* power is the ability to do all your modifications in one pass, with full
|
|
131
|
-
* freedom inside a single callback — now with async work, awaits, and
|
|
132
|
-
* timeouts supported.
|
|
210
|
+
* Walks through a deep JavaScript data structure, building a copy by default.
|
|
211
|
+
* Two optional callbacks can mask, filter, substitute, or collect values.
|
|
212
|
+
* Callback results are awaited in traversal order; thrown errors and rejected promises reject the walk.
|
|
213
|
+
* Set settings.copy to false to walk without building a result.
|
|
214
|
+
* By default, circular references point to the ancestor copy without visiting its contents again.
|
|
133
215
|
*
|
|
134
216
|
* @function walk
|
|
135
|
-
* @param {Options} options - Required. Object with
|
|
217
|
+
* @param {Options} options - Required. Object with `data`, optional callbacks, and optional `settings`.
|
|
136
218
|
* @param {...*} args - Optional. Additional arguments forwarded to both callbacks.
|
|
137
|
-
* @returns {Promise<*>} -
|
|
219
|
+
* @returns {Promise<*>} - Resolves to the created result, or undefined when settings.copy is false.
|
|
138
220
|
* @example
|
|
139
|
-
*
|
|
221
|
+
* let result = await walk ({
|
|
140
222
|
* data: someData,
|
|
141
223
|
* keyCallback: keyCallbackFn,
|
|
142
224
|
* objectCallback: objectCallbackFn
|
|
143
225
|
* })
|
|
226
|
+
*
|
|
227
|
+
* // Note: objectCallback is executed before keyCallback.
|
|
228
|
+
* // If you modify an object with objectCallback, keyCallback will be
|
|
229
|
+
* // executed on the result of objectCallback.
|
|
144
230
|
*/
|
|
145
|
-
declare function walk(
|
|
231
|
+
declare function walk(options: Options, ...args: any[]): Promise<any>;
|
|
146
232
|
export default walk;
|
|
147
233
|
//# sourceMappingURL=main.d.ts.map
|
package/types/main.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.js"],"names":[],"mappings":"
|
|
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"}
|
package/types/pass.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export type PassInstruction = {
|
|
2
|
+
value: any;
|
|
3
|
+
hasValue: boolean;
|
|
4
|
+
};
|
|
5
|
+
/**
|
|
6
|
+
* Private instruction created by the PASS helper.
|
|
7
|
+
*
|
|
8
|
+
* @typedef {object} PassInstruction
|
|
9
|
+
* @property {*} value
|
|
10
|
+
* @property {boolean} hasValue
|
|
11
|
+
*/
|
|
12
|
+
/**
|
|
13
|
+
* Use the current value, or a supplied replacement, without its
|
|
14
|
+
* immediate key callbacks. Nested object callbacks continue normally.
|
|
15
|
+
*
|
|
16
|
+
* @param {*} [value] - Replacement value. Omit to keep the current value.
|
|
17
|
+
* @returns {PassInstruction}
|
|
18
|
+
*/
|
|
19
|
+
declare function PASS(value?: any): PassInstruction;
|
|
20
|
+
declare function isPass(value: any): boolean;
|
|
21
|
+
export { isPass };
|
|
22
|
+
export default PASS;
|
|
23
|
+
//# sourceMappingURL=pass.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pass.d.ts","sourceRoot":"","sources":["../src/pass.js"],"names":[],"mappings":"AAQI,YAAkB,eAAe,GACjC;IAAc,KAAK,EAAR,GAAC,CACZ;IAAoB,QAAQ,EAAjB,OAAO,CACrB;CAAA,CAAA;AAND;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,iBAAS,IAAI,CAAG,KAAK,AAHjB,CACA,EADQ,GAGS,GAFP,eAAe,CAM5B;AAID,iBAAS,MAAM,CAAG,KAAK,KAAA,WAEtB;AAID,OAAO,EAAE,MAAM,EAAE,CAAA;eACF,IAAI"}
|
|
@@ -0,0 +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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"setKey.d.ts","sourceRoot":"","sources":["../src/setKey.js"],"names":[],"mappings":"AAEA,iBAAS,MAAM,CAAG,MAAM,KAAA,EAAE,CAAC,KAAA,EAAE,KAAK,KAAA,QAGjC;eAIc,MAAM"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validateForInsertion.d.ts","sourceRoot":"","sources":["../src/validateForInsertion.js"],"names":[],"mappings":"AAAA,iBAAS,oBAAoB,CAAG,CAAC,KAAA,EAAE,MAAM,KAAA,WAKxC;eAIc,oBAAoB"}
|