@handy-common-utils/promise-utils 1.7.0 → 1.7.2
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/README.md +1050 -475
- package/dist/promise-utils.d.ts +57 -24
- package/dist/promise-utils.d.ts.map +1 -1
- package/dist/promise-utils.js +98 -36
- package/dist/promise-utils.js.map +1 -0
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -110,242 +110,258 @@ await PromiseUtils.synchronized('my-lock', async () => {
|
|
|
110
110
|
|
|
111
111
|
## @handy-common-utils/promise-utils
|
|
112
112
|
|
|
113
|
-
###
|
|
113
|
+
### Classes
|
|
114
114
|
|
|
115
|
-
|
|
115
|
+
| Class | Description |
|
|
116
|
+
| ------ | ------ |
|
|
117
|
+
| [PromiseUtils](#classespromiseutilsmd) | - |
|
|
116
118
|
|
|
117
|
-
###
|
|
119
|
+
### Type Aliases
|
|
118
120
|
|
|
119
|
-
|
|
121
|
+
| Type Alias | Description |
|
|
122
|
+
| ------ | ------ |
|
|
123
|
+
| [PromiseStateType](#type-aliasespromisestatetypemd) | - |
|
|
120
124
|
|
|
121
125
|
### Variables
|
|
122
126
|
|
|
123
|
-
|
|
127
|
+
| Variable | Description |
|
|
128
|
+
| ------ | ------ |
|
|
129
|
+
| [cancellableDelayedReject](#variablescancellabledelayedrejectmd) | Creates a cancellable timer that will reject after a specified number of milliseconds. |
|
|
130
|
+
| [cancellableDelayedResolve](#variablescancellabledelayedresolvemd) | Creates a cancellable timer that will resolve after a specified number of milliseconds. |
|
|
131
|
+
| [delayedReject](#variablesdelayedrejectmd) | Creates a Promise that rejects after a specified number of milliseconds. |
|
|
132
|
+
| [delayedResolve](#variablesdelayedresolvemd) | Creates a Promise that resolves after a specified number of milliseconds. |
|
|
133
|
+
| [EXPONENTIAL\_SEQUENCE](#variablesexponential_sequencemd) | Array of 25 exponential numbers starting from 1 up to 33554432. It can be used to form your own backoff interval array. |
|
|
134
|
+
| [FIBONACCI\_SEQUENCE](#variablesfibonacci_sequencemd) | Array of 25 Fibonacci numbers starting from 1 up to 317811. It can be used to form your own backoff interval array. |
|
|
135
|
+
| [inParallel](#variablesinparallelmd) | Executes multiple jobs/operations in parallel. By default, all operations are executed regardless of any failures. In most cases, using withConcurrency might be more convenient. |
|
|
136
|
+
| [promiseState](#variablespromisestatemd) | Retrieves the state of the specified Promise. Note: The returned value is a Promise that resolves immediately. |
|
|
137
|
+
| [PromiseState](#variablespromisestate-1md) | The state of a Promise can only be one of: Pending, Fulfilled, and Rejected. |
|
|
138
|
+
| [repeat](#variablesrepeatmd) | Executes an operation repeatedly and collects all the results. This function is very useful for many scenarios, such like client-side pagination. |
|
|
139
|
+
| [runPeriodically](#variablesrunperiodicallymd) | Runs an operation periodically with configurable intervals and stopping conditions. |
|
|
140
|
+
| [synchronised](#variablessynchronisedmd) | This is just another spelling of synchronized. |
|
|
141
|
+
| [synchronized](#variablessynchronizedmd) | Provides mutual exclusion similar to synchronized in Java. Ensures no concurrent execution of any operation function associated with the same lock. The operation function has access to the state (when synchronized is called), settledState (when the operation function is called), and result (either the fulfilled result or the rejected reason) of the previous operation. If there is no previous invocation, state, settledState, and result will all be undefined. |
|
|
142
|
+
| [timeoutReject](#variablestimeoutrejectmd) | Applies a timeout to a Promise or a function that returns a Promise. If the timeout occurs, the returned Promise rejects with the specified reason. If the timeout does not occur, the returned Promise resolves or rejects based on the outcome of the original Promise. If the rejectReason parameter is a function and the timeout does not occur, the function will not be called. Note: The rejection of the operation parameter is not handled by this function. You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously." |
|
|
143
|
+
| [timeoutResolve](#variablestimeoutresolvemd) | Applies a timeout to a Promise or a function that returns a Promise. If the timeout occurs, the returned Promise resolves to the specified result. If the timeout does not occur, the returned Promise resolves or rejects based on the outcome of the original Promise. If the result parameter is a function and the timeout does not occur, the function will not be called. Note: The rejection of the operation parameter is not handled by this function. You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously." |
|
|
144
|
+
| [withConcurrency](#variableswithconcurrencymd) | Executes multiple jobs/operations with a specified level of concurrency. |
|
|
145
|
+
| [withRetry](#variableswithretrymd) | Repeatedly performs an operation until a specified criteria is met. |
|
|
124
146
|
|
|
125
|
-
|
|
147
|
+
## Classes
|
|
126
148
|
|
|
127
|
-
Array of 25 exponential numbers starting from 1 up to 33554432.
|
|
128
|
-
It can be used to form your own backoff interval array.
|
|
129
149
|
|
|
130
|
-
|
|
150
|
+
<a id="classespromiseutilsmd"></a>
|
|
131
151
|
|
|
132
|
-
|
|
133
|
-
// 1ms, 2ms, 4ms, 8ms, 16ms, 32ms
|
|
134
|
-
PromiseUtils.withRetry(() => doSomething(), EXPONENTIAL_SEQUENCE.slice(0, 5), err => err.statusCode === 429);
|
|
135
|
-
// 1s, 2s, 4s, 8s, 10s, 10s, 10s, 10s, 10s, 10s
|
|
136
|
-
PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(EXPONENTIAL_SEQUENCE[i], 10)), err => err.statusCode === 429);
|
|
137
|
-
// with +-10% randomness: 1s, 2s, 4s, 8s
|
|
138
|
-
PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 4).map(n => 1000 * n * (1 + (Math.random() - 0.5) / 5)), err => err.statusCode === 429);
|
|
139
|
-
```
|
|
152
|
+
### Abstract Class: PromiseUtils
|
|
140
153
|
|
|
141
|
-
|
|
154
|
+
#### Constructors
|
|
142
155
|
|
|
143
|
-
|
|
156
|
+
<a id="api-constructor"></a>
|
|
144
157
|
|
|
145
|
-
|
|
158
|
+
##### Constructor
|
|
146
159
|
|
|
147
|
-
|
|
148
|
-
It can be used to form your own backoff interval array.
|
|
160
|
+
> **new PromiseUtils**(): `PromiseUtils`
|
|
149
161
|
|
|
150
|
-
|
|
162
|
+
###### Returns
|
|
151
163
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
// 1s, 2s, 3s, 4s, 8s, 10s, 10s, 10s, 10s, 10s
|
|
156
|
-
PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(FIBONACCI_SEQUENCE[i], 10)), err => err.statusCode === 429);
|
|
157
|
-
// with +-10% randomness: 1s, 2s, 3s, 5s, 8s, 13s
|
|
158
|
-
PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 5).map(n => 1000 * n * (1 + (Math.random() - 0.5) / 5)), err => err.statusCode === 429);
|
|
159
|
-
```
|
|
164
|
+
`PromiseUtils`
|
|
165
|
+
|
|
166
|
+
#### Methods
|
|
160
167
|
|
|
161
|
-
|
|
168
|
+
<a id="api-cancellabledelayedreject"></a>
|
|
162
169
|
|
|
163
|
-
|
|
170
|
+
##### cancellableDelayedReject()
|
|
164
171
|
|
|
165
|
-
|
|
172
|
+
> `static` **cancellableDelayedReject**\<`T`, `R`\>(`ms`, `reason`): `object`
|
|
166
173
|
|
|
167
174
|
Creates a cancellable timer that will reject after a specified number of milliseconds.
|
|
168
175
|
|
|
169
176
|
The returned object contains:
|
|
170
|
-
- stop() to cancel the scheduled rejection (if called before the timer fires). Calling
|
|
171
|
-
stop() prevents the promise from being settled by this timer.
|
|
172
|
-
- promise which will reject with the supplied reason (or the value returned by the
|
|
173
|
-
reason function) after ms milliseconds unless stop() is called first.
|
|
177
|
+
- `stop()` to cancel the scheduled rejection (if called before the timer fires). Calling
|
|
178
|
+
`stop()` prevents the promise from being settled by this timer.
|
|
179
|
+
- `promise` which will reject with the supplied `reason` (or the value returned by the
|
|
180
|
+
`reason` function) after `ms` milliseconds unless `stop()` is called first.
|
|
174
181
|
|
|
175
|
-
If the reason is a PromiseLike that rejects, its rejection value will be used as the rejection reason.
|
|
182
|
+
If the `reason` is a PromiseLike that rejects, its rejection value will be used as the rejection reason.
|
|
176
183
|
|
|
177
|
-
|
|
184
|
+
###### Type Parameters
|
|
178
185
|
|
|
179
|
-
|
|
|
180
|
-
|
|
|
186
|
+
| Type Parameter | Default type |
|
|
187
|
+
| ------ | ------ |
|
|
181
188
|
| `T` | `never` |
|
|
182
189
|
| `R` | `any` |
|
|
183
190
|
|
|
184
|
-
|
|
191
|
+
###### Parameters
|
|
185
192
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
193
|
+
| Parameter | Type | Description |
|
|
194
|
+
| ------ | ------ | ------ |
|
|
188
195
|
| `ms` | `number` | The number of milliseconds after which the scheduled rejection will occur. |
|
|
189
|
-
| `reason` | `R` \| `PromiseLike`\<`R`\> \| () => `R` \| `PromiseLike`\<`R`\> | The reason for the rejection, or a function that supplies the reason. |
|
|
196
|
+
| `reason` | `R` \| `PromiseLike`\<`R`\> \| (() => `R` \| `PromiseLike`\<`R`\>) | The reason for the rejection, or a function that supplies the reason. |
|
|
190
197
|
|
|
191
|
-
|
|
198
|
+
###### Returns
|
|
192
199
|
|
|
193
|
-
`
|
|
200
|
+
`object`
|
|
194
201
|
|
|
195
|
-
An object with stop() and promise
|
|
202
|
+
An object with `stop()` and `promise`.
|
|
196
203
|
|
|
197
204
|
| Name | Type |
|
|
198
|
-
|
|
|
205
|
+
| ------ | ------ |
|
|
199
206
|
| `promise` | `Promise`\<`T`\> |
|
|
200
|
-
| `stop` | () => `void` |
|
|
207
|
+
| `stop()` | () => `void` |
|
|
201
208
|
|
|
202
|
-
|
|
209
|
+
***
|
|
203
210
|
|
|
204
|
-
|
|
211
|
+
<a id="api-cancellabledelayedresolve"></a>
|
|
205
212
|
|
|
206
|
-
|
|
213
|
+
##### cancellableDelayedResolve()
|
|
214
|
+
|
|
215
|
+
> `static` **cancellableDelayedResolve**\<`T`\>(`ms`, `result?`): `object`
|
|
207
216
|
|
|
208
217
|
Creates a cancellable timer that will resolve after a specified number of milliseconds.
|
|
209
218
|
|
|
210
219
|
The returned object contains:
|
|
211
|
-
- stop() to cancel the scheduled resolution (if called before the timer fires). Calling
|
|
212
|
-
stop() prevents the promise from being settled by this timer.
|
|
213
|
-
- promise which will resolve with the supplied result (or the value returned by the
|
|
214
|
-
result function) after ms milliseconds unless stop() is called first.
|
|
220
|
+
- `stop()` to cancel the scheduled resolution (if called before the timer fires). Calling
|
|
221
|
+
`stop()` prevents the promise from being settled by this timer.
|
|
222
|
+
- `promise` which will resolve with the supplied `result` (or the value returned by the
|
|
223
|
+
`result` function) after `ms` milliseconds unless `stop()` is called first.
|
|
215
224
|
|
|
216
|
-
If the result is a
|
|
225
|
+
Note: If the `result` is a function that returns a Promise, the returned `promise` will
|
|
226
|
+
resolve with that Promise's resolution (i.e. it behaves like resolving with a PromiseLike).
|
|
217
227
|
|
|
218
|
-
|
|
228
|
+
###### Type Parameters
|
|
219
229
|
|
|
220
|
-
|
|
|
221
|
-
|
|
|
230
|
+
| Type Parameter |
|
|
231
|
+
| ------ |
|
|
222
232
|
| `T` |
|
|
223
233
|
|
|
224
|
-
|
|
234
|
+
###### Parameters
|
|
225
235
|
|
|
226
|
-
|
|
|
227
|
-
|
|
|
236
|
+
| Parameter | Type | Description |
|
|
237
|
+
| ------ | ------ | ------ |
|
|
228
238
|
| `ms` | `number` | The number of milliseconds after which the scheduled resolution will occur. |
|
|
229
|
-
| `result?` | `T` \| `PromiseLike`\<`T`\> \| () => `T` \| `PromiseLike`\<`T`\> | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
239
|
+
| `result?` | `T` \| `PromiseLike`\<`T`\> \| (() => `T` \| `PromiseLike`\<`T`\>) | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
230
240
|
|
|
231
|
-
|
|
241
|
+
###### Returns
|
|
232
242
|
|
|
233
|
-
`
|
|
243
|
+
`object`
|
|
234
244
|
|
|
235
|
-
An object with stop() and promise
|
|
245
|
+
An object with `stop()` and `promise`.
|
|
236
246
|
|
|
237
247
|
| Name | Type |
|
|
238
|
-
|
|
|
248
|
+
| ------ | ------ |
|
|
239
249
|
| `promise` | `Promise`\<`T`\> |
|
|
240
|
-
| `stop` | () => `void` |
|
|
250
|
+
| `stop()` | () => `void` |
|
|
241
251
|
|
|
242
|
-
|
|
252
|
+
***
|
|
243
253
|
|
|
244
|
-
|
|
254
|
+
<a id="api-delayedreject"></a>
|
|
245
255
|
|
|
246
|
-
|
|
256
|
+
##### delayedReject()
|
|
257
|
+
|
|
258
|
+
> `static` **delayedReject**\<`T`, `R`\>(`ms`, `reason`): `Promise`\<`T`\>
|
|
247
259
|
|
|
248
260
|
Creates a Promise that rejects after a specified number of milliseconds.
|
|
249
261
|
|
|
250
|
-
The reason argument may be:
|
|
262
|
+
The `reason` argument may be:
|
|
251
263
|
- a value to reject with,
|
|
252
264
|
- a PromiseLike whose rejection will be adopted by the returned Promise, or
|
|
253
265
|
- a function which is invoked when the timer fires and may return a value or a PromiseLike.
|
|
254
266
|
|
|
255
|
-
If reason is a function, it is called when the timer elapses; if it returns a Promise,
|
|
267
|
+
If `reason` is a function, it is called when the timer elapses; if it returns a Promise,
|
|
256
268
|
the returned Promise will reject with that Promise's rejection reason (or reject with the
|
|
257
269
|
returned value if it resolves).
|
|
258
270
|
|
|
259
|
-
|
|
271
|
+
###### Type Parameters
|
|
260
272
|
|
|
261
|
-
|
|
|
262
|
-
|
|
|
273
|
+
| Type Parameter | Default type |
|
|
274
|
+
| ------ | ------ |
|
|
263
275
|
| `T` | `never` |
|
|
264
276
|
| `R` | `any` |
|
|
265
277
|
|
|
266
|
-
|
|
278
|
+
###### Parameters
|
|
267
279
|
|
|
268
|
-
|
|
|
269
|
-
|
|
|
280
|
+
| Parameter | Type | Description |
|
|
281
|
+
| ------ | ------ | ------ |
|
|
270
282
|
| `ms` | `number` | The number of milliseconds after which the created Promise will reject. |
|
|
271
|
-
| `reason` | `R` \| `PromiseLike`\<`R`\> \| () => `R` \| `PromiseLike`\<`R`\> | The reason for the rejection, or a function that supplies the reason. |
|
|
283
|
+
| `reason` | `R` \| `PromiseLike`\<`R`\> \| (() => `R` \| `PromiseLike`\<`R`\>) | The reason for the rejection, or a function that supplies the reason. |
|
|
272
284
|
|
|
273
|
-
|
|
285
|
+
###### Returns
|
|
274
286
|
|
|
275
287
|
`Promise`\<`T`\>
|
|
276
288
|
|
|
277
289
|
A Promise that rejects with the specified reason after the specified delay.
|
|
278
290
|
|
|
279
|
-
|
|
291
|
+
***
|
|
280
292
|
|
|
281
|
-
|
|
293
|
+
<a id="api-delayedresolve"></a>
|
|
282
294
|
|
|
283
|
-
|
|
295
|
+
##### delayedResolve()
|
|
296
|
+
|
|
297
|
+
> `static` **delayedResolve**\<`T`\>(`ms`, `result?`): `Promise`\<`T`\>
|
|
284
298
|
|
|
285
299
|
Creates a Promise that resolves after a specified number of milliseconds.
|
|
286
300
|
|
|
287
|
-
The result argument may be:
|
|
301
|
+
The `result` argument may be:
|
|
288
302
|
- a value to resolve with,
|
|
289
303
|
- a PromiseLike whose resolution will be adopted by the returned Promise, or
|
|
290
304
|
- a function which is invoked when the timer fires and may return a value or a PromiseLike.
|
|
291
305
|
|
|
292
|
-
If result is a function, it is called when the timer elapses; if it returns a Promise,
|
|
306
|
+
If `result` is a function, it is called when the timer elapses; if it returns a Promise,
|
|
293
307
|
the returned Promise will adopt that Promise's outcome.
|
|
294
308
|
|
|
295
|
-
|
|
309
|
+
###### Type Parameters
|
|
296
310
|
|
|
297
|
-
|
|
|
298
|
-
|
|
|
311
|
+
| Type Parameter |
|
|
312
|
+
| ------ |
|
|
299
313
|
| `T` |
|
|
300
314
|
|
|
301
|
-
|
|
315
|
+
###### Parameters
|
|
302
316
|
|
|
303
|
-
|
|
|
304
|
-
|
|
|
317
|
+
| Parameter | Type | Description |
|
|
318
|
+
| ------ | ------ | ------ |
|
|
305
319
|
| `ms` | `number` | The number of milliseconds after which the created Promise will resolve. |
|
|
306
|
-
| `result?` | `T` \| `PromiseLike`\<`T`\> \| () => `T` \| `PromiseLike`\<`T`\> | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
320
|
+
| `result?` | `T` \| `PromiseLike`\<`T`\> \| (() => `T` \| `PromiseLike`\<`T`\>) | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
307
321
|
|
|
308
|
-
|
|
322
|
+
###### Returns
|
|
309
323
|
|
|
310
324
|
`Promise`\<`T`\>
|
|
311
325
|
|
|
312
326
|
A Promise that resolves with the specified result after the specified delay.
|
|
313
327
|
|
|
314
|
-
|
|
328
|
+
***
|
|
329
|
+
|
|
330
|
+
<a id="api-inparallel"></a>
|
|
315
331
|
|
|
316
|
-
|
|
332
|
+
##### inParallel()
|
|
317
333
|
|
|
318
|
-
|
|
334
|
+
> `static` **inParallel**\<`Data`, `Result`, `TError`\>(`parallelism`, `jobs`, `operation`, `options?`): `Promise`\<(`Result` \| `TError`)[]\>
|
|
319
335
|
|
|
320
336
|
Executes multiple jobs/operations in parallel. By default, all operations are executed regardless of any failures.
|
|
321
|
-
In most cases, using withConcurrency might be more convenient.
|
|
337
|
+
In most cases, using [PromiseUtils.withConcurrency](#api-withconcurrency) might be more convenient.
|
|
322
338
|
|
|
323
339
|
By default, this function does not throw or reject an error when any job/operation fails.
|
|
324
340
|
Errors from operations are returned alongside results in the returned array.
|
|
325
341
|
This function only resolves when all jobs/operations are settled (either resolved or rejected).
|
|
326
342
|
|
|
327
|
-
If options.abortOnError is set to true, this function throws (or rejects with) an error immediately when any job/operation fails.
|
|
328
|
-
In this mode,
|
|
343
|
+
If `options.abortOnError` is set to true, this function throws (or rejects with) an error immediately when any job/operation fails.
|
|
344
|
+
In this mode, no further operations will be started after a failure occurs.
|
|
329
345
|
|
|
330
|
-
|
|
346
|
+
###### Type Parameters
|
|
331
347
|
|
|
332
|
-
|
|
|
333
|
-
|
|
|
334
|
-
| `Data` |
|
|
335
|
-
| `Result` |
|
|
336
|
-
| `TError` | `Result` |
|
|
348
|
+
| Type Parameter | Default type | Description |
|
|
349
|
+
| ------ | ------ | ------ |
|
|
350
|
+
| `Data` | - | The type of the job data, typically an Array. |
|
|
351
|
+
| `Result` | - | The type of the return value from the operation function. |
|
|
352
|
+
| `TError` | `Result` | The type for the error that could be thrown from the operation function, defaults to `Result`. |
|
|
337
353
|
|
|
338
|
-
|
|
354
|
+
###### Parameters
|
|
339
355
|
|
|
340
|
-
|
|
|
341
|
-
|
|
|
356
|
+
| Parameter | Type | Description |
|
|
357
|
+
| ------ | ------ | ------ |
|
|
342
358
|
| `parallelism` | `number` | The number of jobs/operations to run concurrently. |
|
|
343
359
|
| `jobs` | `Iterable`\<`Data`\> | The job data to be processed. This function can safely handle an infinite or unknown number of elements. |
|
|
344
|
-
| `operation` | (`job
|
|
345
|
-
| `options?` | `
|
|
346
|
-
| `options.abortOnError
|
|
360
|
+
| `operation` | (`job`, `index`) => `Promise`\<`Result`\> | The function that processes job data asynchronously. |
|
|
361
|
+
| `options?` | \{ `abortOnError`: `boolean`; \} | Options to control the function's behavior. |
|
|
362
|
+
| `options.abortOnError?` | `boolean` | If true, the function aborts and throws an error on the first failed operation. |
|
|
347
363
|
|
|
348
|
-
|
|
364
|
+
###### Returns
|
|
349
365
|
|
|
350
366
|
`Promise`\<(`Result` \| `TError`)[]\>
|
|
351
367
|
|
|
@@ -353,380 +369,597 @@ A promise that resolves to an array containing the results of the operations.
|
|
|
353
369
|
Each element is either a fulfilled result or a rejected error/reason.
|
|
354
370
|
The results or errors in the returned array are in the same order as the corresponding elements in the jobs array.
|
|
355
371
|
|
|
356
|
-
|
|
372
|
+
###### Example
|
|
373
|
+
|
|
374
|
+
```ts
|
|
375
|
+
// Capture errors in the returned array
|
|
376
|
+
const attributesAndPossibleErrors: Array<JobResult|JobError> = await PromiseUtils.inParallel(5, topicArns, async (topicArn) => {
|
|
377
|
+
const topicAttributes = (await sns.getTopicAttributes({ TopicArn: topicArn }).promise()).Attributes!;
|
|
378
|
+
return topicAttributes;
|
|
379
|
+
});
|
|
380
|
+
|
|
381
|
+
// Abort on the first error
|
|
382
|
+
let results: Array<JobResult>;
|
|
383
|
+
try {
|
|
384
|
+
results = await PromiseUtils.inParallel(100, jobs, async (job) => processor.process(job), { abortOnError: true });
|
|
385
|
+
} catch (error) {
|
|
386
|
+
// handle the error
|
|
387
|
+
}
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
***
|
|
357
391
|
|
|
358
|
-
|
|
392
|
+
<a id="api-promisestate"></a>
|
|
359
393
|
|
|
360
|
-
|
|
394
|
+
##### promiseState()
|
|
395
|
+
|
|
396
|
+
> `static` **promiseState**(`p`): `Promise`\<`"Pending"` \| `"Fulfilled"` \| `"Rejected"`\>
|
|
361
397
|
|
|
362
398
|
Retrieves the state of the specified Promise.
|
|
363
399
|
Note: The returned value is a Promise that resolves immediately.
|
|
364
400
|
|
|
365
|
-
|
|
401
|
+
###### Parameters
|
|
366
402
|
|
|
367
|
-
|
|
|
368
|
-
|
|
|
403
|
+
| Parameter | Type | Description |
|
|
404
|
+
| ------ | ------ | ------ |
|
|
369
405
|
| `p` | `Promise`\<`any`\> | The Promise whose state is to be determined. |
|
|
370
406
|
|
|
371
|
-
|
|
407
|
+
###### Returns
|
|
372
408
|
|
|
373
|
-
`Promise
|
|
409
|
+
`Promise`\<`"Pending"` \| `"Fulfilled"` \| `"Rejected"`\>
|
|
374
410
|
|
|
375
411
|
A Promise that resolves immediately with the state of the input Promise.
|
|
376
412
|
|
|
377
|
-
|
|
413
|
+
***
|
|
414
|
+
|
|
415
|
+
<a id="api-repeat"></a>
|
|
378
416
|
|
|
379
|
-
|
|
417
|
+
##### repeat()
|
|
380
418
|
|
|
381
|
-
|
|
419
|
+
> `static` **repeat**\<`Result`, `Param`, `Collection`\>(`operation`, `nextParameter`, `collect`, `initialCollection`, `initialParameter?`): `Promise`\<`Collection`\>
|
|
382
420
|
|
|
383
421
|
Executes an operation repeatedly and collects all the results.
|
|
384
422
|
This function is very useful for many scenarios, such like client-side pagination.
|
|
385
423
|
|
|
386
|
-
|
|
424
|
+
###### Type Parameters
|
|
387
425
|
|
|
388
|
-
|
|
|
389
|
-
|
|
|
390
|
-
| `Result` |
|
|
391
|
-
| `Param` |
|
|
392
|
-
| `Collection` |
|
|
426
|
+
| Type Parameter | Description |
|
|
427
|
+
| ------ | ------ |
|
|
428
|
+
| `Result` | The type of the operation result. |
|
|
429
|
+
| `Param` | The type of the input to the operation, typically a paging parameter. |
|
|
430
|
+
| `Collection` | The type of the collection returned by this function. |
|
|
393
431
|
|
|
394
|
-
|
|
432
|
+
###### Parameters
|
|
395
433
|
|
|
396
|
-
|
|
|
397
|
-
|
|
|
398
|
-
| `operation` | (`parameter
|
|
399
|
-
| `nextParameter` | (`response
|
|
400
|
-
| `collect` | (`collection
|
|
434
|
+
| Parameter | Type | Description |
|
|
435
|
+
| ------ | ------ | ------ |
|
|
436
|
+
| `operation` | (`parameter`) => `Promise`\<`Result`\> | A function that takes a parameter as input and returns a result. Typically, the parameter has optional fields to control paging. |
|
|
437
|
+
| `nextParameter` | (`response`) => `Partial`\<`Param`\> \| `Promise`\<`Partial`\<`Param`\>\> \| `null` | A function for calculating the next parameter from the operation result. Normally, this parameter controls paging. This function should return null when no further invocation of the operation function is desired. If further invocation is desired, the return value of this function can be a Promise or a non-Promise value. |
|
|
438
|
+
| `collect` | (`collection`, `result`) => `Collection` | A function for merging the operation result into the collection. |
|
|
401
439
|
| `initialCollection` | `Collection` | The initial collection, which will be the first argument passed to the first invocation of the collect function. |
|
|
402
440
|
| `initialParameter` | `Partial`\<`Param`\> | The parameter for the first operation. |
|
|
403
441
|
|
|
404
|
-
|
|
442
|
+
###### Returns
|
|
405
443
|
|
|
406
444
|
`Promise`\<`Collection`\>
|
|
407
445
|
|
|
408
446
|
A promise that resolves to a collection of all the results returned by the operation function.
|
|
409
447
|
|
|
410
|
-
|
|
448
|
+
###### Example
|
|
449
|
+
|
|
450
|
+
```ts
|
|
451
|
+
const domainNameObjects = await PromiseUtils.repeat(
|
|
452
|
+
pagingParam => apig.getDomainNames({limit: 500, ...pagingParam}).promise(),
|
|
453
|
+
response => response.position? {position: response.position} : null,
|
|
454
|
+
(collection, response) => collection.concat(response.items!),
|
|
455
|
+
[] as APIGateway.DomainName[],
|
|
456
|
+
);
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
***
|
|
460
|
+
|
|
461
|
+
<a id="api-runperiodically"></a>
|
|
411
462
|
|
|
412
|
-
|
|
463
|
+
##### runPeriodically()
|
|
413
464
|
|
|
414
|
-
|
|
465
|
+
> `static` **runPeriodically**\<`T`\>(`operation`, `interval`, `options?`): `object`
|
|
415
466
|
|
|
416
467
|
Runs an operation periodically with configurable intervals and stopping conditions.
|
|
417
468
|
|
|
418
|
-
|
|
469
|
+
- `interval` may be a single number (ms), an array of numbers, or a function
|
|
470
|
+
that receives the iteration number (starting at 1) and returns the next
|
|
471
|
+
interval in milliseconds or `undefined` to stop.
|
|
472
|
+
- If the interval array runs out of elements or the function returns `undefined`
|
|
473
|
+
(or a negative value), no further invocations will be scheduled.
|
|
419
474
|
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
475
|
+
Options:
|
|
476
|
+
- `maxExecutions` stop after N runs (inclusive).
|
|
477
|
+
- `maxDurationMs` stop after elapsed ms since the first scheduled start.
|
|
478
|
+
- `schedule` controls how the interval is measured:
|
|
479
|
+
- `'delayAfterEnd'`: wait the interval after the previous operation completes
|
|
480
|
+
before scheduling the next one (equivalent to a fixed delay between ends).
|
|
481
|
+
- `'delayBetweenStarts'`: keep start times on a regular schedule (interval measured
|
|
482
|
+
between the starts of successive operations).
|
|
483
|
+
The default schedule is `'delayBetweenStarts'`.
|
|
484
|
+
|
|
485
|
+
Returns an object with `stop()` to cancel further executions and `done` which
|
|
486
|
+
resolves when the periodic runner stops. If the provided `operation` throws or
|
|
487
|
+
rejects, the `done` promise will reject with that error so callers can handle it.
|
|
488
|
+
|
|
489
|
+
Note: The first invocation of `operation` is scheduled after the first interval
|
|
490
|
+
elapses (i.e. this function does NOT call `operation` immediately). If you need
|
|
491
|
+
an immediate run, invoke `operation(1)` yourself before calling `runPeriodically`.
|
|
492
|
+
|
|
493
|
+
###### Type Parameters
|
|
494
|
+
|
|
495
|
+
| Type Parameter | Description |
|
|
496
|
+
| ------ | ------ |
|
|
497
|
+
| `T` | The operation return type (ignored by the runner; used for typing). |
|
|
423
498
|
|
|
424
|
-
|
|
499
|
+
###### Parameters
|
|
425
500
|
|
|
426
|
-
|
|
|
427
|
-
|
|
|
428
|
-
| `operation` | (`iteration
|
|
429
|
-
| `interval` | `number` \| `number`[] \| (`iteration
|
|
430
|
-
| `options?` | `
|
|
431
|
-
| `options.maxDurationMs?` | `number` |
|
|
432
|
-
| `options.maxExecutions?` | `number` |
|
|
433
|
-
| `options.schedule?` |
|
|
501
|
+
| Parameter | Type | Description |
|
|
502
|
+
| ------ | ------ | ------ |
|
|
503
|
+
| `operation` | (`iteration`) => `T` \| `Promise`\<`T`\> | Function to run each iteration. Receives the iteration index (1-based). |
|
|
504
|
+
| `interval` | `number` \| `number`[] \| ((`iteration`) => `number` \| `undefined`) | Number | number[] | ((iteration: number) => number|undefined) defining waits. |
|
|
505
|
+
| `options?` | \{ `maxDurationMs?`: `number`; `maxExecutions?`: `number`; `schedule?`: `"delayAfterEnd"` \| `"delayBetweenStarts"`; \} | Optional configuration. |
|
|
506
|
+
| `options.maxDurationMs?` | `number` | Stop after N milliseconds. |
|
|
507
|
+
| `options.maxExecutions?` | `number` | Stop after N executions. |
|
|
508
|
+
| `options.schedule?` | `"delayAfterEnd"` \| `"delayBetweenStarts"` | How to measure intervals: `'delayAfterEnd'` or `'delayBetweenStarts'`. |
|
|
434
509
|
|
|
435
|
-
|
|
510
|
+
###### Returns
|
|
436
511
|
|
|
437
|
-
`
|
|
512
|
+
`object`
|
|
438
513
|
|
|
439
|
-
An object
|
|
514
|
+
An object containing `stop()` to cancel further executions and `done` Promise
|
|
515
|
+
which resolves when the periodic runner stops (or rejects if the operation errors).
|
|
440
516
|
|
|
441
517
|
| Name | Type |
|
|
442
|
-
|
|
|
518
|
+
| ------ | ------ |
|
|
443
519
|
| `done` | `Promise`\<`void`\> |
|
|
444
|
-
| `stop` | () => `void` |
|
|
520
|
+
| `stop()` | () => `void` |
|
|
445
521
|
|
|
446
|
-
|
|
522
|
+
***
|
|
447
523
|
|
|
448
|
-
|
|
524
|
+
<a id="api-synchronised"></a>
|
|
449
525
|
|
|
450
|
-
|
|
526
|
+
##### synchronised()
|
|
451
527
|
|
|
452
|
-
|
|
528
|
+
> `static` **synchronised**\<`T`\>(`lock`, `operation`): `Promise`\<`T`\>
|
|
529
|
+
|
|
530
|
+
This is just another spelling of [PromiseUtils.synchronized](#api-synchronized).
|
|
453
531
|
|
|
454
|
-
|
|
532
|
+
###### Type Parameters
|
|
455
533
|
|
|
456
|
-
|
|
|
457
|
-
|
|
|
534
|
+
| Type Parameter |
|
|
535
|
+
| ------ |
|
|
458
536
|
| `T` |
|
|
459
537
|
|
|
460
|
-
|
|
538
|
+
###### Parameters
|
|
461
539
|
|
|
462
|
-
|
|
|
463
|
-
|
|
|
464
|
-
| `lock` | `any` | The object (such as a string, a number, or this in a class) used to identify the lock. |
|
|
465
|
-
| `operation` | (`previousState
|
|
540
|
+
| Parameter | Type | Description |
|
|
541
|
+
| ------ | ------ | ------ |
|
|
542
|
+
| `lock` | `any` | The object (such as a string, a number, or `this` in a class) used to identify the lock. |
|
|
543
|
+
| `operation` | (`previousState`, `previousSettledState`, `previousResult`) => `Promise`\<`T`\> | The function that performs the computation and returns a Promise. |
|
|
466
544
|
|
|
467
|
-
|
|
545
|
+
###### Returns
|
|
468
546
|
|
|
469
547
|
`Promise`\<`T`\>
|
|
470
548
|
|
|
471
549
|
The result of the operation function.
|
|
472
550
|
|
|
473
|
-
|
|
551
|
+
***
|
|
474
552
|
|
|
475
|
-
|
|
553
|
+
<a id="api-synchronized"></a>
|
|
476
554
|
|
|
477
|
-
|
|
555
|
+
##### synchronized()
|
|
478
556
|
|
|
479
|
-
|
|
557
|
+
> `static` **synchronized**\<`T`\>(`lock`, `operation`): `Promise`\<`T`\>
|
|
558
|
+
|
|
559
|
+
Provides mutual exclusion similar to `synchronized` in Java.
|
|
480
560
|
Ensures no concurrent execution of any operation function associated with the same lock.
|
|
481
|
-
The operation function has access to the state (when synchronized is called),
|
|
561
|
+
The operation function has access to the state (when `synchronized` is called),
|
|
482
562
|
settledState (when the operation function is called),
|
|
483
563
|
and result (either the fulfilled result or the rejected reason) of the previous operation.
|
|
484
564
|
If there is no previous invocation, state, settledState, and result will all be undefined.
|
|
485
565
|
|
|
486
|
-
|
|
566
|
+
###### Type Parameters
|
|
487
567
|
|
|
488
|
-
|
|
|
489
|
-
|
|
|
568
|
+
| Type Parameter |
|
|
569
|
+
| ------ |
|
|
490
570
|
| `T` |
|
|
491
571
|
|
|
492
|
-
|
|
572
|
+
###### Parameters
|
|
493
573
|
|
|
494
|
-
|
|
|
495
|
-
|
|
|
496
|
-
| `lock` | `any` | The object (such as a string, a number, or this in a class) used to identify the lock. |
|
|
497
|
-
| `operation` | (`previousState
|
|
574
|
+
| Parameter | Type | Description |
|
|
575
|
+
| ------ | ------ | ------ |
|
|
576
|
+
| `lock` | `any` | The object (such as a string, a number, or `this` in a class) used to identify the lock. |
|
|
577
|
+
| `operation` | (`previousState`, `previousSettledState`, `previousResult`) => `Promise`\<`T`\> | The function that performs the computation and returns a Promise. |
|
|
498
578
|
|
|
499
|
-
|
|
579
|
+
###### Returns
|
|
500
580
|
|
|
501
581
|
`Promise`\<`T`\>
|
|
502
582
|
|
|
503
583
|
The result of the operation function.
|
|
504
584
|
|
|
505
|
-
|
|
585
|
+
***
|
|
586
|
+
|
|
587
|
+
<a id="api-timeoutreject"></a>
|
|
506
588
|
|
|
507
|
-
|
|
589
|
+
##### timeoutReject()
|
|
508
590
|
|
|
509
|
-
|
|
591
|
+
> `static` **timeoutReject**\<`T`, `R`\>(`operation`, `ms`, `rejectReason`): `Promise`\<`T`\>
|
|
510
592
|
|
|
511
593
|
Applies a timeout to a Promise or a function that returns a Promise.
|
|
512
594
|
If the timeout occurs, the returned Promise rejects with the specified reason.
|
|
513
595
|
If the timeout does not occur, the returned Promise resolves or rejects based on the outcome of the original Promise.
|
|
514
|
-
If the rejectReason parameter is a function and the timeout does not occur, the function will not be called.
|
|
515
|
-
Note: The rejection of the operation parameter is not handled by this function. You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously."
|
|
596
|
+
If the `rejectReason` parameter is a function and the timeout does not occur, the function will not be called.
|
|
597
|
+
Note: The rejection of the `operation` parameter is not handled by this function. You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously."
|
|
516
598
|
|
|
517
|
-
|
|
599
|
+
###### Type Parameters
|
|
518
600
|
|
|
519
|
-
|
|
|
520
|
-
|
|
|
601
|
+
| Type Parameter | Default type |
|
|
602
|
+
| ------ | ------ |
|
|
521
603
|
| `T` | `never` |
|
|
522
604
|
| `R` | `any` |
|
|
523
605
|
|
|
524
|
-
|
|
606
|
+
###### Parameters
|
|
525
607
|
|
|
526
|
-
|
|
|
527
|
-
|
|
|
528
|
-
| `operation` | `Promise`\<`T`\> \| () => `Promise`\<`T`\> | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
608
|
+
| Parameter | Type | Description |
|
|
609
|
+
| ------ | ------ | ------ |
|
|
610
|
+
| `operation` | `Promise`\<`T`\> \| (() => `Promise`\<`T`\>) | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
529
611
|
| `ms` | `number` | The number of milliseconds for the timeout. |
|
|
530
|
-
| `rejectReason` | `R` \| `PromiseLike`\<`R`\> \| () => `R` \| `PromiseLike`\<`R`\> | The reason to reject with if the timeout occurs, or a function that supplies the reason. |
|
|
612
|
+
| `rejectReason` | `R` \| `PromiseLike`\<`R`\> \| (() => `R` \| `PromiseLike`\<`R`\>) | The reason to reject with if the timeout occurs, or a function that supplies the reason. |
|
|
531
613
|
|
|
532
|
-
|
|
614
|
+
###### Returns
|
|
533
615
|
|
|
534
616
|
`Promise`\<`T`\>
|
|
535
617
|
|
|
536
618
|
A new Promise that rejects with the specified reason if the timeout occurs.
|
|
537
619
|
|
|
538
|
-
|
|
620
|
+
***
|
|
621
|
+
|
|
622
|
+
<a id="api-timeoutresolve"></a>
|
|
539
623
|
|
|
540
|
-
|
|
624
|
+
##### timeoutResolve()
|
|
541
625
|
|
|
542
|
-
|
|
626
|
+
> `static` **timeoutResolve**\<`T`\>(`operation`, `ms`, `result?`): `Promise`\<`T`\>
|
|
543
627
|
|
|
544
628
|
Applies a timeout to a Promise or a function that returns a Promise.
|
|
545
629
|
If the timeout occurs, the returned Promise resolves to the specified result.
|
|
546
630
|
If the timeout does not occur, the returned Promise resolves or rejects based on the outcome of the original Promise.
|
|
547
|
-
If the result parameter is a function and the timeout does not occur, the function will not be called.
|
|
548
|
-
Note: The rejection of the operation parameter is not handled by this function.
|
|
631
|
+
If the `result` parameter is a function and the timeout does not occur, the function will not be called.
|
|
632
|
+
Note: The rejection of the `operation` parameter is not handled by this function.
|
|
549
633
|
You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously."
|
|
550
634
|
|
|
551
|
-
|
|
635
|
+
###### Type Parameters
|
|
552
636
|
|
|
553
|
-
|
|
|
554
|
-
|
|
|
637
|
+
| Type Parameter |
|
|
638
|
+
| ------ |
|
|
555
639
|
| `T` |
|
|
556
640
|
|
|
557
|
-
|
|
641
|
+
###### Parameters
|
|
558
642
|
|
|
559
|
-
|
|
|
560
|
-
|
|
|
561
|
-
| `operation` | `Promise`\<`T`\> \| () => `Promise`\<`T`\> | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
643
|
+
| Parameter | Type | Description |
|
|
644
|
+
| ------ | ------ | ------ |
|
|
645
|
+
| `operation` | `Promise`\<`T`\> \| (() => `Promise`\<`T`\>) | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
562
646
|
| `ms` | `number` | The number of milliseconds for the timeout. |
|
|
563
|
-
| `result?` | `T` \| `PromiseLike`\<`T`\> \| () => `T` \| `PromiseLike`\<`T`\> | The result to resolve with if the timeout occurs, or a function that supplies the result. |
|
|
647
|
+
| `result?` | `T` \| `PromiseLike`\<`T`\> \| (() => `T` \| `PromiseLike`\<`T`\>) | The result to resolve with if the timeout occurs, or a function that supplies the result. |
|
|
564
648
|
|
|
565
|
-
|
|
649
|
+
###### Returns
|
|
566
650
|
|
|
567
651
|
`Promise`\<`T`\>
|
|
568
652
|
|
|
569
653
|
A new Promise that resolves to the specified result if the timeout occurs.
|
|
570
654
|
|
|
571
|
-
|
|
655
|
+
***
|
|
572
656
|
|
|
573
|
-
|
|
657
|
+
<a id="api-withconcurrency"></a>
|
|
574
658
|
|
|
575
|
-
|
|
659
|
+
##### withConcurrency()
|
|
660
|
+
|
|
661
|
+
> `static` **withConcurrency**\<`Data`, `Result`\>(`concurrency`, `jobs`, `operation`): `Promise`\<`Result`[]\>
|
|
576
662
|
|
|
577
663
|
Executes multiple jobs/operations with a specified level of concurrency.
|
|
578
664
|
|
|
579
|
-
|
|
665
|
+
Unlike `inParallel(...)`, this function may throw or reject an error when a job/operation fails.
|
|
666
|
+
When an error is thrown, the function rejects immediately, and no further operations will be started.
|
|
667
|
+
If you want all the operations to always be executed, use [PromiseUtils.inParallel](#api-inparallel) instead.
|
|
668
|
+
|
|
669
|
+
###### Type Parameters
|
|
580
670
|
|
|
581
|
-
|
|
|
582
|
-
|
|
|
583
|
-
| `Data` |
|
|
584
|
-
| `Result` |
|
|
671
|
+
| Type Parameter | Description |
|
|
672
|
+
| ------ | ------ |
|
|
673
|
+
| `Data` | The type of the job data, typically an Array. |
|
|
674
|
+
| `Result` | The type of the return value from the operation function. |
|
|
585
675
|
|
|
586
|
-
|
|
676
|
+
###### Parameters
|
|
587
677
|
|
|
588
|
-
|
|
|
589
|
-
|
|
|
678
|
+
| Parameter | Type | Description |
|
|
679
|
+
| ------ | ------ | ------ |
|
|
590
680
|
| `concurrency` | `number` | The number of jobs/operations to run concurrently. |
|
|
591
681
|
| `jobs` | `Iterable`\<`Data`\> | The job data to be processed. This function can handle an infinite or unknown number of elements safely. |
|
|
592
|
-
| `operation` | (`job
|
|
682
|
+
| `operation` | (`job`, `index`) => `Promise`\<`Result`\> | The function that processes job data asynchronously. |
|
|
593
683
|
|
|
594
|
-
|
|
684
|
+
###### Returns
|
|
595
685
|
|
|
596
686
|
`Promise`\<`Result`[]\>
|
|
597
687
|
|
|
598
688
|
A promise that resolves to an array containing the results from the operation function.
|
|
599
689
|
The results in the returned array are in the same order as the corresponding elements in the jobs array.
|
|
600
690
|
|
|
601
|
-
|
|
691
|
+
###### Example
|
|
692
|
+
|
|
693
|
+
```ts
|
|
694
|
+
// At any time, there would be no more than 5 concurrency API calls. Error would be re-thrown immediately when it occurs.
|
|
695
|
+
const attributes = await PromiseUtils.withConcurrency(5, topicArns, async (topicArn) => {
|
|
696
|
+
const topicAttributes = (await sns.getTopicAttributes({ TopicArn: topicArn }).promise()).Attributes!;
|
|
697
|
+
return topicAttributes;
|
|
698
|
+
});
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
***
|
|
602
702
|
|
|
603
|
-
|
|
703
|
+
<a id="api-withretry"></a>
|
|
604
704
|
|
|
605
|
-
|
|
705
|
+
##### withRetry()
|
|
706
|
+
|
|
707
|
+
> `static` **withRetry**\<`Result`, `TError`\>(`operation`, `backoff`, `shouldRetry?`): `Promise`\<`Result`\>
|
|
606
708
|
|
|
607
709
|
Repeatedly performs an operation until a specified criteria is met.
|
|
608
710
|
|
|
609
|
-
|
|
711
|
+
###### Type Parameters
|
|
610
712
|
|
|
611
|
-
|
|
|
612
|
-
|
|
|
613
|
-
| `Result` |
|
|
614
|
-
| `TError` | `any` |
|
|
713
|
+
| Type Parameter | Default type | Description |
|
|
714
|
+
| ------ | ------ | ------ |
|
|
715
|
+
| `Result` | - | Type of the operation result. |
|
|
716
|
+
| `TError` | `any` | Type of the possible error that could be generated by the operation. |
|
|
615
717
|
|
|
616
|
-
|
|
718
|
+
###### Parameters
|
|
617
719
|
|
|
618
|
-
|
|
|
619
|
-
|
|
|
620
|
-
| `operation` | (`attempt
|
|
621
|
-
| `backoff` | `number`[] \| (`attempt
|
|
622
|
-
| `shouldRetry` | (`previousError
|
|
720
|
+
| Parameter | Type | Description |
|
|
721
|
+
| ------ | ------ | ------ |
|
|
722
|
+
| `operation` | (`attempt`, `previousResult`, `previousError`) => `Promise`\<`Result`\> | A function that outputs a Promise result. Typically, the operation does not use its arguments. |
|
|
723
|
+
| `backoff` | `number`[] \| ((`attempt`, `previousResult`, `previousError`) => `number` \| `undefined`) | An array of retry backoff periods (in milliseconds) or a function for calculating them. If retry is desired, the specified backoff period is waited before the next call to the operation. If the array runs out of elements or the function returns `undefined` or a negative number, no further calls to the operation will be made. The `attempt` argument passed to the backoff function starts from 1, as it is called immediately after the first attempt and before the first retry. |
|
|
724
|
+
| `shouldRetry` | (`previousError`, `previousResult`, `attempt`) => `boolean` | A predicate function for deciding whether another call to the operation should occur. If this argument is not defined, a retry will occur whenever the operation rejects with an error. The `shouldRetry` function is evaluated before the `backoff`. The `attempt` argument passed to the shouldRetry function starts from 1. |
|
|
623
725
|
|
|
624
|
-
|
|
726
|
+
###### Returns
|
|
625
727
|
|
|
626
728
|
`Promise`\<`Result`\>
|
|
627
729
|
|
|
628
730
|
A promise of the operation result, potentially with retries applied.
|
|
629
731
|
|
|
630
|
-
|
|
732
|
+
###### Example
|
|
631
733
|
|
|
734
|
+
```ts
|
|
735
|
+
const result = await PromiseUtils.withRetry(() => doSomething(), [100, 200, 300, 500, 800, 1000]);
|
|
736
|
+
const result2 = await PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(FIBONACCI_SEQUENCE[i], 10), err => err.statusCode === 429);
|
|
737
|
+
const result3 = await PromiseUtils.withRetry(() => doSomething(), attempt => attempt <= 8 ? 1000 * Math.min(FIBONACCI_SEQUENCE[attempt - 1], 10) : undefined, err => err.statusCode === 429);
|
|
738
|
+
```
|
|
632
739
|
|
|
633
|
-
|
|
740
|
+
## Type Aliases
|
|
634
741
|
|
|
635
|
-
### Class: PromiseUtils
|
|
636
742
|
|
|
637
|
-
|
|
743
|
+
<a id="type-aliasespromisestatetypemd"></a>
|
|
638
744
|
|
|
639
|
-
|
|
745
|
+
### Type Alias: PromiseStateType
|
|
640
746
|
|
|
641
|
-
|
|
747
|
+
> **PromiseStateType** = keyof *typeof* [`PromiseState`](#variablespromisestate-1md)
|
|
642
748
|
|
|
643
|
-
|
|
749
|
+
## Variables
|
|
644
750
|
|
|
645
|
-
##### cancellableDelayedReject
|
|
646
751
|
|
|
647
|
-
|
|
752
|
+
<a id="variablesexponential_sequencemd"></a>
|
|
648
753
|
|
|
649
|
-
|
|
754
|
+
### Variable: EXPONENTIAL\_SEQUENCE
|
|
650
755
|
|
|
651
|
-
|
|
652
|
-
- `stop()` to cancel the scheduled rejection (if called before the timer fires). Calling
|
|
653
|
-
`stop()` prevents the promise from being settled by this timer.
|
|
654
|
-
- `promise` which will reject with the supplied `reason` (or the value returned by the
|
|
655
|
-
`reason` function) after `ms` milliseconds unless `stop()` is called first.
|
|
756
|
+
> `const` **EXPONENTIAL\_SEQUENCE**: `number`[]
|
|
656
757
|
|
|
657
|
-
|
|
758
|
+
Array of 25 exponential numbers starting from 1 up to 33554432.
|
|
759
|
+
It can be used to form your own backoff interval array.
|
|
658
760
|
|
|
659
|
-
|
|
761
|
+
#### Example
|
|
660
762
|
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
763
|
+
```ts
|
|
764
|
+
// 1ms, 2ms, 4ms, 8ms, 16ms, 32ms
|
|
765
|
+
PromiseUtils.withRetry(() => doSomething(), EXPONENTIAL_SEQUENCE.slice(0, 5), err => err.statusCode === 429);
|
|
766
|
+
// 1s, 2s, 4s, 8s, 10s, 10s, 10s, 10s, 10s, 10s
|
|
767
|
+
PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(EXPONENTIAL_SEQUENCE[i], 10)), err => err.statusCode === 429);
|
|
768
|
+
// with +-10% randomness: 1s, 2s, 4s, 8s
|
|
769
|
+
PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 4).map(n => 1000 * n * (1 + (Math.random() - 0.5) / 5)), err => err.statusCode === 429);
|
|
770
|
+
```
|
|
665
771
|
|
|
666
|
-
###### Parameters
|
|
667
772
|
|
|
668
|
-
|
|
669
|
-
| :------ | :------ | :------ |
|
|
670
|
-
| `ms` | `number` | The number of milliseconds after which the scheduled rejection will occur. |
|
|
671
|
-
| `reason` | `R` \| `PromiseLike`\<`R`\> \| () => `R` \| `PromiseLike`\<`R`\> | The reason for the rejection, or a function that supplies the reason. |
|
|
773
|
+
<a id="variablesfibonacci_sequencemd"></a>
|
|
672
774
|
|
|
673
|
-
|
|
775
|
+
### Variable: FIBONACCI\_SEQUENCE
|
|
674
776
|
|
|
675
|
-
`
|
|
777
|
+
> `const` **FIBONACCI\_SEQUENCE**: `number`[]
|
|
676
778
|
|
|
677
|
-
|
|
779
|
+
Array of 25 Fibonacci numbers starting from 1 up to 317811.
|
|
780
|
+
It can be used to form your own backoff interval array.
|
|
678
781
|
|
|
679
|
-
|
|
680
|
-
| :------ | :------ |
|
|
681
|
-
| `promise` | `Promise`\<`T`\> |
|
|
682
|
-
| `stop` | () => `void` |
|
|
782
|
+
#### Example
|
|
683
783
|
|
|
684
|
-
|
|
784
|
+
```ts
|
|
785
|
+
// 1ms, 2ms, 3ms, 5ms, 8ms, 13ms
|
|
786
|
+
PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 5), err => err.statusCode === 429);
|
|
787
|
+
// 1s, 2s, 3s, 4s, 8s, 10s, 10s, 10s, 10s, 10s
|
|
788
|
+
PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(FIBONACCI_SEQUENCE[i], 10)), err => err.statusCode === 429);
|
|
789
|
+
// with +-10% randomness: 1s, 2s, 3s, 5s, 8s, 13s
|
|
790
|
+
PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 5).map(n => 1000 * n * (1 + (Math.random() - 0.5) / 5)), err => err.statusCode === 429);
|
|
791
|
+
```
|
|
685
792
|
|
|
686
|
-
##### cancellableDelayedResolve
|
|
687
793
|
|
|
688
|
-
|
|
794
|
+
<a id="variablespromisestate-1md"></a>
|
|
689
795
|
|
|
690
|
-
|
|
796
|
+
### Variable: PromiseState
|
|
691
797
|
|
|
692
|
-
|
|
693
|
-
- `stop()` to cancel the scheduled resolution (if called before the timer fires). Calling
|
|
694
|
-
`stop()` prevents the promise from being settled by this timer.
|
|
695
|
-
- `promise` which will resolve with the supplied `result` (or the value returned by the
|
|
696
|
-
`result` function) after `ms` milliseconds unless `stop()` is called first.
|
|
798
|
+
> `const` **PromiseState**: `object`
|
|
697
799
|
|
|
698
|
-
|
|
699
|
-
resolve with that Promise's resolution (i.e. it behaves like resolving with a PromiseLike).
|
|
800
|
+
The state of a Promise can only be one of: Pending, Fulfilled, and Rejected.
|
|
700
801
|
|
|
701
|
-
|
|
802
|
+
#### Type Declaration
|
|
702
803
|
|
|
703
|
-
| Name |
|
|
704
|
-
|
|
|
705
|
-
| `
|
|
804
|
+
| Name | Type | Default value |
|
|
805
|
+
| ------ | ------ | ------ |
|
|
806
|
+
| <a id="api-property-fulfilled"></a> `Fulfilled` | `"Fulfilled"` | `'Fulfilled'` |
|
|
807
|
+
| <a id="api-property-pending"></a> `Pending` | `"Pending"` | `'Pending'` |
|
|
808
|
+
| <a id="api-property-rejected"></a> `Rejected` | `"Rejected"` | `'Rejected'` |
|
|
706
809
|
|
|
707
|
-
###### Parameters
|
|
708
810
|
|
|
709
|
-
|
|
710
|
-
| :------ | :------ | :------ |
|
|
711
|
-
| `ms` | `number` | The number of milliseconds after which the scheduled resolution will occur. |
|
|
712
|
-
| `result?` | `T` \| `PromiseLike`\<`T`\> \| () => `T` \| `PromiseLike`\<`T`\> | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
811
|
+
<a id="variablescancellabledelayedrejectmd"></a>
|
|
713
812
|
|
|
714
|
-
|
|
813
|
+
### Variable: cancellableDelayedReject
|
|
715
814
|
|
|
716
|
-
`
|
|
815
|
+
> `const` **cancellableDelayedReject**: \<`T`, `R`\>(`ms`, `reason`) => `object` = `PromiseUtils.cancellableDelayedReject`
|
|
717
816
|
|
|
718
|
-
|
|
817
|
+
Creates a cancellable timer that will reject after a specified number of milliseconds.
|
|
818
|
+
|
|
819
|
+
The returned object contains:
|
|
820
|
+
- stop() to cancel the scheduled rejection (if called before the timer fires). Calling
|
|
821
|
+
stop() prevents the promise from being settled by this timer.
|
|
822
|
+
- promise which will reject with the supplied reason (or the value returned by the
|
|
823
|
+
reason function) after ms milliseconds unless stop() is called first.
|
|
824
|
+
|
|
825
|
+
If the reason is a PromiseLike that rejects, its rejection value will be used as the rejection reason.
|
|
826
|
+
|
|
827
|
+
Creates a cancellable timer that will reject after a specified number of milliseconds.
|
|
828
|
+
|
|
829
|
+
The returned object contains:
|
|
830
|
+
- `stop()` to cancel the scheduled rejection (if called before the timer fires). Calling
|
|
831
|
+
`stop()` prevents the promise from being settled by this timer.
|
|
832
|
+
- `promise` which will reject with the supplied `reason` (or the value returned by the
|
|
833
|
+
`reason` function) after `ms` milliseconds unless `stop()` is called first.
|
|
834
|
+
|
|
835
|
+
If the `reason` is a PromiseLike that rejects, its rejection value will be used as the rejection reason.
|
|
836
|
+
|
|
837
|
+
#### Type Parameters
|
|
838
|
+
|
|
839
|
+
| Type Parameter | Default type |
|
|
840
|
+
| ------ | ------ |
|
|
841
|
+
| `T` | `never` |
|
|
842
|
+
| `R` | `any` |
|
|
843
|
+
|
|
844
|
+
#### Parameters
|
|
845
|
+
|
|
846
|
+
| Parameter | Type | Description |
|
|
847
|
+
| ------ | ------ | ------ |
|
|
848
|
+
| `ms` | `number` | The number of milliseconds after which the scheduled rejection will occur. |
|
|
849
|
+
| `reason` | `R` \| `PromiseLike`\<`R`\> \| (() => `R` \| `PromiseLike`\<`R`\>) | The reason for the rejection, or a function that supplies the reason. |
|
|
850
|
+
|
|
851
|
+
#### Returns
|
|
852
|
+
|
|
853
|
+
`object`
|
|
854
|
+
|
|
855
|
+
An object with `stop()` and `promise`.
|
|
856
|
+
|
|
857
|
+
| Name | Type |
|
|
858
|
+
| ------ | ------ |
|
|
859
|
+
| `promise` | `Promise`\<`T`\> |
|
|
860
|
+
| `stop()` | () => `void` |
|
|
861
|
+
|
|
862
|
+
#### Param
|
|
863
|
+
|
|
864
|
+
**ms**
|
|
865
|
+
|
|
866
|
+
The number of milliseconds after which the scheduled rejection will occur.
|
|
867
|
+
|
|
868
|
+
#### Param
|
|
869
|
+
|
|
870
|
+
**reason**
|
|
871
|
+
|
|
872
|
+
The reason for the rejection, or a function that supplies the reason.
|
|
873
|
+
|
|
874
|
+
#### Returns
|
|
875
|
+
|
|
876
|
+
An object with stop() and promise.
|
|
877
|
+
|
|
878
|
+
|
|
879
|
+
<a id="variablescancellabledelayedresolvemd"></a>
|
|
880
|
+
|
|
881
|
+
### Variable: cancellableDelayedResolve
|
|
882
|
+
|
|
883
|
+
> `const` **cancellableDelayedResolve**: \<`T`\>(`ms`, `result?`) => `object` = `PromiseUtils.cancellableDelayedResolve`
|
|
884
|
+
|
|
885
|
+
Creates a cancellable timer that will resolve after a specified number of milliseconds.
|
|
886
|
+
|
|
887
|
+
The returned object contains:
|
|
888
|
+
- stop() to cancel the scheduled resolution (if called before the timer fires). Calling
|
|
889
|
+
stop() prevents the promise from being settled by this timer.
|
|
890
|
+
- promise which will resolve with the supplied result (or the value returned by the
|
|
891
|
+
result function) after ms milliseconds unless stop() is called first.
|
|
892
|
+
|
|
893
|
+
If the result is a PromiseLike, its resolution value will be used as the resolved value.
|
|
894
|
+
|
|
895
|
+
Creates a cancellable timer that will resolve after a specified number of milliseconds.
|
|
896
|
+
|
|
897
|
+
The returned object contains:
|
|
898
|
+
- `stop()` to cancel the scheduled resolution (if called before the timer fires). Calling
|
|
899
|
+
`stop()` prevents the promise from being settled by this timer.
|
|
900
|
+
- `promise` which will resolve with the supplied `result` (or the value returned by the
|
|
901
|
+
`result` function) after `ms` milliseconds unless `stop()` is called first.
|
|
902
|
+
|
|
903
|
+
Note: If the `result` is a function that returns a Promise, the returned `promise` will
|
|
904
|
+
resolve with that Promise's resolution (i.e. it behaves like resolving with a PromiseLike).
|
|
905
|
+
|
|
906
|
+
#### Type Parameters
|
|
907
|
+
|
|
908
|
+
| Type Parameter |
|
|
909
|
+
| ------ |
|
|
910
|
+
| `T` |
|
|
911
|
+
|
|
912
|
+
#### Parameters
|
|
913
|
+
|
|
914
|
+
| Parameter | Type | Description |
|
|
915
|
+
| ------ | ------ | ------ |
|
|
916
|
+
| `ms` | `number` | The number of milliseconds after which the scheduled resolution will occur. |
|
|
917
|
+
| `result?` | `T` \| `PromiseLike`\<`T`\> \| (() => `T` \| `PromiseLike`\<`T`\>) | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
918
|
+
|
|
919
|
+
#### Returns
|
|
920
|
+
|
|
921
|
+
`object`
|
|
922
|
+
|
|
923
|
+
An object with `stop()` and `promise`.
|
|
719
924
|
|
|
720
925
|
| Name | Type |
|
|
721
|
-
|
|
|
926
|
+
| ------ | ------ |
|
|
722
927
|
| `promise` | `Promise`\<`T`\> |
|
|
723
|
-
| `stop` | () => `void` |
|
|
928
|
+
| `stop()` | () => `void` |
|
|
929
|
+
|
|
930
|
+
#### Param
|
|
931
|
+
|
|
932
|
+
**ms**
|
|
933
|
+
|
|
934
|
+
The number of milliseconds after which the scheduled resolution will occur.
|
|
724
935
|
|
|
725
|
-
|
|
936
|
+
#### Param
|
|
726
937
|
|
|
727
|
-
|
|
938
|
+
**result**
|
|
728
939
|
|
|
729
|
-
|
|
940
|
+
The result to be resolved by the Promise, or a function that supplies the result.
|
|
941
|
+
|
|
942
|
+
#### Returns
|
|
943
|
+
|
|
944
|
+
An object with stop() and promise.
|
|
945
|
+
|
|
946
|
+
|
|
947
|
+
<a id="variablesdelayedrejectmd"></a>
|
|
948
|
+
|
|
949
|
+
### Variable: delayedReject
|
|
950
|
+
|
|
951
|
+
> `const` **delayedReject**: \<`T`, `R`\>(`ms`, `reason`) => `Promise`\<`T`\> = `PromiseUtils.delayedReject`
|
|
952
|
+
|
|
953
|
+
Creates a Promise that rejects after a specified number of milliseconds.
|
|
954
|
+
|
|
955
|
+
The reason argument may be:
|
|
956
|
+
- a value to reject with,
|
|
957
|
+
- a PromiseLike whose rejection will be adopted by the returned Promise, or
|
|
958
|
+
- a function which is invoked when the timer fires and may return a value or a PromiseLike.
|
|
959
|
+
|
|
960
|
+
If reason is a function, it is called when the timer elapses; if it returns a Promise,
|
|
961
|
+
the returned Promise will reject with that Promise's rejection reason (or reject with the
|
|
962
|
+
returned value if it resolves).
|
|
730
963
|
|
|
731
964
|
Creates a Promise that rejects after a specified number of milliseconds.
|
|
732
965
|
|
|
@@ -739,31 +972,58 @@ If `reason` is a function, it is called when the timer elapses; if it returns a
|
|
|
739
972
|
the returned Promise will reject with that Promise's rejection reason (or reject with the
|
|
740
973
|
returned value if it resolves).
|
|
741
974
|
|
|
742
|
-
|
|
975
|
+
#### Type Parameters
|
|
743
976
|
|
|
744
|
-
|
|
|
745
|
-
|
|
|
977
|
+
| Type Parameter | Default type |
|
|
978
|
+
| ------ | ------ |
|
|
746
979
|
| `T` | `never` |
|
|
747
980
|
| `R` | `any` |
|
|
748
981
|
|
|
749
|
-
|
|
982
|
+
#### Parameters
|
|
750
983
|
|
|
751
|
-
|
|
|
752
|
-
|
|
|
984
|
+
| Parameter | Type | Description |
|
|
985
|
+
| ------ | ------ | ------ |
|
|
753
986
|
| `ms` | `number` | The number of milliseconds after which the created Promise will reject. |
|
|
754
|
-
| `reason` | `R` \| `PromiseLike`\<`R`\> \| () => `R` \| `PromiseLike`\<`R`\> | The reason for the rejection, or a function that supplies the reason. |
|
|
987
|
+
| `reason` | `R` \| `PromiseLike`\<`R`\> \| (() => `R` \| `PromiseLike`\<`R`\>) | The reason for the rejection, or a function that supplies the reason. |
|
|
755
988
|
|
|
756
|
-
|
|
989
|
+
#### Returns
|
|
757
990
|
|
|
758
991
|
`Promise`\<`T`\>
|
|
759
992
|
|
|
760
993
|
A Promise that rejects with the specified reason after the specified delay.
|
|
761
994
|
|
|
762
|
-
|
|
995
|
+
#### Param
|
|
996
|
+
|
|
997
|
+
**ms**
|
|
998
|
+
|
|
999
|
+
The number of milliseconds after which the created Promise will reject.
|
|
763
1000
|
|
|
764
|
-
|
|
1001
|
+
#### Param
|
|
765
1002
|
|
|
766
|
-
|
|
1003
|
+
**reason**
|
|
1004
|
+
|
|
1005
|
+
The reason for the rejection, or a function that supplies the reason.
|
|
1006
|
+
|
|
1007
|
+
#### Returns
|
|
1008
|
+
|
|
1009
|
+
A Promise that rejects with the specified reason after the specified delay.
|
|
1010
|
+
|
|
1011
|
+
|
|
1012
|
+
<a id="variablesdelayedresolvemd"></a>
|
|
1013
|
+
|
|
1014
|
+
### Variable: delayedResolve
|
|
1015
|
+
|
|
1016
|
+
> `const` **delayedResolve**: \<`T`\>(`ms`, `result?`) => `Promise`\<`T`\> = `PromiseUtils.delayedResolve`
|
|
1017
|
+
|
|
1018
|
+
Creates a Promise that resolves after a specified number of milliseconds.
|
|
1019
|
+
|
|
1020
|
+
The result argument may be:
|
|
1021
|
+
- a value to resolve with,
|
|
1022
|
+
- a PromiseLike whose resolution will be adopted by the returned Promise, or
|
|
1023
|
+
- a function which is invoked when the timer fires and may return a value or a PromiseLike.
|
|
1024
|
+
|
|
1025
|
+
If result is a function, it is called when the timer elapses; if it returns a Promise,
|
|
1026
|
+
the returned Promise will adopt that Promise's outcome.
|
|
767
1027
|
|
|
768
1028
|
Creates a Promise that resolves after a specified number of milliseconds.
|
|
769
1029
|
|
|
@@ -775,60 +1035,87 @@ The `result` argument may be:
|
|
|
775
1035
|
If `result` is a function, it is called when the timer elapses; if it returns a Promise,
|
|
776
1036
|
the returned Promise will adopt that Promise's outcome.
|
|
777
1037
|
|
|
778
|
-
|
|
1038
|
+
#### Type Parameters
|
|
779
1039
|
|
|
780
|
-
|
|
|
781
|
-
|
|
|
1040
|
+
| Type Parameter |
|
|
1041
|
+
| ------ |
|
|
782
1042
|
| `T` |
|
|
783
1043
|
|
|
784
|
-
|
|
1044
|
+
#### Parameters
|
|
785
1045
|
|
|
786
|
-
|
|
|
787
|
-
|
|
|
1046
|
+
| Parameter | Type | Description |
|
|
1047
|
+
| ------ | ------ | ------ |
|
|
788
1048
|
| `ms` | `number` | The number of milliseconds after which the created Promise will resolve. |
|
|
789
|
-
| `result?` | `T` \| `PromiseLike`\<`T`\> \| () => `T` \| `PromiseLike`\<`T`\> | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
1049
|
+
| `result?` | `T` \| `PromiseLike`\<`T`\> \| (() => `T` \| `PromiseLike`\<`T`\>) | The result to be resolved by the Promise, or a function that supplies the result. |
|
|
790
1050
|
|
|
791
|
-
|
|
1051
|
+
#### Returns
|
|
792
1052
|
|
|
793
1053
|
`Promise`\<`T`\>
|
|
794
1054
|
|
|
795
1055
|
A Promise that resolves with the specified result after the specified delay.
|
|
796
1056
|
|
|
797
|
-
|
|
1057
|
+
#### Param
|
|
1058
|
+
|
|
1059
|
+
**ms**
|
|
1060
|
+
|
|
1061
|
+
The number of milliseconds after which the created Promise will resolve.
|
|
1062
|
+
|
|
1063
|
+
#### Param
|
|
1064
|
+
|
|
1065
|
+
**result**
|
|
1066
|
+
|
|
1067
|
+
The result to be resolved by the Promise, or a function that supplies the result.
|
|
1068
|
+
|
|
1069
|
+
#### Returns
|
|
1070
|
+
|
|
1071
|
+
A Promise that resolves with the specified result after the specified delay.
|
|
1072
|
+
|
|
1073
|
+
|
|
1074
|
+
<a id="variablesinparallelmd"></a>
|
|
798
1075
|
|
|
799
|
-
|
|
1076
|
+
### Variable: inParallel
|
|
800
1077
|
|
|
801
|
-
|
|
1078
|
+
> `const` **inParallel**: \<`Data`, `Result`, `TError`\>(`parallelism`, `jobs`, `operation`, `options?`) => `Promise`\<(`Result` \| `TError`)[]\> = `PromiseUtils.inParallel`
|
|
802
1079
|
|
|
803
1080
|
Executes multiple jobs/operations in parallel. By default, all operations are executed regardless of any failures.
|
|
804
|
-
In most cases, using
|
|
1081
|
+
In most cases, using withConcurrency might be more convenient.
|
|
1082
|
+
|
|
1083
|
+
By default, this function does not throw or reject an error when any job/operation fails.
|
|
1084
|
+
Errors from operations are returned alongside results in the returned array.
|
|
1085
|
+
This function only resolves when all jobs/operations are settled (either resolved or rejected).
|
|
1086
|
+
|
|
1087
|
+
If options.abortOnError is set to true, this function throws (or rejects with) an error immediately when any job/operation fails.
|
|
1088
|
+
In this mode, no further operations will be started after a failure occurs.
|
|
1089
|
+
|
|
1090
|
+
Executes multiple jobs/operations in parallel. By default, all operations are executed regardless of any failures.
|
|
1091
|
+
In most cases, using [PromiseUtils.withConcurrency](#withconcurrency) might be more convenient.
|
|
805
1092
|
|
|
806
1093
|
By default, this function does not throw or reject an error when any job/operation fails.
|
|
807
1094
|
Errors from operations are returned alongside results in the returned array.
|
|
808
1095
|
This function only resolves when all jobs/operations are settled (either resolved or rejected).
|
|
809
1096
|
|
|
810
1097
|
If `options.abortOnError` is set to true, this function throws (or rejects with) an error immediately when any job/operation fails.
|
|
811
|
-
In this mode,
|
|
1098
|
+
In this mode, no further operations will be started after a failure occurs.
|
|
812
1099
|
|
|
813
|
-
|
|
1100
|
+
#### Type Parameters
|
|
814
1101
|
|
|
815
|
-
|
|
|
816
|
-
|
|
|
817
|
-
| `Data` |
|
|
818
|
-
| `Result` |
|
|
1102
|
+
| Type Parameter | Default type | Description |
|
|
1103
|
+
| ------ | ------ | ------ |
|
|
1104
|
+
| `Data` | - | The type of the job data, typically an Array. |
|
|
1105
|
+
| `Result` | - | The type of the return value from the operation function. |
|
|
819
1106
|
| `TError` | `Result` | The type for the error that could be thrown from the operation function, defaults to `Result`. |
|
|
820
1107
|
|
|
821
|
-
|
|
1108
|
+
#### Parameters
|
|
822
1109
|
|
|
823
|
-
|
|
|
824
|
-
|
|
|
1110
|
+
| Parameter | Type | Description |
|
|
1111
|
+
| ------ | ------ | ------ |
|
|
825
1112
|
| `parallelism` | `number` | The number of jobs/operations to run concurrently. |
|
|
826
1113
|
| `jobs` | `Iterable`\<`Data`\> | The job data to be processed. This function can safely handle an infinite or unknown number of elements. |
|
|
827
|
-
| `operation` | (`job
|
|
828
|
-
| `options?` | `
|
|
829
|
-
| `options.abortOnError
|
|
1114
|
+
| `operation` | (`job`, `index`) => `Promise`\<`Result`\> | The function that processes job data asynchronously. |
|
|
1115
|
+
| `options?` | \{ `abortOnError`: `boolean`; \} | Options to control the function's behavior. |
|
|
1116
|
+
| `options.abortOnError?` | `boolean` | If true, the function aborts and throws an error on the first failed operation. |
|
|
830
1117
|
|
|
831
|
-
|
|
1118
|
+
#### Returns
|
|
832
1119
|
|
|
833
1120
|
`Promise`\<(`Result` \| `TError`)[]\>
|
|
834
1121
|
|
|
@@ -836,7 +1123,7 @@ A promise that resolves to an array containing the results of the operations.
|
|
|
836
1123
|
Each element is either a fulfilled result or a rejected error/reason.
|
|
837
1124
|
The results or errors in the returned array are in the same order as the corresponding elements in the jobs array.
|
|
838
1125
|
|
|
839
|
-
|
|
1126
|
+
#### Example
|
|
840
1127
|
|
|
841
1128
|
```ts
|
|
842
1129
|
// Capture errors in the returned array
|
|
@@ -854,61 +1141,115 @@ try {
|
|
|
854
1141
|
}
|
|
855
1142
|
```
|
|
856
1143
|
|
|
857
|
-
|
|
1144
|
+
#### Param
|
|
1145
|
+
|
|
1146
|
+
**parallelism**
|
|
1147
|
+
|
|
1148
|
+
The number of jobs/operations to run concurrently.
|
|
1149
|
+
|
|
1150
|
+
#### Param
|
|
1151
|
+
|
|
1152
|
+
**jobs**
|
|
1153
|
+
|
|
1154
|
+
The job data to be processed. This function can safely handle an infinite or unknown number of elements.
|
|
1155
|
+
|
|
1156
|
+
#### Param
|
|
1157
|
+
|
|
1158
|
+
**operation**
|
|
1159
|
+
|
|
1160
|
+
The function that processes job data asynchronously.
|
|
1161
|
+
|
|
1162
|
+
#### Param
|
|
1163
|
+
|
|
1164
|
+
**options**
|
|
1165
|
+
|
|
1166
|
+
Options to control the function's behavior.
|
|
1167
|
+
|
|
1168
|
+
#### Param
|
|
1169
|
+
|
|
1170
|
+
**options.abortOnError**
|
|
1171
|
+
|
|
1172
|
+
If true, the function aborts and throws an error on the first failed operation.
|
|
858
1173
|
|
|
859
|
-
|
|
1174
|
+
#### Returns
|
|
860
1175
|
|
|
861
|
-
|
|
1176
|
+
A promise that resolves to an array containing the results of the operations.
|
|
1177
|
+
Each element is either a fulfilled result or a rejected error/reason.
|
|
1178
|
+
The results or errors in the returned array are in the same order as the corresponding elements in the jobs array.
|
|
1179
|
+
|
|
1180
|
+
|
|
1181
|
+
<a id="variablespromisestatemd"></a>
|
|
1182
|
+
|
|
1183
|
+
### Variable: promiseState
|
|
1184
|
+
|
|
1185
|
+
> `const` **promiseState**: (`p`) => `Promise`\<`"Pending"` \| `"Fulfilled"` \| `"Rejected"`\> = `PromiseUtils.promiseState`
|
|
862
1186
|
|
|
863
1187
|
Retrieves the state of the specified Promise.
|
|
864
1188
|
Note: The returned value is a Promise that resolves immediately.
|
|
865
1189
|
|
|
866
|
-
|
|
1190
|
+
Retrieves the state of the specified Promise.
|
|
1191
|
+
Note: The returned value is a Promise that resolves immediately.
|
|
1192
|
+
|
|
1193
|
+
#### Parameters
|
|
867
1194
|
|
|
868
|
-
|
|
|
869
|
-
|
|
|
1195
|
+
| Parameter | Type | Description |
|
|
1196
|
+
| ------ | ------ | ------ |
|
|
870
1197
|
| `p` | `Promise`\<`any`\> | The Promise whose state is to be determined. |
|
|
871
1198
|
|
|
872
|
-
|
|
1199
|
+
#### Returns
|
|
873
1200
|
|
|
874
|
-
`Promise
|
|
1201
|
+
`Promise`\<`"Pending"` \| `"Fulfilled"` \| `"Rejected"`\>
|
|
875
1202
|
|
|
876
1203
|
A Promise that resolves immediately with the state of the input Promise.
|
|
877
1204
|
|
|
878
|
-
|
|
1205
|
+
#### Param
|
|
1206
|
+
|
|
1207
|
+
**p**
|
|
1208
|
+
|
|
1209
|
+
The Promise whose state is to be determined.
|
|
1210
|
+
|
|
1211
|
+
#### Returns
|
|
1212
|
+
|
|
1213
|
+
A Promise that resolves immediately with the state of the input Promise.
|
|
879
1214
|
|
|
880
|
-
##### repeat
|
|
881
1215
|
|
|
882
|
-
|
|
1216
|
+
<a id="variablesrepeatmd"></a>
|
|
1217
|
+
|
|
1218
|
+
### Variable: repeat
|
|
1219
|
+
|
|
1220
|
+
> `const` **repeat**: \<`Result`, `Param`, `Collection`\>(`operation`, `nextParameter`, `collect`, `initialCollection`, `initialParameter`) => `Promise`\<`Collection`\> = `PromiseUtils.repeat`
|
|
1221
|
+
|
|
1222
|
+
Executes an operation repeatedly and collects all the results.
|
|
1223
|
+
This function is very useful for many scenarios, such like client-side pagination.
|
|
883
1224
|
|
|
884
1225
|
Executes an operation repeatedly and collects all the results.
|
|
885
1226
|
This function is very useful for many scenarios, such like client-side pagination.
|
|
886
1227
|
|
|
887
|
-
|
|
1228
|
+
#### Type Parameters
|
|
888
1229
|
|
|
889
|
-
|
|
|
890
|
-
|
|
|
1230
|
+
| Type Parameter | Description |
|
|
1231
|
+
| ------ | ------ |
|
|
891
1232
|
| `Result` | The type of the operation result. |
|
|
892
1233
|
| `Param` | The type of the input to the operation, typically a paging parameter. |
|
|
893
1234
|
| `Collection` | The type of the collection returned by this function. |
|
|
894
1235
|
|
|
895
|
-
|
|
1236
|
+
#### Parameters
|
|
896
1237
|
|
|
897
|
-
|
|
|
898
|
-
|
|
|
899
|
-
| `operation` | (`parameter
|
|
900
|
-
| `nextParameter` | (`response
|
|
901
|
-
| `collect` | (`collection
|
|
1238
|
+
| Parameter | Type | Description |
|
|
1239
|
+
| ------ | ------ | ------ |
|
|
1240
|
+
| `operation` | (`parameter`) => `Promise`\<`Result`\> | A function that takes a parameter as input and returns a result. Typically, the parameter has optional fields to control paging. |
|
|
1241
|
+
| `nextParameter` | (`response`) => `Partial`\<`Param`\> \| `Promise`\<`Partial`\<`Param`\>\> \| `null` | A function for calculating the next parameter from the operation result. Normally, this parameter controls paging. This function should return null when no further invocation of the operation function is desired. If further invocation is desired, the return value of this function can be a Promise or a non-Promise value. |
|
|
1242
|
+
| `collect` | (`collection`, `result`) => `Collection` | A function for merging the operation result into the collection. |
|
|
902
1243
|
| `initialCollection` | `Collection` | The initial collection, which will be the first argument passed to the first invocation of the collect function. |
|
|
903
1244
|
| `initialParameter` | `Partial`\<`Param`\> | The parameter for the first operation. |
|
|
904
1245
|
|
|
905
|
-
|
|
1246
|
+
#### Returns
|
|
906
1247
|
|
|
907
1248
|
`Promise`\<`Collection`\>
|
|
908
1249
|
|
|
909
1250
|
A promise that resolves to a collection of all the results returned by the operation function.
|
|
910
1251
|
|
|
911
|
-
|
|
1252
|
+
#### Example
|
|
912
1253
|
|
|
913
1254
|
```ts
|
|
914
1255
|
const domainNameObjects = await PromiseUtils.repeat(
|
|
@@ -919,11 +1260,72 @@ const domainNameObjects = await PromiseUtils.repeat(
|
|
|
919
1260
|
);
|
|
920
1261
|
```
|
|
921
1262
|
|
|
922
|
-
|
|
1263
|
+
#### Param
|
|
1264
|
+
|
|
1265
|
+
**operation**
|
|
1266
|
+
|
|
1267
|
+
A function that takes a parameter as input and returns a result. Typically, the parameter has optional fields to control paging.
|
|
1268
|
+
|
|
1269
|
+
#### Param
|
|
1270
|
+
|
|
1271
|
+
**nextParameter**
|
|
1272
|
+
|
|
1273
|
+
A function for calculating the next parameter from the operation result. Normally, this parameter controls paging. This function should return null when no further invocation of the operation function is desired. If further invocation is desired, the return value of this function can be a Promise or a non-Promise value.
|
|
1274
|
+
|
|
1275
|
+
#### Param
|
|
1276
|
+
|
|
1277
|
+
**collect**
|
|
1278
|
+
|
|
1279
|
+
A function for merging the operation result into the collection.
|
|
1280
|
+
|
|
1281
|
+
#### Param
|
|
1282
|
+
|
|
1283
|
+
**initialCollection**
|
|
923
1284
|
|
|
924
|
-
|
|
1285
|
+
The initial collection, which will be the first argument passed to the first invocation of the collect function.
|
|
925
1286
|
|
|
926
|
-
|
|
1287
|
+
#### Param
|
|
1288
|
+
|
|
1289
|
+
**initialParameter**
|
|
1290
|
+
|
|
1291
|
+
The parameter for the first operation.
|
|
1292
|
+
|
|
1293
|
+
#### Returns
|
|
1294
|
+
|
|
1295
|
+
A promise that resolves to a collection of all the results returned by the operation function.
|
|
1296
|
+
|
|
1297
|
+
|
|
1298
|
+
<a id="variablesrunperiodicallymd"></a>
|
|
1299
|
+
|
|
1300
|
+
### Variable: runPeriodically
|
|
1301
|
+
|
|
1302
|
+
> `const` **runPeriodically**: \<`T`\>(`operation`, `interval`, `options?`) => `object` = `PromiseUtils.runPeriodically`
|
|
1303
|
+
|
|
1304
|
+
Runs an operation periodically with configurable intervals and stopping conditions.
|
|
1305
|
+
|
|
1306
|
+
- `interval` may be a single number (ms), an array of numbers, or a function
|
|
1307
|
+
that receives the iteration number (starting at 1) and returns the next
|
|
1308
|
+
interval in milliseconds or `undefined` to stop.
|
|
1309
|
+
- If the interval array runs out of elements or the function returns `undefined`
|
|
1310
|
+
(or a negative value), no further invocations will be scheduled.
|
|
1311
|
+
|
|
1312
|
+
Options:
|
|
1313
|
+
- `maxExecutions` stop after N runs (inclusive).
|
|
1314
|
+
- `maxDurationMs` stop after elapsed ms since the first scheduled start.
|
|
1315
|
+
- `schedule` controls how the interval is measured:
|
|
1316
|
+
- `'delayAfterEnd'`: wait the interval after the previous operation completes
|
|
1317
|
+
before scheduling the next one (equivalent to a fixed delay between ends).
|
|
1318
|
+
- `'delayBetweenStarts'`: keep start times on a regular schedule (interval measured
|
|
1319
|
+
between the starts of successive operations).
|
|
1320
|
+
The default schedule is `'delayBetweenStarts'`.
|
|
1321
|
+
|
|
1322
|
+
Returns an object with `stop()` to cancel further executions and `done` which
|
|
1323
|
+
resolves when the periodic runner stops. If the provided `operation` throws or
|
|
1324
|
+
rejects, the `done` promise will reject with that error so callers can handle it.
|
|
1325
|
+
|
|
1326
|
+
Note: The first invocation of `operation` is scheduled after the first interval
|
|
1327
|
+
elapses (i.e. this function does NOT call `operation` immediately). If you need
|
|
1328
|
+
an immediate run, invoke `operation(1)` yourself before calling `runPeriodically`.
|
|
927
1329
|
|
|
928
1330
|
Runs an operation periodically with configurable intervals and stopping conditions.
|
|
929
1331
|
|
|
@@ -951,67 +1353,141 @@ Note: The first invocation of `operation` is scheduled after the first interval
|
|
|
951
1353
|
elapses (i.e. this function does NOT call `operation` immediately). If you need
|
|
952
1354
|
an immediate run, invoke `operation(1)` yourself before calling `runPeriodically`.
|
|
953
1355
|
|
|
954
|
-
|
|
1356
|
+
#### Type Parameters
|
|
955
1357
|
|
|
956
|
-
|
|
|
957
|
-
|
|
|
1358
|
+
| Type Parameter | Description |
|
|
1359
|
+
| ------ | ------ |
|
|
958
1360
|
| `T` | The operation return type (ignored by the runner; used for typing). |
|
|
959
1361
|
|
|
960
|
-
|
|
1362
|
+
#### Parameters
|
|
961
1363
|
|
|
962
|
-
|
|
|
963
|
-
|
|
|
964
|
-
| `operation` | (`iteration
|
|
965
|
-
| `interval` | `number` \| `number`[] \| (`iteration
|
|
966
|
-
| `options?` | `
|
|
967
|
-
| `options.maxDurationMs?` | `number` |
|
|
968
|
-
| `options.maxExecutions?` | `number` |
|
|
969
|
-
| `options.schedule?` |
|
|
1364
|
+
| Parameter | Type | Description |
|
|
1365
|
+
| ------ | ------ | ------ |
|
|
1366
|
+
| `operation` | (`iteration`) => `T` \| `Promise`\<`T`\> | Function to run each iteration. Receives the iteration index (1-based). |
|
|
1367
|
+
| `interval` | `number` \| `number`[] \| ((`iteration`) => `number` \| `undefined`) | Number | number[] | ((iteration: number) => number|undefined) defining waits. |
|
|
1368
|
+
| `options?` | \{ `maxDurationMs?`: `number`; `maxExecutions?`: `number`; `schedule?`: `"delayAfterEnd"` \| `"delayBetweenStarts"`; \} | Optional configuration. |
|
|
1369
|
+
| `options.maxDurationMs?` | `number` | Stop after N milliseconds. |
|
|
1370
|
+
| `options.maxExecutions?` | `number` | Stop after N executions. |
|
|
1371
|
+
| `options.schedule?` | `"delayAfterEnd"` \| `"delayBetweenStarts"` | How to measure intervals: `'delayAfterEnd'` or `'delayBetweenStarts'`. |
|
|
970
1372
|
|
|
971
|
-
|
|
1373
|
+
#### Returns
|
|
972
1374
|
|
|
973
|
-
`
|
|
1375
|
+
`object`
|
|
974
1376
|
|
|
975
1377
|
An object containing `stop()` to cancel further executions and `done` Promise
|
|
976
1378
|
which resolves when the periodic runner stops (or rejects if the operation errors).
|
|
977
1379
|
|
|
978
1380
|
| Name | Type |
|
|
979
|
-
|
|
|
1381
|
+
| ------ | ------ |
|
|
980
1382
|
| `done` | `Promise`\<`void`\> |
|
|
981
|
-
| `stop` | () => `void` |
|
|
1383
|
+
| `stop()` | () => `void` |
|
|
1384
|
+
|
|
1385
|
+
#### Template
|
|
1386
|
+
|
|
1387
|
+
**T**
|
|
1388
|
+
|
|
1389
|
+
The operation return type (ignored by the runner; used for typing).
|
|
1390
|
+
|
|
1391
|
+
#### Param
|
|
1392
|
+
|
|
1393
|
+
**operation**
|
|
1394
|
+
|
|
1395
|
+
Function to run each iteration. Receives the iteration index (1-based).
|
|
1396
|
+
|
|
1397
|
+
#### Param
|
|
1398
|
+
|
|
1399
|
+
**interval**
|
|
982
1400
|
|
|
983
|
-
|
|
1401
|
+
Number | number[] | ((iteration: number) => number|undefined) defining waits.
|
|
984
1402
|
|
|
985
|
-
|
|
1403
|
+
#### Param
|
|
986
1404
|
|
|
987
|
-
|
|
1405
|
+
**options**
|
|
988
1406
|
|
|
989
|
-
|
|
1407
|
+
Optional configuration.
|
|
990
1408
|
|
|
991
|
-
|
|
1409
|
+
#### Param
|
|
992
1410
|
|
|
993
|
-
|
|
994
|
-
|
|
1411
|
+
**options.maxExecutions**
|
|
1412
|
+
|
|
1413
|
+
Stop after N executions.
|
|
1414
|
+
|
|
1415
|
+
#### Param
|
|
1416
|
+
|
|
1417
|
+
**options.maxDurationMs**
|
|
1418
|
+
|
|
1419
|
+
Stop after N milliseconds.
|
|
1420
|
+
|
|
1421
|
+
#### Param
|
|
1422
|
+
|
|
1423
|
+
**options.schedule**
|
|
1424
|
+
|
|
1425
|
+
How to measure intervals: `'delayAfterEnd'` or `'delayBetweenStarts'`.
|
|
1426
|
+
|
|
1427
|
+
#### Returns
|
|
1428
|
+
|
|
1429
|
+
An object containing `stop()` to cancel further executions and `done` Promise
|
|
1430
|
+
which resolves when the periodic runner stops (or rejects if the operation errors).
|
|
1431
|
+
|
|
1432
|
+
|
|
1433
|
+
<a id="variablessynchronisedmd"></a>
|
|
1434
|
+
|
|
1435
|
+
### Variable: synchronised
|
|
1436
|
+
|
|
1437
|
+
> `const` **synchronised**: \<`T`\>(`lock`, `operation`) => `Promise`\<`T`\> = `PromiseUtils.synchronised`
|
|
1438
|
+
|
|
1439
|
+
This is just another spelling of synchronized.
|
|
1440
|
+
|
|
1441
|
+
This is just another spelling of [PromiseUtils.synchronized](#synchronized).
|
|
1442
|
+
|
|
1443
|
+
#### Type Parameters
|
|
1444
|
+
|
|
1445
|
+
| Type Parameter |
|
|
1446
|
+
| ------ |
|
|
995
1447
|
| `T` |
|
|
996
1448
|
|
|
997
|
-
|
|
1449
|
+
#### Parameters
|
|
998
1450
|
|
|
999
|
-
|
|
|
1000
|
-
|
|
|
1451
|
+
| Parameter | Type | Description |
|
|
1452
|
+
| ------ | ------ | ------ |
|
|
1001
1453
|
| `lock` | `any` | The object (such as a string, a number, or `this` in a class) used to identify the lock. |
|
|
1002
|
-
| `operation` | (`previousState
|
|
1454
|
+
| `operation` | (`previousState`, `previousSettledState`, `previousResult`) => `Promise`\<`T`\> | The function that performs the computation and returns a Promise. |
|
|
1003
1455
|
|
|
1004
|
-
|
|
1456
|
+
#### Returns
|
|
1005
1457
|
|
|
1006
1458
|
`Promise`\<`T`\>
|
|
1007
1459
|
|
|
1008
1460
|
The result of the operation function.
|
|
1009
1461
|
|
|
1010
|
-
|
|
1462
|
+
#### Param
|
|
1011
1463
|
|
|
1012
|
-
|
|
1464
|
+
**lock**
|
|
1013
1465
|
|
|
1014
|
-
|
|
1466
|
+
The object (such as a string, a number, or this in a class) used to identify the lock.
|
|
1467
|
+
|
|
1468
|
+
#### Param
|
|
1469
|
+
|
|
1470
|
+
**operation**
|
|
1471
|
+
|
|
1472
|
+
The function that performs the computation and returns a Promise.
|
|
1473
|
+
|
|
1474
|
+
#### Returns
|
|
1475
|
+
|
|
1476
|
+
The result of the operation function.
|
|
1477
|
+
|
|
1478
|
+
|
|
1479
|
+
<a id="variablessynchronizedmd"></a>
|
|
1480
|
+
|
|
1481
|
+
### Variable: synchronized
|
|
1482
|
+
|
|
1483
|
+
> `const` **synchronized**: \<`T`\>(`lock`, `operation`) => `Promise`\<`T`\> = `PromiseUtils.synchronized`
|
|
1484
|
+
|
|
1485
|
+
Provides mutual exclusion similar to synchronized in Java.
|
|
1486
|
+
Ensures no concurrent execution of any operation function associated with the same lock.
|
|
1487
|
+
The operation function has access to the state (when synchronized is called),
|
|
1488
|
+
settledState (when the operation function is called),
|
|
1489
|
+
and result (either the fulfilled result or the rejected reason) of the previous operation.
|
|
1490
|
+
If there is no previous invocation, state, settledState, and result will all be undefined.
|
|
1015
1491
|
|
|
1016
1492
|
Provides mutual exclusion similar to `synchronized` in Java.
|
|
1017
1493
|
Ensures no concurrent execution of any operation function associated with the same lock.
|
|
@@ -1020,30 +1496,53 @@ settledState (when the operation function is called),
|
|
|
1020
1496
|
and result (either the fulfilled result or the rejected reason) of the previous operation.
|
|
1021
1497
|
If there is no previous invocation, state, settledState, and result will all be undefined.
|
|
1022
1498
|
|
|
1023
|
-
|
|
1499
|
+
#### Type Parameters
|
|
1024
1500
|
|
|
1025
|
-
|
|
|
1026
|
-
|
|
|
1501
|
+
| Type Parameter |
|
|
1502
|
+
| ------ |
|
|
1027
1503
|
| `T` |
|
|
1028
1504
|
|
|
1029
|
-
|
|
1505
|
+
#### Parameters
|
|
1030
1506
|
|
|
1031
|
-
|
|
|
1032
|
-
|
|
|
1507
|
+
| Parameter | Type | Description |
|
|
1508
|
+
| ------ | ------ | ------ |
|
|
1033
1509
|
| `lock` | `any` | The object (such as a string, a number, or `this` in a class) used to identify the lock. |
|
|
1034
|
-
| `operation` | (`previousState
|
|
1510
|
+
| `operation` | (`previousState`, `previousSettledState`, `previousResult`) => `Promise`\<`T`\> | The function that performs the computation and returns a Promise. |
|
|
1035
1511
|
|
|
1036
|
-
|
|
1512
|
+
#### Returns
|
|
1037
1513
|
|
|
1038
1514
|
`Promise`\<`T`\>
|
|
1039
1515
|
|
|
1040
1516
|
The result of the operation function.
|
|
1041
1517
|
|
|
1042
|
-
|
|
1518
|
+
#### Param
|
|
1519
|
+
|
|
1520
|
+
**lock**
|
|
1521
|
+
|
|
1522
|
+
The object (such as a string, a number, or this in a class) used to identify the lock.
|
|
1523
|
+
|
|
1524
|
+
#### Param
|
|
1525
|
+
|
|
1526
|
+
**operation**
|
|
1043
1527
|
|
|
1044
|
-
|
|
1528
|
+
The function that performs the computation and returns a Promise.
|
|
1045
1529
|
|
|
1046
|
-
|
|
1530
|
+
#### Returns
|
|
1531
|
+
|
|
1532
|
+
The result of the operation function.
|
|
1533
|
+
|
|
1534
|
+
|
|
1535
|
+
<a id="variablestimeoutrejectmd"></a>
|
|
1536
|
+
|
|
1537
|
+
### Variable: timeoutReject
|
|
1538
|
+
|
|
1539
|
+
> `const` **timeoutReject**: \<`T`, `R`\>(`operation`, `ms`, `rejectReason`) => `Promise`\<`T`\> = `PromiseUtils.timeoutReject`
|
|
1540
|
+
|
|
1541
|
+
Applies a timeout to a Promise or a function that returns a Promise.
|
|
1542
|
+
If the timeout occurs, the returned Promise rejects with the specified reason.
|
|
1543
|
+
If the timeout does not occur, the returned Promise resolves or rejects based on the outcome of the original Promise.
|
|
1544
|
+
If the rejectReason parameter is a function and the timeout does not occur, the function will not be called.
|
|
1545
|
+
Note: The rejection of the operation parameter is not handled by this function. You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously."
|
|
1047
1546
|
|
|
1048
1547
|
Applies a timeout to a Promise or a function that returns a Promise.
|
|
1049
1548
|
If the timeout occurs, the returned Promise rejects with the specified reason.
|
|
@@ -1051,32 +1550,62 @@ If the timeout does not occur, the returned Promise resolves or rejects based on
|
|
|
1051
1550
|
If the `rejectReason` parameter is a function and the timeout does not occur, the function will not be called.
|
|
1052
1551
|
Note: The rejection of the `operation` parameter is not handled by this function. You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously."
|
|
1053
1552
|
|
|
1054
|
-
|
|
1553
|
+
#### Type Parameters
|
|
1055
1554
|
|
|
1056
|
-
|
|
|
1057
|
-
|
|
|
1555
|
+
| Type Parameter | Default type |
|
|
1556
|
+
| ------ | ------ |
|
|
1058
1557
|
| `T` | `never` |
|
|
1059
1558
|
| `R` | `any` |
|
|
1060
1559
|
|
|
1061
|
-
|
|
1560
|
+
#### Parameters
|
|
1062
1561
|
|
|
1063
|
-
|
|
|
1064
|
-
|
|
|
1065
|
-
| `operation` | `Promise`\<`T`\> \| () => `Promise`\<`T`\> | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
1562
|
+
| Parameter | Type | Description |
|
|
1563
|
+
| ------ | ------ | ------ |
|
|
1564
|
+
| `operation` | `Promise`\<`T`\> \| (() => `Promise`\<`T`\>) | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
1066
1565
|
| `ms` | `number` | The number of milliseconds for the timeout. |
|
|
1067
|
-
| `rejectReason` | `R` \| `PromiseLike`\<`R`\> \| () => `R` \| `PromiseLike`\<`R`\> | The reason to reject with if the timeout occurs, or a function that supplies the reason. |
|
|
1566
|
+
| `rejectReason` | `R` \| `PromiseLike`\<`R`\> \| (() => `R` \| `PromiseLike`\<`R`\>) | The reason to reject with if the timeout occurs, or a function that supplies the reason. |
|
|
1068
1567
|
|
|
1069
|
-
|
|
1568
|
+
#### Returns
|
|
1070
1569
|
|
|
1071
1570
|
`Promise`\<`T`\>
|
|
1072
1571
|
|
|
1073
1572
|
A new Promise that rejects with the specified reason if the timeout occurs.
|
|
1074
1573
|
|
|
1075
|
-
|
|
1574
|
+
#### Param
|
|
1575
|
+
|
|
1576
|
+
**operation**
|
|
1577
|
+
|
|
1578
|
+
The original Promise or a function that returns a Promise to which the timeout will be applied.
|
|
1579
|
+
|
|
1580
|
+
#### Param
|
|
1581
|
+
|
|
1582
|
+
**ms**
|
|
1583
|
+
|
|
1584
|
+
The number of milliseconds for the timeout.
|
|
1585
|
+
|
|
1586
|
+
#### Param
|
|
1587
|
+
|
|
1588
|
+
**rejectReason**
|
|
1589
|
+
|
|
1590
|
+
The reason to reject with if the timeout occurs, or a function that supplies the reason.
|
|
1591
|
+
|
|
1592
|
+
#### Returns
|
|
1593
|
+
|
|
1594
|
+
A new Promise that rejects with the specified reason if the timeout occurs.
|
|
1595
|
+
|
|
1596
|
+
|
|
1597
|
+
<a id="variablestimeoutresolvemd"></a>
|
|
1076
1598
|
|
|
1077
|
-
|
|
1599
|
+
### Variable: timeoutResolve
|
|
1078
1600
|
|
|
1079
|
-
|
|
1601
|
+
> `const` **timeoutResolve**: \<`T`\>(`operation`, `ms`, `result?`) => `Promise`\<`T`\> = `PromiseUtils.timeoutResolve`
|
|
1602
|
+
|
|
1603
|
+
Applies a timeout to a Promise or a function that returns a Promise.
|
|
1604
|
+
If the timeout occurs, the returned Promise resolves to the specified result.
|
|
1605
|
+
If the timeout does not occur, the returned Promise resolves or rejects based on the outcome of the original Promise.
|
|
1606
|
+
If the result parameter is a function and the timeout does not occur, the function will not be called.
|
|
1607
|
+
Note: The rejection of the operation parameter is not handled by this function.
|
|
1608
|
+
You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously."
|
|
1080
1609
|
|
|
1081
1610
|
Applies a timeout to a Promise or a function that returns a Promise.
|
|
1082
1611
|
If the timeout occurs, the returned Promise resolves to the specified result.
|
|
@@ -1085,61 +1614,86 @@ If the `result` parameter is a function and the timeout does not occur, the func
|
|
|
1085
1614
|
Note: The rejection of the `operation` parameter is not handled by this function.
|
|
1086
1615
|
You may want to handle it outside this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously."
|
|
1087
1616
|
|
|
1088
|
-
|
|
1617
|
+
#### Type Parameters
|
|
1089
1618
|
|
|
1090
|
-
|
|
|
1091
|
-
|
|
|
1619
|
+
| Type Parameter |
|
|
1620
|
+
| ------ |
|
|
1092
1621
|
| `T` |
|
|
1093
1622
|
|
|
1094
|
-
|
|
1623
|
+
#### Parameters
|
|
1095
1624
|
|
|
1096
|
-
|
|
|
1097
|
-
|
|
|
1098
|
-
| `operation` | `Promise`\<`T`\> \| () => `Promise`\<`T`\> | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
1625
|
+
| Parameter | Type | Description |
|
|
1626
|
+
| ------ | ------ | ------ |
|
|
1627
|
+
| `operation` | `Promise`\<`T`\> \| (() => `Promise`\<`T`\>) | The original Promise or a function that returns a Promise to which the timeout will be applied. |
|
|
1099
1628
|
| `ms` | `number` | The number of milliseconds for the timeout. |
|
|
1100
|
-
| `result?` | `T` \| `PromiseLike`\<`T`\> \| () => `T` \| `PromiseLike`\<`T`\> | The result to resolve with if the timeout occurs, or a function that supplies the result. |
|
|
1629
|
+
| `result?` | `T` \| `PromiseLike`\<`T`\> \| (() => `T` \| `PromiseLike`\<`T`\>) | The result to resolve with if the timeout occurs, or a function that supplies the result. |
|
|
1101
1630
|
|
|
1102
|
-
|
|
1631
|
+
#### Returns
|
|
1103
1632
|
|
|
1104
1633
|
`Promise`\<`T`\>
|
|
1105
1634
|
|
|
1106
1635
|
A new Promise that resolves to the specified result if the timeout occurs.
|
|
1107
1636
|
|
|
1108
|
-
|
|
1637
|
+
#### Param
|
|
1638
|
+
|
|
1639
|
+
**operation**
|
|
1640
|
+
|
|
1641
|
+
The original Promise or a function that returns a Promise to which the timeout will be applied.
|
|
1642
|
+
|
|
1643
|
+
#### Param
|
|
1644
|
+
|
|
1645
|
+
**ms**
|
|
1646
|
+
|
|
1647
|
+
The number of milliseconds for the timeout.
|
|
1648
|
+
|
|
1649
|
+
#### Param
|
|
1650
|
+
|
|
1651
|
+
**result**
|
|
1652
|
+
|
|
1653
|
+
The result to resolve with if the timeout occurs, or a function that supplies the result.
|
|
1654
|
+
|
|
1655
|
+
#### Returns
|
|
1656
|
+
|
|
1657
|
+
A new Promise that resolves to the specified result if the timeout occurs.
|
|
1658
|
+
|
|
1659
|
+
|
|
1660
|
+
<a id="variableswithconcurrencymd"></a>
|
|
1109
1661
|
|
|
1110
|
-
|
|
1662
|
+
### Variable: withConcurrency
|
|
1111
1663
|
|
|
1112
|
-
|
|
1664
|
+
> `const` **withConcurrency**: \<`Data`, `Result`\>(`concurrency`, `jobs`, `operation`) => `Promise`\<`Result`[]\> = `PromiseUtils.withConcurrency`
|
|
1665
|
+
|
|
1666
|
+
Executes multiple jobs/operations with a specified level of concurrency.
|
|
1113
1667
|
|
|
1114
1668
|
Executes multiple jobs/operations with a specified level of concurrency.
|
|
1115
1669
|
|
|
1116
1670
|
Unlike `inParallel(...)`, this function may throw or reject an error when a job/operation fails.
|
|
1117
|
-
When an error is
|
|
1118
|
-
If you want all the operations to always be executed, use [inParallel](#inparallel) instead.
|
|
1671
|
+
When an error is thrown, the function rejects immediately, and no further operations will be started.
|
|
1672
|
+
If you want all the operations to always be executed, use [PromiseUtils.inParallel](#inparallel) instead.
|
|
1119
1673
|
|
|
1120
|
-
|
|
1674
|
+
#### Type Parameters
|
|
1121
1675
|
|
|
1122
|
-
|
|
|
1123
|
-
|
|
|
1676
|
+
| Type Parameter | Description |
|
|
1677
|
+
| ------ | ------ |
|
|
1124
1678
|
| `Data` | The type of the job data, typically an Array. |
|
|
1125
1679
|
| `Result` | The type of the return value from the operation function. |
|
|
1126
1680
|
|
|
1127
|
-
|
|
1681
|
+
#### Parameters
|
|
1128
1682
|
|
|
1129
|
-
|
|
|
1130
|
-
|
|
|
1683
|
+
| Parameter | Type | Description |
|
|
1684
|
+
| ------ | ------ | ------ |
|
|
1131
1685
|
| `concurrency` | `number` | The number of jobs/operations to run concurrently. |
|
|
1132
1686
|
| `jobs` | `Iterable`\<`Data`\> | The job data to be processed. This function can handle an infinite or unknown number of elements safely. |
|
|
1133
|
-
| `operation` | (`job
|
|
1687
|
+
| `operation` | (`job`, `index`) => `Promise`\<`Result`\> | The function that processes job data asynchronously. |
|
|
1134
1688
|
|
|
1135
|
-
|
|
1689
|
+
#### Returns
|
|
1136
1690
|
|
|
1137
1691
|
`Promise`\<`Result`[]\>
|
|
1138
1692
|
|
|
1139
1693
|
A promise that resolves to an array containing the results from the operation function.
|
|
1140
1694
|
The results in the returned array are in the same order as the corresponding elements in the jobs array.
|
|
1141
1695
|
|
|
1142
|
-
|
|
1696
|
+
#### Example
|
|
1143
1697
|
|
|
1144
1698
|
```ts
|
|
1145
1699
|
// At any time, there would be no more than 5 concurrency API calls. Error would be re-thrown immediately when it occurs.
|
|
@@ -1149,36 +1703,62 @@ const attributes = await PromiseUtils.withConcurrency(5, topicArns, async (topic
|
|
|
1149
1703
|
});
|
|
1150
1704
|
```
|
|
1151
1705
|
|
|
1152
|
-
|
|
1706
|
+
#### Param
|
|
1707
|
+
|
|
1708
|
+
**concurrency**
|
|
1153
1709
|
|
|
1154
|
-
|
|
1710
|
+
The number of jobs/operations to run concurrently.
|
|
1155
1711
|
|
|
1156
|
-
|
|
1712
|
+
#### Param
|
|
1713
|
+
|
|
1714
|
+
**jobs**
|
|
1715
|
+
|
|
1716
|
+
The job data to be processed. This function can handle an infinite or unknown number of elements safely.
|
|
1717
|
+
|
|
1718
|
+
#### Param
|
|
1719
|
+
|
|
1720
|
+
**operation**
|
|
1721
|
+
|
|
1722
|
+
The function that processes job data asynchronously.
|
|
1723
|
+
|
|
1724
|
+
#### Returns
|
|
1725
|
+
|
|
1726
|
+
A promise that resolves to an array containing the results from the operation function.
|
|
1727
|
+
The results in the returned array are in the same order as the corresponding elements in the jobs array.
|
|
1728
|
+
|
|
1729
|
+
|
|
1730
|
+
<a id="variableswithretrymd"></a>
|
|
1731
|
+
|
|
1732
|
+
### Variable: withRetry
|
|
1733
|
+
|
|
1734
|
+
> `const` **withRetry**: \<`Result`, `TError`\>(`operation`, `backoff`, `shouldRetry`) => `Promise`\<`Result`\> = `PromiseUtils.withRetry`
|
|
1735
|
+
|
|
1736
|
+
Repeatedly performs an operation until a specified criteria is met.
|
|
1157
1737
|
|
|
1158
1738
|
Repeatedly performs an operation until a specified criteria is met.
|
|
1159
1739
|
|
|
1160
|
-
|
|
1740
|
+
#### Type Parameters
|
|
1161
1741
|
|
|
1162
|
-
|
|
|
1163
|
-
|
|
|
1164
|
-
| `Result` |
|
|
1742
|
+
| Type Parameter | Default type | Description |
|
|
1743
|
+
| ------ | ------ | ------ |
|
|
1744
|
+
| `Result` | - | Type of the operation result. |
|
|
1165
1745
|
| `TError` | `any` | Type of the possible error that could be generated by the operation. |
|
|
1166
1746
|
|
|
1167
|
-
|
|
1747
|
+
#### Parameters
|
|
1168
1748
|
|
|
1169
|
-
|
|
|
1170
|
-
|
|
|
1171
|
-
| `operation` | (`attempt
|
|
1172
|
-
| `backoff` | `number`[] \| (`attempt
|
|
1173
|
-
| `shouldRetry` | (`previousError
|
|
1749
|
+
| Parameter | Type | Description |
|
|
1750
|
+
| ------ | ------ | ------ |
|
|
1751
|
+
| `operation` | (`attempt`, `previousResult`, `previousError`) => `Promise`\<`Result`\> | A function that outputs a Promise result. Typically, the operation does not use its arguments. |
|
|
1752
|
+
| `backoff` | `number`[] \| ((`attempt`, `previousResult`, `previousError`) => `number` \| `undefined`) | An array of retry backoff periods (in milliseconds) or a function for calculating them. If retry is desired, the specified backoff period is waited before the next call to the operation. If the array runs out of elements or the function returns `undefined` or a negative number, no further calls to the operation will be made. The `attempt` argument passed to the backoff function starts from 1, as it is called immediately after the first attempt and before the first retry. |
|
|
1753
|
+
| `shouldRetry` | (`previousError`, `previousResult`, `attempt`) => `boolean` | A predicate function for deciding whether another call to the operation should occur. If this argument is not defined, a retry will occur whenever the operation rejects with an error. The `shouldRetry` function is evaluated before the `backoff`. The `attempt` argument passed to the shouldRetry function starts from 1. |
|
|
1174
1754
|
|
|
1175
|
-
|
|
1755
|
+
#### Returns
|
|
1176
1756
|
|
|
1177
1757
|
`Promise`\<`Result`\>
|
|
1178
1758
|
|
|
1179
1759
|
A promise of the operation result, potentially with retries applied.
|
|
1180
1760
|
|
|
1181
|
-
|
|
1761
|
+
#### Example
|
|
1182
1762
|
|
|
1183
1763
|
```ts
|
|
1184
1764
|
const result = await PromiseUtils.withRetry(() => doSomething(), [100, 200, 300, 500, 800, 1000]);
|
|
@@ -1186,30 +1766,25 @@ const result2 = await PromiseUtils.withRetry(() => doSomething(), Array.from({le
|
|
|
1186
1766
|
const result3 = await PromiseUtils.withRetry(() => doSomething(), attempt => attempt <= 8 ? 1000 * Math.min(FIBONACCI_SEQUENCE[attempt - 1], 10) : undefined, err => err.statusCode === 429);
|
|
1187
1767
|
```
|
|
1188
1768
|
|
|
1189
|
-
|
|
1769
|
+
#### Param
|
|
1190
1770
|
|
|
1771
|
+
**operation**
|
|
1191
1772
|
|
|
1192
|
-
|
|
1773
|
+
A function that outputs a Promise result. Typically, the operation does not use its arguments.
|
|
1193
1774
|
|
|
1194
|
-
|
|
1775
|
+
#### Param
|
|
1195
1776
|
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
#### Enumeration Members
|
|
1199
|
-
|
|
1200
|
-
##### Fulfilled
|
|
1777
|
+
**backoff**
|
|
1201
1778
|
|
|
1202
|
-
|
|
1779
|
+
An array of retry backoff periods (in milliseconds) or a function for calculating them.
|
|
1203
1780
|
|
|
1204
|
-
|
|
1781
|
+
#### Param
|
|
1205
1782
|
|
|
1206
|
-
|
|
1783
|
+
**shouldRetry**
|
|
1207
1784
|
|
|
1208
|
-
|
|
1785
|
+
A predicate function for deciding whether another call to the operation should occur.
|
|
1209
1786
|
|
|
1210
|
-
|
|
1787
|
+
#### Returns
|
|
1211
1788
|
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
• **Rejected** = ``"Rejected"``
|
|
1789
|
+
A promise of the operation result, potentially with retries applied.
|
|
1215
1790
|
<!-- API end -->
|