@creejs/commons-lang 2.1.11 → 2.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creejs/commons-lang",
-  "version": "2.1.11",
+  "version": "2.1.13",
   "description": "Commons Utils About Language, used inside creejs",
   "keywords": [
     "commons",

package/types/array-utils.d.ts

@@ -0,0 +1,39 @@
+declare namespace _default {
+    export { first };
+    export { last };
+    export { equals };
+    export { equalsIgnoreOrder };
+}
+export default _default;
+/**
+ * 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
+ */
+export function first(arr: any[], defaultValue?: any): any;
+/**
+ * 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
+ */
+export function last(arr: any[], defaultValue?: any): any;
+/**
+ * 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
+ */
+export function equals(arr1: any[], arr2: any[], compareFn?: (a: any, b: any) => 0 | 1 | -1): boolean;
+/**
+ * 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
+ */
+export function equalsIgnoreOrder(arr1: any[], arr2: any[], compareFn?: (a: any, b: any) => 0 | 1 | -1): boolean;

package/types/index.d.ts

@@ -14,6 +14,7 @@ declare namespace _default {
     export { TypedArrayUtils };
     export { ArrayBufferUtils };
     export { TimeUtils };
+    export { ArrayUtils };
 }
 export default _default;
 import LangUtils from './lang-utils.js';
@@ -28,4 +29,5 @@ import ReflectUtils from './reflect-utils.js';
 import TypedArrayUtils from './typed-array-utils.js';
 import ArrayBufferUtils from './array-buffer-utils.js';
 import TimeUtils from './time-utils.js';
-export { LangUtils, StringUtils, TypeUtils, TypeAssert, ExecUtils, PromiseUtils, LangUtils as Lang, TypeUtils as Type, ExecUtils as Exec, ClassProxyUtils, InstanceProxyUtils, ReflectUtils, TypedArrayUtils, ArrayBufferUtils, TimeUtils };
+import ArrayUtils from './array-utils.js';
+export { LangUtils, StringUtils, TypeUtils, TypeAssert, ExecUtils, PromiseUtils, LangUtils as Lang, TypeUtils as Type, ExecUtils as Exec, ClassProxyUtils, InstanceProxyUtils, ReflectUtils, TypedArrayUtils, ArrayBufferUtils, TimeUtils, ArrayUtils };

package/types/promise-utils.d.ts

@@ -3,13 +3,9 @@
  * 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}
  */
-export function defer(timeout?: number, timeoutMessage?: string): {
-    promise: Promise<any>;
-    reject: Function;
-    resolve: Function;
-};
+export function defer(timeout?: number, timeoutMessage?: string): Deferred;
 /**
  * Creates a timeout wrapper around a promise that rejects if the promise doesn't resolve within the given time.
  * @param {Promise<*>} promise - The promise to wrap with a timeout
@@ -29,13 +25,13 @@ export function timeout(promise: Promise<any>, time?: number, message?: string):
  * 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}[]>}
  */
-export function allSettled(promises: Promise<any>): Array<{
+export function allSettled(promises: Promise<any>[]): Promise<{
     ok: boolean;
     result: any;
-}>;
+}[]>;
 /**
    * Execute the task Function, and ensure it returns a Promise.
    * @param {function} task
@@ -51,7 +47,7 @@ export function returnValuePromised(task: Function): Promise<any>;
    *
    * @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
    */
 export function delay(promise?: Promise<any> | number | undefined, ms?: number | undefined): Promise<any>;
 /**
@@ -59,10 +55,10 @@ export function delay(promise?: Promise<any> | number | undefined, ms?: number |
    * 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
    */
-export function series(tasks: any): Promise<any[]>;
+export function series(tasks: Function[]): Promise<any[]>;
 /**
    * AllSettled Mode to execute Tasks(functions) in series (one after another) and returns their results in order.
    * 1. tasks are executed one by one
@@ -81,7 +77,7 @@ export function seriesAllSettled(tasks: Function[]): Promise<Array<{
    * 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
    */
 export function parallel(tasks: Function[], maxParallel?: number): Promise<any[]>;
@@ -91,7 +87,7 @@ export function parallel(tasks: Function[], maxParallel?: number): Promise<any[]
    * 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
    */
 export function parallelAllSettled(tasks: Function[], maxParallel?: number): Promise<any[]>;
@@ -107,3 +103,13 @@ declare namespace _default {
     export { parallelAllSettled };
 }
 export default _default;
+export type Deferred = {
+    promise: Promise<any>;
+    timerHandler: NodeJS.Timeout;
+    timerCleared: boolean;
+    resolved: boolean;
+    rejected: boolean;
+    canceled: boolean;
+    reject: (reason: Error) => void;
+    resolve: (...args: any[]) => void;
+};

package/types/time-utils.d.ts

@@ -1,10 +1,46 @@
 declare namespace _default {
+    export { s2ns };
+    export { ms2ns };
     export { timestamp64 };
+    export { lapseNano };
+    export { lapseMillis };
+    export { timeoutNano };
+    export { timeoutMillis };
 }
 export default _default;
+export const s2ns: 1000000000;
+export const ms2ns: 1000000;
 /**
  * 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
  */
 export function timestamp64(): bigint;
+/**
+ * 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).
+ */
+export function lapseNano(start: bigint, end?: bigint): bigint;
+/**
+ * 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.
+ */
+export function lapseMillis(start: bigint, end?: bigint): bigint;
+/**
+ * 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.
+ */
+export function timeoutNano(nanoTimestamp64: bigint, nanoTimeout: bigint | number): boolean;
+/**
+ * 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.
+ */
+export function timeoutMillis(nanoTimestamp64: bigint, millisTimeout: bigint | number): boolean;