@creejs/commons-lang 2.1.12 → 2.1.14

package/dist/cjs/index-dev.cjs

@@ -1357,11 +1357,34 @@ function substringsBetween (str, startMarker, endMarker) {
 }
 
 /**
- * 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();
@@ -1403,7 +1426,20 @@ var ExecUtils = {
   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
@@ -1426,12 +1462,16 @@ var PromiseUtils = {
  * 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(() => {
@@ -1439,17 +1479,16 @@ function defer (timeout = -1, timeoutMessage) {
       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) => {
@@ -1461,12 +1500,14 @@ function defer (timeout = -1, timeoutMessage) {
       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'));
   };
@@ -1513,8 +1554,8 @@ function timeout (promise, time, message) {
  * 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);
@@ -1557,13 +1598,14 @@ function returnValuePromised (task) {
    *
    * @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();
   }
@@ -1572,16 +1614,16 @@ function delay (promise, ms) {
   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);
@@ -1597,8 +1639,8 @@ function delay (promise, ms) {
    * 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);
@@ -1638,7 +1680,7 @@ async function seriesAllSettled (tasks) {
    * 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) {
@@ -1680,7 +1722,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<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) {
@@ -1718,6 +1760,7 @@ async function parallelAllSettled (tasks, maxParallel = 5) {
 
 // owned
 
+// module vars
 const { isPlainObject } = TypeUtils;
 
 /**
@@ -1782,6 +1825,8 @@ function newProxyInstance (cls, args, propertyHandler, sealed = true) {
   return Reflect.construct(proxyCls, args ?? [])
 }
 
+// owned
+
 /**
  * @module InstanceProxyUtils
  */
@@ -1808,7 +1853,6 @@ var InstanceProxyUtils = {
 
 // owned
 
-
 /**
  * Retrieves all unique method names from a class's prototype chain. *
  * @param {Function} cls - The class to inspect
@@ -1885,8 +1929,6 @@ var ReflectUtils = {
 };
 
 // internal
-
-
 // owned
 
 /**
@@ -1970,6 +2012,8 @@ function equals$1 (src, target) {
   return true
 }
 
+// owned
+
 var ArrayBufferUtils = {
   readString,
   writeString,