toolbox-x 1.2.1 → 2.0.0

package/dist/index-CIJWxnDS.d.mts

@@ -0,0 +1,292 @@
+/**
+ * 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 { G as ConditionFns, Jr as ProtoMethodOptions, K as Constructor, U as ClassDetails, dt as Primitive, mt as VoidFn, nt as Maybe, q as DelayedFn, vr as ArrayOfObjectsToStringOptions, y as GenericObject, yr as ArrayOfPrimitivesToStringOptions } from "./object-X5fSMx-I.mjs";
+import { a as Flattened } from "./array-26Vs2HCs.mjs";
+
+//#region src/array/basics.d.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.
+ */
+declare const flattenArray: <T>(input: T | T[]) => Flattened<T>[];
+/**
+ * * 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.**
+ */
+declare const filterArrayOfObjects: <T extends GenericObject>(array: Maybe<T[]>, conditions: ConditionFns<T>) => T[];
+/**
+ * * 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.
+ */
+declare const isInvalidOrEmptyArray: <T>(value: T) => boolean;
+/**
+ * * Shuffle the elements of an array.
+ *
+ * @param array Array to shuffle.
+ * @returns Shuffled array.
+ */
+declare const shuffleArray: <T>(array: T[]) => T[];
+/**
+ * * 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.
+ */
+declare const getLastArrayElement: <T>(array: T[]) => Maybe<T>;
+//#endregion
+//#region src/number/prime.d.ts
+/**
+ * * Checks if a number is prime.
+ *
+ * @param number The number to check.
+ * @returns Boolean: `true` if the number is prime, otherwise `false`.
+ */
+declare const isPrime: (number: number) => boolean;
+/**
+ * * 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).
+ */
+declare const findPrimeNumbers: (start?: number, end?: number) => number[];
+//#endregion
+//#region src/utils/index.d.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.
+ */
+declare const isDeepEqual: (a: unknown, b: unknown) => boolean;
+/**
+ * * Converts an array of objects to a string using a specific property (supports nested path to primitive values) and separator.
+ *
+ * @example
+ * const users = [
+ * 	{ id: 1, name: { first: 'Alice' }, city: 'Bangu', },
+ * 	{ id: 4, name: { first: 'Bob' }, city: 'Banguland', },
+ * ];
+ * convertArrayToString(users, { target: 'name.first', separator: ' | ' });
+ * // "Alice | Bob"
+ *
+ * @param array Array of objects to convert.
+ * @param options Options including the target property and separator.
+ * @returns String formed by joining the property values with the given separator.
+ */
+declare function convertArrayToString<T extends GenericObject>(array: Maybe<T[]>, options: ArrayOfObjectsToStringOptions<T>): string;
+/**
+ * * Converts an array of primitive values to a string using a custom separator.
+ *
+ * @example
+ * convertArrayToString(['red', 'green', 'blue'], { separator: ' - ' });
+ * // "red - green - blue"
+ *
+ * @example
+ * convertArrayToString([1, 2, 3]);
+ * // "1, 2, 3"
+ *
+ * @param array Array of primitive values to convert.
+ * @param options Optional separator configuration.
+ * @returns String formed by joining array elements with the given separator.
+ */
+declare function convertArrayToString<T extends Primitive>(array: Maybe<T[]>, options?: ArrayOfPrimitivesToStringOptions): string;
+/**
+ * * 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.
+ */
+declare function debounceAction<T extends VoidFn>(callback: T, delay?: number): DelayedFn<T>;
+/**
+ * * 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);
+ */
+declare function throttleAction<T extends VoidFn>(callback: T, delay?: number): DelayedFn<T>;
+/**
+ * * 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.
+ */
+declare function getInstanceMethodNames(cls: Constructor): string[];
+/**
+ * * 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.
+ */
+declare function getStaticMethodNames(cls: Constructor): string[];
+/**
+ * * 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.
+ */
+declare function countInstanceMethods(cls: Constructor): number;
+/**
+ * * 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.
+ */
+declare function countStaticMethods(cls: Constructor): number;
+/**
+ * * 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.
+ */
+declare function getInstanceGetterNames(cls: Constructor): string[];
+/**
+ * * 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.
+ */
+declare function getStaticGetterNames(cls: Constructor): string[];
+/**
+ * * 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.
+ */
+declare function getClassDetails(cls: Constructor): ClassDetails;
+/**
+ * * 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.
+ */
+declare function stableStringify(obj: unknown): string;
+/**
+ * * Remove trailing or leading garbage characters **after/before JSON object or array**.
+ * @param str String to sanitize/strip.
+ * @returns Sanitized/stripped JSON string.
+ */
+declare function stripJsonEdgeGarbage(str: string): string;
+/**
+ * * 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.
+ */
+declare const parseJSON: <T = unknown>(value: string, parsePrimitives?: boolean) => T;
+/**
+ * * 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`.
+ */
+declare function deepParsePrimitives<T = unknown>(input: unknown): T;
+/**
+ * * 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!!!"
+ */
+declare function definePrototypeMethod<Proto extends object, Name extends keyof Proto, Args extends unknown[], Return>(proto: Proto, name: Name, impl: (...args: Args) => Return, options?: ProtoMethodOptions): void;
+//#endregion
+export { shuffleArray as C, isInvalidOrEmptyArray as S, findPrimeNumbers as _, deepParsePrimitives as a, flattenArray 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, isPrime as v, getLastArrayElement as x, filterArrayOfObjects as y };