@creejs/commons-lang 2.1.11 → 2.1.13

package/dist/cjs/index-dev.cjs

@@ -12,7 +12,7 @@ var LangUtils = {
   defaults,
   extend,
   extends: extend,
-  equals: equals$1,
+  equals: equals$2,
   isBrowser,
   isNode
 };
@@ -80,7 +80,7 @@ function extend (target, ...sources) {
  * @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
   }
@@ -579,7 +579,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=${JSON.stringify(value)}`)
   }
 }
 /**
@@ -1403,7 +1403,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 +1439,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 +1456,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 +1477,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 +1531,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 +1575,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 +1591,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 +1616,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 +1657,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 +1699,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) {
@@ -1908,7 +1927,7 @@ var ReflectUtils = {
 var TypedArrayUtils = {
   startsWith,
   isSameType,
-  equals
+  equals: equals$1
 };
 
 /**
@@ -1923,7 +1942,7 @@ function startsWith (src, searching) {
   assertNotNil(searching, 'searching');
 
   const header = src.subarray(0, searching.length);
-  return equals(header, searching)
+  return equals$1(header, searching)
 }
 
 /**
@@ -1949,7 +1968,7 @@ function isSameType (src, target) {
  * @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)) {
@@ -2094,21 +2113,164 @@ function writeArrayBuffer (target, dataArrayBuffer, targetOffset = 0, dataOffset
   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
 }
 
 /**
@@ -2132,10 +2294,12 @@ var index = {
   ReflectUtils,
   TypedArrayUtils,
   ArrayBufferUtils,
-  TimeUtils
+  TimeUtils,
+  ArrayUtils
 };
 
 exports.ArrayBufferUtils = ArrayBufferUtils;
+exports.ArrayUtils = ArrayUtils;
 exports.ClassProxyUtils = ClassProxyUtils;
 exports.Exec = ExecUtils;
 exports.ExecUtils = ExecUtils;