@creejs/commons-lang 2.1.10 → 2.1.12

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)}`)
   }
 }
 /**
@@ -1908,7 +1908,7 @@ var ReflectUtils = {
 var TypedArrayUtils = {
   startsWith,
   isSameType,
-  equals
+  equals: equals$1
 };
 
 /**
@@ -1923,7 +1923,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 +1949,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,6 +2094,166 @@ 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 = {
+  s2ns,
+  ms2ns,
+  timestamp64,
+  lapseNano,
+  lapseMillis,
+  timeoutNano,
+  timeoutMillis
+};
+
+/**
+ * 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 () {
+  // 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)
+}
+
+/**
+ * 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
+}
+
 /**
  * @module Lang
  * @description Core language utilities for type checking, string manipulation, and common operations.
@@ -2114,10 +2274,13 @@ var index = {
   InstanceProxyUtils,
   ReflectUtils,
   TypedArrayUtils,
-  ArrayBufferUtils
+  ArrayBufferUtils,
+  TimeUtils,
+  ArrayUtils
 };
 
 exports.ArrayBufferUtils = ArrayBufferUtils;
+exports.ArrayUtils = ArrayUtils;
 exports.ClassProxyUtils = ClassProxyUtils;
 exports.Exec = ExecUtils;
 exports.ExecUtils = ExecUtils;
@@ -2127,6 +2290,7 @@ exports.LangUtils = LangUtils;
 exports.PromiseUtils = PromiseUtils;
 exports.ReflectUtils = ReflectUtils;
 exports.StringUtils = StringUtils;
+exports.TimeUtils = TimeUtils;
 exports.Type = TypeUtils;
 exports.TypeAssert = TypeAssert;
 exports.TypeUtils = TypeUtils;