toolbox-x 1.0.0

package/dist/array-rUnEVisO.d.cts

@@ -0,0 +1,130 @@
+/**
+ * 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 { E as NestedPrimitiveKey, nt as NormalPrimitiveKey, y as GenericObject } from "./object-Blq0Amdv.cjs";
+
+//#region src/types/array.d.ts
+/** * Flatten Array or Wrap in Array */
+type Flattened<T> = T extends (infer U)[] ? Flattened<U> : T;
+/**
+ * * Configuration for `createOptionsArray`.
+ * - Defines the mapping between keys in the input objects and the keys in the output options.
+ *
+ * @typeParam T - The type of the objects in the input array.
+ * @typeParam K1 - The name of the key for the first field in the output (default: `'value'`).
+ * @typeParam K2 - The name of the key for the second field in the output (default: `'label'`).
+ * @typeParam V - Whether to keep the `value` field as number if it is a number. Defaults to `false`.
+ */
+interface OptionsConfig<T, K1, K2, V extends boolean = false> {
+  /**
+   * - The key in the input objects to use for the first field of the option. Only primitive values (`string | number | boolean | null | undefined`) are accepted.
+   * @example
+   * // If the input objects have an `id` field and you want to use it as the `value` field in the output:
+   * createOptionsArray(data, {firstFieldKey: 'id'}).
+   */
+  firstFieldKey: NormalPrimitiveKey<T>;
+  /**
+   * - The key in the input objects to use for the second field of the option. Only primitive values (`string | number | boolean | null | undefined`) are accepted.
+   * @example
+   * // If the input objects have a `name` field and you want to use it as the `label` field in the output:
+   * createOptionsArray(data, {firstFieldKey: 'id', secondFieldKey: 'name'}).
+   */
+  secondFieldKey: NormalPrimitiveKey<T>;
+  /**
+   * - The name of the first field in the output object.
+   * - Defaults to `'value'`.
+   * @example
+   * // If you want the output field to be named `'key'` instead of `'value'`:
+   * createOptionsArray(data, {firstFieldKey: 'id', secondFieldKey: 'name', firstFieldName: 'key'}).
+   */
+  firstFieldName?: K1;
+  /**
+   * - The name of the second field in the output object.
+   * - Defaults to `'label'`.
+   * @example
+   * // If you want the output field to be named `'title'` instead of `'label'`:
+   * createOptionsArray(data, {firstFieldKey: 'id', secondFieldKey: 'name', firstFieldName: 'key', secondFieldName: 'title'}).
+   */
+  secondFieldName?: K2;
+  /**
+   * - If `true`, numeric values from `firstFieldKey` will remain as numbers.
+   * - All other values (including booleans, null, undefined) will be converted to strings.
+   * - When `false` (default), all values are converted to strings.
+   * - Defaults to `false`.
+   * @example
+   * // Numeric IDs remain as numbers
+   * createOptionsArray(data, {
+   *   firstFieldKey: 'id',
+   *   secondFieldKey: 'name',
+   *   retainNumberValue: true
+   * });
+   *
+   * // All values become strings (default behavior)
+   * createOptionsArray(data, {
+   *   firstFieldKey: 'id',
+   *   secondFieldKey: 'name'
+   * });
+   */
+  retainNumberValue?: V;
+}
+/** Type for first field key */
+type FirstFieldKey<T extends GenericObject, K1 extends string = 'value', K2 extends string = 'label', V extends boolean = false> = T[OptionsConfig<T, K1, K2, V>['firstFieldKey']];
+/** Type for firs field value */
+type FirstFieldValue<T extends GenericObject, K1 extends string = 'value', K2 extends string = 'label', V extends boolean = false> = V extends true ? FirstFieldKey<T, K1, K2, V> extends Exclude<FirstFieldKey<T, K1, K2, V>, number> ? string : number : string;
+/** Type of values for the option fields */
+type FieldValue<P extends K1 | K2, T extends GenericObject, K1 extends string = 'value', K2 extends string = 'label', V extends boolean = false> = P extends K1 ? FirstFieldValue<T, K1, K2, V> : string;
+/** Type of an option in `OptionsArray` */
+type Option<T extends GenericObject, K1 extends string = 'value', K2 extends string = 'label', V extends boolean = false> = { [P in K1 | K2]: FieldValue<P, T, K1, K2, V> };
+/** * Option for sorting order. */
+interface OrderOption {
+  /**
+   * * The order in which to sort the array. Defaults to `'asc'`.
+   * - `'asc'`: Sort in ascending order.
+   * - `'desc'`: Sort in descending order.
+   */
+  sortOrder?: 'asc' | 'desc';
+}
+/** * Options for setting sortByField for sorting an array of objects. */
+interface SortByOption<T extends GenericObject> extends OrderOption {
+  /** The field by which to sort the objects in the array. */
+  sortByField: NestedPrimitiveKey<T>;
+}
+/** * Options for sorting array. */
+type SortOptions<T> = T extends GenericObject ? SortByOption<T> : OrderOption;
+/** Optional settings to configure comparison behavior. */
+interface SortNature {
+  /** If true, compares string chunks without case sensitivity. Defaults to `true`. */
+  caseInsensitive?: boolean;
+  /** If true, uses localeCompare for string chunk comparisons. Defaults to `false`. */
+  localeAware?: boolean;
+}
+/** * Options for customizing the search behavior. */
+interface FindOptions<T extends GenericObject = {}> {
+  /** * Enables fuzzy matching when exact match fails. Defaults to `false`. */
+  fuzzy?: boolean;
+  /** * Optional key for caching the result. Defaults to `finder-cache` */
+  cacheKey?: string;
+  /** * Forces binary search even for small datasets. Defaults to `false`. */
+  forceBinary?: boolean;
+  /** * If true, matcher and keys will be normalized to lowercase. Defaults to `true`. */
+  caseInsensitive?: boolean;
+  /** * If true, uses built in `Array.sort()`. Defaults to `true`. Pass `false` if data is already sorted. */
+  needSorting?: boolean;
+  /** * Optional data source to use instead of constructor items. */
+  data?: T[] | (() => T[]);
+}
+//#endregion
+export { Flattened as a, OrderOption as c, SortOptions as d, FirstFieldValue as i, SortByOption as l, FindOptions as n, Option as o, FirstFieldKey as r, OptionsConfig as s, FieldValue as t, SortNature as u };

package/dist/basics-D_eSv0cu.cjs

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ */
+
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+
+//#region src/string/basics.ts
+/**
+* * Utility to truncate a string to a specified length.
+*
+* @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 truncateString(str, maxLength) {
+	if (!require_primitives.isNonEmptyString(str)) return "";
+	const trimmedString = str.trim();
+	if (!trimmedString) return "";
+	if (trimmedString.length <= maxLength) return trimmedString;
+	return trimmedString.slice(0, maxLength).concat("...");
+}
+/**
+* * 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.nazmul-nhb.dev/docs/utilities/hash/uuid uuid} for `uuid` generation
+* @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/randomHex 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 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 && prefix.trim(),
+		date,
+		randomString,
+		suffix && suffix.trim()
+	].filter(Boolean).join(separator);
+	switch (caseOption) {
+		case "upper": return ID.toUpperCase();
+		case "lower": return ID.toLowerCase();
+		default: return ID;
+	}
+}
+/**
+* * Trims all the words in a string or an array of strings.
+*
+* @param input String or array of strings.
+* @returns Trimmed string or array of strings.
+*/
+function trimString(input) {
+	if (!input) return "";
+	if (require_primitives.isNonEmptyString(input)) return input.trim().replace(/\s+/g, " ");
+	if (Array.isArray(input)) return input.map((str) => require_primitives.isNonEmptyString(str) ? str.trim().replace(/\s+/g, " ") : str);
+	throw new TypeError("Expected string or array of strings!", { cause: "Invalid Input Type" });
+}
+
+//#endregion
+Object.defineProperty(exports, 'generateRandomID', {
+  enumerable: true,
+  get: function () {
+    return generateRandomID;
+  }
+});
+Object.defineProperty(exports, 'trimString', {
+  enumerable: true,
+  get: function () {
+    return trimString;
+  }
+});
+Object.defineProperty(exports, 'truncateString', {
+  enumerable: true,
+  get: function () {
+    return truncateString;
+  }
+});

package/dist/basics-Dp_aEK81.mjs

@@ -0,0 +1,115 @@
+/**
+ * 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 } from "./primitives-KsFUp3kQ.mjs";
+
+//#region src/string/basics.ts
+/**
+* * Utility to truncate a string to a specified length.
+*
+* @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 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("...");
+}
+/**
+* * 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.nazmul-nhb.dev/docs/utilities/hash/uuid uuid} for `uuid` generation
+* @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/randomHex 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 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 && prefix.trim(),
+		date,
+		randomString,
+		suffix && suffix.trim()
+	].filter(Boolean).join(separator);
+	switch (caseOption) {
+		case "upper": return ID.toUpperCase();
+		case "lower": return ID.toLowerCase();
+		default: return ID;
+	}
+}
+/**
+* * Trims all the words in a string or an array of strings.
+*
+* @param input String or array of strings.
+* @returns Trimmed string or array of strings.
+*/
+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
+export { trimString as n, truncateString as r, generateRandomID as t };

package/dist/basics-WEYWlnRO.d.cts

@@ -0,0 +1,95 @@
+/**
+ * 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 { F as RandomIdOptions } from "./string-CsNsm_65.cjs";
+
+//#region src/string/basics.d.ts
+/**
+ * * Utility to truncate a string to a specified length.
+ *
+ * @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`).
+ */
+declare function truncateString(str: string, maxLength: number): 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 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.nazmul-nhb.dev/docs/utilities/hash/uuid uuid} for `uuid` generation
+ * @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/randomHex 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"
+ */
+declare function generateRandomID(options?: RandomIdOptions): string;
+/**
+ * * Trims all the words in a string.
+ *
+ * @param input The string to trim.
+ * @returns Trimmed string.
+ */
+declare function trimString(input: string): string;
+/**
+ * * Trims all the words in an array of strings.
+ *
+ * @param input The array of strings to trim.
+ * @returns Trimmed array of strings.
+ */
+declare function trimString(input: string[]): string[];
+//#endregion
+export { trimString as n, truncateString as r, generateRandomID as t };

package/dist/basics-uBSfkBEI.d.mts

@@ -0,0 +1,95 @@
+/**
+ * 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 { F as RandomIdOptions } from "./string-CBAbxaG1.mjs";
+
+//#region src/string/basics.d.ts
+/**
+ * * Utility to truncate a string to a specified length.
+ *
+ * @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`).
+ */
+declare function truncateString(str: string, maxLength: number): 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 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.nazmul-nhb.dev/docs/utilities/hash/uuid uuid} for `uuid` generation
+ * @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/randomHex 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"
+ */
+declare function generateRandomID(options?: RandomIdOptions): string;
+/**
+ * * Trims all the words in a string.
+ *
+ * @param input The string to trim.
+ * @returns Trimmed string.
+ */
+declare function trimString(input: string): string;
+/**
+ * * Trims all the words in an array of strings.
+ *
+ * @param input The array of strings to trim.
+ * @returns Trimmed array of strings.
+ */
+declare function trimString(input: string[]): string[];
+//#endregion
+export { trimString as n, truncateString as r, generateRandomID as t };