@creejs/commons-lang 2.1.18 → 2.1.20

package/dist/cjs/index-dev.cjs

@@ -14,7 +14,9 @@ var LangUtils = {
   extends: extend,
   equals: equals$2,
   isBrowser,
-  isNode
+  isNode,
+  cloneToPlainObject,
+  deepCloneToPlainObject
 };
 
 /**
@@ -72,6 +74,41 @@ function extend (target, ...sources) {
   return target
 }
 
+/**
+ * Creates a shallow clone of an object by copying its enumerable properties to a new plain object.
+ * 1. This returns a PlainObject
+ * 2. It lose the type information of the original object
+ * 3. Shallow clone, copy only the first level properties
+ * @param {{[key:string]: any}} obj - The object to clone.
+ * @returns {{[key:string]: any}} A new plain object with the same enumerable properties as the input object.
+ */
+function cloneToPlainObject (obj) {
+  if (obj == null) {
+    return obj
+  }
+  if (typeof obj !== 'object') {
+    throw new Error('Only Object allowed to clone')
+  }
+  return { ...obj }
+}
+
+/**
+ * Deep clones an object by converting it to JSON and back to a plain object.
+ * 1. This will lose any non-JSON-serializable properties (e.g. functions, Symbols).
+ * 2. Only Use this to clone PlainObject
+ * @param {{[key:string]: any}} obj - The object to clone
+ * @returns {{[key:string]: any}} A new plain object with the cloned properties
+ */
+function deepCloneToPlainObject (obj) {
+  if (obj == null) {
+    return obj
+  }
+  if (typeof obj !== 'object') {
+    throw new Error('Only Object allowed to clone')
+  }
+  return JSON.parse(JSON.stringify(obj))
+}
+
 /**
  * Compares two values for equality
  * 1. First checks strict equality (===),
@@ -579,7 +616,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)}`)
   }
 }
 /**
@@ -591,7 +628,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)}`)
   }
 }
 /**
@@ -603,7 +640,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)}`)
   }
 }
 
@@ -615,7 +652,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}`)
   }
 }
 
@@ -627,7 +664,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}`)
   }
 }
 
@@ -639,7 +676,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}`)
   }
 }
 
@@ -652,7 +689,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)}`)
   }
 }
 /**
@@ -664,7 +701,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)}`)
   }
 }
 /**
@@ -676,7 +713,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)}`)
   }
 }
 /**
@@ -688,7 +725,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)}`)
   }
 }
 /**
@@ -700,7 +737,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)}`)
   }
 }
 /**
@@ -712,7 +749,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)}`)
   }
 }
 /**
@@ -724,7 +761,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)}`)
   }
 }
 /**
@@ -736,7 +773,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)}`)
   }
 }
 
@@ -748,7 +785,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`)
   }
 }
 
@@ -761,7 +798,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)}`)
   }
 }
 
@@ -773,7 +810,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`)
   }
 }
 /**
@@ -785,7 +822,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)}`)
   }
 }
 
@@ -797,7 +834,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)}`)
   }
 }
 
@@ -808,7 +845,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`)
   }
 }
 /**
@@ -818,7 +855,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`)
   }
 }
 /**
@@ -828,7 +865,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`)
   }
 }
 /**
@@ -838,7 +875,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`)
   }
 }
 /**
@@ -848,7 +885,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`)
   }
 }
 /**
@@ -858,7 +895,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`)
   }
 }
 /**
@@ -868,7 +905,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`)
   }
 }
 /**
@@ -878,7 +915,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`)
   }
 }
 /**
@@ -888,7 +925,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`)
   }
 }
 /**
@@ -898,7 +935,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`)
   }
 }
 /**
@@ -908,7 +945,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`)
   }
 }
 /**
@@ -918,7 +955,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`)
   }
 }
 
@@ -930,7 +967,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`)
   }
 }
 
@@ -959,7 +996,8 @@ var StringUtils = {
   substringAfterLast,
   substringBetween,
   substringBetweenGreedy,
-  substringsBetween
+  substringsBetween,
+  safeToString
 };
 
 /**
@@ -1356,6 +1394,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.
@@ -1433,6 +1487,7 @@ var ExecUtils = {
  * promise: Promise<*>,
  * timerHandler: NodeJS.Timeout,
  * timerCleared: boolean,
+ * pending: boolean,
  * resolved: boolean,
  * rejected: boolean,
  * canceled: boolean,
@@ -1445,7 +1500,8 @@ var ExecUtils = {
  * @typedef {{
  *  promise: Promise<*>,
  *  timerHandler: NodeJS.Timeout,
- *  resolve: (...args:any[])=> void
+ *  _resolve: (...args:any[])=> void,
+ *  wakeup: ()=> void
  * }} Waiter
  */
 
@@ -1454,6 +1510,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,
@@ -1462,6 +1519,7 @@ var PromiseUtils = {
   series,
   seriesAllSettled,
   parallel,
+  parallelAny,
   parallelAllSettled,
   wait
 };
@@ -1477,48 +1535,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
 }
@@ -1589,7 +1665,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)
@@ -1610,7 +1686,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();
@@ -1642,21 +1718,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
 }
@@ -1731,7 +1864,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) {
@@ -1751,7 +1884,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)));
@@ -1767,6 +1899,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
@@ -1785,17 +1987,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
 }
 
@@ -2256,6 +2461,7 @@ function timeoutMillis (nanoTimestamp64, millisTimeout) {
 
 var ArrayUtils = {
   first,
+  chunk,
   last,
   equals,
   equalsIgnoreOrder
@@ -2339,6 +2545,27 @@ 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.