@creejs/commons-lang 2.0.0 → 2.0.2

package/lib/promise-utils.js

@@ -1,317 +0,0 @@
-// @ts-nocheck
-'use strict'
-
-/**
- * @module PromiseUtils
- * @description Promise utility functions for enhanced promise handling, including timeout, delay, parallel execution, and series execution.
- */
-
-const { assertNumber, assertPromise, assertArray, assertFunction } = require('./type-assert')
-const { isPromise, isNumber } = require('./type-utils')
-/**
- * Creates a "Deferred" Object with Timeout support
- * 1. timeout=-1, it means no timeout check
- * @param {number} [timeout=-1] - Timeout duration in milliseconds
- * @param {string} [timeoutMessage]
- * @returns {{promise: Promise<*>, reject: function, resolve: function}}
- */
-function defer (timeout = -1, timeoutMessage) {
-  assertNumber(timeout)
-  const rtnVal = {}
-
-  let timerHandler
-  if (timeout >= 0) {
-    rtnVal.timerHandler = timerHandler = setTimeout(() => {
-      clearTimeout(timerHandler) // must clear it
-      rtnVal.timerCleared = true // easy to check in test case
-      rtnVal.reject(new Error(timeoutMessage ?? `Promise Timeout: ${timeout}ms`))
-    }, timeout)
-    rtnVal.timerHandler = timerHandler
-  }
-
-  rtnVal.promise = new Promise((resolve, reject) => {
-    rtnVal.resolve = (...args) => {
-      if (timerHandler != null) {
-        clearTimeout(timerHandler) // must clear it
-        rtnVal.timerCleared = true // easy to check in test case
-      }
-      rtnVal.resolved = true
-      resolve(...args)
-    }
-
-    rtnVal.reject = (err) => {
-      if (timerHandler != null) {
-        clearTimeout(timerHandler) // must clear it
-        rtnVal.timerCleared = true // easy to check in test case
-      }
-      rtnVal.rejected = true
-      reject(err)
-    }
-  })
-  rtnVal.promise.cancel = () => {
-    if (timerHandler != null) {
-      clearTimeout(timerHandler) // must clear it
-      rtnVal.timerCleared = true // easy to check in test case
-    }
-    rtnVal.rejected = true // easy to check in test case
-    rtnVal.canceled = rtnVal.promise.canceled = true // easy to check in test case
-    rtnVal.reject(new Error('Cancelled'))
-  }
-  return rtnVal
-}
-
-/**
- * Creates a timeout wrapper around a promise that rejects if the promise doesn't resolve within the given time.
- * @param {Promise<*>} promise - The promise to wrap with a timeout
- * @param {number} [time=1] - Timeout duration in milliseconds
- * @param {string} [message=`Promise Timeout: ${time}ms`] - Custom rejection message
- * @returns {Promise<*>} A new promise that either resolves with the original promise's value, rejects with original promise's error or timeout error
- * @throws {TypeError} If input is not a promise or timeout is not a number
- */
-function timeout (promise, time, message) {
-  assertPromise(promise)
-
-  time = time ?? 1
-  assertNumber(time)
-
-  const deferred = PromiseUtils.defer(time, message)
-  const startTs = Date.now()
-  promise.then((...args) => { // original promise settled, but timeout
-    const elapsed = Date.now() - startTs
-    if (elapsed <= time) {
-      deferred.resolve(...args)
-    } else {
-      deferred.reject(new Error(message ?? `Promise Timeout: ${time}ms`))
-    }
-  }).catch((err) => {
-    // prevent double reject
-    !deferred.resolved && !deferred.rejected && deferred.reject(err)
-  })
-  return deferred.promise
-}
-
-/**
- * Excutes All promises in parallel and returns an array of results.
- *
- * Why:
- * 1. Promise.allSettled() returns
- *    * { status: 'fulfilled', value: any } when promise fulfills
- *    * { status: 'rejected', reason: any } when promise rejects
- * 2. It's NOT convenient to use Promise.allSettled() to get the results of all promises.
- *    * the data structure is not consistent when fullfilled or rejected
- *    * have to check "string" type of status to know sucess or failure
- * @param {Promise} promises
- * @returns {Array<{ok: boolean, result: any}>}
- */
-async function allSettled (promises) {
-  assertArray(promises)
-  const results = await Promise.allSettled(promises)
-  const rtnVal = []
-  for (const result of results) {
-    if (result.status === 'fulfilled') {
-      rtnVal.push({ ok: true, result: result.value })
-    }
-    if (result.status === 'rejected') {
-      rtnVal.push({ ok: false, result: result.reason })
-    }
-  }
-  return rtnVal
-}
-
-/**
-   * Execute the task Function, and ensure it returns a Promise.
-   * @param {function} task
-   * @returns {Promise<*>}
-   */
-function returnValuePromised (task) {
-  try {
-    const taskRtnVal = task()
-    if (isPromise(taskRtnVal)) {
-      return taskRtnVal
-    }
-    return Promise.resolve(taskRtnVal)
-  } catch (e) {
-    return Promise.reject(e)
-  }
-}
-
-/**
-   * Delays a promise by a specified time.
-   * 1. delay(), wait 1ms
-   * 2. delay(1000), wait 1000ms
-   * 3. delay(promise), after promise settled, wait 1000ms
-   * 4. delay(promise, 2000), after promise settled, wait 2000ms
-   *
-   * @param {Promise<*>|number|undefined} [promise] - The input promise to delay
-   * @param {number|undefined} [ms] - Minimum delay in milliseconds (default: 1)
-   * @returns {Promise} A new promise that settles after the delay period
-   */
-function delay (promise, ms) {
-  if (isNumber(promise)) {
-    ms = promise
-    promise = Promise.resolve()
-  } else if (promise == null && ms == null) {
-    ms = 1
-    promise = Promise.resolve()
-  }
-  promise != null && assertPromise(promise)
-  ms = ms ?? 1000
-  assertNumber(ms)
-  const deferred = PromiseUtils.defer()
-  const startTs = Date.now()
-  promise
-    .then((...args) => {
-      const escaped = Date.now() - startTs
-      if (escaped < ms) {
-        setTimeout(() => deferred.resolve(...args), ms - escaped)
-      } else {
-        deferred.resolve(...args)
-      }
-    })
-    .catch((err) => {
-      const escaped = Date.now() - startTs
-      if (escaped < ms) {
-        setTimeout(() => deferred.reject(err), ms - escaped)
-      } else {
-        deferred.reject(err)
-      }
-    })
-  return deferred.promise
-}
-
-/**
-   * Fast-Fail mode to execute Tasks(functions) in series (one after another) and returns their results in order.
-   * 1. function are executed one by one
-   * 2. Fast Fail: if any tasks fail, the whole chain is rejected with the first error
-   * 3. if an element is not function, rejects the whole chain with Error(Not Function)
-   * @param {Function[]} promises
-   * @returns {Promise<Array>} Promise that resolves with an array of results in the same order as input tasks
-   */
-async function series (tasks) {
-  assertArray(tasks)
-  const results = []
-  for (const task of tasks) {
-    assertFunction(task)
-    results.push(await task())
-  }
-  return results
-}
-
-/**
-   * AllSettled Mode to execute Tasks(functions) in series (one after another) and returns their results in order.
-   * 1. tasks are executed one by one
-   * 2. Each result is an object with `ok` (boolean) and `result` (resolved value or error).
-   * 3. if a task is not Function, rejects the whole chain with Error(Not Function)
-   * @param {Function[]} tasks
-   * @returns {Promise<Array<{ok: boolean, result: *}>>}
-   */
-async function seriesAllSettled (tasks) {
-  assertArray(tasks)
-  const results = []
-  for (const task of tasks) {
-    assertFunction(task)
-    try {
-      results.push({ ok: true, result: await task() })
-    } catch (err) {
-      results.push({ ok: false, result: err })
-    }
-  }
-  return results
-}
-
-/**
-   * FastFail Mode to Execute tasks in parallel with a maximum concurrency limit
-   * 1. tasks are executed in parallel with a maximum concurrency limit
-   * 2. rejects whole chain with the first error, when first task fails
-   * @param {Function[]} tasks
-   * @param {number} [maxParallel=5]
-   * @returns {Promise<Array>} Array of resolved values from all promises
-   * @throws {TypeError} If input is not an array of function or maxParallel is not a number
-   */
-async function parallel (tasks, maxParallel = 5) {
-  assertArray(tasks)
-  assertNumber(maxParallel)
-  if (maxParallel <= 0) {
-    throw new Error(`Invalid maxParallel: ${maxParallel}, should > 0`)
-  }
-  tasks.forEach((task) => assertFunction(task))
-  const rtnVal = []
-  // once for all, run all tasks
-  if (tasks.length <= maxParallel) {
-    const resultsForBatch = await Promise.all(tasks.map(task => PromiseUtils.returnValuePromised(task)))
-    rtnVal.push(...resultsForBatch)
-    return rtnVal
-  }
-  // run group by MaxParallel
-  const tasksToRun = []
-  for (const task of tasks) {
-    assertFunction(task)
-    tasksToRun.push(task)
-    if (tasksToRun.length >= maxParallel) {
-      const resultsForBatch = await Promise.all(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
-      rtnVal.push(...resultsForBatch)
-      tasksToRun.length = 0
-    }
-  }
-  // Run all rested
-  if (tasksToRun.length > 0 && tasksToRun.length < maxParallel) {
-    const resultsForBatch = await Promise.all(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
-    rtnVal.push(...resultsForBatch)
-  }
-  return rtnVal
-}
-
-/**
-   * AllSettled Mode to execute tasks in parallel with a maximum concurrency limit
-   * 1. tasks are executed in parallel with a maximum concurrency limit
-   * 2. all tasks will be executed, even some of them failed.
-   * @param {Function[]} tasks
-   * @param {number} [maxParallel=5] - Maximum number of tasks to run in parallel
-   * @returns {Promise<Array>} Array of resolved values from all promises
-   * @throws {TypeError} If input is not an array of function or maxParallel is not a number
-   */
-async function parallelAllSettled (tasks, maxParallel = 5) {
-  assertArray(tasks)
-  assertNumber(maxParallel)
-  if (maxParallel <= 0) {
-    throw new Error(`Invalid maxParallel: ${maxParallel}, should > 0`)
-  }
-  tasks.forEach((task) => assertFunction(task))
-  const rtnVal = []
-  // once for all, run all promises
-  if (tasks.length <= maxParallel) {
-    const resultsForBatch = await PromiseUtils.allSettled(tasks.map(task => PromiseUtils.returnValuePromised(task)))
-    rtnVal.push(...resultsForBatch)
-    return rtnVal
-  }
-  // run group by MaxParallel
-  const tasksToRun = []
-  for (const task of tasks) {
-    assertFunction(task)
-    tasksToRun.push(task)
-    if (tasksToRun.length >= maxParallel) {
-      const resultsForBatch = await PromiseUtils.allSettled(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
-      rtnVal.push(...resultsForBatch)
-      tasksToRun.length = 0
-    }
-  }
-  // Run all rested
-  if (tasksToRun.length > 0 && tasksToRun.length < maxParallel) {
-    const resultsForBatch = await PromiseUtils.allSettled(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
-    rtnVal.push(...resultsForBatch)
-  }
-  return rtnVal
-}
-const PromiseUtils = {
-  defer,
-  delay,
-  timeout,
-  allSettled,
-  returnValuePromised,
-  series,
-  seriesAllSettled,
-  parallel,
-  parallelAllSettled
-}
-
-module.exports = PromiseUtils