toolbox-x 1.2.0 → 2.0.0

package/dist/dom.d.mts

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 
-import { A as ParsedQuery, G as Deserializer, M as QueryObject, ct as Serializer, j as ParsedQueryGeneric, y as GenericObject } from "./object-ChFVh95z.mjs";
-import { P as QueryString } from "./string-CkwTVFeL.mjs";
-import { a as OriginFileObj, i as FormDataConfigs, o as ParsedFormData, r as FileUpload, s as SerializedForm, t as CustomFile } from "./form-DoQGMTOc.mjs";
+import { J as Deserializer, M as ParsedQueryGeneric, N as QueryObject, ft as Serializer, j as ParsedQuery, y as GenericObject } from "./object-X5fSMx-I.mjs";
+import { F as QueryString } from "./string-C51m7T6d.mjs";
+import { a as OriginFileObj, i as FormDataConfigs, o as ParsedFormData, r as FileUpload, s as SerializedForm, t as CustomFile } from "./form-DPdS2AhM.mjs";
 
 //#region src/dom/query.d.ts
 /**

package/dist/dom.mjs

@@ -15,11 +15,10 @@
  */
 
 import { a as isNonEmptyString, d as isString } from "./primitives-Djsevc69.mjs";
-import { j as isValidArray, v as isEmptyObject, w as isNotEmptyObject } from "./specials-Cye93-uo.mjs";
-import { t as isDateLike } from "./guards-Cp6KAkVI.mjs";
-import { n as trimString } from "./basics-1_M7UvCn.mjs";
-import { _ as isOriginFileObj, a as flattenObjectKeyValue, d as isCustomFile, f as isCustomFileArray, g as isFileUpload, h as isFileOrBlob, l as parseObjectValues, m as isFileList, p as isFileArray, v as isValidFormData } from "./objectify-CfXtS_E0.mjs";
-import { a as deepParsePrimitives } from "./utils-CN3ocK98.mjs";
+import { j as isValidArray, v as isEmptyObject, w as isNotEmptyObject } from "./specials-Hq5Ncd6y.mjs";
+import { t as isDateLike } from "./guards-BK1QuvFZ.mjs";
+import { I as deepParsePrimitives, n as trimString } from "./basics-CebgkY-n.mjs";
+import { _ as isOriginFileObj, a as flattenObjectKeyValue, d as isCustomFile, f as isCustomFileArray, g as isFileUpload, h as isFileOrBlob, l as parseObjectValues, m as isFileList, p as isFileArray, v as isValidFormData } from "./objectify-CQa8gQib.mjs";
 
 //#region src/dom/query.ts
 /**

package/dist/{form-DoQGMTOc.d.mts → form-Cp1OyCRI.d.cts}

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-import { $r as RequireExactly, S as KeyForObject, T as NestedKeyString, u as DotNotationKey, x as KeyForArray } from "./object-ChFVh95z.mjs";
-import { P as QueryString } from "./string-CkwTVFeL.mjs";
+import { S as KeyForObject, T as NestedKeyString, ri as RequireExactly, u as DotNotationKey, x as KeyForArray } from "./object-X5fSMx-I.cjs";
+import { F as QueryString } from "./string-CO7HP50i.cjs";
 
 //#region src/types/form.d.ts
 /** - Configuration options to control FormData generation behavior. */

package/dist/{form-mP-nl8EC.d.cts → form-DPdS2AhM.d.mts}

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-import { $r as RequireExactly, S as KeyForObject, T as NestedKeyString, u as DotNotationKey, x as KeyForArray } from "./object-ChFVh95z.cjs";
-import { P as QueryString } from "./string-Dq2b8rcN.cjs";
+import { S as KeyForObject, T as NestedKeyString, ri as RequireExactly, u as DotNotationKey, x as KeyForArray } from "./object-X5fSMx-I.mjs";
+import { F as QueryString } from "./string-C51m7T6d.mjs";
 
 //#region src/types/form.d.ts
 /** - Configuration options to control FormData generation behavior. */

package/dist/guards-B2s2wlVN.mjs

@@ -0,0 +1,425 @@
+/**
+ * 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 { d as isString, m as isUndefined } from "./primitives-Djsevc69.mjs";
+import { b as isFunction, w as isNotEmptyObject } from "./specials-Hq5Ncd6y.mjs";
+import { a as normalizeNumber } from "./utilities-DPscNbS1.mjs";
+import { G as stableStringify, n as trimString } from "./basics-CebgkY-n.mjs";
+
+//#region src/object/basics.ts
+/**
+* * Deep clone an object using `structuredClone` or deterministic *JSON serialization*.
+*
+* @param obj Object to clone.
+* @param serialize Whether to force deterministic JSON serialization instead of using `structuredClone`. Defaults to `false`.
+* @returns Deep cloned object.
+*
+* @remarks
+* **Primary behavior**
+* - By default (`serialize = false`), the function uses {@link https://developer.mozilla.org/docs/Web/API/Window/structuredClone structuredClone} when available. This supports:
+*   - Circular references
+*   - `Date` objects
+*   - `Map` / `Set`
+*   - `RegExp`
+*   - Typed arrays
+*   - Most built-in JavaScript types
+*   - Preserves `undefined` values
+*
+* - **Note:** `structuredClone` **does not preserve class prototypes**, even though it preserves data types like `Date`, `Map`, and `Set`.
+*
+* **Deterministic serialization mode**
+* - When `serialize = true`, or when `structuredClone` is unavailable, the function falls back to **stable JSON serialization** via `stableStringify`. This guarantees:
+*   - All object keys are sorted alphabetically.
+*   - Consistent output across environments (deterministic).
+*   - All `undefined` values are converted to `null`.
+*   - 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.
+*
+* - This mode is ideal for:
+*   - Hashing
+*   - Signature generation
+*   - Deep equality checks
+*   - Anything requiring deterministic, environment-neutral output
+*
+* **Deterministic mode limitations**
+* - JSON serialization will:
+*   - Drop functions and `Symbol` values.
+*   - Lose prototype and class instance information.
+*   - Convert all date-like objects into strings.
+*   - Fail on circular references.
+*
+* **Final safety fallback**
+* - If JSON serialization fails (e.g., due to circular references), the function returns a **shallow clone** (`{ ...obj }`) to ensure the cloning never throws.
+*/
+function cloneObject(obj, serialize = false) {
+	try {
+		if (!serialize && typeof structuredClone === "function") return structuredClone(obj);
+		return JSON.parse(stableStringify(obj));
+	} catch {
+		return { ...obj };
+	}
+}
+/**
+* * Count the number of fields in an object.
+*
+* @param obj Object to check.
+* @returns Number of fields in the object.
+*/
+function countObjectFields(obj) {
+	if (obj != null) return Object.keys(obj)?.length;
+	return 0;
+}
+function extractObjectKeys(obj, tuple) {
+	const keys = isNotEmptyObject(obj) ? Object.keys(obj) : [];
+	return tuple ? keys : keys;
+}
+/**
+* * Recursively extracts all nested keys from an object as an array.
+*
+* @remarks
+* - Returns an empty array (`[]`) for an empty object or a non-object value.
+* - For only top-level keys, use {@link extractObjectKeys}.
+*
+* @param obj The object from which to extract the keys.
+* @returns An array of all the nested keys (string literals) from the specified object.
+*/
+function extractObjectKeysDeep(obj) {
+	function _getDeepKeys(candidate) {
+		let result = [];
+		for (const key in candidate) {
+			result.push(key);
+			if (isNotEmptyObject(candidate[key])) result = [...result, ..._getDeepKeys(candidate[key])];
+		}
+		return result;
+	}
+	return isNotEmptyObject(obj) ? _getDeepKeys(obj) : [];
+}
+/**
+* * Extracts all the top-level entries of an object as an array of key-value pairs.
+*
+* @remarks
+* - Returns an empty array (`[]`) for an empty object or a non-object value.
+* - Internally uses {@link Object.entries}.
+*
+* @param obj The object from which to extract the entries.
+* @returns An array of key-value pairs.
+*/
+function extractObjectEntries(obj) {
+	return isNotEmptyObject(obj) ? Object.entries(obj) : [];
+}
+
+//#endregion
+//#region src/array/basics.ts
+/**
+* * Flattens a nested array recursively or wraps any non-array data type in an array.
+*
+* @param input - The input value, which can be a nested array or a non-array value.
+* @returns A fully flattened array of type `Flatten<T>`. If the input is not an array, it wraps it in a single-element array.
+*/
+const flattenArray = (input) => {
+	if (!Array.isArray(input)) return [input];
+	return input.reduce((acc, item) => {
+		return acc.concat(Array.isArray(item) ? flattenArray(item) : [item]);
+	}, []);
+};
+/**
+* * Filters an array of objects based on multiple conditions for specified keys.
+*
+* @param array - The array of objects to filter.
+* @param conditions - An object where keys represent the property names and values represent filter conditions.
+*                     The conditions can be a function `(value: T[K]) => boolean`.
+* @returns The filtered array of objects.
+* @throws `Error` If the input is not a valid array.
+*
+* @remarks Use `findAll` instance method from `Finder` class for **more advanced filtering and searching.**
+*/
+const filterArrayOfObjects = (array, conditions) => {
+	if (!Array.isArray(array)) throw new TypeError("The provided input is not a valid array!");
+	return array?.filter((item) => {
+		return extractObjectEntries(conditions)?.every((pair) => {
+			const [key, conditionFn] = pair ?? [];
+			if (key && isFunction(conditionFn)) return conditionFn(item[key]);
+			return true;
+		});
+	});
+};
+/**
+* * Checks if a value is an empty array or an array with only empty values.
+*
+* @param value - The value to check.
+* @returns `true` if the value is not an array, an empty array, or an array containing only `null`, `undefined`, empty objects, or empty arrays.
+*/
+const isInvalidOrEmptyArray = (value) => {
+	if (!Array.isArray(value)) return true;
+	if (value?.length === 0) return true;
+	return value?.every((item) => item == null || Array.isArray(item) && item?.length === 0 || typeof item === "object" && Object.keys(item || {})?.length === 0);
+};
+/**
+* * Shuffle the elements of an array.
+*
+* @param array Array to shuffle.
+* @returns Shuffled array.
+*/
+const shuffleArray = (array) => {
+	if (isInvalidOrEmptyArray(array)) return array;
+	const shuffled = [...array];
+	for (let i = shuffled?.length - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1));
+		[shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+	}
+	return shuffled;
+};
+/**
+* * Get the last element of an array.
+*
+* @param array Array to get the last element from.
+* @returns The last element or `undefined` if the array is empty.
+*/
+const getLastArrayElement = (array) => {
+	return array?.length > 0 ? array[array?.length - 1] : void 0;
+};
+
+//#endregion
+//#region src/number/guards.ts
+/**
+* * Check if a number is even or not.
+*
+* @param input The number or numeric string to check.
+* @returns Boolean: `true` if even and `false` if not even.
+*/
+const isEven = (input) => {
+	const parsed = normalizeNumber(input);
+	if (isUndefined(parsed)) return false;
+	return parsed % 2 === 0;
+};
+/**
+* * Checks if a number is odd or not.
+*
+* @param input The number or numeric string to check.
+* @returns Boolean: `true` if odd and `false` if not odd.
+*/
+const isOdd = (input) => {
+	const parsed = normalizeNumber(input);
+	if (isUndefined(parsed)) return false;
+	return parsed % 2 !== 0;
+};
+/**
+* * Checks if a number is a multiple of another number.
+*
+* @param input - The number to check.
+* @param multipleOf - The number to check against.
+* @returns `true` if `input` is a multiple of `multipleOf`, otherwise `false`.
+*/
+const isMultiple = (input, multipleOf) => {
+	return input % multipleOf === 0;
+};
+/**
+* * Checks if a number is a perfect square.
+*
+* @param num The number to check.
+* @returns `true` if the number is a perfect square, otherwise `false`.
+*/
+function isPerfectSquare(num) {
+	return Number.isInteger(Math.sqrt(num));
+}
+/**
+* * Checks if a number is part of the Fibonacci sequence.
+*
+* @param num The number to check.
+* @returns `true` if the number is a Fibonacci number, otherwise `false`.
+*/
+function isFibonacci(num) {
+	return isPerfectSquare(5 * num * num + 4) || isPerfectSquare(5 * num * num - 4);
+}
+/**
+* * Checks whether any input is not a finite number.
+*
+* @param numbers - The list of numbers to validate.
+* @returns `true` if any input is not finite.
+*/
+function areInvalidNumbers(...numbers) {
+	return numbers?.some((n) => !Number.isFinite(n));
+}
+
+//#endregion
+//#region src/number/prime.ts
+/**
+* * Checks if a number is prime.
+*
+* @param number The number to check.
+* @returns Boolean: `true` if the number is prime, otherwise `false`.
+*/
+const isPrime = (number) => {
+	if (number < 2) return false;
+	if (number === 2 || number === 3) return true;
+	if (number % 2 === 0 || number % 3 === 0) return false;
+	for (let i = 5; i * i <= number; i += 6) if (number % i === 0 || number % (i + 2) === 0) return false;
+	return true;
+};
+/**
+* * Find prime numbers in a given range.
+*
+* @param start The starting number of the range. Default is `1`.
+* @param end The ending number of the range. Default is `1000`.
+* @returns An array of prime numbers within the range (inclusive).
+*/
+const findPrimeNumbers = (start = 1, end = 1e3) => {
+	let startNumber = start, endNumber = end;
+	if (start > end) [startNumber, endNumber] = [end, start];
+	return Array.from({ length: endNumber - startNumber + 1 }, (_, i) => startNumber + i).filter(isPrime);
+};
+
+//#endregion
+//#region src/string/convert.ts
+/**
+* * Replaces all occurrences of a string or pattern in the given input string.
+*
+* - If `find` is a string, it is converted into a global regular expression (`/find/g`).
+* - If `find` is a `RegExp`, the global (`g`) flag is ensured.
+* - Trims the input before performing replacements.
+*
+* @param input - The string in which replacements should be performed.
+* @param find - The substring or regex pattern to search for.
+* @param replace - The string to replace matches with.
+* @returns The modified/refined string with replacements applied.
+*/
+const replaceAllInString = (input, find, replace) => {
+	const trimmedString = trimString(input);
+	const regex = isString(find) ? new RegExp(find, "g") : new RegExp(find, find?.flags.includes("g") ? find?.flags : find?.flags + "g");
+	return trimmedString?.replace(regex, replace);
+};
+/**
+* * Converts a string into a URL-friendly slug.
+* @param input - The string to be converted.
+* @returns The slugified string.
+*/
+const slugifyString = (input) => {
+	return trimString(normalizeString(input))?.toLowerCase()?.replace(/[^a-z0-9]+/g, "-")?.replace(/^-+|-+$/g, "");
+};
+/**
+* * Masks part of a string for privacy.
+* @param input - The string to mask.
+* @param options - Options for masking a string.
+* @returns The masked string.
+*/
+const maskString = (input, options) => {
+	const { start = 1, end = 1, maskCharacter: maskChar = "*" } = options || {};
+	const trimmedString = trimString(input);
+	if (trimmedString?.length <= start + end) return maskChar?.repeat(trimmedString?.length);
+	return trimmedString.slice(0, start) + maskChar?.repeat(trimmedString?.length - start - end) + (end > 0 ? trimmedString.slice(-end) : "");
+};
+/**
+* * Reverses a given string.
+* @param input - The string to reverse.
+* @returns The reversed string.
+*
+* @remarks It {@link trimString trims} the whitespace of the input string before reversing it.
+*/
+const reverseString = (input) => {
+	return trimString(input)?.split("")?.reverse()?.join("");
+};
+/**
+* * Normalizes a string by removing diacritics (accents).
+* @param str The input string.
+* @returns The normalized string.
+*/
+function normalizeString(str) {
+	return str?.normalize("NFD")?.replace(/[\u0300-\u036f]/g, "");
+}
+/**
+* * Extracts all email addresses from a string.
+* @param str The input string.
+* @returns An array of extracted email addresses.
+*/
+function extractEmails(str) {
+	return str?.match(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g) || [];
+}
+/**
+* * Extracts all URLs from a string.
+* @param str The input string.
+* @returns An array of extracted URLs.
+*/
+function extractURLs(str) {
+	return str?.match(/https?:\/\/[^\s/$.?#].[^\s]*/g) || [];
+}
+/**
+* * Returns a grammatically correct unit string, optionally prefixed with the number.
+*
+* @remarks For complex and versatile pluralization, please refer to {@link https://toolbox-x.nazmul-nhb.dev/docs/utils/string/pluralizer pluralizer} or {@link https://toolbox-x.nazmul-nhb.dev/docs/classes/pluralizer Pluralizer Class} instead.
+*
+* @param count The numeric value to determine singular or plural.
+* @param unit The unit name (e.g., "day", "hour").
+* @param withNumber Whether to prefix the count before the unit. Defaults to `true`.
+* @returns Formatted unit string like `"1 day"`, `"2 months"`, or `"hour"`.
+*/
+function formatUnitWithPlural(count, unit, withNumber = true) {
+	const pluralized = Math.abs(count) === 1 ? unit : `${unit}s`;
+	return withNumber ? `${count} ${pluralized}` : pluralized;
+}
+
+//#endregion
+//#region src/string/guards.ts
+/**
+* * Checks if a string is a palindrome.
+* @param input - The string to check.
+* @returns True if the string is a palindrome, otherwise false.
+*/
+const isPalindrome = (input) => {
+	const normalized = input.toLowerCase().replace(/[^a-z0-9]/g, "");
+	return normalized === reverseString(normalized);
+};
+/**
+* * Checks if a string is in camelCase format.
+* @param str The string to check.
+* @returns `true` if the string is in camelCase, otherwise `false`.
+*/
+function isCamelCase(str) {
+	return /^[a-z]+([A-Z][a-z]*)*$/.test(str);
+}
+/**
+* * Checks if a string is in PascalCase format.
+* @param str The string to check.
+* @returns `true` if the string is in PascalCase, otherwise `false`.
+*/
+function isPascalCase(str) {
+	return /^[A-Z][a-zA-Z]*$/.test(str);
+}
+/**
+* * Checks if a string is in snake_case format.
+* @param str The string to check.
+* @returns `true` if the string is in snake_case, otherwise `false`.
+*/
+function isSnakeCase(str) {
+	return /^[a-z]+(_[a-z]+)*$/.test(str);
+}
+/**
+* * Checks if a string is in kebab-case format.
+* @param str The string to check.
+* @returns `true` if the string is in kebab-case, otherwise `false`.
+*/
+function isKebabCase(str) {
+	return /^[a-z]+(-[a-z]+)*$/.test(str);
+}
+/**
+* * Checks if a string contains only emojis.
+* @param str The string to check.
+* @returns `true` if the string contains only emojis, otherwise `false`.
+*/
+function isEmojiOnly(str) {
+	return /^[\p{Emoji}]+$/u.test(str);
+}
+
+//#endregion
+export { extractObjectEntries as A, filterArrayOfObjects as C, shuffleArray as D, isInvalidOrEmptyArray as E, extractObjectKeysDeep as M, cloneObject as O, isPerfectSquare as S, getLastArrayElement as T, areInvalidNumbers as _, isPascalCase as a, isMultiple as b, extractURLs as c, normalizeString as d, replaceAllInString as f, isPrime as g, findPrimeNumbers as h, isPalindrome as i, extractObjectKeys as j, countObjectFields as k, formatUnitWithPlural as l, slugifyString as m, isEmojiOnly as n, isSnakeCase as o, reverseString as p, isKebabCase as r, extractEmails as s, isCamelCase as t, maskString as u, isEven as v, flattenArray as w, isOdd as x, isFibonacci as y };

package/dist/{guards-Cp6KAkVI.mjs → guards-BK1QuvFZ.mjs}

@@ -16,8 +16,8 @@
 
 import { a as isNonEmptyString, d as isString, n as isBoolean } from "./primitives-Djsevc69.mjs";
 import { n as NATIVE_TZ_IDS, t as IANA_TZ_IDS } from "./timezone-avZ4TvDx.mjs";
-import { T as isObject, b as isFunction, d as isNumericString } from "./specials-Cye93-uo.mjs";
-import { a as normalizeNumber } from "./utilities-B9axOvOX.mjs";
+import { T as isObject, b as isFunction, d as isNumericString } from "./specials-Hq5Ncd6y.mjs";
+import { a as normalizeNumber } from "./utilities-DPscNbS1.mjs";
 
 //#region src/date/guards.ts
 /**
@@ -41,7 +41,7 @@ function isValidTime(value) {
 * @returns `true` if the value is a valid utc offset, `false` otherwise.
 */
 function isValidUTCOffset(value) {
-	return isString(value) ? /^UTC[+-]?\d{1,2}:\d{2}$/.test(value) : false;
+	return isString(value) ? /^UTC[+-]?(?:0[0-9]|1[0-4]):(?:00|15|30|45)$/.test(value) : false;
 }
 /**
 * * Validates whether the provided value is a recognized IANA time zone identifier (excluding `"Factory"`), based on the {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones IANA TZ Database}.

package/dist/{guards-DP5k4_Mm.cjs → guards-Bsh6Bfdq.cjs}

@@ -16,8 +16,8 @@
 
 const require_primitives = require('./primitives-CBGICrDR.cjs');
 const require_timezone = require('./timezone-CSz7R0L6.cjs');
-const require_specials = require('./specials-BM6cx43o.cjs');
-const require_utilities = require('./utilities-CzyXCRHM.cjs');
+const require_specials = require('./specials-dkYP1Nh2.cjs');
+const require_utilities = require('./utilities-CWV1GPGY.cjs');
 
 //#region src/date/guards.ts
 /**
@@ -41,7 +41,7 @@ function isValidTime(value) {
 * @returns `true` if the value is a valid utc offset, `false` otherwise.
 */
 function isValidUTCOffset(value) {
-	return require_primitives.isString(value) ? /^UTC[+-]?\d{1,2}:\d{2}$/.test(value) : false;
+	return require_primitives.isString(value) ? /^UTC[+-]?(?:0[0-9]|1[0-4]):(?:00|15|30|45)$/.test(value) : false;
 }
 /**
 * * Validates whether the provided value is a recognized IANA time zone identifier (excluding `"Factory"`), based on the {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones IANA TZ Database}.