@creejs/commons-lang 2.1.11 → 2.1.13

package/dist/umd/index.dev.js

@@ -14,7 +14,7 @@
     defaults,
     extend,
     extends: extend,
-    equals: equals$1,
+    equals: equals$2,
     isBrowser,
     isNode
   };
@@ -82,7 +82,7 @@
    * @param {*} value2 - Second value to compare
    * @returns {boolean} True if values are equal, false otherwise
    */
-  function equals$1 (value1, value2) {
+  function equals$2 (value1, value2) {
     if (value1 === value2) {
       return true
     }
@@ -581,7 +581,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=${JSON.stringify(value)}`)
     }
   }
   /**
@@ -1405,7 +1405,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 +1441,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 +1458,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 +1479,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 +1533,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 +1577,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 +1593,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 +1618,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 +1659,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 +1701,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) {
@@ -1910,7 +1929,7 @@
   var TypedArrayUtils = {
     startsWith,
     isSameType,
-    equals
+    equals: equals$1
   };
 
   /**
@@ -1925,7 +1944,7 @@
     assertNotNil(searching, 'searching');
 
     const header = src.subarray(0, searching.length);
-    return equals(header, searching)
+    return equals$1(header, searching)
   }
 
   /**
@@ -1951,7 +1970,7 @@
    * @returns {boolean} True if the typed arrays are equal, false otherwise.
    * @throws {Error} If either `src` or `target` is null or undefined.
    */
-  function equals (src, target) {
+  function equals$1 (src, target) {
     assertNotNil(src, 'src');
     assertNotNil(target, 'target');
     if (!isSameType(src, target)) {
@@ -2096,21 +2115,164 @@
     targetView.set(dataView, targetOffset);
   }
 
+  // module vars
+  const ms2ns = 1_000_000;
+  const s2ns = 1_000_000_000;
+
   var TimeUtils = {
-    timestamp64
+    s2ns,
+    ms2ns,
+    timestamp64,
+    lapseNano,
+    lapseMillis,
+    timeoutNano,
+    timeoutMillis
   };
 
-  const ms2ns = BigInt(1_000_000);
   /**
    * Gets the current timestamp in nanoseconds (if running in Node.js) or milliseconds (in browser).
    * Uses `process.hrtime.bigint()` for high-resolution timestamps in Node.js, falls back to `Date.now()` in browsers.
    * @returns {bigint} Current timestamp as a BigInt
    */
   function timestamp64 () {
-    if (typeof performance !== 'undefined') {
-      return BigInt(Math.floor(performance.timeOrigin + performance.now())) * ms2ns
+    // sinon can not fake performance.timeOrigin, so we have to check it
+    if (typeof performance !== 'undefined' && typeof performance.timeOrigin === 'number') {
+      // timeOrigin specifies the high resolution millisecond timestamp, eg. 1756350801931.159
+      const base = performance.timeOrigin;
+      // the current high resolution millisecond timestamp, eg.31767926.416357
+      const now = performance.now();
+      return BigInt((base + now) * ms2ns)
     }
-    return BigInt(Date.now()) * ms2ns
+    return BigInt(Date.now() * ms2ns)
+  }
+
+  /**
+   * Calculates the time elapsed in nanoseconds between the given timestamp and now.
+   * @param {bigint} start - start timestamp64, in nanoseconds.
+   * @param {bigint} [end] - end timestamp64, in nanoseconds. If not provided, uses current timestamp64.
+   * @returns {bigint} The elapsed time in nanoseconds (current timestamp64 - ts64).
+   */
+  function lapseNano (start, end) {
+    return (end ?? timestamp64()) - start
+  }
+
+  /**
+   * Calculates the time elapsed in milliseconds between the given timestamp and now.
+   * @param {bigint} start - start The timestamp in 64-bit format.
+   * @param {bigint} [end] - end timestamp64, in nanoseconds. If not provided, uses current timestamp64.
+   * @returns {bigint} The elapsed time in milliseconds.
+   */
+  function lapseMillis (start, end) {
+    end = end ?? timestamp64();
+    const lapseNano = end - start;
+    return BigInt(lapseNano) / BigInt(ms2ns)
+  }
+
+  /**
+   * compare current timestamp64 against the given ts64, and check if the elapsed time exceeds the specified timeout.
+   * @param {bigint} nanoTimestamp64 - The timestamp to compare against (in nanoseconds).
+   * @param {bigint|number} nanoTimeout - The timeout threshold (in nanoseconds).
+   * @returns {boolean} True if elapsed time exceeds timeout, false otherwise.
+   */
+  function timeoutNano (nanoTimestamp64, nanoTimeout) {
+    return lapseNano(nanoTimestamp64) > nanoTimeout
+  }
+
+  /**
+   * compare current timestamp64 against the given ts64, and check if the elapsed time exceeds the specified timeout.
+   * @param {bigint} nanoTimestamp64 - The timestamp to compare against (in nanoseconds).
+   * @param {bigint|number} millisTimeout - The timeout threshold (in milliseconds).
+   * @returns {boolean} True if elapsed time exceeds timeout, false otherwise.
+   */
+  function timeoutMillis (nanoTimestamp64, millisTimeout) {
+    return lapseMillis(nanoTimestamp64) > millisTimeout
+  }
+
+  // owned
+
+  var ArrayUtils = {
+    first,
+    last,
+    equals,
+    equalsIgnoreOrder
+  };
+
+  /**
+   * Gets the first element of an array
+   * @param {any[]} arr - The input array
+   * @param {any} [defaultValue] - The value to return if the array is empty or first element is undefined/null.
+   * @returns {any} The first element of the array, or the defaultValue if the array is empty or not an array.
+   * @throws {Error} if arr is not an array
+   */
+  function first (arr, defaultValue) {
+    assertArray(arr, 'arr');
+    return arr[0] ?? defaultValue
+  }
+
+  /**
+   * Gets the last element of an array
+   * @param {any[]} arr - The input array
+   * @param {any} [defaultValue] - The value to return if the array is empty or last element is undefined/null
+   * @returns {any} The last element of the array or the defaultValue
+   * @throws {Error} if arr is not an array
+   */
+  function last (arr, defaultValue) {
+    assertArray(arr, 'arr');
+    return arr[arr.length - 1] ?? defaultValue
+  }
+
+  /**
+   * Checks if two arrays are equal ignoring element order
+   * @param {any[]} arr1 - first array to compare
+   * @param {any[]} arr2 - Second array to compare
+   * @param {(a:any, b:any) => 0|1|-1} [compareFn]
+   * @returns {boolean} True if arrays have same elements (order-independent), false otherwise
+   */
+  function equalsIgnoreOrder (arr1, arr2, compareFn) {
+    if (!Array.isArray(arr1) || !Array.isArray(arr2)) {
+      return false
+    }
+    if (arr1.length !== arr2.length) {
+      return false
+    }
+    arr1.sort(compareFn);
+    arr2.sort(compareFn);
+    for (let i = 0; i < arr1.length; i++) {
+      if (compareFn) {
+        if (compareFn(arr1[i], arr2[i]) !== 0) {
+          return false
+        }
+      } else if (arr1[i] !== arr2[i]) {
+        return false
+      }
+    }
+    return true
+  }
+
+  /**
+   * Checks if two arrays are equal by order
+   * @param {any[]} arr1 - first array to compare
+   * @param {any[]} arr2 - Second array to compare
+   * @param {(a:any, b:any) => 0|1|-1} [compareFn]
+   * @returns {boolean} True if arrays have same elements (order-independent), false otherwise
+   */
+  function equals (arr1, arr2, compareFn) {
+    if (!Array.isArray(arr1) || !Array.isArray(arr2)) {
+      return false
+    }
+    if (arr1.length !== arr2.length) {
+      return false
+    }
+    for (let i = 0; i < arr1.length; i++) {
+      if (compareFn) {
+        if (compareFn(arr1[i], arr2[i]) !== 0) {
+          return false
+        }
+      } else if (arr1[i] !== arr2[i]) {
+        return false
+      }
+    }
+    return true
   }
 
   /**
@@ -2134,10 +2296,12 @@
     ReflectUtils,
     TypedArrayUtils,
     ArrayBufferUtils,
-    TimeUtils
+    TimeUtils,
+    ArrayUtils
   };
 
   exports.ArrayBufferUtils = ArrayBufferUtils;
+  exports.ArrayUtils = ArrayUtils;
   exports.ClassProxyUtils = ClassProxyUtils;
   exports.Exec = ExecUtils;
   exports.ExecUtils = ExecUtils;