@creejs/commons-lang 2.1.19 → 2.1.21

package/dist/umd/index.dev.js

@@ -4,6 +4,104 @@
   (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.CommonsLang = {}));
 })(this, (function (exports) { 'use strict';
 
+  class _Error extends Error {
+    /**
+     * Creates and returns a 404 Not Found error instance with the given message.
+     * @param {string} message - The error message to include.
+     * @returns {_Error} A new Error instance with status code 404.
+     */
+    static notFound (message) {
+      return new _Error(`Not Found: ${message}`, 404)
+    }
+
+    static notImpled () {
+      return new _Error('Not Impled Yet', 501)
+    }
+
+    /**
+     * Creates and returns a new Error instance for not supported operations.
+     * @param {string} message - The error message to include.
+     * @returns {_Error} A new Error instance with "Not Supported:" prefix and 505 status code.
+     */
+    static notSupported (message) {
+      return new _Error('Not Supported:' + message, 505)
+    }
+
+    /**
+     * Checks if the given error is a "Not Supported" error.
+     * @param {Error|_Error|{[key:string]:any}|unknown} err - The error to check
+     * @returns {boolean} True if the error is a Not Supported error (code 505), false otherwise
+     */
+    static isNotSupported (err) {
+      // @ts-ignore
+      return err?.code === 505
+    }
+
+    /**
+     * Error constructor with custom message and code.
+     * @param {string} message - Error message
+     * @param {number|string} code - Error code
+     */
+    constructor (message, code) {
+      super(message);
+      this.code = code;
+    }
+  }
+
+  class AggregatedError extends Error {
+    /**
+     * Checks if the given error is an AggregatedErrorLike
+     * 1. have "message:string" property
+     * 2. have "errors:Error[]" property
+     * @param {any} err - The error to check
+     * @returns {boolean} True if the error is an AggregatedError, false otherwise
+     */
+    static isAggregatedErrorLike (err) {
+      return err && Array.isArray(err.errors)
+    }
+
+    /**
+     * Checks if the given error is an instance of AggregatedError.
+     * @param {Error} err - The error to check.
+     * @returns {boolean} True if the error is an AggregatedError, false otherwise.
+     */
+    static isAggregatedError (err) {
+      return err instanceof AggregatedError
+    }
+
+    /**
+     * Error constructor with custom message and code.
+     * @param {string} message - Error message
+     * @param {any[]} [errors] - Errors
+     */
+    constructor (message, errors) {
+      super(message);
+      this.errors = errors ?? [];
+    }
+
+    /**
+     * Adds an error to the errors collection.
+     * @param {any} err - The error object to be added.
+     */
+    addError (err) {
+      this.errors.push(err);
+    }
+
+    /**
+     * Removes a specific error from the errors array.
+     * @param {Error} err - The error instance to remove.
+     * @returns {boolean} True if the error was found and removed, false otherwise.
+     */
+    removeError (err) {
+      const index = this.errors.indexOf(err);
+      if (index === -1) {
+        return false
+      }
+      this.errors.splice(index, 1);
+      return true
+    }
+  }
+
   /**
    * @module LangUtils
    * @description Language utility functions
@@ -618,7 +716,7 @@
      */
   function assertArray (value, paramName) {
     if (!Array.isArray(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Array: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Array: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -630,7 +728,7 @@
      */
   function assertString (value, paramName) {
     if (!isString(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not String: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not String: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -642,7 +740,7 @@
      */
   function assertNumber (value, paramName) {
     if (!isNumber(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Number: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Number: type=${typeof value} value=${safeToString(value)}`)
     }
   }
 
@@ -654,7 +752,7 @@
    */
   function assertPositive (value, paramName) {
     if (!isPositive(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Positive: ${value}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Positive: ${value}`)
     }
   }
 
@@ -666,7 +764,7 @@
    */
   function assertNegative (value, paramName) {
     if (!isNegative(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Negative: ${value}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Negative: ${value}`)
     }
   }
 
@@ -678,7 +776,7 @@
    */
   function assertNotNegative (value, paramName) {
     if (!isNotNegative(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not "0 or Positive": ${value}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not "0 or Positive": ${value}`)
     }
   }
 
@@ -691,7 +789,7 @@
      */
   function assertBoolean (value, paramName) {
     if (!isBoolean(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Boolean: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Boolean: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -703,7 +801,7 @@
      */
   function assertObject (value, paramName) {
     if (!isObject(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Object: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Object: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -715,7 +813,7 @@
      */
   function assertPlainObject (value, paramName) {
     if (!isPlainObject$1(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not PlainObject: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not PlainObject: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -727,7 +825,7 @@
      */
   function assertSymbol (value, paramName) {
     if (!isSymbol(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Symbol: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Symbol: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -739,7 +837,7 @@
      */
   function assertFunction (value, paramName) {
     if (!isFunction(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Function: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Function: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -751,7 +849,7 @@
      */
   function assertInstance (value, paramName) {
     if (!isInstance(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Class Instance: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Class Instance: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -763,7 +861,7 @@
      */
   function assertPromise (value, paramName) {
     if (!isPromise(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Promise: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Promise: type=${typeof value} value=${safeToString(value)}`)
     }
   }
   /**
@@ -775,7 +873,7 @@
      */
   function assertNil (value, paramName) {
     if (!isNil(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Neither Null nor Undefined: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Neither Null nor Undefined: type=${typeof value} value=${safeToString(value)}`)
     }
   }
 
@@ -787,7 +885,7 @@
    */
   function assertNotNil (value, paramName) {
     if (isNil(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Should Not Nil`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Should Not Nil`)
     }
   }
 
@@ -800,7 +898,7 @@
      */
   function assertNull (value, paramName) {
     if (!isNull(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Null: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Null: type=${typeof value} value=${safeToString(value)}`)
     }
   }
 
@@ -812,7 +910,7 @@
    */
   function assertNotNull (value, paramName) {
     if (isNull(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Should Not Null`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Should Not Null`)
     }
   }
   /**
@@ -824,7 +922,7 @@
      */
   function assertUndefined (value, paramName) {
     if (!isUndefined(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Undefined: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Undefined: type=${typeof value} value=${safeToString(value)}`)
     }
   }
 
@@ -836,7 +934,7 @@
    */
   function assertStringOrSymbol (value, paramName) {
     if (!isString(value) && !isSymbol(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not String or Symbol: type=${typeof value} value=${JSON.stringify(value)}`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not String or Symbol: type=${typeof value} value=${safeToString(value)}`)
     }
   }
 
@@ -847,7 +945,7 @@
    */
   function assertTypedArray (value, paramName) {
     if (isTypedArray(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not TypedArray`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not TypedArray`)
     }
   }
   /**
@@ -857,7 +955,7 @@
    */
   function assertInt8Array (value, paramName) {
     if (isInt8Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Int8Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Int8Array`)
     }
   }
   /**
@@ -867,7 +965,7 @@
    */
   function assertUint8Array (value, paramName) {
     if (isUint8Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint8Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint8Array`)
     }
   }
   /**
@@ -877,7 +975,7 @@
    */
   function assertUint8ClampedArray (value, paramName) {
     if (isUint8ClampedArray(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint8ClampedArray`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint8ClampedArray`)
     }
   }
   /**
@@ -887,7 +985,7 @@
    */
   function assertInt16Array (value, paramName) {
     if (isInt16Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Int16Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Int16Array`)
     }
   }
   /**
@@ -897,7 +995,7 @@
    */
   function assertUint16Array (value, paramName) {
     if (isUint16Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint16Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint16Array`)
     }
   }
   /**
@@ -907,7 +1005,7 @@
    */
   function assertInt32Array (value, paramName) {
     if (isInt32Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Int32Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Int32Array`)
     }
   }
   /**
@@ -917,7 +1015,7 @@
    */
   function assertUint32Array (value, paramName) {
     if (isUint32Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint32Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint32Array`)
     }
   }
   /**
@@ -927,7 +1025,7 @@
    */
   function assertFloat32Array (value, paramName) {
     if (isFloat32Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Float32Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Float32Array`)
     }
   }
   /**
@@ -937,7 +1035,7 @@
    */
   function assertFloat64Array (value, paramName) {
     if (isFloat64Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Float64Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Float64Array`)
     }
   }
   /**
@@ -947,7 +1045,7 @@
    */
   function assertBigInt64Array (value, paramName) {
     if (isBigInt64Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not BigInt64Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not BigInt64Array`)
     }
   }
   /**
@@ -957,7 +1055,7 @@
    */
   function assertBigUint64Array (value, paramName) {
     if (isBigUint64Array(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not BigUint64Array`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not BigUint64Array`)
     }
   }
 
@@ -969,7 +1067,7 @@
    */
   function assertArrayBuffer (value, paramName) {
     if (!isArrayBuffer(value)) {
-      throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not ArrayBuffer`)
+      throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not ArrayBuffer`)
     }
   }
 
@@ -998,7 +1096,8 @@
     substringAfterLast,
     substringBetween,
     substringBetweenGreedy,
-    substringsBetween
+    substringsBetween,
+    safeToString
   };
 
   /**
@@ -1395,6 +1494,22 @@
     return substrings
   }
 
+  /**
+   * Safely converts a value to its string representation.
+   * Attempts to use JSON.stringify first, falls back to toString() if stringify fails.
+   * @param {*} value - The value to convert to string
+   * @returns {string} The string representation of the value
+   */
+  function safeToString (value) {
+    let valueStr;
+    try {
+      valueStr = JSON.stringify(value);
+    } catch (e) {
+      valueStr = value.toString();
+    }
+    return valueStr
+  }
+
   /**
    * @module ExecUtils
    * @description Utils about how to execute task functions.
@@ -1472,6 +1587,7 @@
    * promise: Promise<*>,
    * timerHandler: NodeJS.Timeout,
    * timerCleared: boolean,
+   * pending: boolean,
    * resolved: boolean,
    * rejected: boolean,
    * canceled: boolean,
@@ -1484,7 +1600,8 @@
    * @typedef {{
    *  promise: Promise<*>,
    *  timerHandler: NodeJS.Timeout,
-   *  resolve: (...args:any[])=> void
+   *  _resolve: (...args:any[])=> void,
+   *  wakeup: ()=> void
    * }} Waiter
    */
 
@@ -1493,6 +1610,7 @@
    * @description Promise utility functions for enhanced promise handling, including timeout, delay, parallel execution, and series execution.
    */
   var PromiseUtils = {
+    any,
     defer,
     delay,
     timeout,
@@ -1501,6 +1619,7 @@
     series,
     seriesAllSettled,
     parallel,
+    parallelAny,
     parallelAllSettled,
     wait
   };
@@ -1516,48 +1635,66 @@
     assertNumber(timeout);
     /** @type {Deferred} */
     const rtnVal = {};
-
+    rtnVal.pending = true;
+    rtnVal.canceled = false;
+    rtnVal.rejected = false;
+    rtnVal.resolved = false;
     /**
      * @type {NodeJS.Timeout}
      */
     let timerHandler;
     if (timeout >= 0) {
+      rtnVal.timerCleared = false;
       rtnVal.timerHandler = timerHandler = setTimeout(() => {
         clearTimeout(timerHandler); // must clear it
-        rtnVal.timerCleared = true; // easy to check in test case
+        rtnVal.timerCleared = true;
         rtnVal.reject(new Error(timeoutMessage ?? `Promise Timeout: ${timeout}ms`));
       }, timeout);
     }
 
     rtnVal.promise = new Promise((resolve, reject) => {
       rtnVal.resolve = (arg) => {
+        if (rtnVal.resolved || rtnVal.rejected || rtnVal.canceled) {
+          return // already done, Can Not operate again
+        }
         if (timerHandler != null) {
           clearTimeout(timerHandler); // must clear it
-          rtnVal.timerCleared = true; // easy to check in test case
+          rtnVal.timerCleared = true;
         }
+        rtnVal.pending = false;
+        rtnVal.canceled = false;
+        rtnVal.rejected = false;
         rtnVal.resolved = true;
         resolve(arg);
       };
 
       rtnVal.reject = (err) => {
+        if (rtnVal.resolved || rtnVal.rejected || rtnVal.canceled) {
+          return // already done, Can Not operate again
+        }
         if (timerHandler != null) {
           clearTimeout(timerHandler); // must clear it
-          rtnVal.timerCleared = true; // easy to check in test case
+          rtnVal.timerCleared = true;
         }
+        rtnVal.pending = false;
+        rtnVal.canceled = false;
+        rtnVal.resolved = false;
         rtnVal.rejected = true;
         reject(err);
       };
     });
     // @ts-ignore
-    rtnVal.promise.cancel = () => {
+    rtnVal.cancel = rtnVal.promise.cancel = (reason) => {
+      if (rtnVal.resolved || rtnVal.rejected || rtnVal.canceled) {
+        return // already done, Can Not operate again
+      }
       if (timerHandler != null) {
         clearTimeout(timerHandler); // must clear it
-        rtnVal.timerCleared = true; // easy to check in test case
+        rtnVal.timerCleared = true;
       }
-      rtnVal.rejected = true; // easy to check in test case
+      rtnVal.reject(reason ?? new Error('Cancelled'));
       // @ts-ignore
-      rtnVal.canceled = rtnVal.promise.canceled = true; // easy to check in test case
-      rtnVal.reject(new Error('Cancelled'));
+      rtnVal.canceled = rtnVal.promise.canceled = true;
     };
     return rtnVal
   }
@@ -1628,7 +1765,7 @@
   function returnValuePromised (task) {
     try {
       const taskRtnVal = task();
-      if (isPromise(taskRtnVal)) {
+      if (TypeUtils.isPromise(taskRtnVal)) {
         return taskRtnVal
       }
       return Promise.resolve(taskRtnVal)
@@ -1649,7 +1786,7 @@
      * @returns {Promise<*>} A new promise that settles after the delay period
      */
   function delay (promise, ms) {
-    if (isNumber(promise)) { // defer(ms)
+    if (TypeUtils.isNumber(promise)) { // defer(ms)
       // @ts-ignore
       ms = promise;
       promise = Promise.resolve();
@@ -1681,21 +1818,78 @@
       });
     return deferred.promise
   }
+  /**
+   * 1. run all tasks
+   * 2. any Task succeed, return its result
+   *    * resolve with the result.
+   *    * the others tasks will run to its end, and results will be dropped.
+   * 3. If all tasks fail, rejects with an array of errors. the array length is same as the input tasks
+   * @param {Array<Promise<any>|Function>} tasks - Array of promises or async functions to execute
+   * @returns {Promise<any>} A promise that resolves with the result of the first successful task
+   */
+  function any (tasks) {
+    assertArray(tasks);
+    if (tasks.length === 0) {
+      throw new Error('Empty Tasks')
+    }
+    const deferred = defer();
+    /** @type {any[]} */
+    const errors = [];
+    for (let i = 0; i < tasks.length; i++) {
+      const task = tasks[i];
+      /** @type {Promise<any>} */
+      let taskPromise;
+      if (TypeUtils.isPromise(task)) {
+        // @ts-ignore
+        taskPromise = task;
+      } else if (TypeUtils.isFunction(task)) {
+        // @ts-ignore
+        taskPromise = returnValuePromised(task);
+      } else {
+        errors.push(new Error(`Invalid Task at index ${i}/${tasks.length - 1}: ${task}`));
+        continue
+      }
+      taskPromise.then(/** @type {any} */ rtnVal => {
+        deferred.resolve(rtnVal);
+      }).catch(e => {
+        errors.push(e);
+        // all tasks failed
+        if (errors.length >= tasks.length) {
+          deferred.reject(errors);
+        }
+      });
+    }
+    if (errors.length === tasks.length) {
+      deferred.reject(errors);
+    }
+    return deferred.promise
+  }
 
   /**
-     * Fast-Fail mode to execute Tasks(functions) in series (one after another) and returns their results in order.
-     * 1. export 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[]} tasks
-     * @returns {Promise<any[]>} Promise that resolves with an array of results in the same order as input tasks
-     */
+   * Execute Tasks(functions) in series (one after another) and returns their results in order.
+   * 1. Tasks are executed one by one
+   *    * if task is a function, execute it.
+   *    * if task is a promise, wait for it to settle.
+   * 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)
+   * 4. All Tasks run successfully, Return Results Array, it's length is same as the input tasks
+   * @param {Array<Promise<any>|Function>} tasks
+   * @returns {Promise<any[]>} 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());
+      if (TypeUtils.isFunction(task)) {
+        // @ts-ignore
+        results.push(await returnValuePromised(task));
+      } else if (TypeUtils.isPromise(task)) {
+        // @ts-ignore
+        results.push(await task);
+      } else {
+        throw new Error(`Invalid Task: ${task}`)
+      }
     }
     return results
   }
@@ -1770,7 +1964,7 @@
      * 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<any[]>} Array of resolved values from all promises
+     * @returns {Promise<{ok: boolean, result: any}[]>}
      * @throws {TypeError} If input is not an array of export function or maxParallel is not a number
      */
   async function parallelAllSettled (tasks, maxParallel = 5) {
@@ -1790,7 +1984,6 @@
     // run group by MaxParallel
     const tasksToRun = [];
     for (const task of tasks) {
-      assertFunction(task);
       tasksToRun.push(task);
       if (tasksToRun.length >= maxParallel) {
         const resultsForBatch = await allSettled(tasksToRun.map(task => returnValuePromised(task)));
@@ -1806,6 +1999,76 @@
     return rtnVal
   }
 
+  /**
+   * Executes multiple async tasks in parallel with limited concurrency,
+   * 1. resolving when any task completes successfully.
+   * 2. Maybe multiple tasks are executed as a bulk block, and all of them resolved.
+   *    * only the first fulfilled value is returned
+   *    * other results are dropped
+   * @param {Array<Function|Promise<any>>} tasks - Array of async functions to execute
+   * @param {number} [maxParallel=5] - Maximum number of tasks to run in parallel
+   * @returns {Promise<any>} Resolves with the result of the first successfully completed task
+   */
+  async function parallelAny (tasks, maxParallel = 5) {
+    assertArray(tasks, 'tasks');
+    assertNumber(maxParallel);
+    if (tasks.length === 0) {
+      throw new Error('Empty Tasks')
+    }
+    if (maxParallel <= 0) {
+      throw new Error(`Invalid maxParallel: ${maxParallel}, should > 0`)
+    }
+    /** @type {any[]} */
+    const errors = [];
+    let taskIndex = 0;
+    let runningTasksCount = 0;
+    const deferred = defer();
+    function takeTaskAndRun () {
+      if (taskIndex >= tasks.length) {
+        return // no more task
+      }
+      // reach max parallel, wait for one task to finish
+      if (runningTasksCount > maxParallel) {
+        return
+      }
+      const task = tasks[taskIndex++];
+      runningTasksCount++;
+      /** @type {Promise<any>} */
+      let taskPromise;
+      if (TypeUtils.isPromise(task)) {
+        // @ts-ignore
+        taskPromise = task;
+      } else if (TypeUtils.isFunction(task)) {
+        // @ts-ignore
+        taskPromise = returnValuePromised(task);
+      } else {
+        errors.push(new TypeError(`Invalid task: ${task}`));
+        takeTaskAndRun();
+        return
+      }
+      taskPromise.then(/** @type {any} */ rtnVal => {
+        deferred.resolve(rtnVal);
+      }).catch(e => {
+        errors.push(e);
+        // No task left, and No successful execution, reject with errors
+        if (errors.length >= tasks.length) {
+          if (deferred.pending) {
+            deferred.reject(errors);
+            return
+          }
+        }
+        takeTaskAndRun();
+      }).finally(() => {
+        runningTasksCount--;
+      });
+    }
+    // start tasks until maxParallel
+    while (runningTasksCount < maxParallel) {
+      takeTaskAndRun();
+    }
+    return deferred.promise
+  }
+
   /**
    * Creates a "Waiter" Object
    * 1. wait the specified time
@@ -1824,17 +2087,20 @@
     let timerHandler;
     rtnVal.timerHandler = timerHandler = setTimeout(() => {
       clearTimeout(timerHandler); // must clear it
-      rtnVal.resolve();
+      rtnVal._resolve();
     }, waitTime);
 
     rtnVal.promise = new Promise((resolve, reject) => {
-      rtnVal.resolve = (arg) => {
+      rtnVal._resolve = (arg) => {
         if (timerHandler != null) {
           clearTimeout(timerHandler); // must clear it
         }
         resolve(arg);
       };
     });
+    rtnVal.wakeup = () => {
+      rtnVal._resolve();
+    };
     return rtnVal
   }
 
@@ -2295,6 +2561,7 @@
 
   var ArrayUtils = {
     first,
+    chunk,
     last,
     equals,
     equalsIgnoreOrder
@@ -2378,13 +2645,35 @@
     return true
   }
 
+  /**
+   * Splits an array into chunks of the specified size.
+   * @param {any[]} array - The array to be chunked.
+   * @param {number} size - The size of each chunk.
+   * @returns {any[]} An array of arrays containing the chunks.
+   */
+  function chunk (array, size) {
+    assertArray(array, 'array');
+    assertPositive(size, 'size');
+    if (array.length <= size) {
+      return array
+    }
+    const chunked = [];
+    let index = 0;
+    while (index < array.length) {
+      chunked.push(array.slice(index, size + index));
+      index += size;
+    }
+    return chunked
+  }
+
   /**
    * @module Lang
    * @description Core language utilities for type checking, string manipulation, and common operations.
    */
 
-
   var index = {
+    _Error,
+    AggregatedError,
     LangUtils,
     StringUtils,
     TypeUtils,
@@ -2403,6 +2692,7 @@
     ArrayUtils
   };
 
+  exports.AggregatedError = AggregatedError;
   exports.ArrayBufferUtils = ArrayBufferUtils;
   exports.ArrayUtils = ArrayUtils;
   exports.ClassProxyUtils = ClassProxyUtils;
@@ -2419,6 +2709,7 @@
   exports.TypeAssert = TypeAssert;
   exports.TypeUtils = TypeUtils;
   exports.TypedArrayUtils = TypedArrayUtils;
+  exports._Error = _Error;
   exports.default = index;
 
   Object.defineProperty(exports, '__esModule', { value: true });