toolbox-x 1.2.0 → 2.0.0

package/dist/utils-CN3ocK98.mjs

@@ -1,449 +0,0 @@
-/**
- * Copyright 2026 - present Nazmul Hassan
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { a as isNonEmptyString, c as isNumber, d as isString, n as isBoolean, u as isPrimitive } from "./primitives-Djsevc69.mjs";
-import { C as isMethodDescriptor, T as isObject, d as isNumericString, g as isArrayOfType, h as isArray, j as isValidArray, w as isNotEmptyObject } from "./specials-Cye93-uo.mjs";
-import { a as normalizeNumber } from "./utilities-B9axOvOX.mjs";
-import { t as isDateLike } from "./guards-Cp6KAkVI.mjs";
-
-//#region src/array/helpers.ts
-/**
-* Safely resolves nested keys from a dot-separated string like "user.city".
-*
-* @param obj - The source object
-* @param path - The nested path string (e.g. "user.city")
-* @returns The resolved value or `undefined`
-*/
-function _resolveNestedKey(obj, path) {
-	if (isNotEmptyObject(obj)) return path?.split(".").reduce((acc, key) => {
-		if (isNotEmptyObject(acc)) return acc[key];
-	}, obj);
-}
-/**
-* Retrieves a numeric value from a nested property in dot notation.
-* Falls back to 0 if value is not a number or numeric string.
-*
-* @param obj - The source object to read from.
-* @param path - The path string like 'user.income.tax'.
-* @returns The numeric value at that path, or 0 if not valid.
-*/
-function _getNumericProp(obj, path) {
-	if (isNotEmptyObject(obj)) {
-		const value = path?.split(".").reduce((acc, key) => {
-			if (isNotEmptyObject(acc)) return acc[key];
-		}, obj);
-		return normalizeNumber(value) ?? 0;
-	} else return 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 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 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]) => typeof desc.get === "function" && 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/utilities/object/parseJsonToObject 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/utilities/object/parseJsonToObject 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 { naturalSort as _, deepParsePrimitives as a, _resolveNestedKey as b, getInstanceGetterNames as c, getStaticMethodNames as d, isDeepEqual as f, throttleAction as g, stripJsonEdgeGarbage as h, debounceAction as i, getInstanceMethodNames as l, stableStringify as m, countInstanceMethods as n, definePrototypeMethod as o, parseJSON as p, countStaticMethods as r, getClassDetails as s, convertArrayToString as t, getStaticGetterNames as u, sortAnArray as v, _getNumericProp as y };