@handy-common-utils/promise-utils 1.4.0 → 1.5.0

package/dist/promise-utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.promiseState = exports.synchronised = exports.synchronized = exports.timeoutReject = exports.timeoutResolve = exports.delayedReject = exports.delayedResolve = exports.inParallel = exports.withRetry = exports.repeat = exports.PromiseUtils = exports.PromiseState = exports.EXPONENTIAL_SEQUENCE = exports.FIBONACCI_SEQUENCE = void 0;
+exports.promiseState = exports.synchronised = exports.synchronized = exports.timeoutReject = exports.timeoutResolve = exports.delayedReject = exports.delayedResolve = exports.inParallel = exports.withConcurrency = exports.withRetry = exports.repeat = exports.PromiseUtils = exports.PromiseState = exports.EXPONENTIAL_SEQUENCE = exports.FIBONACCI_SEQUENCE = void 0;
 /**
  * Array of 25 Fibonacci numbers starting from 1 up to 317811.
  * It can be used to form your own backoff interval array.
@@ -36,8 +36,8 @@ var PromiseState;
 })(PromiseState || (exports.PromiseState = PromiseState = {}));
 class PromiseUtils {
     /**
-     * Do an operation repeatedly and collect all the results.
-     * This function is useful for client side pagination.
+     * Executes an operation repeatedly and collects all the results.
+     * This function is very useful for many scenarios, such like client-side pagination.
      *
      * @example
      * const domainNameObjects = await PromiseUtils.repeat(
@@ -47,19 +47,19 @@ class PromiseUtils {
      *   [] as APIGateway.DomainName[],
      * );
      *
-     * @template Result type of the operation result
-     * @template Param  type of the input to the operation, normally the input is a paging parameter
-     * @template Collection type of the returned value of this function
+     * @template Result The type of the operation result.
+     * @template Param The type of the input to the operation, typically a paging parameter.
+     * @template Collection The type of the collection returned by this function.
      *
-     * @param operation a function that takes paging parameter as input and outputs a result, normally the operation supports paging
-     * @param nextParameter 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.
-     * @param collect the function for merging operation result into the collection
-     * @param initialCollection initial collection which would be the first argument passed into the first invocation of the collect function
-     * @param initialParameter the parameter for the first operation
-     * @returns Promise of collection of all the results returned by the operation function
+     * @param operation A function that takes a parameter as input and returns a result. Typically, the parameter has optional fields to control paging.
+     * @param nextParameter 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.
+     * @param collect A function for merging the operation result into the collection.
+     * @param initialCollection The initial collection, which will be the first argument passed to the first invocation of the collect function.
+     * @param initialParameter The parameter for the first operation.
+     * @returns A promise that resolves to a collection of all the results returned by the operation function.
      *
      */
     static async repeat(operation, nextParameter, collect, initialCollection, initialParameter = {}) {
@@ -77,27 +77,26 @@ class PromiseUtils {
         return collection;
     }
     /**
-     * Do an operation repeatedly until a criteria is met.
+     * Repeatedly performs an operation until a specified criteria is met.
      *
      * @example
      * 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);
      *
-     * @template Result type of the operation result
-     * @template TError  type of the possible error that could be generated by the operation
+     * @template Result Type of the operation result.
+     * @template TError Type of the possible error that could be generated by the operation.
      *
-     * @param operation a function that outputs a Promise result, normally the operation does not use its arguments
-     * @param backoff 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.
-     * @param shouldRetry 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 Promise of the operation result potentially with retries already applied
+     * @param operation A function that outputs a Promise result. Typically, the operation does not use its arguments.
+     * @param backoff 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.
+     * @param shouldRetry 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.
+     * @returns A promise of the operation result, potentially with retries applied.
      */
     static async withRetry(operation, backoff, shouldRetry = (previousError, _previousResult, _attempt) => previousError !== undefined) {
         let attempt = 1;
@@ -118,21 +117,51 @@ class PromiseUtils {
         return finalOutcome.result;
     }
     /**
-     * Run multiple jobs/operations in parallel.
+     * Executes multiple jobs/operations with a specified level of concurrency.
      *
-     * By default this function does not throw / reject with error when any of the job/operation fails.
-     * Operation errors are returned together with operation results in the same returned array.
-     * That also means this function only returns when all the jobs/operations settle (either resolve or reject).
+     * Unlike `inParallel(...)`, this function may throw or reject an error when a job/operation fails.
+     * When an error is re-thrown, remaining operations will not be executed.
+     * If you want all the operations to always be executed, use {@link PromiseUtils.inParallel} instead.
      *
-     * However, if options.abortOnError is true, this function throws / rejects with error when any of the job/operation fails.
-     * That also means, some of the jobs/operations may not get the chance to be executed if one of them fails.
+     * @example
+     * // At any time, there would be no more than 5 concurrency API calls. Error would be re-thrown immediately when it occurs.
+     * const attributes = await PromiseUtils.withConcurrency(5, topicArns, async (topicArn) => {
+     *   const topicAttributes = (await sns.getTopicAttributes({ TopicArn: topicArn }).promise()).Attributes!;
+     *   return topicAttributes;
+     * });
+     *
+     *
+     * @template Data   The type of the job data, typically an Array.
+     * @template Result The type of the return value from the operation function.
+     *
+     * @param concurrency The number of jobs/operations to run concurrently.
+     * @param jobs The job data to be processed. This function can handle an infinite or unknown number of elements safely.
+     * @param operation The function that processes job data asynchronously.
+     * @returns A promise that resolves to an array containing the results from the operation function.
+     *          The results in the returned array are in the same order as the corresponding elements in the jobs array.
+     */
+    static async withConcurrency(concurrency, jobs, operation) {
+        return (0, exports.inParallel)(concurrency, jobs, operation);
+    }
+    /**
+     * Executes multiple jobs/operations in parallel. By default, all operations are executed regardless of any failures.
+     * In most cases, using {@link PromiseUtils.withConcurrency} might be more convenient.
+     *
+     * By default, this function does not throw or reject an error when any job/operation fails.
+     * Errors from operations are returned alongside results in the returned array.
+     * This function only resolves when all jobs/operations are settled (either resolved or rejected).
+     *
+     * If `options.abortOnError` is set to true, this function throws (or rejects with) an error immediately when any job/operation fails.
+     * In this mode, some jobs/operations may not be executed if one fails.
      *
      * @example
-     * const attributesAndPossibleErrors = await PromiseUtils.inParallel(5, topicArns, async (topicArn) => {
+     * // Capture errors in the returned array
+     * const attributesAndPossibleErrors: Array<JobResult|JobError> = await PromiseUtils.inParallel(5, topicArns, async (topicArn) => {
      *   const topicAttributes = (await sns.getTopicAttributes({ TopicArn: topicArn }).promise()).Attributes!;
      *   return topicAttributes;
      * });
      *
+     * // Abort on the first error
      * let results: Array<JobResult>;
      * try {
      *   results = await PromiseUtils.inParallel(100, jobs, async (job) => processor.process(job), { abortOnError: true });
@@ -140,17 +169,18 @@ class PromiseUtils {
      *   // handle the error
      * }
      *
-     * @template Data   Type of the job data, usually it would be an Array
-     * @template Result Type of the return value of the operation function
+     * @template Data   The type of the job data, typically an Array.
+     * @template Result The type of the return value from the operation function.
+     * @template TError The type for the error that could be thrown from the operation function, defaults to `Result`.
      *
-     * @param parallelism how many jobs/operations can be running at the same time
-     * @param jobs        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.
-     * @param operation   the function that turns job data into result asynchronously
-     * @param options     Options for controlling the behavior of this function.
-     * @returns Promise of void if the operation function does not return a value,
-     *          or promise of an array containing outcomes from the operation function.
-     *          In the returned array containing outcomes, each element is either the fulfilled result, or the rejected error/reason.
+     * @param parallelism The number of jobs/operations to run concurrently.
+     * @param jobs The job data to be processed. This function can safely handle an infinite or unknown number of elements.
+     * @param operation The function that processes job data asynchronously.
+     * @param options Options to control the function's behavior.
+     * @param options.abortOnError If true, the function aborts and throws an error on the first failed operation.
+     * @returns A promise that resolves to an array containing the results of the operations.
+     *  Each element is either a fulfilled result or a rejected error/reason.
+     *  The results or errors in the returned array are in the same order as the corresponding elements in the jobs array.
      */
     static async inParallel(parallelism, jobs, operation, options) {
         if (parallelism < 1) {
@@ -176,21 +206,23 @@ class PromiseUtils {
         return jobResults;
     }
     /**
-     * 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 result.
-     * @returns the new Promise created
+     * Creates a Promise that resolves after a specified number of milliseconds.
+     *
+     * @param ms The number of milliseconds after which the created Promise will resolve.
+     * @param result The result to be resolved by the Promise, or a function that supplies the result.
+     * @returns A new Promise that resolves with the specified result after the specified delay.
      */
     static delayedResolve(ms, result) {
         // eslint-disable-next-line no-promise-executor-return
         return new Promise(resolve => setTimeout(() => resolve(typeof result === 'function' ? result() : result), ms));
     }
     /**
-     * Create a Promise that rejects after number of milliseconds specified.
-     * @param ms number of milliseconds after which the created Promise would reject
-     * @param reason the reason of the rejection for the Promise, or a function that supplies the reason.
-     * If the reason ends up to be a rejected Promise, then the outcome (could be fulfilled or rejected) of it will be the reject reason of the Promise returned.
-     * @returns the new Promise created
+     * Creates a Promise that rejects after a specified number of milliseconds.
+     *
+     * @param ms The number of milliseconds after which the created Promise will reject.
+     * @param reason The reason for the rejection, or a function that supplies the reason.
+     *               If the reason is a rejected Promise, the outcome of it will be the rejection reason of the returned Promise.
+     * @returns A new Promise that rejects with the specified reason after the specified delay.
      */
     static delayedReject(ms, reason) {
         // eslint-disable-next-line no-promise-executor-return
@@ -201,15 +233,16 @@ class PromiseUtils {
     }
     /**
      * 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".
+     * 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."
      *
-     * @param operation The original Promise or a function that returns a Promise for which the timeout will be applied.
+     * @param operation The original Promise or a function that returns a Promise to 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.
+     * @param result The result to resolve with if the timeout occurs, or a function that supplies the result.
+     * @returns 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;
@@ -223,15 +256,15 @@ class PromiseUtils {
     }
     /**
      * 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".
+     * 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."
      *
-     * @param operation The original Promise or a function that returns a Promise for which the timeout will be applied.
+     * @param operation The original Promise or a function that returns a Promise to 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.
+     * @returns 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;
@@ -244,10 +277,11 @@ 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 containing the state of the input Promise
+     * Retrieves the state of the specified Promise.
+     * Note: The returned value is a Promise that resolves immediately.
+     *
+     * @param p The Promise whose state is to be determined.
+     * @returns A Promise that resolves immediately with the state of the input Promise.
      */
     static promiseState(p) {
         const t = {};
@@ -255,14 +289,16 @@ class PromiseUtils {
             .then(v => (v === t) ? PromiseState.Pending : PromiseState.Fulfilled, () => PromiseState.Rejected);
     }
     /**
-     * Equivalent of `synchronized` in Java.
-     * In any situation there's 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 (could be the fulfilled result or the rejected reason) of the previous operation.
-     * In case there is no previous invocation, state, settledState and result would all be undefined.
-     * @param lock        the object (could be a string, a number, or `this` in a class) that is used to apply the lock
-     * @param operation   function for doing the computation and returning a Promise
-     * @returns the result of the operation function
+     * 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.
+     *
+     * @param lock The object (such as a string, a number, or `this` in a class) used to identify the lock.
+     * @param operation The function that performs the computation and returns a Promise.
+     * @returns The result of the operation function.
      */
     static async synchronized(lock, operation) {
         let resultPromise;
@@ -291,9 +327,9 @@ class PromiseUtils {
     }
     /**
      * This is just another spelling of {@link PromiseUtils.synchronized}.
-     * @param lock        the object (could be a string, a number, or `this` in a class) that is used to apply the lock
-     * @param operation   function for doing the computation and returning a Promise
-     * @returns the result of the operation function
+     * @param lock The object (such as a string, a number, or `this` in a class) used to identify the lock.
+     * @param operation The function that performs the computation and returns a Promise.
+     * @returns The result of the operation function.
      */
     static async synchronised(lock, operation) {
         return PromiseUtils.synchronized(lock, operation);
@@ -309,6 +345,10 @@ exports.repeat = PromiseUtils.repeat;
  * See {@link PromiseUtils.withRetry} for full documentation.
  */
 exports.withRetry = PromiseUtils.withRetry;
+/**
+ * See {@link PromiseUtils.withConcurrency} for full documentation.
+ */
+exports.withConcurrency = PromiseUtils.withConcurrency;
 /**
  * See {@link PromiseUtils.inParallel} for full documentation.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handy-common-utils/promise-utils",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Promise related utilities",
   "scripts": {
     "pretest": "eslint . --ext .ts",
@@ -16,7 +16,7 @@
   "types": "dist/promise-utils.d.ts",
   "bin": {},
   "devDependencies": {
-    "@handy-common-utils/dev-dependencies-mocha": "^1.3.1",
+    "@handy-common-utils/dev-dependencies-mocha": "^1.5.4",
     "@types/node": "^18.17.1"
   },
   "publishConfig": {