@develia/commons 0.4.16 → 0.4.18

package/src/utilities.ts

@@ -1,480 +1,653 @@
-// 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';
-}
-
-
-/**
- * Structural deep equality check.
- *
- * Compares primitives by value, and objects/arrays/Maps/Sets/Dates/RegExps
- * by structure. Handles circular references.
- *
- * @param a - First value.
- * @param b - Second value.
- * @returns `true` if `a` and `b` are structurally equal.
- */
-export function deepEqual(a: unknown, b: unknown): boolean {
-    return _deepEqual(a, b);
-}
-
-/**
- * Internal implementation of deep equality check.
- * @param a - First value.
- * @param b - Second value.
- * @param seen - Internal map used to handle circular references.
- */
-function _deepEqual(
-    a: unknown,
-    b: unknown,
-    seen: WeakMap<object, unknown> = new WeakMap()
-): boolean {
-    if (a === b) return true;
-    if (a === null || b === null) return false;
-    if (typeof a !== typeof b) return false;
-    if (typeof a !== "object") return false;
-
-    const objA = a as object;
-    if (seen.has(objA)) return seen.get(objA) === b;
-    seen.set(objA, b);
-
-    if (a instanceof Date) return b instanceof Date && a.getTime() === b.getTime();
-    if (a instanceof RegExp) return b instanceof RegExp && a.toString() === b.toString();
-    if (Array.isArray(a) !== Array.isArray(b)) return false;
-
-    if (a instanceof Map) {
-        if (!(b instanceof Map) || a.size !== b.size) return false;
-        for (const [k, v] of a) {
-            if (!b.has(k) || !_deepEqual(v, b.get(k), seen)) return false;
-        }
-        return true;
-    }
-
-    if (a instanceof Set) {
-        if (!(b instanceof Set) || a.size !== b.size) return false;
-        for (const v of a) if (!b.has(v)) return false;
-        return true;
-    }
-
-    const keysA = Reflect.ownKeys(a as object);
-    const keysB = Reflect.ownKeys(b as object);
-    if (keysA.length !== keysB.length) return false;
-
-    for (const key of keysA) {
-        if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
-        if (!_deepEqual((a as any)[key], (b as any)[key], seen)) return false;
-    }
-
-    return true;
-}
-
-
-/**
- * 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;
-
-}
-
-/**
- * Creates an object composed of the picked object properties.
- *
- * @template T - The type of the source object.
- * @template K - The type of the keys to pick.
- * @param obj - The source object.
- * @param props - The property names to pick.
- * @returns A new object with the picked properties.
- */
-export function pick<T extends object, K extends keyof T>(obj: T, props: K[]): Pick<T, K> {
-    const result = {} as Pick<T, K>;
-    if (obj === null || typeof obj !== 'object') {
-        return result;
-    }
-
-    for (const key of props) {
-        if (key in obj) {
-            result[key] = obj[key];
-        }
-    }
-    return result;
-}
-
-/**
- * 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);
-}
-
-
-/**
- * Create a deep, independent copy of a value.
- *
- * Supports primitives, plain objects, arrays, `Date`, `RegExp`, `Map`, `Set`,
- * symbol-keyed properties and circular references. Functions are copied by
- * reference. Class instances preserve their prototype.
- *
- * @template T - The value's type.
- * @param value - The value to clone.
- * @returns A deep clone of `value`.
- */
-export function deepClone<T>(value: T): T {
-    return _deepClone(value);
-}
-
-/**
- * Internal implementation of deep clone.
- * @param value - The value to clone.
- * @param seen - Internal map used to handle circular references.
- */
-function _deepClone<T>(
-    value: T,
-    seen: WeakMap<object, unknown> = new WeakMap()
-): T {
-    if (value === null || typeof value !== "object") return value;
-
-    const obj = value as unknown as object;
-    if (seen.has(obj)) return seen.get(obj) as T;
-
-    if (value instanceof Date) return new Date(value) as T;
-    if (value instanceof RegExp) return new RegExp(value) as T;
-
-    if (value instanceof Map) {
-        const copy = new Map();
-        seen.set(value, copy);
-        for (const [k, v] of value) {
-            copy.set(_deepClone(k, seen), _deepClone(v, seen));
-        }
-        return copy as T;
-    }
-
-    if (value instanceof Set) {
-        const copy = new Set();
-        seen.set(value, copy);
-        for (const v of value) {
-            copy.add(_deepClone(v, seen));
-        }
-        return copy as T;
-    }
-
-    const copy: any = Array.isArray(value)
-        ? []
-        : Object.create(Object.getPrototypeOf(value));
-
-    seen.set(obj, copy);
-
-    for (const key of Reflect.ownKeys(obj)) {
-        copy[key] = _deepClone((value as any)[key], seen);
-    }
-
-    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, Constructor} 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 != null && typeof 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';
+}
+
+
+/**
+ * Structural deep equality check.
+ *
+ * Compares primitives by value, and objects/arrays/Maps/Sets/Dates/RegExps
+ * by structure. Handles circular references.
+ *
+ * @param a - First value.
+ * @param b - Second value.
+ * @param includeInherited - Whether inherited enumerable properties are compared. Defaults to `true`.
+ * @returns `true` if `a` and `b` are structurally equal.
+ */
+export function deepEqual(a: unknown, b: unknown, includeInherited = true): boolean {
+    return _deepEqual(a, b, includeInherited);
+}
+
+/**
+ * Internal implementation of deep equality check.
+ * @param a - First value.
+ * @param b - Second value.
+ * @param includeInherited - Whether inherited enumerable properties are compared.
+ * @param seen - Internal map used to handle circular references.
+ */
+function _deepEqual(
+    a: unknown,
+    b: unknown,
+    includeInherited: boolean,
+    seen: Map<object, unknown> = new Map()
+): boolean {
+    if (a === b) return true;
+    if (a === null || b === null) return false;
+    if (typeof a !== typeof b) return false;
+    if (typeof a !== "object") return false;
+
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+
+    if (a instanceof RegExp || b instanceof RegExp) {
+        return a instanceof RegExp && b instanceof RegExp && a.toString() === b.toString();
+    }
+
+    if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+    if (a instanceof Map || b instanceof Map) {
+        if (!(a instanceof Map) || !(b instanceof Map)) return false;
+    }
+
+    if (a instanceof Set || b instanceof Set) {
+        if (!(a instanceof Set) || !(b instanceof Set)) return false;
+    }
+
+    const objA = a as object;
+    if (seen.has(objA)) return seen.get(objA) === b;
+    seen.set(objA, b);
+
+    if (a instanceof Map && b instanceof Map) {
+        return _deepEqualMap(a, b, includeInherited, seen);
+    }
+
+    if (a instanceof Set && b instanceof Set) {
+        return _deepEqualSet(a, b, includeInherited, seen);
+    }
+
+    const objB = b as object;
+    const keysA = _deepEqualKeys(objA, includeInherited);
+    const keysB = _deepEqualKeys(objB, includeInherited);
+    if (keysA.length !== keysB.length) return false;
+
+    for (const key of keysA) {
+        if (!_deepEqualHasKey(objB, key, includeInherited)) return false;
+        if (!_deepEqual((a as any)[key], (b as any)[key], includeInherited, seen)) return false;
+    }
+
+    return true;
+}
+
+function _deepEqualMap(
+    a: Map<unknown, unknown>,
+    b: Map<unknown, unknown>,
+    includeInherited: boolean,
+    seen: Map<object, unknown>
+): boolean {
+    if (a.size !== b.size) return false;
+
+    const entriesB = Array.from(b.entries());
+    const matched = new Set<number>();
+
+    for (const [keyA, valueA] of a) {
+        let found = false;
+
+        for (let i = 0; i < entriesB.length; i++) {
+            if (matched.has(i)) continue;
+
+            const [keyB, valueB] = entriesB[i];
+            const candidateSeen = new Map(seen);
+            if (
+                _deepEqual(keyA, keyB, includeInherited, candidateSeen) &&
+                _deepEqual(valueA, valueB, includeInherited, candidateSeen)
+            ) {
+                matched.add(i);
+                _mergeDeepEqualSeen(candidateSeen, seen);
+                found = true;
+                break;
+            }
+        }
+
+        if (!found) return false;
+    }
+
+    return true;
+}
+
+function _deepEqualSet(
+    a: Set<unknown>,
+    b: Set<unknown>,
+    includeInherited: boolean,
+    seen: Map<object, unknown>
+): boolean {
+    if (a.size !== b.size) return false;
+
+    const valuesB = Array.from(b.values());
+    const matched = new Set<number>();
+
+    for (const valueA of a) {
+        let found = false;
+
+        for (let i = 0; i < valuesB.length; i++) {
+            if (matched.has(i)) continue;
+
+            const candidateSeen = new Map(seen);
+            if (_deepEqual(valueA, valuesB[i], includeInherited, candidateSeen)) {
+                matched.add(i);
+                _mergeDeepEqualSeen(candidateSeen, seen);
+                found = true;
+                break;
+            }
+        }
+
+        if (!found) return false;
+    }
+
+    return true;
+}
+
+function _deepEqualKeys(value: object, includeInherited: boolean): PropertyKey[] {
+    const keys: PropertyKey[] = [];
+    const seen = new Set<PropertyKey>();
+    const addKey = (key: PropertyKey) => {
+        if (seen.has(key)) return;
+        seen.add(key);
+        keys.push(key);
+    };
+
+    for (const key of Reflect.ownKeys(value)) {
+        addKey(key);
+    }
+
+    if (!includeInherited) return keys;
+
+    let prototype = Object.getPrototypeOf(value);
+    while (prototype !== null) {
+        for (const key of Reflect.ownKeys(prototype)) {
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+            if (descriptor?.enumerable) addKey(key);
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+
+    return keys;
+}
+
+function _deepEqualHasKey(value: object, key: PropertyKey, includeInherited: boolean): boolean {
+    return includeInherited
+        ? key in value
+        : Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function _mergeDeepEqualSeen(source: Map<object, unknown>, target: Map<object, unknown>): void {
+    for (const [key, value] of source) {
+        target.set(key, value);
+    }
+}
+
+
+/**
+ * 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 => Object.prototype.hasOwnProperty.call(b, 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<T>(value: T): value is Exclude<T, 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 isNullish(value);
+}
+
+/**
+ * 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 {
+    if (isNullish(value)) return true;
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === 'string') return value === '';
+    return false;
+}
+
+/**
+ * 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 {
+    if (typeof value === 'string') return value.trim() === '';
+    return isEmpty(value);
+}
+
+
+/**
+ * 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;
+
+}
+
+/**
+ * Creates an object composed of the picked object properties.
+ *
+ * @template T - The type of the source object.
+ * @template K - The type of the keys to pick.
+ * @param obj - The source object.
+ * @param props - The property names to pick.
+ * @returns A new object with the picked properties.
+ */
+export function pick<T extends object, K extends keyof T>(obj: T, props: K[]): Pick<T, K> {
+    const result = {} as Pick<T, K>;
+    if (obj === null || typeof obj !== 'object') {
+        return result;
+    }
+
+    for (const key of props) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+
+/**
+ * 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);
+}
+
+
+/**
+ * Create a deep, independent copy of a value.
+ *
+ * Supports primitives, plain objects, arrays, `Date`, `RegExp`, `Map`, `Set`,
+ * symbol-keyed properties and circular references. Functions are copied by
+ * reference. Class instances preserve their prototype.
+ *
+ * @template T - The value's type.
+ * @param value - The value to clone.
+ * @returns A deep clone of `value`.
+ */
+export function deepClone<T>(value: T): T {
+    return _deepClone(value);
+}
+
+/**
+ * Internal implementation of deep clone.
+ * @param value - The value to clone.
+ * @param seen - Internal map used to handle circular references.
+ */
+function _deepClone<T>(
+    value: T,
+    seen: WeakMap<object, unknown> = new WeakMap()
+): T {
+    if (value === null || typeof value !== "object") return value;
+
+    const obj = value as unknown as object;
+    if (seen.has(obj)) return seen.get(obj) as T;
+
+    if (value instanceof Date) return new Date(value) as T;
+    if (value instanceof RegExp) {
+        const copy = new RegExp(value);
+        copy.lastIndex = value.lastIndex;
+        return copy as T;
+    }
+
+    if (value instanceof Map) {
+        const copy = new Map();
+        seen.set(value, copy);
+        for (const [k, v] of value) {
+            copy.set(_deepClone(k, seen), _deepClone(v, seen));
+        }
+        return copy as T;
+    }
+
+    if (value instanceof Set) {
+        const copy = new Set();
+        seen.set(value, copy);
+        for (const v of value) {
+            copy.add(_deepClone(v, seen));
+        }
+        return copy as T;
+    }
+
+    const copy: any = Array.isArray(value)
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+
+    seen.set(obj, copy);
+
+    for (const key of Reflect.ownKeys(obj)) {
+        copy[key] = _deepClone((value as any)[key], seen);
+    }
+
+    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);
+}
+
+/**
+ * Patches a method onto a class prototype.
+ *
+ * This function allows adding new methods to existing classes (monkey-patching).
+ * If the method name already exists on the prototype, a warning is issued
+ * and the method is not overwritten.
+ *
+ * If `method` is a function, its name is extracted (if not provided) and
+ * it is wrapped to pass the instance (`this`) as the first argument.
+ *
+ * @template T - The type of the class constructor.
+ * @param {T} target - The class constructor whose prototype will be patched.
+ * @param {any} method - The implementation or value to patch.
+ * @param {string | symbol} [name] - Optional name for the method. If not provided and method is a function, method.name is used.
+ * @returns {boolean} Returns `true` if the method was successfully added, or `false` if it already existed.
+ */
+export function monkeyPatch<T extends Constructor>(
+    target: T,
+    method: any,
+    name?: string | symbol
+): boolean {
+
+    let methodName;
+    let methodValue = method;
+
+    if (typeof method === 'function') {
+        methodName = name ?? (method as Function).name;
+        methodValue = function (this: any, ...args: any[]) {
+            return method.apply(this, [this, ...args]);
+        };
+    } else {
+        methodName = name;
+    }
+
+    if (!methodName) {
+        throw new Error("Monkey patch failed: No name provided and could not be extracted from function.");
+    }
+
+    if (methodName in target.prototype) {
+        console.warn(`Method '${String(methodName)}' already exists on ${target.name}`);
+        return false;
+    }
+
+    Object.defineProperty(target.prototype, methodName, {
+        value: methodValue,
+        writable: true,
+        configurable: true,
+        enumerable: false
+    });
+
+    return true;
+}