@creejs/commons-lang 2.1.19 → 2.1.21

package/dist/cjs/index-dev.cjs

@@ -2,6 +2,104 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+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
@@ -616,7 +714,7 @@ var TypeAssert = {
    */
 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)}`)
   }
 }
 /**
@@ -628,7 +726,7 @@ function assertArray (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -640,7 +738,7 @@ function assertString (value, paramName) {
    */
 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)}`)
   }
 }
 
@@ -652,7 +750,7 @@ function assertNumber (value, paramName) {
  */
 function assertPositive (value, paramName) {
   if (!isPositive(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Positive: ${value}`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Positive: ${value}`)
   }
 }
 
@@ -664,7 +762,7 @@ function assertPositive (value, paramName) {
  */
 function assertNegative (value, paramName) {
   if (!isNegative(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Negative: ${value}`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Negative: ${value}`)
   }
 }
 
@@ -676,7 +774,7 @@ function assertNegative (value, paramName) {
  */
 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}`)
   }
 }
 
@@ -689,7 +787,7 @@ function assertNotNegative (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -701,7 +799,7 @@ function assertBoolean (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -713,7 +811,7 @@ function assertObject (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -725,7 +823,7 @@ function assertPlainObject (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -737,7 +835,7 @@ function assertSymbol (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -749,7 +847,7 @@ function assertFunction (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -761,7 +859,7 @@ function assertInstance (value, paramName) {
    */
 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)}`)
   }
 }
 /**
@@ -773,7 +871,7 @@ function assertPromise (value, paramName) {
    */
 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)}`)
   }
 }
 
@@ -785,7 +883,7 @@ function assertNil (value, paramName) {
  */
 function assertNotNil (value, paramName) {
   if (isNil(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Should Not Nil`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Should Not Nil`)
   }
 }
 
@@ -798,7 +896,7 @@ function assertNotNil (value, paramName) {
    */
 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)}`)
   }
 }
 
@@ -810,7 +908,7 @@ function assertNull (value, paramName) {
  */
 function assertNotNull (value, paramName) {
   if (isNull(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Should Not Null`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Should Not Null`)
   }
 }
 /**
@@ -822,7 +920,7 @@ function assertNotNull (value, paramName) {
    */
 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)}`)
   }
 }
 
@@ -834,7 +932,7 @@ function assertUndefined (value, paramName) {
  */
 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)}`)
   }
 }
 
@@ -845,7 +943,7 @@ function assertStringOrSymbol (value, paramName) {
  */
 function assertTypedArray (value, paramName) {
   if (isTypedArray(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not TypedArray`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not TypedArray`)
   }
 }
 /**
@@ -855,7 +953,7 @@ function assertTypedArray (value, paramName) {
  */
 function assertInt8Array (value, paramName) {
   if (isInt8Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Int8Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Int8Array`)
   }
 }
 /**
@@ -865,7 +963,7 @@ function assertInt8Array (value, paramName) {
  */
 function assertUint8Array (value, paramName) {
   if (isUint8Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint8Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint8Array`)
   }
 }
 /**
@@ -875,7 +973,7 @@ function assertUint8Array (value, paramName) {
  */
 function assertUint8ClampedArray (value, paramName) {
   if (isUint8ClampedArray(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint8ClampedArray`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint8ClampedArray`)
   }
 }
 /**
@@ -885,7 +983,7 @@ function assertUint8ClampedArray (value, paramName) {
  */
 function assertInt16Array (value, paramName) {
   if (isInt16Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Int16Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Int16Array`)
   }
 }
 /**
@@ -895,7 +993,7 @@ function assertInt16Array (value, paramName) {
  */
 function assertUint16Array (value, paramName) {
   if (isUint16Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint16Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint16Array`)
   }
 }
 /**
@@ -905,7 +1003,7 @@ function assertUint16Array (value, paramName) {
  */
 function assertInt32Array (value, paramName) {
   if (isInt32Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Int32Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Int32Array`)
   }
 }
 /**
@@ -915,7 +1013,7 @@ function assertInt32Array (value, paramName) {
  */
 function assertUint32Array (value, paramName) {
   if (isUint32Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Uint32Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Uint32Array`)
   }
 }
 /**
@@ -925,7 +1023,7 @@ function assertUint32Array (value, paramName) {
  */
 function assertFloat32Array (value, paramName) {
   if (isFloat32Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Float32Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Float32Array`)
   }
 }
 /**
@@ -935,7 +1033,7 @@ function assertFloat32Array (value, paramName) {
  */
 function assertFloat64Array (value, paramName) {
   if (isFloat64Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Float64Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not Float64Array`)
   }
 }
 /**
@@ -945,7 +1043,7 @@ function assertFloat64Array (value, paramName) {
  */
 function assertBigInt64Array (value, paramName) {
   if (isBigInt64Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not BigInt64Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not BigInt64Array`)
   }
 }
 /**
@@ -955,7 +1053,7 @@ function assertBigInt64Array (value, paramName) {
  */
 function assertBigUint64Array (value, paramName) {
   if (isBigUint64Array(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not BigUint64Array`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not BigUint64Array`)
   }
 }
 
@@ -967,7 +1065,7 @@ function assertBigUint64Array (value, paramName) {
  */
 function assertArrayBuffer (value, paramName) {
   if (!isArrayBuffer(value)) {
-    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not ArrayBuffer`)
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ''}Not ArrayBuffer`)
   }
 }
 
@@ -996,7 +1094,8 @@ var StringUtils = {
   substringAfterLast,
   substringBetween,
   substringBetweenGreedy,
-  substringsBetween
+  substringsBetween,
+  safeToString
 };
 
 /**
@@ -1393,6 +1492,22 @@ function substringsBetween (str, startMarker, endMarker) {
   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.
@@ -1470,6 +1585,7 @@ var ExecUtils = {
  * promise: Promise<*>,
  * timerHandler: NodeJS.Timeout,
  * timerCleared: boolean,
+ * pending: boolean,
  * resolved: boolean,
  * rejected: boolean,
  * canceled: boolean,
@@ -1482,7 +1598,8 @@ var ExecUtils = {
  * @typedef {{
  *  promise: Promise<*>,
  *  timerHandler: NodeJS.Timeout,
- *  resolve: (...args:any[])=> void
+ *  _resolve: (...args:any[])=> void,
+ *  wakeup: ()=> void
  * }} Waiter
  */
 
@@ -1491,6 +1608,7 @@ var ExecUtils = {
  * @description Promise utility functions for enhanced promise handling, including timeout, delay, parallel execution, and series execution.
  */
 var PromiseUtils = {
+  any,
   defer,
   delay,
   timeout,
@@ -1499,6 +1617,7 @@ var PromiseUtils = {
   series,
   seriesAllSettled,
   parallel,
+  parallelAny,
   parallelAllSettled,
   wait
 };
@@ -1514,48 +1633,66 @@ function defer (timeout = -1, timeoutMessage) {
   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
 }
@@ -1626,7 +1763,7 @@ async function allSettled (promises) {
 function returnValuePromised (task) {
   try {
     const taskRtnVal = task();
-    if (isPromise(taskRtnVal)) {
+    if (TypeUtils.isPromise(taskRtnVal)) {
       return taskRtnVal
     }
     return Promise.resolve(taskRtnVal)
@@ -1647,7 +1784,7 @@ function returnValuePromised (task) {
    * @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();
@@ -1679,21 +1816,78 @@ function delay (promise, ms) {
     });
   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
 }
@@ -1768,7 +1962,7 @@ async function parallel (tasks, maxParallel = 5) {
    * 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) {
@@ -1788,7 +1982,6 @@ async function parallelAllSettled (tasks, maxParallel = 5) {
   // 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)));
@@ -1804,6 +1997,76 @@ async function parallelAllSettled (tasks, maxParallel = 5) {
   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
@@ -1822,17 +2085,20 @@ function wait (waitTime) {
   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
 }
 
@@ -2293,6 +2559,7 @@ function timeoutMillis (nanoTimestamp64, millisTimeout) {
 
 var ArrayUtils = {
   first,
+  chunk,
   last,
   equals,
   equalsIgnoreOrder
@@ -2376,13 +2643,35 @@ function equals (arr1, arr2, compareFn) {
   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,
@@ -2401,6 +2690,7 @@ var index = {
   ArrayUtils
 };
 
+exports.AggregatedError = AggregatedError;
 exports.ArrayBufferUtils = ArrayBufferUtils;
 exports.ArrayUtils = ArrayUtils;
 exports.ClassProxyUtils = ClassProxyUtils;
@@ -2417,5 +2707,6 @@ exports.Type = TypeUtils;
 exports.TypeAssert = TypeAssert;
 exports.TypeUtils = TypeUtils;
 exports.TypedArrayUtils = TypedArrayUtils;
+exports._Error = _Error;
 exports.default = index;
 //# sourceMappingURL=index-dev.cjs.map