@creejs/commons-lang 2.1.19 → 2.1.21

package/types/_error.d.ts

@@ -0,0 +1,30 @@
+export default class _Error extends Error {
+    /**
+     * Creates and returns a 404 Not Found error instance with the given message.
+     * @param {string} message - The error message to include.
+     * @returns {_Error} A new Error instance with status code 404.
+     */
+    static notFound(message: string): _Error;
+    static notImpled(): _Error;
+    /**
+     * Creates and returns a new Error instance for not supported operations.
+     * @param {string} message - The error message to include.
+     * @returns {_Error} A new Error instance with "Not Supported:" prefix and 505 status code.
+     */
+    static notSupported(message: string): _Error;
+    /**
+     * Checks if the given error is a "Not Supported" error.
+     * @param {Error|_Error|{[key:string]:any}|unknown} err - The error to check
+     * @returns {boolean} True if the error is a Not Supported error (code 505), false otherwise
+     */
+    static isNotSupported(err: Error | _Error | {
+        [key: string]: any;
+    } | unknown): boolean;
+    /**
+     * Error constructor with custom message and code.
+     * @param {string} message - Error message
+     * @param {number|string} code - Error code
+     */
+    constructor(message: string, code: number | string);
+    code: string | number;
+}

package/types/aggregated-error.d.ts

@@ -0,0 +1,34 @@
+export default class AggregatedError extends Error {
+    /**
+     * Checks if the given error is an AggregatedErrorLike
+     * 1. have "message:string" property
+     * 2. have "errors:Error[]" property
+     * @param {any} err - The error to check
+     * @returns {boolean} True if the error is an AggregatedError, false otherwise
+     */
+    static isAggregatedErrorLike(err: any): boolean;
+    /**
+     * Checks if the given error is an instance of AggregatedError.
+     * @param {Error} err - The error to check.
+     * @returns {boolean} True if the error is an AggregatedError, false otherwise.
+     */
+    static isAggregatedError(err: Error): boolean;
+    /**
+     * Error constructor with custom message and code.
+     * @param {string} message - Error message
+     * @param {any[]} [errors] - Errors
+     */
+    constructor(message: string, errors?: any[]);
+    errors: any[];
+    /**
+     * Adds an error to the errors collection.
+     * @param {any} err - The error object to be added.
+     */
+    addError(err: any): void;
+    /**
+     * Removes a specific error from the errors array.
+     * @param {Error} err - The error instance to remove.
+     * @returns {boolean} True if the error was found and removed, false otherwise.
+     */
+    removeError(err: Error): boolean;
+}

package/types/array-utils.d.ts

@@ -1,5 +1,6 @@
 declare namespace _default {
     export { first };
+    export { chunk };
     export { last };
     export { equals };
     export { equalsIgnoreOrder };
@@ -13,6 +14,13 @@ export default _default;
  * @throws {Error} if arr is not an array
  */
 export function first(arr: any[], defaultValue?: any): any;
+/**
+ * Splits an array into chunks of the specified size.
+ * @param {any[]} array - The array to be chunked.
+ * @param {number} size - The size of each chunk.
+ * @returns {any[]} An array of arrays containing the chunks.
+ */
+export function chunk(array: any[], size: number): any[];
 /**
  * Gets the last element of an array
  * @param {any[]} arr - The input array

package/types/index.d.ts

@@ -1,4 +1,6 @@
 declare namespace _default {
+    export { _Error };
+    export { AggregatedError };
     export { LangUtils };
     export { StringUtils };
     export { TypeUtils };
@@ -17,6 +19,8 @@ declare namespace _default {
     export { ArrayUtils };
 }
 export default _default;
+import _Error from './_error.js';
+import AggregatedError from './aggregated-error.js';
 import LangUtils from './lang-utils.js';
 import StringUtils from './string-utils.js';
 import TypeUtils from './type-utils.js';
@@ -30,4 +34,4 @@ import TypedArrayUtils from './typed-array-utils.js';
 import ArrayBufferUtils from './array-buffer-utils.js';
 import TimeUtils from './time-utils.js';
 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 };
+export { _Error, AggregatedError, 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

@@ -51,14 +51,34 @@ export function returnValuePromised(task: Function): Promise<any>;
    */
 export function delay(promise?: Promise<any> | number | undefined, ms?: number | undefined): Promise<any>;
 /**
-   * Fast-Fail mode to execute Tasks(functions) in series (one after another) and returns their results in order.
-   * 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[]} tasks
-   * @returns {Promise<any[]>} Promise that resolves with an array of results in the same order as input tasks
-   */
-export function series(tasks: Function[]): Promise<any[]>;
+ * 1. run all tasks
+ * 2. any Task succeed, return its result
+ *    * resolve with the result.
+ *    * the others tasks will run to its end, and results will be dropped.
+ * 3. If all tasks fail, rejects with an array of errors. the array length is same as the input tasks
+ * @param {Array<Promise<any>|Function>} tasks - Array of promises or async functions to execute
+ * @returns {Promise<any>} A promise that resolves with the result of the first successful task
+ */
+export function any(tasks: Array<Promise<any> | Function>): Promise<any>;
+/**
+ * Execute Tasks(functions) in series (one after another) and returns their results in order.
+ * 1. Tasks are executed one by one
+ *    * if task is a function, execute it.
+ *    * if task is a promise, wait for it to settle.
+ * 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)
+ * 4. All Tasks run successfully, Return Results Array, it's length is same as the input tasks
+ * @param {Array<Promise<any>|Function>} tasks
+ * @returns {Promise<any[]>} Promise that resolves with an array of results in the same order as input tasks
+ */
+export function series(tasks: Array<Promise<any> | Function>): Promise<any[]>;
+/**
+ * Resolves with the first successfully completed task from the given array of tasks.
+ * If all tasks fail, rejects with an array of errors.
+ * @param {Array<Promise<any>|Function>} tasks - Array of promises or async functions to execute
+ * @returns {Promise<any>} A promise that resolves with the result of the first successful task
+ */
+export function seriesAny(tasks: Array<Promise<any> | 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
@@ -87,10 +107,24 @@ 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<any[]>} Array of resolved values from all promises
+   * @returns {Promise<{ok: boolean, result: any}[]>}
    * @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[]>;
+export function parallelAllSettled(tasks: Function[], maxParallel?: number): Promise<{
+    ok: boolean;
+    result: any;
+}[]>;
+/**
+ * Executes multiple async tasks in parallel with limited concurrency,
+ * 1. resolving when any task completes successfully.
+ * 2. Maybe multiple tasks are executed as a bulk block, and all of them resolved.
+ *    * only the first fulfilled value is returned
+ *    * other results are dropped
+ * @param {Array<Function|Promise<any>>} tasks - Array of async functions to execute
+ * @param {number} [maxParallel=5] - Maximum number of tasks to run in parallel
+ * @returns {Promise<any>} Resolves with the result of the first successfully completed task
+ */
+export function parallelAny(tasks: Array<Function | Promise<any>>, maxParallel?: number): Promise<any>;
 /**
  * Creates a "Waiter" Object
  * 1. wait the specified time
@@ -100,6 +134,7 @@ export function parallelAllSettled(tasks: Function[], maxParallel?: number): Pro
  */
 export function wait(waitTime: number): Waiter;
 declare namespace _default {
+    export { any };
     export { defer };
     export { delay };
     export { timeout };
@@ -108,6 +143,7 @@ declare namespace _default {
     export { series };
     export { seriesAllSettled };
     export { parallel };
+    export { parallelAny };
     export { parallelAllSettled };
     export { wait };
 }
@@ -116,6 +152,7 @@ export type Deferred = {
     promise: Promise<any>;
     timerHandler: NodeJS.Timeout;
     timerCleared: boolean;
+    pending: boolean;
     resolved: boolean;
     rejected: boolean;
     canceled: boolean;
@@ -125,5 +162,6 @@ export type Deferred = {
 export type Waiter = {
     promise: Promise<any>;
     timerHandler: NodeJS.Timeout;
-    resolve: (...args: any[]) => void;
+    _resolve: (...args: any[]) => void;
+    wakeup: () => void;
 };

package/types/string-utils.d.ts

@@ -150,6 +150,13 @@ export function substringBetweenGreedy(str: string, startMarker: string, endMark
  * @throws {Error} If any input is not a string
  */
 export function substringsBetween(str: string, startMarker: string, endMarker: string): string[];
+/**
+ * Safely converts a value to its string representation.
+ * Attempts to use JSON.stringify first, falls back to toString() if stringify fails.
+ * @param {*} value - The value to convert to string
+ * @returns {string} The string representation of the value
+ */
+export function safeToString(value: any): string;
 declare namespace _default {
     export { isEmpty };
     export { assertNotEmpty };
@@ -168,5 +175,6 @@ declare namespace _default {
     export { substringBetween };
     export { substringBetweenGreedy };
     export { substringsBetween };
+    export { safeToString };
 }
 export default _default;