@creejs/commons-lang 2.1.12 → 2.1.14

package/dist/umd/index.dev.js

@@ -1359,11 +1359,34 @@
   }
 
   /**
-   * Executes a task silently, suppressing any errors or rejections.
+   * @module ExecUtils
+   * @description Utils about how to execute task functions.
+   */
+
+
+  /**
+   * @typedef {{
+   *  error: (...args:any[]) => void,
+   *  warn: (...args:any[]) => void,
+   *  info: (...args:any[]) => void,
+   *  debug: (...args:any[]) => void,
+   *  trace: (...args:any[]) => void,
+   *  isErrorEnabled: () => boolean,
+   *  isWarnEnabled: () => boolean,
+   *  isInfoEnabled: () => boolean,
+   *  isDebugEnabled: () => boolean,
+   *  isTraceEnabled: () => boolean,
+   * }} LoggerLike
+   */
+
+  /**
+   * 1. Executes a task silently, suppressing any errors or rejections.
+   * 2. if loggerLike is provided, will log the error via it
    * @param {Function} task - The export function to execute.
+   * @param {LoggerLike} loggerLike - The logger-like object to use for logging.
    * @returns {Promise<*>|*} The return value of the task, or a Promise if the task is asynchronous.
    */
-  function quiet (task) {
+  function quiet (task, loggerLike) {
     assertFunction(task);
     try {
       const rtnVal = task();
@@ -1405,7 +1428,20 @@
     quietKeepError
   };
 
-  // @ts-nocheck
+  // owned
+
+  /**
+   * @typedef {{
+   * promise: Promise<*>,
+   * timerHandler: NodeJS.Timeout,
+   * timerCleared: boolean,
+   * resolved: boolean,
+   * rejected: boolean,
+   * canceled: boolean,
+   * reject: (reason: Error)=> void,
+   * resolve: (...args:any[])=> void
+   * }} Deferred
+   */
 
   /**
    * @module PromiseUtils
@@ -1428,12 +1464,16 @@
    * 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}}
+   * @returns {Deferred}
    */
   function defer (timeout = -1, timeoutMessage) {
     assertNumber(timeout);
+    /** @type {Deferred} */
     const rtnVal = {};
 
+    /**
+     * @type {NodeJS.Timeout}
+     */
     let timerHandler;
     if (timeout >= 0) {
       rtnVal.timerHandler = timerHandler = setTimeout(() => {
@@ -1441,17 +1481,16 @@
         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) => {
+      rtnVal.resolve = (arg) => {
         if (timerHandler != null) {
           clearTimeout(timerHandler); // must clear it
           rtnVal.timerCleared = true; // easy to check in test case
         }
         rtnVal.resolved = true;
-        resolve(...args);
+        resolve(arg);
       };
 
       rtnVal.reject = (err) => {
@@ -1463,12 +1502,14 @@
         reject(err);
       };
     });
+    // @ts-ignore
     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
+      // @ts-ignore
       rtnVal.canceled = rtnVal.promise.canceled = true; // easy to check in test case
       rtnVal.reject(new Error('Cancelled'));
     };
@@ -1515,8 +1556,8 @@
    * 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}>}
+   * @param {Promise<*>[]} promises
+   * @returns {Promise<{ok: boolean, result: any}[]>}
    */
   async function allSettled (promises) {
     assertArray(promises);
@@ -1559,13 +1600,14 @@
      *
      * @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
+     * @returns {Promise<*>} A new promise that settles after the delay period
      */
   function delay (promise, ms) {
-    if (isNumber(promise)) {
+    if (isNumber(promise)) { // defer(ms)
+      // @ts-ignore
       ms = promise;
       promise = Promise.resolve();
-    } else if (promise == null && ms == null) {
+    } else if (promise == null && ms == null) { // defer(promise, ms)
       ms = 1;
       promise = Promise.resolve();
     }
@@ -1574,16 +1616,16 @@
     assertNumber(ms);
     const deferred = 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) => {
+    // @ts-ignore
+    promise.then((...args) => {
+      const escaped = Date.now() - startTs;
+      if (escaped < ms) {
+        setTimeout(() => deferred.resolve(...args), ms - escaped);
+      } else {
+        deferred.resolve(...args);
+      }
+    })
+      .catch((/** @type {Error} */ err) => {
         const escaped = Date.now() - startTs;
         if (escaped < ms) {
           setTimeout(() => deferred.reject(err), ms - escaped);
@@ -1599,8 +1641,8 @@
      * 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[]} promises
-     * @returns {Promise<Array>} Promise that resolves with an array of results in the same order as input tasks
+     * @param {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);
@@ -1640,7 +1682,7 @@
      * 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
+     * @returns {Promise<any[]>} Array of resolved values from all promises
      * @throws {TypeError} If input is not an array of export function or maxParallel is not a number
      */
   async function parallel (tasks, maxParallel = 5) {
@@ -1682,7 +1724,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<Array>} Array of resolved values from all promises
+     * @returns {Promise<any[]>} Array of resolved values from all promises
      * @throws {TypeError} If input is not an array of export function or maxParallel is not a number
      */
   async function parallelAllSettled (tasks, maxParallel = 5) {
@@ -1720,6 +1762,7 @@
 
   // owned
 
+  // module vars
   const { isPlainObject } = TypeUtils;
 
   /**
@@ -1784,6 +1827,8 @@
     return Reflect.construct(proxyCls, args ?? [])
   }
 
+  // owned
+
   /**
    * @module InstanceProxyUtils
    */
@@ -1810,7 +1855,6 @@
 
   // owned
 
-
   /**
    * Retrieves all unique method names from a class's prototype chain. *
    * @param {Function} cls - The class to inspect
@@ -1887,8 +1931,6 @@
   };
 
   // internal
-
-
   // owned
 
   /**
@@ -1972,6 +2014,8 @@
     return true
   }
 
+  // owned
+
   var ArrayBufferUtils = {
     readString,
     writeString,