@develia/commons 0.4.8 → 0.4.12

package/src/utilities.ts

@@ -1,404 +1,404 @@
-// noinspection JSUnusedGlobalSymbols
-
-
-import KeyValuePair from "./key-value-pair.js";
-import type {Resolvable} from "./types.js";
-import Type from "./type.js";
-
-export function lazy<T extends object>(factory: () => T): T {
-    let instance: T | null = null;
-
-    const getInstance = (): T => {
-        if (!instance) {
-            instance = factory();
-        }
-        return instance;
-    };
-
-    return new Proxy({} as T, {
-        get(_, prop, receiver) {
-            return Reflect.get(getInstance(), prop, receiver);
-        },
-        set(_, prop, value, receiver) {
-            return Reflect.set(getInstance(), prop, value, receiver);
-        },
-        has(_, prop) {
-            return Reflect.has(getInstance(), prop);
-        },
-        deleteProperty(_, prop) {
-            return Reflect.deleteProperty(getInstance(), prop);
-        },
-        ownKeys() {
-            return Reflect.ownKeys(getInstance());
-        },
-        getOwnPropertyDescriptor(_, prop) {
-            return Reflect.getOwnPropertyDescriptor(getInstance(), prop);
-        },
-        getPrototypeOf() {
-            return Reflect.getPrototypeOf(getInstance());
-        },
-    });
-}
-
-/**
- * Checks if an object is iterable.
- *
- * @param {any} obj - The object to check.
- * @return {boolean} - Returns true if the object is iterable, otherwise false.
- */
-export function isIterable(obj: any): boolean {
-    return obj[Symbol.iterator] === 'function';
-}
-
-/**
- * Checks if a given value is a string.
- *
- * @param {*} value - The value to check.
- * @return {boolean} - Returns true if the value is a string, otherwise returns false.
- */
-export function isString(value: any): value is string {
-    return typeof value === 'string';
-}
-
-/**
- * Checks if a value is a number.
- *
- * @param {any} value - The value to check.
- * @return {boolean} - Returns true if the value is a number, otherwise false.
- */
-export function isNumber(value: any): value is number {
-    return typeof value === 'number';
-}
-
-/**
- * Checks if a given value is a boolean.
- *
- * @param {any} value - The value to be checked.
- *
- * @return {boolean} - Returns true if the value is a boolean, otherwise false.
- */
-export function isBoolean(value: any): value is boolean {
-    return typeof value === 'boolean';
-}
-
-/**
- * Checks if a value is an object.
- * @param {any} value - The value to be checked.
- * @returns {boolean} - Returns true if the value is an object, otherwise returns false.
- */
-export function isObject(value: any): value is object {
-    return value != null && typeof value === 'object' && !Array.isArray(value);
-}
-
-/**
- * Determines if a value is an array.
- *
- * @param value - The value to be checked.
- *
- * @return Whether the value is an array.
- */
-export function isArray(value: any): value is any[] {
-    return Array.isArray(value);
-}
-
-/**
- * Checks if a value is a function.
- *
- * @param {any} value - The value to be checked.
- * @return {boolean} - Returns true if the value is a function, otherwise returns false.
- */
-export function isFunction(value: any): value is Function {
-    return typeof value === 'function';
-}
-
-
-/**
- * Compares two objects or arrays to check if they have the same fields and values,
- * or the same elements if they are arrays (deep equality check).
- *
- * @param {any} a - The first object or array.
- * @param {any} b - The second object or array.
- * @return {boolean} - Returns true if the objects/arrays are deeply equal, otherwise false.
- */
-export function deepEqual(a: any, b: any): boolean {
-    if (a === b) {
-        return true;
-    }
-
-    if (a === null || b === null || typeof a !== typeof b) {
-        return false;
-    }
-
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length) {
-            return false;
-        }
-        for (let i = 0; i < a.length; i++) {
-            if (!deepEqual(a[i], b[i])) {
-                return false;
-            }
-        }
-        return true;
-    }
-
-    if (typeof a === "object" && typeof b === "object") {
-        const keysA = Object.keys(a);
-        const keysB = Object.keys(b);
-
-        if (keysA.length !== keysB.length) {
-            return false;
-        }
-        for (const key of keysA) {
-            if (!keysB.includes(key) || !deepEqual(a[key], b[key])) {
-                return false;
-            }
-        }
-        return true;
-    }
-
-    return false;
-}
-
-
-/**
- * Submits an HTML form programmatically using the specified HTTP method (default is POST),
- * without using AJAX. Supports nested objects and arrays using bracket notation (e.g., `user[name]`, `tags[]`).
- *
- * @param url - The destination URL where the form will be submitted.
- * @param data - An object containing key-value pairs. Supports nested structures and arrays.
- * @param method - HTTP method to use: 'POST' or 'GET' (default: 'POST').
- * @param target - Optional parameter specifying the target for the form submission (e.g., '_blank', '_self', '_parent', '_top').
- */
-
-
-/**
- * Compares two objects or arrays to check if they have the same immediate fields and values,
- * or the same immediate elements if they are arrays (shallow equality check).
- *
- * @param {any} a - The first object or array.
- * @param {any} b - The second object or array.
- * @return {boolean} - Returns true if the objects/arrays are shallowly equal, otherwise false.
- */
-export function shallowEqual(a: any, b: any): boolean {
-    if (a === b) {
-        return true;
-    }
-
-    if (a === null || b === null || typeof a !== typeof b) {
-        return false;
-    }
-
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length) {
-            return false;
-        }
-        return a.every((value, index) => value === b[index]);
-    }
-
-    if (typeof a === "object" && typeof b === "object") {
-        const keysA = Object.keys(a);
-        const keysB = Object.keys(b);
-
-        if (keysA.length !== keysB.length) {
-            return false;
-        }
-        return keysA.every(key => b.hasOwnProperty(key) && a[key] === b[key]);
-    }
-
-    return false;
-}
-
-
-/**
- * Pauses the execution of an asynchronous function for a specified duration.
- *
- * @param {number} ms - The delay duration in milliseconds.
- * @return {Promise<void>} A promise that resolves after the specified delay.
- */
-export async function delay(ms: number): Promise<void> {
-    await new Promise(resolve => setTimeout(resolve, ms));
-}
-
-/**
- * Checks if a value is undefined.
- *
- * @param {any} value - The value to check.
- * @returns {boolean} - True if the value is undefined, false otherwise.
- */
-export function isUndefined(value: any): value is undefined {
-    return typeof value === 'undefined';
-}
-
-/**
- * Checks if a value is defined or not.
- *
- * @param {any} value - The value to be checked.
- *
- * @return {boolean} - True if the value is defined, false otherwise.
- */
-export function isDefined(value: any): value is undefined {
-    return typeof value !== 'undefined';
-}
-
-/**
- * Checks if a given value is null.
- *
- * @param {any} value - The value to check for null.
- * @return {boolean} - Returns true if the value is null, otherwise returns false.
- */
-export function isNull(value: any): value is null {
-    return value === null;
-}
-
-
-/**
- * Determines whether the given value is of type bigint.
- * @param {any} value - The value to be checked.
- * @return {boolean} - Returns true if the value is of type bigint, false otherwise.
- */
-export function isBigInt(value: any): value is bigint {
-    return typeof value === 'bigint';
-}
-
-/**
- * Checks if a given value is a symbol.
- *
- * @param {any} value - The value to be checked.
- * @return {boolean} - Returns true if the value is a symbol, false otherwise.
- */
-export function isSymbol(value: any): value is symbol {
-    return typeof value === 'symbol';
-}
-
-/**
- * Checks if a value is null or undefined.
- *
- * @param {any} value - The value to check.
- * @return {boolean} - Returns true if the value is null or undefined, false otherwise.
- * @deprecated
- */
-export function isNullOrUndefined(value: any): boolean {
-    return value === null || typeof value === 'undefined';
-}
-
-/**
- * Checks if a value is null or undefined.
- *
- * @param {any} value - The value to check.
- * @return {boolean} - Returns true if the value is null or undefined, false otherwise.
-
- */
-export function isNullish(value: any): boolean {
-    return value === null || typeof value === 'undefined';
-}
-
-/**
- * Checks if a given value is empty.
- *
- * @param {any} value - The value to check.
- * @return {boolean} - Returns true if the value is empty, otherwise returns false.
- */
-export function isEmpty(value: any): boolean {
-    return (Array.isArray(value) && value.length === 0) ||
-        (typeof value === 'string' && value === '') ||
-        value === null || typeof value === 'undefined';
-}
-
-/**
- * Check if a value is empty or contains only whitespace characters.
- *
- * @param {any} value - The value to check.
- * @return {boolean} Returns true if the value is empty or contains only whitespace characters, otherwise returns false.
- */
-export function isEmptyOrWhitespace(value: any): boolean {
-    return (Array.isArray(value) && value.length === 0) ||
-        (typeof value === 'string' && value.trim() === '') ||
-        value === null || typeof value === 'undefined';
-}
-
-
-/**
- * Converts an object into an array of key-value pairs.
- *
- * @param {Record<string, any>} obj - The object to convert.
- * @return {KeyValuePair<string, any>[]} - The array of key-value pairs.
- */
-export function toPairs(obj: Record<string, any>): KeyValuePair<string, any>[] {
-
-    let output = [];
-    for (const key in obj) {
-        output.push(new KeyValuePair(key, obj[key]));
-    }
-    return output;
-
-}
-
-/**
- * Converts a given thing into a Promise.
- * @template T
- * @param {any} thing - The thing to be converted into a Promise.
- * @returns {Promise<T>} - A Promise representing the given thing.
- */
-export function promisify<T>(thing: Resolvable<T>): Promise<T> {
-
-    if (thing instanceof Promise)
-        return thing;
-
-
-    if (isFunction(thing)) {
-        return new Promise<T>((resolve, reject) => {
-            try {
-                const result = thing();
-                resolve(result);
-            } catch (error) {
-                reject(error);
-            }
-        });
-    }
-
-    return Promise.resolve(thing);
-}
-
-
-/**
- * Creates a deep clone of the given object.
- * @template T
- * @param {T} obj - The object to clone.
- * @return {T} - The deep clone of the given object.
- */
-export function deepClone<T>(obj: T): T {
-    if (obj === null || typeof obj !== 'object') {
-        return obj;
-    }
-
-    if (Array.isArray(obj)) {
-        const copy: any[] = [];
-        for (const element of obj) {
-            copy.push(deepClone(element));
-        }
-        return copy as T;
-    }
-
-    const copy: { [key: string]: any } = {};
-    for (const key in obj) {
-        if (obj.hasOwnProperty(key)) {
-            copy[key] = deepClone((obj as { [key: string]: any })[key]);
-        }
-    }
-    return copy as T;
-}
-
-/**
- * Returns the type of the given value.
- *
- * @param {any} value - The value to determine the type of.
- * @return {Type} - The type of the given value.
- * @deprecated use Type.of(...)
- */
-export function getType(value: any): Type {
-
-    return Type.of(value);
-}
-
-
-
+// noinspection JSUnusedGlobalSymbols
+
+
+import KeyValuePair from "./key-value-pair.js";
+import type {Resolvable} from "./types.js";
+import Type from "./type.js";
+
+export function lazy<T extends object>(factory: () => T): T {
+    let instance: T | null = null;
+
+    const getInstance = (): T => {
+        if (!instance) {
+            instance = factory();
+        }
+        return instance;
+    };
+
+    return new Proxy({} as T, {
+        get(_, prop, receiver) {
+            return Reflect.get(getInstance(), prop, receiver);
+        },
+        set(_, prop, value, receiver) {
+            return Reflect.set(getInstance(), prop, value, receiver);
+        },
+        has(_, prop) {
+            return Reflect.has(getInstance(), prop);
+        },
+        deleteProperty(_, prop) {
+            return Reflect.deleteProperty(getInstance(), prop);
+        },
+        ownKeys() {
+            return Reflect.ownKeys(getInstance());
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            return Reflect.getOwnPropertyDescriptor(getInstance(), prop);
+        },
+        getPrototypeOf() {
+            return Reflect.getPrototypeOf(getInstance());
+        },
+    });
+}
+
+/**
+ * Checks if an object is iterable.
+ *
+ * @param {any} obj - The object to check.
+ * @return {boolean} - Returns true if the object is iterable, otherwise false.
+ */
+export function isIterable(obj: any): boolean {
+    return obj[Symbol.iterator] === 'function';
+}
+
+/**
+ * Checks if a given value is a string.
+ *
+ * @param {*} value - The value to check.
+ * @return {boolean} - Returns true if the value is a string, otherwise returns false.
+ */
+export function isString(value: any): value is string {
+    return typeof value === 'string';
+}
+
+/**
+ * Checks if a value is a number.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is a number, otherwise false.
+ */
+export function isNumber(value: any): value is number {
+    return typeof value === 'number';
+}
+
+/**
+ * Checks if a given value is a boolean.
+ *
+ * @param {any} value - The value to be checked.
+ *
+ * @return {boolean} - Returns true if the value is a boolean, otherwise false.
+ */
+export function isBoolean(value: any): value is boolean {
+    return typeof value === 'boolean';
+}
+
+/**
+ * Checks if a value is an object.
+ * @param {any} value - The value to be checked.
+ * @returns {boolean} - Returns true if the value is an object, otherwise returns false.
+ */
+export function isObject(value: any): value is object {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Determines if a value is an array.
+ *
+ * @param value - The value to be checked.
+ *
+ * @return Whether the value is an array.
+ */
+export function isArray(value: any): value is any[] {
+    return Array.isArray(value);
+}
+
+/**
+ * Checks if a value is a function.
+ *
+ * @param {any} value - The value to be checked.
+ * @return {boolean} - Returns true if the value is a function, otherwise returns false.
+ */
+export function isFunction(value: any): value is Function {
+    return typeof value === 'function';
+}
+
+
+/**
+ * Compares two objects or arrays to check if they have the same fields and values,
+ * or the same elements if they are arrays (deep equality check).
+ *
+ * @param {any} a - The first object or array.
+ * @param {any} b - The second object or array.
+ * @return {boolean} - Returns true if the objects/arrays are deeply equal, otherwise false.
+ */
+export function deepEqual(a: any, b: any): boolean {
+    if (a === b) {
+        return true;
+    }
+
+    if (a === null || b === null || typeof a !== typeof b) {
+        return false;
+    }
+
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqual(a[i], b[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    if (typeof a === "object" && typeof b === "object") {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+
+        if (keysA.length !== keysB.length) {
+            return false;
+        }
+        for (const key of keysA) {
+            if (!keysB.includes(key) || !deepEqual(a[key], b[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    return false;
+}
+
+
+/**
+ * Submits an HTML form programmatically using the specified HTTP method (default is POST),
+ * without using AJAX. Supports nested objects and arrays using bracket notation (e.g., `user[name]`, `tags[]`).
+ *
+ * @param url - The destination URL where the form will be submitted.
+ * @param data - An object containing key-value pairs. Supports nested structures and arrays.
+ * @param method - HTTP method to use: 'POST' or 'GET' (default: 'POST').
+ * @param target - Optional parameter specifying the target for the form submission (e.g., '_blank', '_self', '_parent', '_top').
+ */
+
+
+/**
+ * Compares two objects or arrays to check if they have the same immediate fields and values,
+ * or the same immediate elements if they are arrays (shallow equality check).
+ *
+ * @param {any} a - The first object or array.
+ * @param {any} b - The second object or array.
+ * @return {boolean} - Returns true if the objects/arrays are shallowly equal, otherwise false.
+ */
+export function shallowEqual(a: any, b: any): boolean {
+    if (a === b) {
+        return true;
+    }
+
+    if (a === null || b === null || typeof a !== typeof b) {
+        return false;
+    }
+
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        return a.every((value, index) => value === b[index]);
+    }
+
+    if (typeof a === "object" && typeof b === "object") {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+
+        if (keysA.length !== keysB.length) {
+            return false;
+        }
+        return keysA.every(key => b.hasOwnProperty(key) && a[key] === b[key]);
+    }
+
+    return false;
+}
+
+
+/**
+ * Pauses the execution of an asynchronous function for a specified duration.
+ *
+ * @param {number} ms - The delay duration in milliseconds.
+ * @return {Promise<void>} A promise that resolves after the specified delay.
+ */
+export async function delay(ms: number): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Checks if a value is undefined.
+ *
+ * @param {any} value - The value to check.
+ * @returns {boolean} - True if the value is undefined, false otherwise.
+ */
+export function isUndefined(value: any): value is undefined {
+    return typeof value === 'undefined';
+}
+
+/**
+ * Checks if a value is defined or not.
+ *
+ * @param {any} value - The value to be checked.
+ *
+ * @return {boolean} - True if the value is defined, false otherwise.
+ */
+export function isDefined(value: any): value is undefined {
+    return typeof value !== 'undefined';
+}
+
+/**
+ * Checks if a given value is null.
+ *
+ * @param {any} value - The value to check for null.
+ * @return {boolean} - Returns true if the value is null, otherwise returns false.
+ */
+export function isNull(value: any): value is null {
+    return value === null;
+}
+
+
+/**
+ * Determines whether the given value is of type bigint.
+ * @param {any} value - The value to be checked.
+ * @return {boolean} - Returns true if the value is of type bigint, false otherwise.
+ */
+export function isBigInt(value: any): value is bigint {
+    return typeof value === 'bigint';
+}
+
+/**
+ * Checks if a given value is a symbol.
+ *
+ * @param {any} value - The value to be checked.
+ * @return {boolean} - Returns true if the value is a symbol, false otherwise.
+ */
+export function isSymbol(value: any): value is symbol {
+    return typeof value === 'symbol';
+}
+
+/**
+ * Checks if a value is null or undefined.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is null or undefined, false otherwise.
+ * @deprecated
+ */
+export function isNullOrUndefined(value: any): boolean {
+    return value === null || typeof value === 'undefined';
+}
+
+/**
+ * Checks if a value is null or undefined.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is null or undefined, false otherwise.
+
+ */
+export function isNullish(value: any): boolean {
+    return value === null || typeof value === 'undefined';
+}
+
+/**
+ * Checks if a given value is empty.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} - Returns true if the value is empty, otherwise returns false.
+ */
+export function isEmpty(value: any): boolean {
+    return (Array.isArray(value) && value.length === 0) ||
+        (typeof value === 'string' && value === '') ||
+        value === null || typeof value === 'undefined';
+}
+
+/**
+ * Check if a value is empty or contains only whitespace characters.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} Returns true if the value is empty or contains only whitespace characters, otherwise returns false.
+ */
+export function isEmptyOrWhitespace(value: any): boolean {
+    return (Array.isArray(value) && value.length === 0) ||
+        (typeof value === 'string' && value.trim() === '') ||
+        value === null || typeof value === 'undefined';
+}
+
+
+/**
+ * Converts an object into an array of key-value pairs.
+ *
+ * @param {Record<string, any>} obj - The object to convert.
+ * @return {KeyValuePair<string, any>[]} - The array of key-value pairs.
+ */
+export function toPairs(obj: Record<string, any>): KeyValuePair<string, any>[] {
+
+    let output = [];
+    for (const key in obj) {
+        output.push(new KeyValuePair(key, obj[key]));
+    }
+    return output;
+
+}
+
+/**
+ * Converts a given thing into a Promise.
+ * @template T
+ * @param {any} thing - The thing to be converted into a Promise.
+ * @returns {Promise<T>} - A Promise representing the given thing.
+ */
+export function promisify<T>(thing: Resolvable<T>): Promise<T> {
+
+    if (thing instanceof Promise)
+        return thing;
+
+
+    if (isFunction(thing)) {
+        return new Promise<T>((resolve, reject) => {
+            try {
+                const result = thing();
+                resolve(result);
+            } catch (error) {
+                reject(error);
+            }
+        });
+    }
+
+    return Promise.resolve(thing);
+}
+
+
+/**
+ * Creates a deep clone of the given object.
+ * @template T
+ * @param {T} obj - The object to clone.
+ * @return {T} - The deep clone of the given object.
+ */
+export function deepClone<T>(obj: T): T {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+
+    if (Array.isArray(obj)) {
+        const copy: any[] = [];
+        for (const element of obj) {
+            copy.push(deepClone(element));
+        }
+        return copy as T;
+    }
+
+    const copy: { [key: string]: any } = {};
+    for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+            copy[key] = deepClone((obj as { [key: string]: any })[key]);
+        }
+    }
+    return copy as T;
+}
+
+/**
+ * Returns the type of the given value.
+ *
+ * @param {any} value - The value to determine the type of.
+ * @return {Type} - The type of the given value.
+ * @deprecated use Type.of(...)
+ */
+export function getType(value: any): Type {
+
+    return Type.of(value);
+}
+
+
+