@bsb/base 9.0.0

package/lib/base/tools.d.ts

@@ -0,0 +1,316 @@
+import { CleanStringStrength, MergeObjectsKey, SimpleStatu } from "../interfaces";
+/**
+ * Just a bunch of utility functions - some are used within the framework, others are just general purpose.
+ * You can use any of these functions instead of writing your own or importing from an additional library.
+ *
+ * This class only has static methods, so don't going creating instances of it.
+ *
+ * If you want to use it, like for isNullOrUndefined, you can just call it directly on the class: `Tools.isNullOrUndefined(value)`.
+ * @category Tools
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html | API: Tools}
+ */
+export declare class Tools {
+    /**
+     * @hidden
+     */
+    constructor();
+    /**
+     * Predefined regular expressions for common string cleaning operations.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#regexes | API: Tools#regexes}
+     */
+    static readonly regexes: {
+        exhard: RegExp;
+        hard: RegExp;
+        soft: RegExp;
+        url: RegExp;
+        ip: RegExp;
+        email: RegExp;
+    };
+    static cleanString(objectToClean: any): string;
+    static cleanString(objectToClean: any, maxLimit: number): string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: RegExp): string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: CleanStringStrength): string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: RegExp, returnNullAndUndefined: true): undefined | null | string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: RegExp, returnNullAndUndefined: false): string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: CleanStringStrength, returnNullAndUndefined: true): undefined | null | string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: CleanStringStrength, returnNullAndUndefined: false): string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: CleanStringStrength.custom, returnNullAndUndefined: true, customRegex: RegExp): undefined | null | string;
+    static cleanString(objectToClean: any, maxLimit: number, strength: CleanStringStrength.custom, returnNullAndUndefined: false, customRegex: RegExp): string;
+    /**
+     * Automatically capitalize the first letter of each word in a string.
+     * @param data - The string to capitalize
+     * @returns The string with each word capitalized
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#autoCapitalizeWords | API: Tools#autoCapitalizeWords}
+     */
+    static autoCapitalizeWords(data: string): string;
+    /**
+     * Get the string keys from an enum object, filtering out numeric keys.
+     * @param obj - The enum object
+     * @returns Array of string keys
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#enumKeys | API: Tools#enumKeys}
+     */
+    static enumKeys<O extends object, K extends keyof O = keyof O>(obj: O): K[];
+    /**
+     * @hidden
+     */
+    private static _flattenObject;
+    /**
+     * Flatten a nested object into a single level with dot notation keys.
+     * @param obj - The object to flatten
+     * @returns The flattened object
+     * @throws Error if the input is not a valid object
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#flattenObject | API: Tools#flattenObject}
+     */
+    static flattenObject<T = unknown, TR = object>(obj: T): TR;
+    /**
+     * Get hierarchical availability of objects based on key-parent relationships.
+     * @param listOfObjects - Array of objects to search through
+     * @param key - The key property name
+     * @param parentkey - The parent key property name
+     * @param value - The value to match against
+     * @returns Array of matching objects including hierarchical children
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#hierachialGetAvailibility | API: Tools#hierachialGetAvailibility}
+     */
+    static hierachialGetAvailibility<T>(listOfObjects: Array<T>, key: string, parentkey: string, value: T): Array<T>;
+    /**
+     * Decode a base64 data URL string and extract the image type and data.
+     * @param dataString - Base64 data URL string (e.g., "data:image/png;base64,...")
+     * @returns Object with type and data properties, or Error if invalid
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#decodeBase64Image | API: Tools#decodeBase64Image}
+     */
+    static decodeBase64Image(dataString: string): any;
+    private static GetValueFromObjectBasedOnStringPathSearcher;
+    /**
+     * Get a value from a nested object using a string path (e.g., "user.profile.name").
+     * Supports comma-separated paths for concatenation and "*" wildcard for all properties.
+     * @param workingObj - The object to search in
+     * @param stringToGet - Dot-notation path string or comma-separated paths
+     * @returns The value at the specified path, or null if not found
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#GetValueFromObjectBasedOnStringPath | API: Tools#GetValueFromObjectBasedOnStringPath}
+     */
+    static GetValueFromObjectBasedOnStringPath(workingObj: any, stringToGet: string): any;
+    /**
+     * Merge two objects deeply, with the second object taking precedence.
+     * @param src - Source object to merge into
+     * @param against - Object to merge from (takes precedence)
+     * @param initialMigration - Whether to clone objects before merging (default: true)
+     * @param referenceKey - Optional reference key for merge operations
+     * @returns The merged object
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#mergeObjects | API: Tools#mergeObjects}
+     */
+    static mergeObjects(src: any, against: any, initialMigration?: boolean, referenceKey?: MergeObjectsKey): any;
+    /**
+     * Replace placeholders in a string with values from an object using {key} syntax.
+     * @param obj - Object containing replacement values
+     * @param str - String with placeholders (e.g., "Hello {name}")
+     * @returns String with placeholders replaced by object values
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#StringReplaceWithObject | API: Tools#StringReplaceWithObject}
+     */
+    static StringReplaceWithObject(obj: any, str: string): string;
+    /**
+     * Convert milliseconds to a human-readable time string.
+     * @param time - Time in milliseconds
+     * @returns Human-readable time string (e.g., "5 minutes", "2 hours")
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#getTimeFromMilliseconds | API: Tools#getTimeFromMilliseconds}
+     */
+    static getTimeFromMilliseconds(time: number): string;
+    /**
+     * Create a delay/sleep for the specified number of milliseconds.
+     * @param time - Time to delay in milliseconds (default: 1000)
+     * @returns Promise that resolves after the specified time
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#delay | API: Tools#delay}
+     */
+    static delay(time?: number): Promise<void>;
+    /**
+     * Wait with delays while checking a condition, throwing an error on timeout.
+     * @param checkFunc - Function that returns true while waiting should continue
+     * @param rejectFunc - Function to call on timeout (before throwing)
+     * @param time - Delay between checks in milliseconds (default: 1000)
+     * @param timeout - Maximum number of check attempts (default: 10)
+     * @throws "Timeout!" when the timeout is exceeded
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#waitDelayThenThrow | API: Tools#waitDelayThenThrow}
+     */
+    static waitDelayThenThrow(checkFunc: Function, rejectFunc: Function, time?: number, timeout?: number): Promise<void>;
+    /**
+     * Check if a value is a simple primitive type (string, number, or boolean).
+     * @param value - The value to check
+     * @returns True if the value is a string, number, or boolean
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isSimpleType | API: Tools#isSimpleType}
+     */
+    static isSimpleType(value: unknown): boolean;
+    /**
+     * Type guard to check if a value is a string.
+     * @param value - The value to check
+     * @returns True if the value is a string
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isString | API: Tools#isString}
+     */
+    static isString(value: unknown): value is string;
+    /**
+     * Type guard to check if a value is a Date object.
+     * @param value - The value to check
+     * @param matchString - Currently unused parameter for potential string date matching
+     * @returns True if the value is a Date instance
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isDate | API: Tools#isDate}
+     */
+    static isDate(value: unknown, matchString?: boolean): value is Date;
+    /**
+     * Type guard to check if a value is an array.
+     * @param value - The value to check
+     * @returns True if the value is an array
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isArray | API: Tools#isArray}
+     */
+    static isArray<T = unknown>(value: unknown): value is Array<T>;
+    /**
+     * Type guard to check if a value is a function.
+     * @param value - The value to check
+     * @returns True if the value is a function
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isFunction | API: Tools#isFunction}
+     */
+    static isFunction(value: any): value is Function;
+    /**
+     * Type guard to check if a value is a symbol.
+     * @param value - The value to check
+     * @returns True if the value is a symbol
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isSymbol | API: Tools#isSymbol}
+     */
+    static isSymbol(value: any): value is symbol;
+    /**
+     * Type guard to check if a value is a valid number (not NaN).
+     * @param value - The value to check
+     * @returns True if the value is a number and not NaN
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isNumber | API: Tools#isNumber}
+     */
+    static isNumber(value: any): value is number;
+    /**
+     * Check if a value can be parsed as a valid number and return the parsed result.
+     * @param value - The value to check and parse
+     * @returns Object with status (true if valid) and value (the parsed number)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isStringNumber | API: Tools#isStringNumber}
+     */
+    static isStringNumber(value: any): SimpleStatu<number>;
+    /**
+     * Type guard to check if a value is a boolean.
+     * @param value - The value to check
+     * @returns True if the value is a boolean
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isBoolean | API: Tools#isBoolean}
+     */
+    static isBoolean(value: unknown): value is boolean;
+    /**
+     * Type guard to check if a value is undefined.
+     * @param value - The value to check
+     * @returns True if the value is undefined
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isUndefined | API: Tools#isUndefined}
+     */
+    static isUndefined(value: unknown): value is undefined;
+    /**
+     * Type guard to check if a value is null.
+     * @param value - The value to check
+     * @returns True if the value is null
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isNull | API: Tools#isNull}
+     */
+    static isNull(value: unknown): value is null;
+    /**
+     * Type guard to check if a value is a plain object (not array, null, etc.).
+     * @param value - The value to check
+     * @returns True if the value is a plain object
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isObject | API: Tools#isObject}
+     */
+    static isObject(value: unknown): value is Object;
+    /**
+     * Type guard to check object constructor type (array or object).
+     * @param value - The value to check
+     * @param type - The type to check for ("array" or "object")
+     * @returns True if the value matches the specified constructor type
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#TypeofObjectConstructor | API: Tools#TypeofObjectConstructor}
+     */
+    static TypeofObjectConstructor<TR = unknown>(value: unknown, type: "array" | "object"): value is TR;
+    /**
+     * Type guard to check if a value is a plain object with string keys.
+     * @param value - The value to check
+     * @returns True if the value is a plain object
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isPlainObject | API: Tools#isPlainObject}
+     */
+    static isPlainObject(value: unknown): value is Record<string, any>;
+    /**
+     * Type guard to check if a value is null or undefined.
+     * @param value - The value to check
+     * @returns True if the value is null or undefined
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#isNullOrUndefined | API: Tools#isNullOrUndefined}
+     */
+    static isNullOrUndefined(value: unknown): value is null | undefined;
+    /**
+     * Generate a random integer between min and max (inclusive).
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (inclusive)
+     * @returns Random integer between min and max
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#genRandomNumber | API: Tools#genRandomNumber}
+     */
+    static genRandomNumber(min: number, max: number): number;
+    /**
+     * Clamp a number between a minimum and maximum value.
+     * @param min - Minimum allowed value
+     * @param max - Maximum allowed value
+     * @param value - Value to clamp
+     * @returns The clamped value
+     * @throws Error if min is greater than max
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#clampNumber | API: Tools#clampNumber}
+     */
+    static clampNumber(min: number, max: number, value: number): number;
+    /**
+     * Sleep/delay execution for the specified number of milliseconds.
+     * @param milliseconds - Time to sleep in milliseconds (default: 1000)
+     * @returns Promise that resolves after the specified time
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#sleep | API: Tools#sleep}
+     */
+    static sleep(milliseconds?: number): Promise<void>;
+    /**
+     * Collection of utility functions for working with arrays.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#arrays | API: Tools#arrays}
+     */
+    static arrays: {
+        /**
+         * Asynchronously map over an array with async callback functions.
+         * @param arr - The array to map over
+         * @param asyncCallback - Async function to call for each item
+         * @returns Promise resolving to the mapped array
+         * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#arrays | API: Tools#arrays}
+         */
+        mapAsync: <Input = any, Output = any>(arr: Array<Input>, asyncCallback: {
+            (item: Input): Promise<Output>;
+        }) => Promise<Array<Output>>;
+        /**
+         * Group array items by a key generated from a function.
+         * @param groupFunc - Function that returns a string key for grouping
+         * @param list - Array to group
+         * @returns Object with keys as group names and values as arrays of grouped items
+         * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#arrays | API: Tools#arrays}
+         */
+        groupListBy: <T = any>(groupFunc: {
+            (object: T): string;
+        }, list: Array<T>) => Record<string, Array<T>>;
+        /**
+         * Collect array items into groups using a grouping function, returning only the grouped arrays.
+         * @param groupFunc - Function that returns a string key for grouping
+         * @param list - Array to collect
+         * @returns Array of arrays where each sub-array contains grouped items
+         * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#arrays | API: Tools#arrays}
+         */
+        collectListBy: <T = any>(groupFunc: {
+            (object: T): string;
+        }, list: Array<T>) => Array<Array<T>>;
+        /**
+         * Get the first item in the array.
+         * @param list - The array to get the first item from
+         * @returns The first item or undefined if array is empty
+         * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#arrays | API: Tools#arrays}
+         */
+        head: <T = any>(list: Array<T>) => T | undefined;
+        /**
+         * Get the last item in the array.
+         * @param list - The array to get the last item from
+         * @returns The last item or undefined if array is empty
+         * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Tools.html#arrays | API: Tools#arrays}
+         */
+        tail: <T = any>(list: Array<T>) => T | undefined;
+    };
+}