@handy-common-utils/promise-utils 1.2.7 → 1.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @handy-common-utils/promise-utils
 
 These Promise related utilities have 100% test coverage. The package is tiny because there is no dependency on any other package.
-Functions provided are `repeat`, `withRetry`, `inParallel`, `delayedResolve`, `delayedReject`, `timoutResolve`, `timeoutReject`, `promiseState`, `synchronized`, etc.
+Functions provided are `repeat`, `withRetry`, `inParallel`, `delayedResolve`, `delayedReject`, `timeoutResolve`, `timeoutReject`, `promiseState`, `synchronized`, etc.
 
 [![Version](https://img.shields.io/npm/v/@handy-common-utils/promise-utils.svg)](https://npmjs.org/package/@handy-common-utils/promise-utils)
 [![Downloads/week](https://img.shields.io/npm/dw/@handy-common-utils/promise-utils.svg)](https://npmjs.org/package/@handy-common-utils/promise-utils)
@@ -76,38 +76,16 @@ await inParallel(5, topicArns, async topicArn => {
 <!-- API start -->
 <a name="readmemd"></a>
 
-@handy-common-utils/promise-utils
-
 ## @handy-common-utils/promise-utils
 
-### Table of contents
-
-#### Enumerations
+### Enumerations
 
 - [PromiseState](#enumspromisestatemd)
 
-#### Classes
+### Classes
 
 - [PromiseUtils](#classespromiseutilsmd)
 
-#### Variables
-
-- [EXPONENTIAL\_SEQUENCE](#exponential_sequence)
-- [FIBONACCI\_SEQUENCE](#fibonacci_sequence)
-
-#### Functions
-
-- [delayedReject](#delayedreject)
-- [delayedResolve](#delayedresolve)
-- [inParallel](#inparallel)
-- [promiseState](#promisestate)
-- [repeat](#repeat)
-- [synchronised](#synchronised)
-- [synchronized](#synchronized)
-- [timeoutReject](#timeoutreject)
-- [timeoutResolve](#timeoutresolve)
-- [withRetry](#withretry)
-
 ### Variables
 
 #### EXPONENTIAL\_SEQUENCE
@@ -117,19 +95,19 @@ await inParallel(5, topicArns, async topicArn => {
 Array of 25 exponential numbers starting from 1 up to 33554432.
 It can be used to form your own backoff interval array.
 
-**`example`**
-```javascript
+**`Example`**
 
+```ts
 // 1ms, 2ms, 4ms, 8ms, 16ms, 32ms
 PromiseUtils.withRetry(() => doSomething(), EXPONENTIAL_SEQUENCE.slice(0, 5), err => err.statusCode === 429);
 // 1s, 2s, 4s, 8s, 10s, 10s, 10s, 10s, 10s, 10s
 PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(EXPONENTIAL_SEQUENCE[i], 10)), err => err.statusCode === 429);
 // with +-10% randomness: 1s, 2s, 4s, 8s
 PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 4).map(n => 1000 * n * (1 + (Math.random() - 0.5) / 5)), err => err.statusCode === 429);
+```
 
 ___
 
-```
 #### FIBONACCI\_SEQUENCE
 
 • `Const` **FIBONACCI\_SEQUENCE**: `number`[]
@@ -137,43 +115,280 @@ ___
 Array of 25 Fibonacci numbers starting from 1 up to 317811.
 It can be used to form your own backoff interval array.
 
-**`example`**
-```javascript
+**`Example`**
 
+```ts
 // 1ms, 2ms, 3ms, 5ms, 8ms, 13ms
 PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 5), err => err.statusCode === 429);
 // 1s, 2s, 3s, 4s, 8s, 10s, 10s, 10s, 10s, 10s
 PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(FIBONACCI_SEQUENCE[i], 10)), err => err.statusCode === 429);
 // with +-10% randomness: 1s, 2s, 3s, 5s, 8s, 13s
 PromiseUtils.withRetry(() => doSomething(), FIBONACCI_SEQUENCE.slice(0, 5).map(n => 1000 * n * (1 + (Math.random() - 0.5) / 5)), err => err.statusCode === 429);
+```
 
-```## Classes
+### Functions
 
+#### delayedReject
 
-<a name="classespromiseutilsmd"></a>
+▸ **delayedReject**<`T`, `R`\>(`ms`, `reason`): `Promise`<`T`\>
 
-[@handy-common-utils/promise-utils](#readmemd) / PromiseUtils
+See [delayedReject](#delayedreject) for full documentation.
 
-### Class: PromiseUtils
+##### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `never` |
+| `R` | `any` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `ms` | `number` |
+| `reason` | `R` \| `PromiseLike`<`R`\> \| () => `R` \| `PromiseLike`<`R`\> |
+
+##### Returns
+
+`Promise`<`T`\>
+
+___
+
+#### delayedResolve
+
+▸ **delayedResolve**<`T`\>(`ms`, `result?`): `Promise`<`T`\>
 
-#### Table of contents
+See [delayedResolve](#delayedresolve) for full documentation.
 
-##### Constructors
+##### Type parameters
+
+| Name |
+| :------ |
+| `T` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `ms` | `number` |
+| `result?` | `T` \| `PromiseLike`<`T`\> \| () => `T` \| `PromiseLike`<`T`\> |
+
+##### Returns
+
+`Promise`<`T`\>
+
+___
+
+#### inParallel
+
+▸ **inParallel**<`Data`, `Result`, `TError`\>(`parallelism`, `jobs`, `operation`): `Promise`<(`Result` \| `TError`)[]\>
+
+See [inParallel](#inparallel) for full documentation.
+
+##### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `Data` | `Data` |
+| `Result` | `Result` |
+| `TError` | `Result` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `parallelism` | `number` |
+| `jobs` | `Iterable`<`Data`\> |
+| `operation` | (`job`: `Data`, `index`: `number`) => `Promise`<`Result`\> |
+
+##### Returns
+
+`Promise`<(`Result` \| `TError`)[]\>
+
+___
 
-- [constructor](#constructor)
+#### promiseState
 
-##### Methods
+▸ **promiseState**(`p`): `Promise`<[`PromiseState`](#enumspromisestatemd)\>
 
-- [delayedReject](#delayedreject)
-- [delayedResolve](#delayedresolve)
-- [inParallel](#inparallel)
-- [promiseState](#promisestate)
-- [repeat](#repeat)
-- [synchronised](#synchronised)
-- [synchronized](#synchronized)
-- [timeoutReject](#timeoutreject)
-- [timeoutResolve](#timeoutresolve)
-- [withRetry](#withretry)
+See [promiseState](#promisestate) for full documentation.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `p` | `Promise`<`any`\> |
+
+##### Returns
+
+`Promise`<[`PromiseState`](#enumspromisestatemd)\>
+
+___
+
+#### repeat
+
+▸ **repeat**<`Result`, `Param`, `Collection`\>(`operation`, `nextParameter`, `collect`, `initialCollection`, `initialParameter?`): `Promise`<`Collection`\>
+
+See [repeat](#repeat) for full documentation.
+
+##### Type parameters
+
+| Name |
+| :------ |
+| `Result` |
+| `Param` |
+| `Collection` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `operation` | (`parameter`: `Partial`<`Param`\>) => `Promise`<`Result`\> |
+| `nextParameter` | (`response`: `Result`) => ``null`` \| `Partial`<`Param`\> \| `Promise`<`Partial`<`Param`\>\> |
+| `collect` | (`collection`: `Collection`, `result`: `Result`) => `Collection` |
+| `initialCollection` | `Collection` |
+| `initialParameter` | `Partial`<`Param`\> |
+
+##### Returns
+
+`Promise`<`Collection`\>
+
+___
+
+#### synchronised
+
+▸ **synchronised**<`T`\>(`lock`, `operation`): `Promise`<`T`\>
+
+See [synchronised](#synchronised) for full documentation.
+
+##### Type parameters
+
+| Name |
+| :------ |
+| `T` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `lock` | `unknown` |
+| `operation` | (`previousState`: `undefined` \| [`PromiseState`](#enumspromisestatemd), `previousSettledState`: `undefined` \| [`PromiseState`](#enumspromisestatemd), `previousResult`: `any`) => `Promise`<`T`\> |
+
+##### Returns
+
+`Promise`<`T`\>
+
+___
+
+#### synchronized
+
+▸ **synchronized**<`T`\>(`lock`, `operation`): `Promise`<`T`\>
+
+See [synchronized](#synchronized) for full documentation.
+
+##### Type parameters
+
+| Name |
+| :------ |
+| `T` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `lock` | `unknown` |
+| `operation` | (`previousState`: `undefined` \| [`PromiseState`](#enumspromisestatemd), `previousSettledState`: `undefined` \| [`PromiseState`](#enumspromisestatemd), `previousResult`: `any`) => `Promise`<`T`\> |
+
+##### Returns
+
+`Promise`<`T`\>
+
+___
+
+#### timeoutReject
+
+▸ **timeoutReject**<`T`, `R`\>(`operation`, `ms`, `rejectReason`): `Promise`<`T`\>
+
+See [timeoutReject](#timeoutreject) for full documentation.
+
+##### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `T` | `never` |
+| `R` | `any` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `operation` | `Promise`<`T`\> \| () => `Promise`<`T`\> |
+| `ms` | `number` |
+| `rejectReason` | `R` \| `PromiseLike`<`R`\> \| () => `R` \| `PromiseLike`<`R`\> |
+
+##### Returns
+
+`Promise`<`T`\>
+
+___
+
+#### timeoutResolve
+
+▸ **timeoutResolve**<`T`\>(`operation`, `ms`, `result?`): `Promise`<`T`\>
+
+See [timeoutResolve](#timeoutresolve) for full documentation.
+
+##### Type parameters
+
+| Name |
+| :------ |
+| `T` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `operation` | `Promise`<`T`\> \| () => `Promise`<`T`\> |
+| `ms` | `number` |
+| `result?` | `T` \| `PromiseLike`<`T`\> \| () => `T` \| `PromiseLike`<`T`\> |
+
+##### Returns
+
+`Promise`<`T`\>
+
+___
+
+#### withRetry
+
+▸ **withRetry**<`Result`, `TError`\>(`operation`, `backoff`, `shouldRetry?`): `Promise`<`Result`\>
+
+See [withRetry](#withretry) for full documentation.
+
+##### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `Result` | `Result` |
+| `TError` | `any` |
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `operation` | (`attempt`: `number`, `previousResult`: `undefined` \| `Result`, `previousError`: `undefined` \| `TError`) => `Promise`<`Result`\> |
+| `backoff` | `number`[] \| (`attempt`: `number`, `previousResult`: `undefined` \| `Result`, `previousError`: `undefined` \| `TError`) => `undefined` \| `number` |
+| `shouldRetry` | (`previousError`: `undefined` \| `TError`, `previousResult`: `undefined` \| `Result`, `attempt`: `number`) => `boolean` |
+
+##### Returns
+
+`Promise`<`Result`\>
+
+## Classes
+
+
+<a name="classespromiseutilsmd"></a>
+
+### Class: PromiseUtils
 
 #### Constructors
 
@@ -228,7 +443,7 @@ Create a Promise that resolves after number of milliseconds specified
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `ms` | `number` | number of milliseconds after which the created Promise would resolve |
-| `result?` | `T` \| `PromiseLike`<`T`\> \| () => `T` \| `PromiseLike`<`T`\> | the result to be resolved for the Promise, or a function that supplies the reuslt. |
+| `result?` | `T` \| `PromiseLike`<`T`\> \| () => `T` \| `PromiseLike`<`T`\> | the result to be resolved for the Promise, or a function that supplies the result. |
 
 ###### Returns
 
@@ -244,19 +459,6 @@ ___
 
 Run multiple jobs/operations in parallel.
 
-**`example`**
-```javascript
-
-const topicArns = topics.map(topic => topic.TopicArn!);
-await PromiseUtils.inParallel(5, topicArns, async topicArn => {
-  const topicAttributes = (await sns.getTopicAttributes({ TopicArn: topicArn }).promise()).Attributes!;
-  const topicDetails = { ...topicAttributes, subscriptions: [] } as any;
-  if (this.shouldInclude(topicArn)) {
-    inventory.snsTopicsByArn.set(topicArn, topicDetails);
-  }
-});
-
-```
 ###### Type parameters
 
 | Name | Type | Description |
@@ -270,7 +472,7 @@ await PromiseUtils.inParallel(5, topicArns, async topicArn => {
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `parallelism` | `number` | how many jobs/operations can be running at the same time |
-| `jobs` | `Iterable`<`Data`\> | job data which will be the input to operation function.                    This function is safe when there are infinite unknown number of elements in the job data. |
+| `jobs` | `Iterable`<`Data`\> | job data which will be the input to operation function. This function is safe when there are infinite unknown number of elements in the job data. |
 | `operation` | (`job`: `Data`, `index`: `number`) => `Promise`<`Result`\> | the function that turns job data into result asynchronously |
 
 ###### Returns
@@ -281,6 +483,19 @@ Promise of void if the operation function does not return a value,
          or promise of an array containing results returned from the operation function.
          In the array containing results, each element is either the fulfilled result, or the rejected error/reason.
 
+**`Example`**
+
+```ts
+const topicArns = topics.map(topic => topic.TopicArn!);
+await PromiseUtils.inParallel(5, topicArns, async topicArn => {
+  const topicAttributes = (await sns.getTopicAttributes({ TopicArn: topicArn }).promise()).Attributes!;
+  const topicDetails = { ...topicAttributes, subscriptions: [] } as any;
+  if (this.shouldInclude(topicArn)) {
+    inventory.snsTopicsByArn.set(topicArn, topicDetails);
+  }
+});
+```
+
 ___
 
 ##### promiseState
@@ -300,7 +515,7 @@ Please note that the returned value is a Promise, although it resolves immediate
 
 `Promise`<[`PromiseState`](#enumspromisestatemd)\>
 
-A Promise that resolves immediately cotaining the state of the input Promise
+A Promise that resolves immediately containing the state of the input Promise
 
 ___
 
@@ -311,17 +526,6 @@ ___
 Do an operation repeatedly and collect all the results.
 This function is useful for client side pagination.
 
-**`example`**
-```javascript
-
-const domainNameObjects = await PromiseUtils.repeat(
-  pagingParam => apig.getDomainNames({limit: 500, ...pagingParam}).promise(),
-  esponse => response.position? {position: response.position} : null,
-  (collection, response) => collection.concat(response.items!),
-  [] as APIGateway.DomainName[],
-);
-
-```
 ###### Type parameters
 
 | Name | Description |
@@ -335,7 +539,7 @@ const domainNameObjects = await PromiseUtils.repeat(
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `operation` | (`parameter`: `Partial`<`Param`\>) => `Promise`<`Result`\> | a function that takes paging parameter as input and outputs a result, normally the operation supports paging |
-| `nextParameter` | (`response`: `Result`) => ``null`` \| `Partial`<`Param`\> \| `Promise`<`Partial`<`Param`\>\> | The function for calculating next parameter from the operation result.                      Normally the parameter controls paging,                      This function should return null when next invocation of the operation function is not desired.                      If next invocation is desired, the return value of this function can be a Promise or not a Promise. |
+| `nextParameter` | (`response`: `Result`) => ``null`` \| `Partial`<`Param`\> \| `Promise`<`Partial`<`Param`\>\> | The function for calculating next parameter from the operation result. Normally the parameter controls paging, This function should return null when next invocation of the operation function is not desired. If next invocation is desired, the return value of this function can be a Promise or not a Promise. |
 | `collect` | (`collection`: `Collection`, `result`: `Result`) => `Collection` | the function for merging operation result into the collection |
 | `initialCollection` | `Collection` | initial collection which would be the first argument passed into the first invocation of the collect function |
 | `initialParameter` | `Partial`<`Param`\> | the parameter for the first operation |
@@ -346,13 +550,24 @@ const domainNameObjects = await PromiseUtils.repeat(
 
 Promise of collection of all the results returned by the operation function
 
+**`Example`**
+
+```ts
+const domainNameObjects = await PromiseUtils.repeat(
+  pagingParam => apig.getDomainNames({limit: 500, ...pagingParam}).promise(),
+  response => response.position? {position: response.position} : null,
+  (collection, response) => collection.concat(response.items!),
+  [] as APIGateway.DomainName[],
+);
+```
+
 ___
 
 ##### synchronised
 
 ▸ `Static` **synchronised**<`T`\>(`lock`, `operation`): `Promise`<`T`\>
 
-This is just another spelling of [PromiseUtils.synchronized](#synchronized).
+This is just another spelling of [synchronized](#synchronized).
 
 ###### Type parameters
 
@@ -410,11 +625,11 @@ ___
 
 ▸ `Static` **timeoutReject**<`T`, `R`\>(`operation`, `ms`, `rejectReason`): `Promise`<`T`\>
 
-Apply timeout to a Promise. In case timeout happens, reject with the reason specified.
-If timeout does not happen, the resolved result or rejection reason of the original Promise would be the outcome of the Promise returned from this function.
-If timeout does not happen and the 'rejectReason' parameter is a function, the function won't be called.
-The 'operation' parameter's rejection would not be handled by this function, you may want to handle it outside of this function,
-just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
+Applies a timeout to a Promise or a function that returns a Promise.
+If the timeout occurs, rejects with the specified reason.
+If the timeout doesn't occur, the resolved result or rejection reason of the original Promise will be the outcome of the Promise returned from this function.
+If the 'reason' parameter is a function and timeout doesn't occur, the function won't be called.
+The rejection of the 'operation' parameter is not handled by this function, you may want to handle it outside of this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
 
 ###### Type parameters
 
@@ -427,15 +642,15 @@ just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Pro
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `operation` | `Promise`<`T`\> | the original Promise for which timeout would be applied |
-| `ms` | `number` | number of milliseconds for the timeout |
-| `rejectReason` | `R` \| `PromiseLike`<`R`\> \| () => `R` \| `PromiseLike`<`R`\> | the reason of the rejection in case timeout happens, or a function that supplies the reason. |
+| `operation` | `Promise`<`T`\> \| () => `Promise`<`T`\> | The original Promise or a function that returns a Promise for which the timeout will be applied. |
+| `ms` | `number` | The number of milliseconds for the timeout. |
+| `rejectReason` | `R` \| `PromiseLike`<`R`\> \| () => `R` \| `PromiseLike`<`R`\> | The reason to reject with if the timeout occurs, or a function that supplies the reason. |
 
 ###### Returns
 
 `Promise`<`T`\>
 
-the new Promise that rejects with the specified reason in case timeout happens
+A new Promise that rejects with the specified reason if the timeout occurs.
 
 ___
 
@@ -443,11 +658,11 @@ ___
 
 ▸ `Static` **timeoutResolve**<`T`\>(`operation`, `ms`, `result?`): `Promise`<`T`\>
 
-Apply timeout to a Promise. In case timeout happens, resolve to the result specified.
-If timeout does not happen, the resolved result or rejection reason of the original Promise would be the outcome of the Promise returned from this function.
-If timeout does not happen and the 'result' parameter is a function, the function won't be called.
-The 'operation' parameter's rejection would not be handled by this function, you may want to handle it outside of this function,
-just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
+Applies a timeout to a Promise or a function that returns a Promise.
+If the timeout occurs, resolves to the specified result.
+If the timeout doesn't occur, the resolved result or rejection reason of the original Promise will be the outcome of the Promise returned from this function.
+If the 'result' parameter is a function and timeout doesn't occur, the function won't be called.
+The rejection of the 'operation' parameter is not handled by this function, you may want to handle it outside of this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
 
 ###### Type parameters
 
@@ -459,15 +674,15 @@ just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Pro
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `operation` | `Promise`<`T`\> | the original Promise for which timeout would be applied |
-| `ms` | `number` | number of milliseconds for the timeout |
-| `result?` | `T` \| `PromiseLike`<`T`\> \| () => `T` \| `PromiseLike`<`T`\> | the result to be resolved in case timeout happens, or a function that supplies the reuslt. |
+| `operation` | `Promise`<`T`\> \| () => `Promise`<`T`\> | The original Promise or a function that returns a Promise for which the timeout will be applied. |
+| `ms` | `number` | The number of milliseconds for the timeout. |
+| `result?` | `T` \| `PromiseLike`<`T`\> \| () => `T` \| `PromiseLike`<`T`\> | The result to be resolved with if the timeout occurs, or a function that supplies the result. |
 
 ###### Returns
 
 `Promise`<`T`\>
 
-the new Promise that resolves to the specified result in case timeout happens
+A new Promise that resolves to the specified result if the timeout occurs.
 
 ___
 
@@ -477,14 +692,6 @@ ___
 
 Do an operation repeatedly until a criteria is met.
 
-**`example`**
-```javascript
-
-const result = await PromiseUtils.withRetry(() => doSomething(), [100, 200, 300, 500, 800, 1000]);
-const result2 = await PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(FIBONACCI_SEQUENCE[i], 10), err => err.statusCode === 429);
-const result3 = await PromiseUtils.withRetry(() => doSomething(), attempt => attempt <= 8 ? 1000 * Math.min(FIBONACCI_SEQUENCE[attempt - 1], 10) : undefined, err => err.statusCode === 429);
-
-```
 ###### Type parameters
 
 | Name | Type | Description |
@@ -497,8 +704,8 @@ const result3 = await PromiseUtils.withRetry(() => doSomething(), attempt => att
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `operation` | (`attempt`: `number`, `previousResult`: `undefined` \| `Result`, `previousError`: `undefined` \| `TError`) => `Promise`<`Result`\> | a function that outputs a Promise result, normally the operation does not use its arguments |
-| `backoff` | `number`[] \| (`attempt`: `number`, `previousResult`: `undefined` \| `Result`, `previousError`: `undefined` \| `TError`) => `undefined` \| `number` | Array of retry backoff periods (unit: milliseconds) or function for calculating them.                If retry is desired, before making next call to the operation the desired backoff period would be waited.                If the array runs out of elements or the function returns `undefined` or either the array or the function returns a negative number,                there would be no further call to the operation.                The `attempt` argument passed into backoff function starts from 1 because the function is called right after the first attempt and before the first retry. |
-| `shouldRetry` | (`previousError`: `undefined` \| `TError`, `previousResult`: `undefined` \| `Result`, `attempt`: `number`) => `boolean` | Predicate function for deciding whether another call to the operation should happen.                    If this argument is not defined, retry would happen whenever the operation rejects with an error.                    `shouldRetry` would be evaluated before `backoff`.                    The `attempt` argument passed into shouldRetry function starts from 1. |
+| `backoff` | `number`[] \| (`attempt`: `number`, `previousResult`: `undefined` \| `Result`, `previousError`: `undefined` \| `TError`) => `undefined` \| `number` | Array of retry backoff periods (unit: milliseconds) or function for calculating them. If retry is desired, before making next call to the operation the desired backoff period would be waited. If the array runs out of elements or the function returns `undefined` or either the array or the function returns a negative number, there would be no further call to the operation. The `attempt` argument passed into backoff function starts from 1 because the function is called right after the first attempt and before the first retry. |
+| `shouldRetry` | (`previousError`: `undefined` \| `TError`, `previousResult`: `undefined` \| `Result`, `attempt`: `number`) => `boolean` | Predicate function for deciding whether another call to the operation should happen. If this argument is not defined, retry would happen whenever the operation rejects with an error. `shouldRetry` would be evaluated before `backoff`. The `attempt` argument passed into shouldRetry function starts from 1. |
 
 ###### Returns
 
@@ -506,40 +713,38 @@ const result3 = await PromiseUtils.withRetry(() => doSomething(), attempt => att
 
 Promise of the operation result potentially with retries already applied
 
+**`Example`**
+
+```ts
+const result = await PromiseUtils.withRetry(() => doSomething(), [100, 200, 300, 500, 800, 1000]);
+const result2 = await PromiseUtils.withRetry(() => doSomething(), Array.from({length: 10}, (_v, i) => 1000 * Math.min(FIBONACCI_SEQUENCE[i], 10), err => err.statusCode === 429);
+const result3 = await PromiseUtils.withRetry(() => doSomething(), attempt => attempt <= 8 ? 1000 * Math.min(FIBONACCI_SEQUENCE[attempt - 1], 10) : undefined, err => err.statusCode === 429);
+```
+
 ## Enums
 
 
 <a name="enumspromisestatemd"></a>
 
-[@handy-common-utils/promise-utils](#readmemd) / PromiseState
-
 ### Enumeration: PromiseState
 
 The state of a Promise can only be one of: Pending, Fulfilled, and Rejected.
 
-#### Table of contents
-
-##### Enumeration members
-
-- [Fulfilled](#fulfilled)
-- [Pending](#pending)
-- [Rejected](#rejected)
-
-#### Enumeration members
+#### Enumeration Members
 
 ##### Fulfilled
 
-• **Fulfilled** = `"Fulfilled"`
+• **Fulfilled** = ``"Fulfilled"``
 
 ___
 
 ##### Pending
 
-• **Pending** = `"Pending"`
+• **Pending** = ``"Pending"``
 
 ___
 
 ##### Rejected
 
-• **Rejected** = `"Rejected"`
+• **Rejected** = ``"Rejected"``
 <!-- API end -->

package/dist/promise-utils.d.ts

@@ -38,7 +38,7 @@ export declare abstract class PromiseUtils {
      * @example
      * const domainNameObjects = await PromiseUtils.repeat(
      *   pagingParam => apig.getDomainNames({limit: 500, ...pagingParam}).promise(),
-     *   esponse => response.position? {position: response.position} : null,
+     *   response => response.position? {position: response.position} : null,
      *   (collection, response) => collection.concat(response.items!),
      *   [] as APIGateway.DomainName[],
      * );
@@ -111,7 +111,7 @@ export declare abstract class PromiseUtils {
     /**
      * Create a Promise that resolves after number of milliseconds specified
      * @param ms number of milliseconds after which the created Promise would resolve
-     * @param result the result to be resolved for the Promise, or a function that supplies the reuslt.
+     * @param result the result to be resolved for the Promise, or a function that supplies the result.
      * @returns the new Promise created
      */
     static delayedResolve<T>(ms: number, result?: T | PromiseLike<T> | (() => (T | PromiseLike<T>))): Promise<T>;
@@ -124,34 +124,36 @@ export declare abstract class PromiseUtils {
      */
     static delayedReject<T = never, R = any>(ms: number, reason: R | PromiseLike<R> | (() => R | PromiseLike<R>)): Promise<T>;
     /**
-     * Apply timeout to a Promise. In case timeout happens, resolve to the result specified.
-     * If timeout does not happen, the resolved result or rejection reason of the original Promise would be the outcome of the Promise returned from this function.
-     * If timeout does not happen and the 'result' parameter is a function, the function won't be called.
-     * The 'operation' parameter's rejection would not be handled by this function, you may want to handle it outside of this function,
-     * just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
-     * @param operation the original Promise for which timeout would be applied
-     * @param ms number of milliseconds for the timeout
-     * @param result the result to be resolved in case timeout happens, or a function that supplies the reuslt.
-     * @return the new Promise that resolves to the specified result in case timeout happens
+     * Applies a timeout to a Promise or a function that returns a Promise.
+     * If the timeout occurs, resolves to the specified result.
+     * If the timeout doesn't occur, the resolved result or rejection reason of the original Promise will be the outcome of the Promise returned from this function.
+     * If the 'result' parameter is a function and timeout doesn't occur, the function won't be called.
+     * The rejection of the 'operation' parameter is not handled by this function, you may want to handle it outside of this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
+     *
+     * @param operation The original Promise or a function that returns a Promise for which the timeout will be applied.
+     * @param ms The number of milliseconds for the timeout.
+     * @param result The result to be resolved with if the timeout occurs, or a function that supplies the result.
+     * @return A new Promise that resolves to the specified result if the timeout occurs.
      */
-    static timeoutResolve<T>(operation: Promise<T>, ms: number, result?: T | PromiseLike<T> | (() => (T | PromiseLike<T>)) | undefined): Promise<T>;
+    static timeoutResolve<T>(operation: Promise<T> | (() => Promise<T>), ms: number, result?: T | PromiseLike<T> | (() => (T | PromiseLike<T>)) | undefined): Promise<T>;
     /**
-     * Apply timeout to a Promise. In case timeout happens, reject with the reason specified.
-     * If timeout does not happen, the resolved result or rejection reason of the original Promise would be the outcome of the Promise returned from this function.
-     * If timeout does not happen and the 'rejectReason' parameter is a function, the function won't be called.
-     * The 'operation' parameter's rejection would not be handled by this function, you may want to handle it outside of this function,
-     * just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
-     * @param operation the original Promise for which timeout would be applied
-     * @param ms number of milliseconds for the timeout
-     * @param rejectReason the reason of the rejection in case timeout happens, or a function that supplies the reason.
-     * @return the new Promise that rejects with the specified reason in case timeout happens
+     * Applies a timeout to a Promise or a function that returns a Promise.
+     * If the timeout occurs, rejects with the specified reason.
+     * If the timeout doesn't occur, the resolved result or rejection reason of the original Promise will be the outcome of the Promise returned from this function.
+     * If the 'reason' parameter is a function and timeout doesn't occur, the function won't be called.
+     * The rejection of the 'operation' parameter is not handled by this function, you may want to handle it outside of this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
+     *
+     * @param operation The original Promise or a function that returns a Promise for which the timeout will be applied.
+     * @param ms The number of milliseconds for the timeout.
+     * @param rejectReason The reason to reject with if the timeout occurs, or a function that supplies the reason.
+     * @return A new Promise that rejects with the specified reason if the timeout occurs.
      */
-    static timeoutReject<T = never, R = any>(operation: Promise<T>, ms: number, rejectReason: R | PromiseLike<R> | (() => R | PromiseLike<R>)): Promise<T>;
+    static timeoutReject<T = never, R = any>(operation: Promise<T> | (() => Promise<T>), ms: number, rejectReason: R | PromiseLike<R> | (() => R | PromiseLike<R>)): Promise<T>;
     /**
      * Get the state of the Promise.
      * Please note that the returned value is a Promise, although it resolves immediately.
      * @param p the Promise for which we would like to know its state
-     * @return A Promise that resolves immediately cotaining the state of the input Promise
+     * @return A Promise that resolves immediately containing the state of the input Promise
      */
     static promiseState(p: Promise<any>): Promise<PromiseState>;
     private static synchronizationLocks;

package/dist/promise-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promise-utils.d.ts","sourceRoot":"","sources":["../src/promise-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"promise-utils.d.ts","sourceRoot":"","sources":["../src/promise-utils.ts"],"names":[],"mappings":"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"}

package/dist/promise-utils.js

@@ -33,7 +33,7 @@ var PromiseState;
     PromiseState["Pending"] = "Pending";
     PromiseState["Fulfilled"] = "Fulfilled";
     PromiseState["Rejected"] = "Rejected";
-})(PromiseState = exports.PromiseState || (exports.PromiseState = {}));
+})(PromiseState || (exports.PromiseState = PromiseState = {}));
 class PromiseUtils {
     /**
      * Do an operation repeatedly and collect all the results.
@@ -42,7 +42,7 @@ class PromiseUtils {
      * @example
      * const domainNameObjects = await PromiseUtils.repeat(
      *   pagingParam => apig.getDomainNames({limit: 500, ...pagingParam}).promise(),
-     *   esponse => response.position? {position: response.position} : null,
+     *   response => response.position? {position: response.position} : null,
      *   (collection, response) => collection.concat(response.items!),
      *   [] as APIGateway.DomainName[],
      * );
@@ -167,7 +167,7 @@ class PromiseUtils {
     /**
      * Create a Promise that resolves after number of milliseconds specified
      * @param ms number of milliseconds after which the created Promise would resolve
-     * @param result the result to be resolved for the Promise, or a function that supplies the reuslt.
+     * @param result the result to be resolved for the Promise, or a function that supplies the result.
      * @returns the new Promise created
      */
     static delayedResolve(ms, result) {
@@ -189,40 +189,44 @@ class PromiseUtils {
         }, ms));
     }
     /**
-     * Apply timeout to a Promise. In case timeout happens, resolve to the result specified.
-     * If timeout does not happen, the resolved result or rejection reason of the original Promise would be the outcome of the Promise returned from this function.
-     * If timeout does not happen and the 'result' parameter is a function, the function won't be called.
-     * The 'operation' parameter's rejection would not be handled by this function, you may want to handle it outside of this function,
-     * just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
-     * @param operation the original Promise for which timeout would be applied
-     * @param ms number of milliseconds for the timeout
-     * @param result the result to be resolved in case timeout happens, or a function that supplies the reuslt.
-     * @return the new Promise that resolves to the specified result in case timeout happens
+     * Applies a timeout to a Promise or a function that returns a Promise.
+     * If the timeout occurs, resolves to the specified result.
+     * If the timeout doesn't occur, the resolved result or rejection reason of the original Promise will be the outcome of the Promise returned from this function.
+     * If the 'result' parameter is a function and timeout doesn't occur, the function won't be called.
+     * The rejection of the 'operation' parameter is not handled by this function, you may want to handle it outside of this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
+     *
+     * @param operation The original Promise or a function that returns a Promise for which the timeout will be applied.
+     * @param ms The number of milliseconds for the timeout.
+     * @param result The result to be resolved with if the timeout occurs, or a function that supplies the result.
+     * @return A new Promise that resolves to the specified result if the timeout occurs.
      */
     static timeoutResolve(operation, ms, result) {
+        const promise = typeof operation === 'function' ? operation() : operation;
         return Promise.race([
-            operation,
-            PromiseUtils.delayedResolve(ms, () => PromiseUtils.promiseState(operation)
+            promise,
+            PromiseUtils.delayedResolve(ms, () => PromiseUtils.promiseState(promise)
                 .then(state => state === PromiseState.Pending ?
                 (typeof result === 'function' ? result() : result) :
                 {})),
         ]);
     }
     /**
-     * Apply timeout to a Promise. In case timeout happens, reject with the reason specified.
-     * If timeout does not happen, the resolved result or rejection reason of the original Promise would be the outcome of the Promise returned from this function.
-     * If timeout does not happen and the 'rejectReason' parameter is a function, the function won't be called.
-     * The 'operation' parameter's rejection would not be handled by this function, you may want to handle it outside of this function,
-     * just for avoiding warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
-     * @param operation the original Promise for which timeout would be applied
-     * @param ms number of milliseconds for the timeout
-     * @param rejectReason the reason of the rejection in case timeout happens, or a function that supplies the reason.
-     * @return the new Promise that rejects with the specified reason in case timeout happens
+     * Applies a timeout to a Promise or a function that returns a Promise.
+     * If the timeout occurs, rejects with the specified reason.
+     * If the timeout doesn't occur, the resolved result or rejection reason of the original Promise will be the outcome of the Promise returned from this function.
+     * If the 'reason' parameter is a function and timeout doesn't occur, the function won't be called.
+     * The rejection of the 'operation' parameter is not handled by this function, you may want to handle it outside of this function to avoid warnings like "(node:4330) PromiseRejectionHandledWarning: Promise rejection was handled asynchronously".
+     *
+     * @param operation The original Promise or a function that returns a Promise for which the timeout will be applied.
+     * @param ms The number of milliseconds for the timeout.
+     * @param rejectReason The reason to reject with if the timeout occurs, or a function that supplies the reason.
+     * @return A new Promise that rejects with the specified reason if the timeout occurs.
      */
     static timeoutReject(operation, ms, rejectReason) {
+        const promise = typeof operation === 'function' ? operation() : operation;
         return Promise.race([
-            operation,
-            PromiseUtils.delayedReject(ms, () => PromiseUtils.promiseState(operation)
+            promise,
+            PromiseUtils.delayedReject(ms, () => PromiseUtils.promiseState(promise)
                 .then(state => state === PromiseState.Pending ?
                 (typeof rejectReason === 'function' ? rejectReason() : rejectReason) :
                 {})),
@@ -232,7 +236,7 @@ class PromiseUtils {
      * Get the state of the Promise.
      * Please note that the returned value is a Promise, although it resolves immediately.
      * @param p the Promise for which we would like to know its state
-     * @return A Promise that resolves immediately cotaining the state of the input Promise
+     * @return A Promise that resolves immediately containing the state of the input Promise
      */
     static promiseState(p) {
         const t = {};
@@ -257,16 +261,19 @@ class PromiseUtils {
             previousState = await PromiseUtils.promiseState(previousResultPromise);
         }
         switch (previousState) {
-            case PromiseState.Pending: // concurrency
+            case PromiseState.Pending: { // concurrency
                 resultPromise = previousResultPromise.then(result => operation(PromiseState.Pending, PromiseState.Fulfilled, result), error => operation(PromiseState.Pending, PromiseState.Rejected, error));
                 break;
-            case undefined: // no concurrency and no history
+            }
+            case undefined: { // no concurrency and no history
                 // eslint-disable-next-line unicorn/no-useless-undefined
                 resultPromise = operation(undefined, undefined, undefined);
                 break;
-            default: // no concurrency but with history
+            }
+            default: { // no concurrency but with history
                 resultPromise = operation(previousState, previousState, await previousResultPromise.catch(error => error));
                 break;
+            }
         }
         PromiseUtils.synchronizationLocks.set(lock, resultPromise);
         return resultPromise;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@handy-common-utils/promise-utils",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "description": "Promise related utilities",
   "scripts": {
     "pretest": "eslint . --ext .ts",
     "test": "nyc mocha",
     "prepare": "shx rm -rf dist && tsc && es-check",
-    "preversion": "generate-api-docs-and-update-readme && replace-in-file README.md '[^#]### Functions[\\s\\S]*?## Classes' '## Classes' && git add README.md"
+    "preversion": "generate-api-docs-and-update-readme && git add README.md"
   },
   "files": [
     "package.json",
@@ -16,11 +16,8 @@
   "types": "dist/promise-utils.d.ts",
   "bin": {},
   "devDependencies": {
-    "@handy-common-utils/dev-dependencies": "^1.0.31",
-    "@types/chai-as-promised": "^7.1.3",
-    "chai-as-promised": "^7.1.1",
-    "es-check": "^5.2.3",
-    "eslint": "^7.32.0"
+    "@handy-common-utils/dev-dependencies-mocha": "^1.3.1",
+    "@types/node": "^18.17.1"
   },
   "publishConfig": {
     "access": "public"
@@ -34,10 +31,18 @@
     "url": "https://github.com/handy-common-utils/promise-utils/issues"
   },
   "keywords": [
-    "prmomise",
+    "promise",
     "utils",
+    "retry",
+    "delay",
+    "resolve",
+    "reject",
     "utilities"
   ],
   "author": "James Hu",
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "volta": {
+    "node": "18.17.0",
+    "npm": "9.6.7"
+  }
 }