type CanBeString = string | {
    toString(): string;
};

type Nullable<T> = T | null | undefined;

type FunctionLike = (...args: any[]) => any;

/**
 * Compares two strings for equality, ignoring case sensitivity.
 *
 * @param text1 - The first string to compare.
 * @param text2 - The second string to compare.
 * @returns `true` if the strings are equal when compared in lowercase, otherwise `false`.
 *
 * @example
 * equalsIgnoreCase("Hello", "hello");
 * // Returns: true
 *
 * @example
 * equalsIgnoreCase("World", "WORLD");
 * // Returns: true
 *
 * @example
 * equalsIgnoreCase("Test", "Toast");
 * // Returns: false
 */
declare function equalsIgnoreCase(text1: string, text2: string): boolean;
/**
 * Checks if a string contains a given query, ignoring case sensitivity.
 *
 * @param text - The string to search within.
 * @param query - The substring to search for.
 * @returns `true` if `query` is found within `text` when both are compared in lowercase, otherwise `false`.
 *
 * @example
 * includesIgnoreCase("Hello World", "world");
 * // Returns: true
 *
 * @example
 * includesIgnoreCase("Programming", "GRAM");
 * // Returns: true
 *
 * @example
 * includesIgnoreCase("TypeScript", "Java");
 * // Returns: false
 */
declare function includesIgnoreCase(text: string, query: string): boolean;

type Color = `#${string}` | string;
/**
 * Converts a hexadecimal color string to its numeric RGB representation.
 *
 * @param color - A hexadecimal color string (e.g., `"#FFFFFF"`) or a plain string representing a hex value.
 * @returns A number representing the RGB value parsed from the hexadecimal string.
 *
 * @example
 * hexToRgb("#FFFFFF");
 * // Returns: 16777215
 *
 * @example
 * hexToRgb("000000");
 * // Returns: 0
 *
 * @example
 * hexToRgb("#FF5733");
 * // Returns: 16724755
 *
 */
declare function hexToRgb(color: Color): number;
/**
 * Converts a numeric RGB value to its hexadecimal color string representation.
 *
 * @param rgb - The numeric RGB value to convert.
 * @param includeHash - Whether to prefix the result with `#`. Defaults to `true`.
 * @returns A hexadecimal color string representing the RGB value, optionally prefixed with `#`.
 *
 * @example
 * rgbToHex(16777215);
 * // Returns: "#ffffff"
 *
 * @example
 * rgbToHex(0, false);
 * // Returns: "000000"
 *
 * @example
 * rgbToHex(16724755);
 * // Returns: "#ff5733"
 */
declare function rgbToHex(rgb: number, includeHash?: boolean): string;

type BuilderText = Nullable<CanBeString> | BuilderText[];
declare function joinBuilder(separator: string, ...text: BuilderText[]): string;
/**
 * Ensures that a value is either kept as is (if not `null`) or converted to `undefined`.
 *
 * @param value - The value to process. If it is `null`, it will return `undefined`; otherwise, it returns the original value.
 * @returns The original value if it is not `null`, otherwise `undefined`.
 *
 * @example
 * notFound("Hello");
 * // Returns: "Hello"
 *
 * @example
 * notFound(null);
 * // Returns: undefined
 *
 * @example
 * notFound(42);
 * // Returns: 42
 */
declare function notFound<T>(value: T): T & {} | undefined;
/**
 * Joins multiple strings or arrays of strings into a single string, separated by line breaks.
 * Filters out any `null` or `undefined` values.
 *
 * @param text - The text segments to be joined. Each segment can be a string, an array of strings, or `null`/`undefined`.
 * @returns The concatenated string with each segment separated by a line break.
 *
 * @example
 * ```ts
 * const result = brBuilder("Hello", [null, "World"], undefined, "!");
 * console.log(result);
 * // Output:
 * // Hello
 * // World
 * // !
 * ```
 */
declare function brBuilder(...text: BuilderText[]): string;
/**
 * Joins multiple strings or arrays of strings into a single string separated by spaces, ignoring `null` and `undefined` values.
 *
 * @param texts - A list of strings or arrays of strings, which may include `null` or `undefined`.
 * @returns A single string where all valid strings are joined by a space.
 *
 * @example
 * spaceBuilder("Hello", "World");
 * // Returns: "Hello World"
 *
 * @example
 * spaceBuilder(["Hello", null], "World");
 * // Returns: "Hello World"
 *
 * @example
 * spaceBuilder(null, undefined, "Only this");
 * // Returns: "Only this"
 */
declare function spaceBuilder(...text: BuilderText[]): string;
/**
 * Replaces all occurrences of the properties in the `replaces` object within the given `text` string. The replacements can be either strings or functions that receive the matched substring.
 *
 * @param text - The text in which the replacements will be made.
 * @param replaces - An object where keys are substrings to be replaced and values are either a string or a function that returns a string to replace the match.
 * @returns A new string with all specified replacements applied.
 *
 * @example
 * replaceText("Hello, {name}!", { "{name}": "Alice" });
 * // Returns: "Hello, Alice!"
 *
 * @example
 * replaceText("Goodbye, {name}. See you later!", { "{name}": (match) => match.toUpperCase() });
 * // Returns: "Goodbye, {NAME}. See you later!"
 *
 * @example
 * replaceText("Price is {price} dollars", { "{price}": (match) => `$${match.replace(/\D/g, "")}` });
 * // Returns: "Price is $100 dollars"
 */
declare function replaceText(text: string, replacements: Record<string, string | ((text: string) => string)>): string;
/**
 * Capitalizes the first letter of a given word, or all words in a phrase if `allWords` is true.
 *
 * @param word - The word or phrase to capitalize.
 * @param allWords - A flag to indicate whether to capitalize the first letter of every word in a phrase. Defaults to `false`.
 * @returns The word or phrase with the specified capitalization.
 *
 * @example
 * capitalize("hello");
 * // Returns: "Hello"
 *
 * @example
 * capitalize("hello world", true);
 * // Returns: "Hello World"
 *
 * @example
 * capitalize("  whitespace  ");
 * // Returns: "Whitespace"
 */
declare function capitalize(word: string, allWords?: boolean): string;
/**
 * Truncates the given text to a specified length and appends the `endText` if the text exceeds the maximum length.
 *
 * @param text - The text to be truncated.
 * @param maxLength - The maximum allowed length of the text.
 * @param endText - A string to append at the end of the truncated text if it exceeds the `maxLength`. Defaults to an empty string.
 * @returns The truncated text with the `endText` appended if the original text exceeds the `maxLength`.
 *
 * @example
 * limitText("Hello, this is a long sentence.", 10);
 * // Returns: "Hello, thi"
 *
 * @example
 * limitText("Hello, this is a long sentence.", 10, "...");
 * // Returns: "Hello, thi..."
 */
declare function limitText(text: string, maxLength: number, endText?: string): string;

declare function randomNumber(min: number, max: number): number;
declare const random: {
    int(min: number, max: number): number;
    float(min: number, max: number): number;
};
declare function parseIntOrDefault(value: string, defaultValue: number, radix?: number): number;
declare function parseFloatOrDefault(value: string, defaultValue: number): number;

type TimeUnit = "seconds" | "minutes" | "hours" | "days";
declare function toMsFunc(value: number, unit?: TimeUnit): number;
/**
 * Converts a numeric value from a specified time unit into milliseconds.
 *
 * @param value - The numeric value to convert.
 * @param unit - The unit of time for the value. Defaults to `"seconds"`.
 *               Can be `"seconds"`, `"minutes"`, `"hours"`, or `"days"`.
 * @returns The equivalent time in milliseconds.
 *
 * @example
 * toMs(5, "seconds");
 * // Returns: 5000
 *
 * @example
 * toMs(2, "minutes");
 * // Returns: 120000
 *
 * @example
 * toMs(1.5, "hours");
 * // Returns: 5400000
 *
 * @example
 * toMs(1, "days");
 * // Returns: 86400000
 *
 * @example
 * toMs(30); // Defaults to seconds
 * // Returns: 30000
 */
declare const toMs: typeof toMsFunc & Readonly<{
    seconds: (value: number) => number;
    minutes: (value: number) => number;
    hours: (value: number) => number;
    days: (value: number) => number;
}>;

interface CreateIntervalOptions {
    time: number;
    immediately?: boolean;
    run(stop: () => void): void;
}
declare function createInterval(options: CreateIntervalOptions): {
    timer: NodeJS.Timeout;
    stop: () => void;
};
interface CreateTimeoutOptions {
    delay: number;
    run(): void;
}
declare function createTimeout(options: CreateTimeoutOptions): {
    timer: NodeJS.Timeout;
    stop: () => void;
};
interface CreateLoopIntervalOptions<T> {
    array: T[];
    time: number;
    immediately?: boolean;
    run(value: T, stop: () => void, lap: number, array: T[]): void;
}
declare function createLoopInterval<T>(options: CreateLoopIntervalOptions<T>): {
    timer: NodeJS.Timeout;
    stop: () => void;
};

/**
 * Validates if the given string is a valid email address.
 *
 * @param email - The email address to validate.
 * @returns `true` if the email is valid, otherwise `false`.
 *
 * @example
 * ```ts
 * const validEmail = isEmail("example@domain.com");
 * console.log(validEmail); // Output: true
 *
 * const invalidEmail = isEmail("example@domain");
 * console.log(invalidEmail); // Output: false
 * ```
 */
declare function isEmail(email: string): boolean;
/**
 * Validates if the given string is a valid URL.
 *
 * @param url - The URL to validate.
 * @returns `true` if the URL is valid, otherwise `false`.
 *
 * @example
 * ```ts
 * const validUrl = isUrl("https://example.com");
 * console.log(validUrl); // Output: true
 *
 * const invalidUrl = isUrl("example.com");
 * console.log(invalidUrl); // Output: false
 * ```
 */
declare function isUrl(url: string): boolean;
/**
 * Checks if the given string is numeric (contains only digits).
 *
 * @param text - The text to check.
 * @returns `true` if the text is numeric, otherwise `false`.
 *
 * @example
 * ```ts
 * const isNumericText = isNumeric("12345");
 * console.log(isNumericText); // Output: true
 *
 * const isNotNumericText = isNumeric("123a45");
 * console.log(isNotNumericText); // Output: false
 * ```
 */
declare function isNumeric(text: string): boolean;
declare function isDefined<T>(value: T): value is (T & {});
declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;

/**
 * Extends a function (or object) by adding properties to it.
 *
 * @template F - The type of the function or object to extend.
 * @template P - The type of the properties to add to the function or object.
 * @param fn - The function or object to which properties will be added.
 * @param props - An object containing properties to add to the function or object.
 * @returns A new function or object that includes the original function along with the added properties.
 *
 * @example
 * const myFunc = () => "Hello!";
 * const extendedFunc = withProperties(myFunc, { description: "A simple greeting function" });
 * console.log(extendedFunc.description); // "A simple greeting function"
 *
 * @example
 * const obj = { name: "John" };
 * const extendedObj = withProperties(obj, { age: 30 });
 * console.log(extendedObj.age); // 30
 */
declare function withProperties<F extends Function | object, P extends Record<string, any>>(fn: F, props: P): F & P;
/**
 * Returns a promise that resolves with the original promise's result or a fallback value if it doesn't resolve within the specified timeout.
 *
 * @template T - The type of the original promise's resolved value.
 * @template R - The type of the fallback value. Defaults to `null`.
 * @param promise - The promise to monitor.
 * @param time - The maximum time (in milliseconds) to wait for the promise to resolve.
 * @param fallback - The value to return if the timeout is reached before the promise resolves. Defaults to `null`.
 * @returns A `Promise` that resolves with either the original result or the fallback value.
 *
 * @example
 * const slowPromise = new Promise(res => setTimeout(() => res("done"), 2000));
 * await withTimeout(slowPromise, 1000, "timeout");
 * // Returns: "timeout" after 1 second
 *
 * @example
 * const fastPromise = Promise.resolve("finished");
 * await withTimeout(fastPromise, 1000, "timeout");
 * // Returns: "finished" immediately
 */
declare function withTimeout<T, R = null>(promise: Promise<T>, time: number, fallback?: R): Promise<T | R>;

type DateUnit = "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "months" | "years";
interface DatePlus extends Date {
    /**
     * Adds a value to a specific unit of the date.
     * @param unit Time unit to add to (`days`, `hours`, `minutes`, `seconds`, `milliseconds`, `months`, `years`).
     * @param value Amount to add (can be negative or fractional, e.g., 1.5 days).
     * @returns The same `DatePlus` instance (supports method chaining).
     *
     * @example
     * const d = new DatePlus("2025-01-01");
     * d.add("days", 5); // adds 5 days
     * @example
     * d.add("hours", 12); // adds 12 hours
     */
    add(unit: DateUnit, value: number): this;
    /**
     * Subtracts a value from a specific unit of the date.
     * @param unit Time unit to subtract from (`days`, `hours`, `minutes`, `seconds`, `milliseconds`, `months`, `years`).
     * @param value Amount to subtract.
     * @returns The same `DatePlus` instance (supports method chaining).
     *
     * @example
     * const d = new DatePlus("2025-01-10");
     * d.sub("days", 3); // subtracts 3 days
     * @example
     * d.sub("hours", 5); // subtracts 5 hours
     */
    sub(unit: DateUnit, value: number): this;
    /**
     * Sets a specific unit of the date to an absolute value.
     * @param unit Time unit to set (`days`, `hours`, `minutes`, `seconds`, `milliseconds`, `months`, `years`).
     * @param value New value for the specified unit.
     * @returns The same `DatePlus` instance (supports method chaining).
     *
     * @example
     * const d = new DatePlus("2025-01-01");
     * d.set("hours", 15); // sets the hour to 15
     * @example
     * d.set("days", 10); // sets the day of the month to 10
     */
    set(unit: DateUnit, value: number): this;
    /**
     * Creates a clone of the current `DatePlus` instance.
     * @returns A new `DatePlus` instance with the same date/time.
     *
     * @example
     * const d1 = new DatePlus("2025-01-01");
     * const d2 = d1.clone();
     * @example
     * d2.add("days", 5); // d1 remains unchanged
     */
    clone(): DatePlus;
    /**
     * Calculates the difference between this date and another date.
     * @param other The other `Date` or `DatePlus` instance to compare against.
     * @param unit Unit to return the difference in (`milliseconds` by default).
     * @returns The difference between the two dates in the specified unit.
     *
     * @example
     * const d1 = new DatePlus("2025-01-01");
     * const d2 = new DatePlus("2025-01-10");
     * console.log(d2.diff(d1, "days")); // 9
     * @example
     * console.log(d2.diff(d1, "milliseconds")); // 777600000
     */
    diff(other: Date | DatePlus, unit?: DateUnit): number;
}
/**
 * Helper function to create a `DatePlus` instance.
 * @param date Optional initial date (`string`, `number`, or `Date`). Defaults to current date/time.
 * @returns A new `DatePlus` instance.
 *
 * @example
 * const d = createDate("2025-01-01");
 * @example
 * const now = createDate(); // current date/time
 */
declare function createDate(date?: string | number | Date): DatePlus;

type ResolveSleepValue<V> = V extends FunctionLike ? ReturnType<V> : V;
declare function baseSleep<V>(time: number, value?: V): Promise<ResolveSleepValue<V>>;
declare const sleep: typeof baseSleep & {
    seconds<V>(time: number, value?: V): Promise<ResolveSleepValue<V>>;
    minutes<V>(time: number, value?: V): Promise<ResolveSleepValue<V>>;
    hours<V>(time: number, value?: V): Promise<ResolveSleepValue<V>>;
};

export { brBuilder, capitalize, createDate, createInterval, createLoopInterval, createTimeout, equalsIgnoreCase, hexToRgb, includesIgnoreCase, isDefined, isEmail, isNumeric, isPromise, isUrl, joinBuilder, limitText, notFound, parseFloatOrDefault, parseIntOrDefault, random, randomNumber, replaceText, rgbToHex, sleep, spaceBuilder, toMs, withProperties, withTimeout };
export type { CanBeString, DatePlus, DateUnit, FunctionLike, Nullable };