toolbox-x 2.2.4 → 2.3.0

package/dist/{basics-20lm69yy.mjs → utils-BO5CcsjK.mjs}

@@ -16,532 +16,289 @@
 
 import { a as isNonEmptyString, c as isNumber, d as isString, m as isUndefined, n as isBoolean, u as isPrimitive } from "./primitives-Djsevc69.mjs";
 import { C as isMethodDescriptor, E as isObjectWithKeys, T as isObject, b as isFunction, c as isHexString, d as isNumericString, g as isArrayOfType, h as isArray, j as isValidArray, m as isUUID, w as isNotEmptyObject } from "./specials-krf7zsqI.mjs";
-import { a as normalizeNumber } from "./utilities-BSv8VbnM.mjs";
-import { t as isDateLike } from "./guards-DKGBsd6x.mjs";
+import { a as normalizeNumber } from "./utilities-CmPwOkdy.mjs";
+import { t as isDateLike } from "./guards-DBunDnng.mjs";
 
-//#region src/array/helpers.ts
+//#region src/string/basics.ts
 /**
-* Safely resolves value of nested key (dot-notation key like `"user.city"`).
+* * Utility to truncate a string to a specified length.
 *
-* @param obj - The source object
-* @param path - The nested path string (e.g. `"user.city"`)
-* @returns The resolved value or `undefined`
+* @param str The string to truncate.
+* @param maxLength The maximum length of the truncated string.
+* @returns Truncated string with ellipsis (`...`) (only if it has more length than `maxLength`).
 */
-function _resolveNestedKey(obj, path) {
-	if (isNotEmptyObject(obj)) return path?.split(".").reduce((acc, key) => {
-		if (isNotEmptyObject(acc)) return acc[key];
-	}, obj);
+function truncateString(str, maxLength) {
+	if (!isNonEmptyString(str)) return "";
+	const trimmedString = str.trim();
+	if (!trimmedString) return "";
+	if (trimmedString.length <= maxLength) return trimmedString;
+	return trimmedString.slice(0, maxLength).concat("...");
 }
 /**
-* Retrieves a numeric value from a nested property (dot-notation key like 'user.income.tax').
-* Falls back to 0 if value is not a number or numeric string.
+* * Generates a random alphanumeric (16 characters long, this length is customizable in the options) ID string composed of an optional `prefix`, `suffix`, a `timestamp`, `caseOption` and a customizable `separator`.
 *
-* @param obj - The source object to read from.
-* @param path - The dot-notation path string like 'user.income.tax'.
-* @returns The numeric value at that path, or 0 if	 not valid.
-*/
-function _getNumericProp(obj, path) {
-	return normalizeNumber(_resolveNestedKey(obj, path)) ?? 0;
-}
-
-//#endregion
-//#region src/array/sort.ts
-/**
-* Compare two strings using natural sorting (e.g., `"file2"` < `"file10"`).
-* - Optionally supports case-insensitive and locale-aware string chunk comparisons.
+* @param options Configuration options for random ID generation.
+* @returns The generated ID string composed of the random alphanumeric string of specified length with optional `timeStamp`, `prefix`, and `suffix`, `caseOption` and `separator`.
 *
-* @param a - The first string to compare.
-* @param b - The second string to compare.
-* @param options - Optional settings to configure comparison behavior.
-* @returns A negative number if `a` comes before `b`, a positive number if `a` comes after `b`, or 0 if equal.
+* @see {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/hash/uuid uuid} for `uuid` generation
+* @see {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/hash/random-hex randomHex} for random hexadecimal string generation
+*
+* @example
+* // Generate an ID with all default options
+* const id = generateRandomID();
+* // Example output: "swo8ckxwsc13w7xw"
+*
+* @example
+* // Generate an ID with a custom prefix and separator
+* const id = generateRandomID({ prefix: 'ID', separator: '-' });
+* // Example output: "ID-eh1ymwfxzwas9jte"
+*
+* @example
+* // Generate an ID with a timestamp
+* const id = generateRandomID({ timeStamp: false });
+* // Example output: "1764610287501pd3r4w85qwkuulgf"
+*
+* @example
+* // Generate an ID with a custom length for the random string
+* const id = generateRandomID({ length: 8 });
+* // Example output: "i623uiev"
+*
+* @example
+* // Generate an ID with a custom suffix
+* const id = generateRandomID({ suffix: 'END' });
+* // Example output: "3csf27a4800rbli9END"
+*
+* @example
+* // Generate an ID with a uppercase random string
+* const id = generateRandomID({ caseOption: "upper" });
+* // Example output: "H0VNU6O8XV1Y30HG"
+*
+* @example
+* // Generate an ID with all options customized
+* const id = generateRandomID({
+*   prefix: 'ID',
+*   suffix: 'END',
+*   timeStamp: true,
+*   length: 10,
+*   separator: '-',
+*   caseOption: "upper"
+* });
+* // Example output: "ID-1764610471474-4KSL51IB91-END"
 */
-function naturalSort(a, b, options) {
-	const { caseInsensitive = true, localeAware = false } = options || {};
-	/**
-	* * Splits a string into an array of number and non-number chunks.
-	* @param str - The string to split.
-	* @returns An array of string and number parts.
-	*/
-	const _createChunks = (str) => {
-		const chunks = [];
-		let current = "";
-		let isNumeric = false;
-		for (const char of str) {
-			const charIsNum = !Number.isNaN(Number(char));
-			if (current?.length === 0) {
-				current = char;
-				isNumeric = charIsNum;
-				continue;
-			}
-			if (charIsNum === isNumeric) current += char;
-			else {
-				chunks?.push(isNumeric ? Number(current) : current);
-				current = char;
-				isNumeric = charIsNum;
-			}
-		}
-		if (current?.length > 0) chunks?.push(isNumeric ? Number(current) : current);
-		return chunks;
-	};
-	const aChunks = _createChunks(a);
-	const bChunks = _createChunks(b);
-	for (let i = 0; i < Math.min(aChunks?.length, bChunks?.length); i++) {
-		let aChunk = aChunks[i];
-		let bChunk = bChunks[i];
-		if (caseInsensitive && isString(aChunk) && isString(bChunk)) {
-			aChunk = aChunk?.toLowerCase();
-			bChunk = bChunk?.toLowerCase();
-		}
-		if (typeof aChunk !== typeof bChunk) return isString(aChunk) ? 1 : -1;
-		if (aChunk !== bChunk) {
-			if (isNumber(aChunk) && isNumber(bChunk)) return aChunk - bChunk;
-			if (isString(aChunk) && isString(bChunk)) {
-				if (localeAware) {
-					const cmp = aChunk.localeCompare(bChunk, void 0, { sensitivity: caseInsensitive ? "accent" : "variant" });
-					if (cmp !== 0) return cmp;
-				}
-				return aChunk < bChunk ? -1 : 1;
-			}
-		}
+function generateRandomID(options) {
+	const { prefix = "", suffix = "", timeStamp = false, length = 16, separator = "", caseOption = null } = options || {};
+	const date = timeStamp ? Date.now() : "";
+	const randomString = Array.from({ length }, () => Math.random().toString(36).slice(2, 3)).join("");
+	const ID = [
+		prefix?.trim(),
+		date,
+		randomString,
+		suffix?.trim()
+	].filter(Boolean).join(separator);
+	switch (caseOption) {
+		case "upper": return ID.toUpperCase();
+		case "lower": return ID.toLowerCase();
+		default: return ID;
 	}
-	return aChunks?.length - bChunks?.length;
 }
 /**
-* * Sorts an array of strings, numbers, booleans, or objects based on the provided options.
+* * Trims all whitespaces in a string or an array of strings.
 *
-* @param array - The array to sort.
-* @param options - Sorting options.
-* @returns The sorted array.
+* @param input String or array of strings.
+* @returns Trimmed string or array of strings.
 */
-function sortAnArray(array, options) {
-	if (!isValidArray(array)) return array;
-	if (isArrayOfType(array, isString)) return [...array].sort((a, b) => options?.sortOrder === "desc" ? naturalSort(b, a) : naturalSort(a, b));
-	if (isArrayOfType(array, isNumber)) return [...array].sort((a, b) => options?.sortOrder === "desc" ? b - a : a - b);
-	if (isArrayOfType(array, isBoolean)) return [...array].sort((a, b) => options?.sortOrder === "desc" ? Number(b) - Number(a) : Number(a) - Number(b));
-	if (isArrayOfType(array, isObject) && options && "sortByField" in options) return [...array].sort((a, b) => {
-		const _getKeyValue = (obj, path) => {
-			return path.split(".").reduce((acc, key) => acc?.[key], obj);
-		};
-		const keyA = _getKeyValue(a, options?.sortByField);
-		const keyB = _getKeyValue(b, options?.sortByField);
-		if (keyA == null || keyB == null) return keyA == null ? 1 : -1;
-		if (isString(keyA) && isString(keyB)) return options?.sortOrder === "desc" ? naturalSort(keyB, keyA) : naturalSort(keyA, keyB);
-		if (isNumber(keyA) && isNumber(keyB)) return options?.sortOrder === "desc" ? keyB - keyA : keyA - keyB;
-		if (isBoolean(keyA) && isBoolean(keyB)) return options?.sortOrder === "desc" ? Number(keyB) - Number(keyA) : Number(keyA) - Number(keyB);
-		return 0;
-	});
-	return [...array];
+function trimString(input) {
+	if (!input) return "";
+	if (isNonEmptyString(input)) return input.trim().replace(/\s+/g, " ");
+	if (Array.isArray(input)) return input.map((str) => isNonEmptyString(str) ? str.trim().replace(/\s+/g, " ") : str);
+	throw new TypeError("Expected string or array of strings!", { cause: "Invalid Input Type" });
 }
 
 //#endregion
-//#region src/utils/index.ts
+//#region src/hash/utils.ts
 /**
-* * Deeply compare two values (arrays, objects, or primitive values).
+* * Generates random bytes in the {@link Uint8Array} format.
 *
-* @param a First value to compare.
-* @param b Second value to compare.
-* @returns Whether the values are deeply equal.
-*/
-const isDeepEqual = (a, b) => {
-	if (a === b) return true;
-	if (typeof a !== typeof b) return false;
-	if (a === null || b === null) return a === b;
-	if (isArray(a) && isArray(b)) {
-		if (a?.length !== b?.length) return false;
-		return a?.every((element, index) => isDeepEqual(element, b?.[index]));
-	}
-	if (isObject(a) && isObject(b)) {
-		const aKeys = Object.keys(a);
-		const bKeys = Object.keys(b);
-		if (aKeys?.length !== bKeys?.length) return false;
-		return aKeys?.every((key) => isDeepEqual(a?.[key], b?.[key]));
-	}
-	return false;
-};
-/**
-* * Converts an array of primitive values or objects to a string using a separator or target key.
+* @param size - The length of the byte array to generate. Defaults to `8`.
+* @returns A random array of bytes.
 *
-* @param array Array to convert.
-* @param options Options for separator or key extraction from objects.
-* @returns String representation of array values.
-*/
-function convertArrayToString(array, options) {
-	if (!isValidArray(array)) return "";
-	const { separator = ", " } = options ?? {};
-	if (isArrayOfType(array, isPrimitive)) return array?.join(separator);
-	else if (isArrayOfType(array, isNotEmptyObject)) if (options && "target" in options) return array?.map((el) => _resolveNestedKey(el, options?.target))?.join(separator);
-	else return "";
-	return "";
-}
-/**
-* * A generic debounce function that delays the execution of a callback.
+* @example
+* ```typescript
+* const bytes = randomBytes(16);
+* // Returns something like: Uint8Array(16) [104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 224, 166, 170, 224, 167, 131]
 *
-* @param callback - The function to debounce.
-* @param delay - The delay in milliseconds. Default is `300ms`.
-* @returns A debounced version of the callback function.
+* // Empty array
+* const empty = randomBytes(0);
+* // Returns: Uint8Array(0) []
 *
-* @example
-* const debouncedSearch = debounceAction((query: string) => {
-*   console.log(`Searching for: ${query}`);
-* }, 300);
+* // Zero or negative values are treated as 0
+* const zero = randomBytes(-5);
+* // Returns: Uint8Array(0) []
+* ```
 *
-* debouncedSearch('laptop'); // Executes after 300ms of inactivity.
+* @remarks
+* - It uses {@link crypto.getRandomValues} when available for secure randomness, and falls back to {@link Math.random} if not.
+* - If {@link crypto.getRandomValues} is available (supported environments include browser and Node.js), it is used for cryptographically secure random number generation.
+* - In environments where {@link crypto.getRandomValues} is not available, the function falls back to {@link Math.random}, which is **not** cryptographically secure.
+* - {@link crypto.getRandomValues} fills the array with random values in the range [0, 255] (inclusive).
+* - {@link Math.random} returns values in the range [0, 1) (exclusive of 1), so the values are scaled to [0, 255].
+* - If `size` is 0 or negative, an empty `Uint8Array` is returned.
 */
-function debounceAction(callback, delay = 300) {
-	let timeoutId;
-	return (...args) => {
-		clearTimeout(timeoutId);
-		timeoutId = setTimeout(() => {
-			callback(...args);
-		}, delay);
-	};
+function randomBytes(size = 8) {
+	if (size <= 0) return new Uint8Array(0);
+	return _fillWithRandomValues(new Uint8Array(size));
 }
 /**
-* * A generic throttle function that ensures a callback is executed at most once per specified interval.
+* * Generates a random hexadecimal string of the specified length.
 *
-* @param callback - The function to throttle.
-* @param delay - The delay in milliseconds. Default is `150ms`.
-* @returns A throttled version of the callback function.
+* @param length - Number of hex characters to generate.
+* @param uppercase - Whether to return uppercase `A–F` characters. Defaults to `false` (lowercase).
 *
-* @example
-* const throttledResize = throttleAction(() => {
-*   console.log('Resized');
-* }, 300);
+* @returns A randomly generated hexadecimal string.
 *
-* window.addEventListener('resize', throttledResize);
-*/
-function throttleAction(callback, delay = 150) {
-	let lastCall = 0;
-	return (...args) => {
-		const now = Date.now();
-		if (now - lastCall >= delay) {
-			lastCall = now;
-			callback(...args);
-		}
-	};
-}
-/**
-* * Retrieves the names of all instance methods defined directly on a class prototype.
+* @remarks
+* - This function generates a random hexadecimal string of the specified length.
+* - It uses {@link crypto.getRandomValues} when available for secure randomness, and falls back to {@link Math.random} if not.
+* - The output is a string of hex characters (`0–9`, `a–f` or `A–F`) with no prefixes or separators.
+* - If `length` is `0` or negative, an empty string is returned.
 *
-* @param cls - The class constructor (not an instance).
-* @returns A sorted array of instance method names.
-*/
-function getInstanceMethodNames(cls) {
-	const prototype = cls.prototype;
-	return sortAnArray(Object.getOwnPropertyNames(prototype).filter((method) => {
-		if (method === "constructor") return false;
-		return isMethodDescriptor(Object.getOwnPropertyDescriptor(prototype, method));
-	}));
-}
-/**
-* * Retrieves the names of all static methods defined directly on a class constructor.
+* @example
+* // 16-character lowercase hex
+* const id = randomHex(16);
 *
-* @param cls - The class constructor (not an instance).
-* @returns A sorted array of static method names.
+* @example
+* // 8-character uppercase hex
+* const token = randomHex(8, true);
 */
-function getStaticMethodNames(cls) {
-	return sortAnArray(Object.getOwnPropertyNames(cls).filter((method) => {
-		return method !== "prototype" && method !== "name" && method !== "length";
-	}));
+function randomHex(length, uppercase = false) {
+	if (length <= 0) return "";
+	const expected = _bytesToRandomHex(new Uint8Array(Math.ceil(length / 2))).slice(0, length);
+	return uppercase ? expected.toUpperCase() : expected;
 }
 /**
-* * Counts the number of instance methods defined directly on a class prototype.
+* * Generates a random numeric string of the specified length.
 *
-* @param cls - The class constructor (not an instance).
-* @returns The number of instance methods defined on the class prototype.
-*/
-function countInstanceMethods(cls) {
-	return getInstanceMethodNames(cls)?.length;
-}
-/**
-* * Counts the number of static methods defined directly on a class constructor.
+* @param length - Length of the numeric string. Defaults to `6`.
+* @returns A randomly generated numeric string.
 *
-* @param cls - The class constructor (not an instance).
-* @returns The number of static methods defined on the class constructor.
-*/
-function countStaticMethods(cls) {
-	return getStaticMethodNames(cls)?.length;
-}
-/**
-* * Retrieves the names of all instance getters defined directly on a class prototype.
+* @example
+* ```typescript
+* const otp = randomNumeric(6);
+* // Returns something like: '123456'
+* ```
 *
-* @param cls - The class constructor (not an instance).
-* @returns A sorted array of instance getter names.
+* @remarks
+* - If `length` is `0` or negative, an empty string is returned.
 */
-function getInstanceGetterNames(cls) {
-	const descriptors = Object.getOwnPropertyDescriptors(cls.prototype);
-	return sortAnArray(Object.entries(descriptors).filter(([key, desc]) => isFunction(desc.get) && key !== "constructor").map(([key]) => key));
+function randomNumeric(length = 6) {
+	return randomBytes(length).map((byte) => byte & 10).join("");
 }
 /**
-* * Retrieves the names of all static getters defined directly on a class constructor.
+* * Generates a random alphanumeric string (letters and numbers) of the specified length.
 *
-* @param cls - The class constructor (not an instance).
-* @returns A sorted array of static getter names.
-*/
-function getStaticGetterNames(cls) {
-	return sortAnArray(Object.entries(Object.getOwnPropertyDescriptors(cls)).filter(([key, desc]) => typeof desc.get === "function" && key !== "prototype").map(([key]) => key));
-}
-/**
-* * Gathers detailed information about the instance and static methods of a class.
+* @param length - The desired length of the random string. Defaults to `8`.
+* @param uppercase - If `true`, the string will contain uppercase letters (A-Z). Defaults to `false` (lowercase).
 *
-* @param cls - The class constructor (not an instance).
-* @returns An object containing names and counts of instance and static methods.
-*/
-function getClassDetails(cls) {
-	const instanceNames = getInstanceMethodNames(cls);
-	const staticNames = getStaticMethodNames(cls);
-	const instanceGetters = getInstanceGetterNames(cls);
-	const staticGetters = getStaticGetterNames(cls);
-	return {
-		instanceMethods: instanceNames,
-		staticMethods: staticNames,
-		instanceGetters,
-		staticGetters,
-		instanceCount: instanceNames?.length,
-		staticCount: staticNames?.length,
-		totalGetters: instanceGetters?.length + staticGetters?.length,
-		totalMethods: instanceNames?.length + staticNames?.length
-	};
-}
-/**
-* * Create a deterministic JSON string representation of any value.
-*   - The output format matches standard JSON but with guaranteed sorted keys.
+* @returns A random string composed of alphanumeric characters.
 *
-* @remarks
-* - This function guarantees **stable, repeatable output** by:
-* 	 - Sorting all object keys alphabetically.
-* 	 - Recursively stabilizing nested objects and arrays.
-* 	 - Converting all `undefined` values into `null` so the output remains valid JSON.
-*   - Converting date-like objects (`Date`, `Chronos`, `Moment.js`, `Day.js`, `Luxon`, `JS-Joda`, `Temporal`) **in the same way that {@link JSON.stringify} would serialize them**, ensuring predictable and JSON-compliant output.
-*   - Falling back to native JSON serialization for primitives.
+* @example
+* ```typescript
+* // Generate a random 8-character alphanumeric string (default: lowercase)
+* const randomStr = randomAlphaNumeric(8);
+* // Example output: "a7b2f9d1"
 *
-* - **Useful for:**
-*   - Hash generation (e.g., signatures, cache keys)
-*   - Deep equality checks
-*   - Producing predictable output across environments
+* // Generate a 12-character uppercase alphanumeric string
+* const randomUpper = randomAlphaNumeric(12, true);
+* // Example output: "X5K9P2M7H4L3"
 *
-* @param obj - The value to stringify into a deterministic JSON string.
-* @returns A stable, deterministic string representation of the input.
-*/
-function stableStringify(obj) {
-	const _replacer = (_, v) => v === void 0 ? null : v;
-	if (isNotEmptyObject(obj)) return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k, _replacer) + ":" + (isDateLike(obj[k]) ? JSON.stringify(obj[k]) : stableStringify(obj[k]))).join(",") + "}";
-	if (isValidArray(obj)) return "[" + obj.map((v) => stableStringify(v)).join(",") + "]";
-	return JSON.stringify(obj, _replacer);
-}
-/**
-* * Remove trailing or leading garbage characters **after/before JSON object or array**.
-* @param str String to sanitize/strip.
-* @returns Sanitized/stripped JSON string.
+* // Generate a 6-character string
+* const shortStr = randomAlphaNumeric(6);
+* ```
+*
+* @remarks
+* - The function generates random bytes and converts them to base-36 (0-9, a-z) characters.
+* - If `length` is `0` or negative, an empty string is returned.
 */
-function stripJsonEdgeGarbage(str) {
-	if (!isNonEmptyString(str)) return "";
-	const lastIdx = Math.max(str.lastIndexOf("}"), str.lastIndexOf("]"));
-	const _idxOf = (sym) => str.indexOf(sym) !== -1 ? str.indexOf(sym) : Infinity;
-	const firstIdx = Math.min(_idxOf("{"), _idxOf("["));
-	if (lastIdx === -1 || firstIdx === Infinity) return str;
-	return str.slice(firstIdx, lastIdx + 1);
+function randomAlphaNumeric(length = 8, uppercase = false) {
+	const bytes = randomBytes(Math.ceil(length / 2));
+	let ran = "";
+	for (const byte of bytes) ran += byte.toString(36).padStart(2, "0");
+	const result = ran.slice(0, length);
+	return uppercase ? result.toUpperCase() : result;
 }
 /**
-* * Parses any valid JSON string, optionally converting stringified primitives inside (nested) arrays or objects.
+* * Converts a UTF-8 string to a byte array (`Uint8Array`).
 *
-* @typeParam T - Expected return type (default is unknown).
-* @param value - The JSON string to parse.
-* @param parsePrimitives - Whether to convert stringified primitives (default: `true`).
-* @returns The parsed JSON value typed as `T`, or the original parsed value with optional primitive conversion.
-* - Returns `{}` if parsing fails, such as when the input is malformed or invalid JSON or passing single quoted string.
+* This function encodes a JavaScript string into UTF-8 bytes, handling all Unicode code points including supplementary characters (surrogate pairs).
 *
-* - *Unlike {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/object/parse-json-to-object parseJsonToObject}, which ensures the root value is an object,
-* this function returns any valid JSON structure such as arrays, strings, numbers, or objects.*
+* @example
+* ```typescript
+* // Basic ASCII
+* const asciiBytes = utf8ToBytes('hello');
+* // Returns:
+* Uint8Array(5) [104, 101, 108, 108, 111]
 *
-* This is useful when you're not sure of the root structure of the JSON, or when you expect something other than an object.
+* // Unicode characters
+* const unicodeBytes = utf8ToBytes('Hello পৃথিবী!');
+* // Returns:
+* Uint8Array(25) [
+*  72, 101, 108, 108, 111,  32,
+* 224, 166, 170, 224, 167, 131,
+* 224, 166, 165, 224, 166, 191,
+* 224, 166, 172, 224, 167, 128,
+*  33
+* ]
+* ```
 *
-* @see {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/object/parse-json-to-object parseJsonToObject} for strict object-only parsing.
-*/
-const parseJSON = (value, parsePrimitives = true) => {
-	try {
-		const parsed = JSON.parse(value);
-		return parsePrimitives ? deepParsePrimitives(parsed) : parsed;
-	} catch {
-		return {};
-	}
-};
-/**
-* * Recursively parses primitive values inside objects and arrays.
+* @param str - The input string to encode as UTF-8 bytes.
+* @returns A `Uint8Array` containing the UTF-8 encoded bytes.
 *
-* @typeParam T - Expected return type after parsing (default is unknown).
-* @param input - Any input value to parse recursively.
-* @returns Input with primitives (strings like "true", "123") converted, typed as `T`.
+* @remarks
+* - The encoding follows the UTF-8 specification:
+*   - 1-byte sequence for code points U+0000 to U+007F (ASCII)
+*   - 2-byte sequence for code points U+0080 to U+07FF
+*   - 3-byte sequence for code points U+0800 to U+FFFF
+*   - 4-byte sequence for code points U+10000 to U+10FFFF (surrogate pairs)
+*
+* **Note:** Invalid surrogate pairs in the input string are silently ignored.
+*
+* @see {@link bytesToUtf8} for the inverse operation
 */
-function deepParsePrimitives(input) {
-	if (Array.isArray(input)) return input?.map(deepParsePrimitives);
-	if (isObject(input)) {
-		const result = {};
-		for (const [key, value] of Object.entries(input)) result[key] = deepParsePrimitives(value);
-		return result;
-	}
-	if (isString(input)) {
-		if (/^(true|false)$/i.test(input)) return input?.toLowerCase() === "true";
-		if (isNumericString(input)) return Number(input);
-		if (input === "null") return null;
-		if (input === "undefined") return;
-		return input;
+function utf8ToBytes(str) {
+	const out = [];
+	for (let i = 0; i < str.length; i++) {
+		const code = str.charCodeAt(i);
+		if (code < 128) out.push(code);
+		else if (code < 2048) out.push(192 | code >> 6, 128 | code & 63);
+		else if (code >= 55296 && code <= 57343) {
+			if (code < 56320 && i + 1 < str.length) {
+				const hi = code;
+				const lo = str.charCodeAt(++i);
+				const codePoint = 65536 + (hi - 55296 << 10) + (lo - 56320);
+				out.push(240 | codePoint >> 18, 128 | codePoint >> 12 & 63, 128 | codePoint >> 6 & 63, 128 | codePoint & 63);
+			}
+		} else out.push(224 | code >> 12, 128 | code >> 6 & 63, 128 | code & 63);
 	}
-	return input;
+	return new Uint8Array(out);
 }
 /**
-* * Defines a method on any prototype — including built-in prototypes — in a safe, idempotent manner.
-* 	 - The method is non-enumerable by default and will not overwrite an existing method unless explicitly allowed.
+* * Converts `UTF-8` encoded bytes back to a string.
 *
-* @param proto   The target prototype object (e.g., String.prototype).
-* @param name    The method name to define on the prototype.
-* @param impl    The function implementation for the method.
-* @param options Optional property-descriptor settings and overwrite rules.
+* This function decodes a `Uint8Array` containing `UTF-8` bytes into a JavaScript string.
 *
 * @example
-* // Safely augment prototype methods by extending the global interface:
-* declare global {
-* 	interface String {
-* 		toBang(): string;
-* 	}
-* }
+* ```typescript
+* // Decode UTF-8 bytes
+* const bytes = new Uint8Array([104, 101, 108, 108, 111]);
+* const str = bytesToUtf8(bytes);
+* // Returns: 'hello'
 *
-* // Define a custom method on String.prototype
-* definePrototypeMethod(String.prototype, 'toBang', function (this: String) {
-* 	return this.toString().concat('!');
-* 	// or
-* 	// return this.concat('!');
-* });
-*
-* "Hi".toBang(); // "Hi!"
-*
-* // Attempting to redefine without overwrite option is ignored
-* definePrototypeMethod(String.prototype, 'toBang', () => 'x'); // ignored
-*
-* // Overwrite intentionally using the overwrite option
-* definePrototypeMethod(
-*   String.prototype,
-*   'toBang',
-*   function (this: String) { return this.concat('!!!'); },
-*   { overwrite: true }
-* );
-*
-* "Hi".toBang(); // "Hi!!!"
-*/
-function definePrototypeMethod(proto, name, impl, options) {
-	if (Object.hasOwn(proto, name) && !options?.overwrite) return;
-	Object.defineProperty(proto, name, {
-		value: function(...args) {
-			return impl.apply(this, args);
-		},
-		enumerable: options?.enumerable ?? false,
-		configurable: options?.configurable ?? false,
-		writable: options?.writable ?? true
-	});
-}
-
-//#endregion
-//#region src/hash/utils.ts
-/**
-* * Generates a random hexadecimal string of the specified length.
-*
-* @param length - Number of hex characters to generate.
-* @param uppercase - Whether to return uppercase `A–F` characters. Defaults to `false` (lowercase).
-*
-* @returns A randomly generated hexadecimal string.
-*
-* @remarks
-* - This function generates a random hexadecimal string of the specified length.
-* - It uses {@link crypto.getRandomValues} when available for secure randomness, and falls back to {@link Math.random} if not.
-* - The output is a string of hex characters (`0–9`, `a–f` or `A–F`) with no prefixes or separators.
-* - If `length` is `0` or negative, an empty string is returned.
-*
-* @example
-* // 16-character lowercase hex
-* const id = randomHex(16);
-*
-* @example
-* // 8-character uppercase hex
-* const token = randomHex(8, true);
-*/
-function randomHex(length, uppercase = false) {
-	if (length <= 0) return "";
-	const expected = _bytesToRandomHex(new Uint8Array(Math.ceil(length / 2))).slice(0, length);
-	return uppercase ? expected.toUpperCase() : expected;
-}
-/**
-* * Converts a UTF-8 string to a byte array (`Uint8Array`).
-*
-* This function encodes a JavaScript string into UTF-8 bytes, handling all Unicode code points including supplementary characters (surrogate pairs).
-*
-* @example
-* ```typescript
-* // Basic ASCII
-* const asciiBytes = utf8ToBytes('hello');
-* // Returns:
-* Uint8Array(5) [104, 101, 108, 108, 111]
-*
-* // Unicode characters
-* const unicodeBytes = utf8ToBytes('Hello পৃথিবী!');
-* // Returns:
-* Uint8Array(25) [
-*  72, 101, 108, 108, 111,  32,
-* 224, 166, 170, 224, 167, 131,
-* 224, 166, 165, 224, 166, 191,
-* 224, 166, 172, 224, 167, 128,
-*  33
-* ]
-* ```
-*
-* @param str - The input string to encode as UTF-8 bytes.
-* @returns A `Uint8Array` containing the UTF-8 encoded bytes.
-*
-* @remarks
-* - The encoding follows the UTF-8 specification:
-*   - 1-byte sequence for code points U+0000 to U+007F (ASCII)
-*   - 2-byte sequence for code points U+0080 to U+07FF
-*   - 3-byte sequence for code points U+0800 to U+FFFF
-*   - 4-byte sequence for code points U+10000 to U+10FFFF (surrogate pairs)
-*
-* **Note:** Invalid surrogate pairs in the input string are silently ignored.
-*
-* @see {@link bytesToUtf8} for the inverse operation
-*/
-function utf8ToBytes(str) {
-	const out = [];
-	for (let i = 0; i < str.length; i++) {
-		const code = str.charCodeAt(i);
-		if (code < 128) out.push(code);
-		else if (code < 2048) out.push(192 | code >> 6, 128 | code & 63);
-		else if (code >= 55296 && code <= 57343) {
-			if (code < 56320 && i + 1 < str.length) {
-				const hi = code;
-				const lo = str.charCodeAt(++i);
-				const codePoint = 65536 + (hi - 55296 << 10) + (lo - 56320);
-				out.push(240 | codePoint >> 18, 128 | codePoint >> 12 & 63, 128 | codePoint >> 6 & 63, 128 | codePoint & 63);
-			}
-		} else out.push(224 | code >> 12, 128 | code >> 6 & 63, 128 | code & 63);
-	}
-	return new Uint8Array(out);
-}
-/**
-* * Converts `UTF-8` encoded bytes back to a string.
-*
-* This function decodes a `Uint8Array` containing `UTF-8` bytes into a JavaScript string.
-*
-* @example
-* ```typescript
-* // Decode UTF-8 bytes
-* const bytes = new Uint8Array([104, 101, 108, 108, 111]);
-* const str = bytesToUtf8(bytes);
-* // Returns: 'hello'
-*
-* // Round-trip conversion
-* const original = 'Hello 🌍';
-* const bytes = utf8ToBytes(original);
-* const decoded = bytesToUtf8(bytes);
-* console.log(original === decoded); // true
-* ```
+* // Round-trip conversion
+* const original = 'Hello 🌍';
+* const bytes = utf8ToBytes(original);
+* const decoded = bytesToUtf8(bytes);
+* console.log(original === decoded); // true
+* ```
 *
 * @param bytes - A `Uint8Array` containing `UTF-8` encoded bytes.
 * @returns The decoded string.
@@ -1654,100 +1411,426 @@ function isUUIDv8(value) {
 }
 
 //#endregion
-//#region src/string/basics.ts
+//#region src/array/helpers.ts
 /**
-* * Utility to truncate a string to a specified length.
+* Safely resolves value of nested key (dot-notation key like `"user.city"`).
 *
-* @param str The string to truncate.
-* @param maxLength The maximum length of the truncated string.
-* @returns Truncated string with ellipsis (`...`) (only if it has more length than `maxLength`).
+* @param obj - The source object
+* @param path - The nested path string (e.g. `"user.city"`)
+* @returns The resolved value or `undefined`
 */
-function truncateString(str, maxLength) {
-	if (!isNonEmptyString(str)) return "";
-	const trimmedString = str.trim();
-	if (!trimmedString) return "";
-	if (trimmedString.length <= maxLength) return trimmedString;
-	return trimmedString.slice(0, maxLength).concat("...");
+function _resolveNestedKey(obj, path) {
+	if (isNotEmptyObject(obj)) return path?.split(".").reduce((acc, key) => {
+		if (isNotEmptyObject(acc)) return acc[key];
+	}, obj);
 }
 /**
-* * Generates a random alphanumeric (16 characters long, this length is customizable in the options) ID string composed of an optional `prefix`, `suffix`, a `timestamp`, `caseOption` and a customizable `separator`.
-*
-* @param options Configuration options for random ID generation.
-* @returns The generated ID string composed of the random alphanumeric string of specified length with optional `timeStamp`, `prefix`, and `suffix`, `caseOption` and `separator`.
-*
-* @see {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/hash/uuid uuid} for `uuid` generation
-* @see {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/hash/random-hex randomHex} for random hexadecimal string generation
-*
-* @example
-* // Generate an ID with all default options
-* const id = generateRandomID();
-* // Example output: "swo8ckxwsc13w7xw"
-*
-* @example
-* // Generate an ID with a custom prefix and separator
-* const id = generateRandomID({ prefix: 'ID', separator: '-' });
-* // Example output: "ID-eh1ymwfxzwas9jte"
-*
-* @example
-* // Generate an ID with a timestamp
-* const id = generateRandomID({ timeStamp: false });
-* // Example output: "1764610287501pd3r4w85qwkuulgf"
-*
-* @example
-* // Generate an ID with a custom length for the random string
-* const id = generateRandomID({ length: 8 });
-* // Example output: "i623uiev"
-*
-* @example
-* // Generate an ID with a custom suffix
-* const id = generateRandomID({ suffix: 'END' });
-* // Example output: "3csf27a4800rbli9END"
-*
-* @example
-* // Generate an ID with a uppercase random string
-* const id = generateRandomID({ caseOption: "upper" });
-* // Example output: "H0VNU6O8XV1Y30HG"
+* Retrieves a numeric value from a nested property (dot-notation key like 'user.income.tax').
+* Falls back to 0 if value is not a number or numeric string.
 *
-* @example
-* // Generate an ID with all options customized
-* const id = generateRandomID({
-*   prefix: 'ID',
-*   suffix: 'END',
-*   timeStamp: true,
-*   length: 10,
-*   separator: '-',
-*   caseOption: "upper"
-* });
-* // Example output: "ID-1764610471474-4KSL51IB91-END"
+* @param obj - The source object to read from.
+* @param path - The dot-notation path string like 'user.income.tax'.
+* @returns The numeric value at that path, or 0 if	 not valid.
 */
-function generateRandomID(options) {
-	const { prefix = "", suffix = "", timeStamp = false, length = 16, separator = "", caseOption = null } = options || {};
-	const date = timeStamp ? Date.now() : "";
-	const randomString = Array.from({ length }, () => Math.random().toString(36).slice(2, 3)).join("");
-	const ID = [
-		prefix?.trim(),
-		date,
-		randomString,
-		suffix?.trim()
-	].filter(Boolean).join(separator);
-	switch (caseOption) {
-		case "upper": return ID.toUpperCase();
-		case "lower": return ID.toLowerCase();
-		default: return ID;
-	}
+function _getNumericProp(obj, path) {
+	return normalizeNumber(_resolveNestedKey(obj, path)) ?? 0;
 }
+
+//#endregion
+//#region src/array/sort.ts
 /**
-* * Trims all whitespaces in a string or an array of strings.
+* Compare two strings using natural sorting (e.g., `"file2"` < `"file10"`).
+* - Optionally supports case-insensitive and locale-aware string chunk comparisons.
 *
-* @param input String or array of strings.
-* @returns Trimmed string or array of strings.
+* @param a - The first string to compare.
+* @param b - The second string to compare.
+* @param options - Optional settings to configure comparison behavior.
+* @returns A negative number if `a` comes before `b`, a positive number if `a` comes after `b`, or 0 if equal.
 */
-function trimString(input) {
-	if (!input) return "";
-	if (isNonEmptyString(input)) return input.trim().replace(/\s+/g, " ");
-	if (Array.isArray(input)) return input.map((str) => isNonEmptyString(str) ? str.trim().replace(/\s+/g, " ") : str);
-	throw new TypeError("Expected string or array of strings!", { cause: "Invalid Input Type" });
+function naturalSort(a, b, options) {
+	const { caseInsensitive = true, localeAware = false } = options || {};
+	/**
+	* * Splits a string into an array of number and non-number chunks.
+	* @param str - The string to split.
+	* @returns An array of string and number parts.
+	*/
+	const _createChunks = (str) => {
+		const chunks = [];
+		let current = "";
+		let isNumeric = false;
+		for (const char of str) {
+			const charIsNum = !Number.isNaN(Number(char));
+			if (current?.length === 0) {
+				current = char;
+				isNumeric = charIsNum;
+				continue;
+			}
+			if (charIsNum === isNumeric) current += char;
+			else {
+				chunks?.push(isNumeric ? Number(current) : current);
+				current = char;
+				isNumeric = charIsNum;
+			}
+		}
+		if (current?.length > 0) chunks?.push(isNumeric ? Number(current) : current);
+		return chunks;
+	};
+	const aChunks = _createChunks(a);
+	const bChunks = _createChunks(b);
+	for (let i = 0; i < Math.min(aChunks?.length, bChunks?.length); i++) {
+		let aChunk = aChunks[i];
+		let bChunk = bChunks[i];
+		if (caseInsensitive && isString(aChunk) && isString(bChunk)) {
+			aChunk = aChunk?.toLowerCase();
+			bChunk = bChunk?.toLowerCase();
+		}
+		if (typeof aChunk !== typeof bChunk) return isString(aChunk) ? 1 : -1;
+		if (aChunk !== bChunk) {
+			if (isNumber(aChunk) && isNumber(bChunk)) return aChunk - bChunk;
+			if (isString(aChunk) && isString(bChunk)) {
+				if (localeAware) {
+					const cmp = aChunk.localeCompare(bChunk, void 0, { sensitivity: caseInsensitive ? "accent" : "variant" });
+					if (cmp !== 0) return cmp;
+				}
+				return aChunk < bChunk ? -1 : 1;
+			}
+		}
+	}
+	return aChunks?.length - bChunks?.length;
+}
+/**
+* * Sorts an array of strings, numbers, booleans, or objects based on the provided options.
+*
+* @param array - The array to sort.
+* @param options - Sorting options.
+* @returns The sorted array.
+*/
+function sortAnArray(array, options) {
+	if (!isValidArray(array)) return array;
+	if (isArrayOfType(array, isString)) return [...array].sort((a, b) => options?.sortOrder === "desc" ? naturalSort(b, a) : naturalSort(a, b));
+	if (isArrayOfType(array, isNumber)) return [...array].sort((a, b) => options?.sortOrder === "desc" ? b - a : a - b);
+	if (isArrayOfType(array, isBoolean)) return [...array].sort((a, b) => options?.sortOrder === "desc" ? Number(b) - Number(a) : Number(a) - Number(b));
+	if (isArrayOfType(array, isObject) && options && "sortByField" in options) return [...array].sort((a, b) => {
+		const _getKeyValue = (obj, path) => {
+			return path.split(".").reduce((acc, key) => acc?.[key], obj);
+		};
+		const keyA = _getKeyValue(a, options?.sortByField);
+		const keyB = _getKeyValue(b, options?.sortByField);
+		if (keyA == null || keyB == null) return keyA == null ? 1 : -1;
+		if (isString(keyA) && isString(keyB)) return options?.sortOrder === "desc" ? naturalSort(keyB, keyA) : naturalSort(keyA, keyB);
+		if (isNumber(keyA) && isNumber(keyB)) return options?.sortOrder === "desc" ? keyB - keyA : keyA - keyB;
+		if (isBoolean(keyA) && isBoolean(keyB)) return options?.sortOrder === "desc" ? Number(keyB) - Number(keyA) : Number(keyA) - Number(keyB);
+		return 0;
+	});
+	return [...array];
+}
+
+//#endregion
+//#region src/utils/index.ts
+/**
+* * Deeply compare two values (arrays, objects, or primitive values).
+*
+* @param a First value to compare.
+* @param b Second value to compare.
+* @returns Whether the values are deeply equal.
+*/
+const isDeepEqual = (a, b) => {
+	if (a === b) return true;
+	if (typeof a !== typeof b) return false;
+	if (a === null || b === null) return a === b;
+	if (isArray(a) && isArray(b)) {
+		if (a?.length !== b?.length) return false;
+		return a?.every((element, index) => isDeepEqual(element, b?.[index]));
+	}
+	if (isObject(a) && isObject(b)) {
+		const aKeys = Object.keys(a);
+		const bKeys = Object.keys(b);
+		if (aKeys?.length !== bKeys?.length) return false;
+		return aKeys?.every((key) => isDeepEqual(a?.[key], b?.[key]));
+	}
+	return false;
+};
+/**
+* * Converts an array of primitive values or objects to a string using a separator or target key.
+*
+* @param array Array to convert.
+* @param options Options for separator or key extraction from objects.
+* @returns String representation of array values.
+*/
+function convertArrayToString(array, options) {
+	if (!isValidArray(array)) return "";
+	const { separator = ", " } = options ?? {};
+	if (isArrayOfType(array, isPrimitive)) return array?.join(separator);
+	else if (isArrayOfType(array, isNotEmptyObject)) if (options && "target" in options) return array?.map((el) => _resolveNestedKey(el, options?.target))?.join(separator);
+	else return "";
+	return "";
+}
+/**
+* * A generic debounce function that delays the execution of a callback.
+*
+* @param callback - The function to debounce.
+* @param delay - The delay in milliseconds. Default is `300ms`.
+* @returns A debounced version of the callback function.
+*
+* @example
+* const debouncedSearch = debounceAction((query: string) => {
+*   console.log(`Searching for: ${query}`);
+* }, 300);
+*
+* debouncedSearch('laptop'); // Executes after 300ms of inactivity.
+*/
+function debounceAction(callback, delay = 300) {
+	let timeoutId;
+	return (...args) => {
+		clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => {
+			callback(...args);
+		}, delay);
+	};
+}
+/**
+* * A generic throttle function that ensures a callback is executed at most once per specified interval.
+*
+* @param callback - The function to throttle.
+* @param delay - The delay in milliseconds. Default is `150ms`.
+* @returns A throttled version of the callback function.
+*
+* @example
+* const throttledResize = throttleAction(() => {
+*   console.log('Resized');
+* }, 300);
+*
+* window.addEventListener('resize', throttledResize);
+*/
+function throttleAction(callback, delay = 150) {
+	let lastCall = 0;
+	return (...args) => {
+		const now = Date.now();
+		if (now - lastCall >= delay) {
+			lastCall = now;
+			callback(...args);
+		}
+	};
+}
+/**
+* * Retrieves the names of all instance methods defined directly on a class prototype.
+*
+* @param cls - The class constructor (not an instance).
+* @returns A sorted array of instance method names.
+*/
+function getInstanceMethodNames(cls) {
+	const prototype = cls.prototype;
+	return sortAnArray(Object.getOwnPropertyNames(prototype).filter((method) => {
+		if (method === "constructor") return false;
+		return isMethodDescriptor(Object.getOwnPropertyDescriptor(prototype, method));
+	}));
+}
+/**
+* * Retrieves the names of all static methods defined directly on a class constructor.
+*
+* @param cls - The class constructor (not an instance).
+* @returns A sorted array of static method names.
+*/
+function getStaticMethodNames(cls) {
+	return sortAnArray(Object.getOwnPropertyNames(cls).filter((method) => {
+		return method !== "prototype" && method !== "name" && method !== "length";
+	}));
+}
+/**
+* * Counts the number of instance methods defined directly on a class prototype.
+*
+* @param cls - The class constructor (not an instance).
+* @returns The number of instance methods defined on the class prototype.
+*/
+function countInstanceMethods(cls) {
+	return getInstanceMethodNames(cls)?.length;
+}
+/**
+* * Counts the number of static methods defined directly on a class constructor.
+*
+* @param cls - The class constructor (not an instance).
+* @returns The number of static methods defined on the class constructor.
+*/
+function countStaticMethods(cls) {
+	return getStaticMethodNames(cls)?.length;
+}
+/**
+* * Retrieves the names of all instance getters defined directly on a class prototype.
+*
+* @param cls - The class constructor (not an instance).
+* @returns A sorted array of instance getter names.
+*/
+function getInstanceGetterNames(cls) {
+	const descriptors = Object.getOwnPropertyDescriptors(cls.prototype);
+	return sortAnArray(Object.entries(descriptors).filter(([key, desc]) => isFunction(desc.get) && key !== "constructor").map(([key]) => key));
+}
+/**
+* * Retrieves the names of all static getters defined directly on a class constructor.
+*
+* @param cls - The class constructor (not an instance).
+* @returns A sorted array of static getter names.
+*/
+function getStaticGetterNames(cls) {
+	return sortAnArray(Object.entries(Object.getOwnPropertyDescriptors(cls)).filter(([key, desc]) => typeof desc.get === "function" && key !== "prototype").map(([key]) => key));
+}
+/**
+* * Gathers detailed information about the instance and static methods of a class.
+*
+* @param cls - The class constructor (not an instance).
+* @returns An object containing names and counts of instance and static methods.
+*/
+function getClassDetails(cls) {
+	const instanceNames = getInstanceMethodNames(cls);
+	const staticNames = getStaticMethodNames(cls);
+	const instanceGetters = getInstanceGetterNames(cls);
+	const staticGetters = getStaticGetterNames(cls);
+	return {
+		instanceMethods: instanceNames,
+		staticMethods: staticNames,
+		instanceGetters,
+		staticGetters,
+		instanceCount: instanceNames?.length,
+		staticCount: staticNames?.length,
+		totalGetters: instanceGetters?.length + staticGetters?.length,
+		totalMethods: instanceNames?.length + staticNames?.length
+	};
+}
+/**
+* * Create a deterministic JSON string representation of any value.
+*   - The output format matches standard JSON but with guaranteed sorted keys.
+*
+* @remarks
+* - This function guarantees **stable, repeatable output** by:
+* 	 - Sorting all object keys alphabetically.
+* 	 - Recursively stabilizing nested objects and arrays.
+* 	 - Converting all `undefined` values into `null` so the output remains valid JSON.
+*   - Converting date-like objects (`Date`, `Chronos`, `Moment.js`, `Day.js`, `Luxon`, `JS-Joda`, `Temporal`) **in the same way that {@link JSON.stringify} would serialize them**, ensuring predictable and JSON-compliant output.
+*   - Falling back to native JSON serialization for primitives.
+*
+* - **Useful for:**
+*   - Hash generation (e.g., signatures, cache keys)
+*   - Deep equality checks
+*   - Producing predictable output across environments
+*
+* @param obj - The value to stringify into a deterministic JSON string.
+* @returns A stable, deterministic string representation of the input.
+*/
+function stableStringify(obj) {
+	const _replacer = (_, v) => v === void 0 ? null : v;
+	if (isNotEmptyObject(obj)) return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k, _replacer) + ":" + (isDateLike(obj[k]) ? JSON.stringify(obj[k]) : stableStringify(obj[k]))).join(",") + "}";
+	if (isValidArray(obj)) return "[" + obj.map((v) => stableStringify(v)).join(",") + "]";
+	return JSON.stringify(obj, _replacer);
+}
+/**
+* * Remove trailing or leading garbage characters **after/before JSON object or array**.
+* @param str String to sanitize/strip.
+* @returns Sanitized/stripped JSON string.
+*/
+function stripJsonEdgeGarbage(str) {
+	if (!isNonEmptyString(str)) return "";
+	const lastIdx = Math.max(str.lastIndexOf("}"), str.lastIndexOf("]"));
+	const _idxOf = (sym) => str.indexOf(sym) !== -1 ? str.indexOf(sym) : Infinity;
+	const firstIdx = Math.min(_idxOf("{"), _idxOf("["));
+	if (lastIdx === -1 || firstIdx === Infinity) return str;
+	return str.slice(firstIdx, lastIdx + 1);
+}
+/**
+* * Parses any valid JSON string, optionally converting stringified primitives inside (nested) arrays or objects.
+*
+* @typeParam T - Expected return type (default is unknown).
+* @param value - The JSON string to parse.
+* @param parsePrimitives - Whether to convert stringified primitives (default: `true`).
+* @returns The parsed JSON value typed as `T`, or the original parsed value with optional primitive conversion.
+* - Returns `{}` if parsing fails, such as when the input is malformed or invalid JSON or passing single quoted string.
+*
+* - *Unlike {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/object/parse-json-to-object parseJsonToObject}, which ensures the root value is an object,
+* this function returns any valid JSON structure such as arrays, strings, numbers, or objects.*
+*
+* This is useful when you're not sure of the root structure of the JSON, or when you expect something other than an object.
+*
+* @see {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/object/parse-json-to-object parseJsonToObject} for strict object-only parsing.
+*/
+const parseJSON = (value, parsePrimitives = true) => {
+	try {
+		const parsed = JSON.parse(value);
+		return parsePrimitives ? deepParsePrimitives(parsed) : parsed;
+	} catch {
+		return {};
+	}
+};
+/**
+* * Recursively parses primitive values inside objects and arrays.
+*
+* @typeParam T - Expected return type after parsing (default is unknown).
+* @param input - Any input value to parse recursively.
+* @returns Input with primitives (strings like "true", "123") converted, typed as `T`.
+*/
+function deepParsePrimitives(input) {
+	if (Array.isArray(input)) return input?.map(deepParsePrimitives);
+	if (isObject(input)) {
+		const result = {};
+		for (const [key, value] of Object.entries(input)) result[key] = deepParsePrimitives(value);
+		return result;
+	}
+	if (isString(input)) {
+		if (/^(true|false)$/i.test(input)) return input?.toLowerCase() === "true";
+		if (isNumericString(input)) return Number(input);
+		if (input === "null") return null;
+		if (input === "undefined") return;
+		return input;
+	}
+	return input;
+}
+/**
+* * Defines a method on any prototype — including built-in prototypes — in a safe, idempotent manner.
+* 	 - The method is non-enumerable by default and will not overwrite an existing method unless explicitly allowed.
+*
+* @param proto   The target prototype object (e.g., String.prototype).
+* @param name    The method name to define on the prototype.
+* @param impl    The function implementation for the method.
+* @param options Optional property-descriptor settings and overwrite rules.
+*
+* @example
+* // Safely augment prototype methods by extending the global interface:
+* declare global {
+* 	interface String {
+* 		toBang(): string;
+* 	}
+* }
+*
+* // Define a custom method on String.prototype
+* definePrototypeMethod(String.prototype, 'toBang', function (this: String) {
+* 	return this.toString().concat('!');
+* 	// or
+* 	// return this.concat('!');
+* });
+*
+* "Hi".toBang(); // "Hi!"
+*
+* // Attempting to redefine without overwrite option is ignored
+* definePrototypeMethod(String.prototype, 'toBang', () => 'x'); // ignored
+*
+* // Overwrite intentionally using the overwrite option
+* definePrototypeMethod(
+*   String.prototype,
+*   'toBang',
+*   function (this: String) { return this.concat('!!!'); },
+*   { overwrite: true }
+* );
+*
+* "Hi".toBang(); // "Hi!!!"
+*/
+function definePrototypeMethod(proto, name, impl, options) {
+	if (Object.hasOwn(proto, name) && !options?.overwrite) return;
+	Object.defineProperty(proto, name, {
+		value: function(...args) {
+			return impl.apply(this, args);
+		},
+		enumerable: options?.enumerable ?? false,
+		configurable: options?.configurable ?? false,
+		writable: options?.writable ?? true
+	});
 }
 
 //#endregion
-export { uint8To32ArrayBE as A, getInstanceMethodNames as B, bytesToUtf8 as C, intTo4BytesBE as D, hmacSha256 as E, debounceAction as F, stableStringify as G, getStaticMethodNames as H, deepParsePrimitives as I, naturalSort as J, stripJsonEdgeGarbage as K, definePrototypeMethod as L, convertArrayToString as M, countInstanceMethods as N, randomHex as O, countStaticMethods as P, getClassDetails as R, bytesToHex as S, hexToBytes as T, isDeepEqual as U, getStaticGetterNames as V, parseJSON as W, _getNumericProp as X, sortAnArray as Y, _resolveNestedKey as Z, _constantTimeEquals as _, isUUIDv1 as a, base64ToBytes as b, isUUIDv4 as c, isUUIDv7 as d, isUUIDv8 as f, sha256 as g, sha1 as h, decodeUUID as i, utf8ToBytes as j, sha256Bytes as k, isUUIDv5 as l, md5 as m, trimString as n, isUUIDv2 as o, uuid as p, throttleAction as q, truncateString as r, isUUIDv3 as s, generateRandomID as t, isUUIDv6 as u, _padStartWith0 as v, concatBytes as w, bytesToBase64 as x, _splitByCharLength as y, getInstanceGetterNames as z };
+export { trimString as $, uuid as A, bytesToUtf8 as B, isUUIDv2 as C, isUUIDv6 as D, isUUIDv5 as E, _padStartWith0 as F, randomAlphaNumeric as G, hexToBytes as H, _splitByCharLength as I, randomNumeric as J, randomBytes as K, base64ToBytes as L, sha1 as M, sha256 as N, isUUIDv7 as O, _constantTimeEquals as P, generateRandomID as Q, bytesToBase64 as R, isUUIDv1 as S, isUUIDv4 as T, hmacSha256 as U, concatBytes as V, intTo4BytesBE as W, uint8To32ArrayBE as X, sha256Bytes as Y, utf8ToBytes as Z, naturalSort as _, deepParsePrimitives as a, _resolveNestedKey as b, getInstanceGetterNames as c, getStaticMethodNames as d, truncateString as et, isDeepEqual as f, throttleAction as g, stripJsonEdgeGarbage as h, debounceAction as i, md5 as j, isUUIDv8 as k, getInstanceMethodNames as l, stableStringify as m, countInstanceMethods as n, definePrototypeMethod as o, parseJSON as p, randomHex as q, countStaticMethods as r, getClassDetails as s, convertArrayToString as t, getStaticGetterNames as u, sortAnArray as v, isUUIDv3 as w, decodeUUID as x, _getNumericProp as y, bytesToHex as z };