qznt 1.0.36 → 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,670 @@
+declare class Cache<T> {
+    private cache;
+    private interval;
+    /**
+     * A lightweight, high-performant in-memory cache.
+     * Uses Map for O(1) lookups and an optional cleanup interval.
+     * @param cleanupMs The interval in milliseconds to run the cleanup function. [default: 60000 (1 minute)]
+     */
+    constructor(cleanupMs?: number);
+    set(key: string | number, value: T, ttlMs?: number): void;
+    get(key: string | number): T | null;
+    private cleanup;
+    clear(): void;
+}
+
+type AnyFunc = (...args: any) => any;
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+type TypedEmitter<TEvents extends Record<string, any>> = {
+    on<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): any;
+    once<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): any;
+    off<K extends keyof TEvents>(event: K, listener: (...args: TEvents[K]) => void): any;
+    emit<K extends keyof TEvents>(event: K, ...args: TEvents[K]): boolean;
+};
+
+type LoopState = "running" | "paused" | "stopped";
+interface LoopEvents<T> {
+    start: [];
+    tick: [result: T];
+    pause: [{
+        remaining: number;
+    }];
+    resume: [];
+    stop: [];
+    error: [error: unknown];
+}
+declare const TypedEmitterBase: {
+    new <T>(): TypedEmitter<LoopEvents<T>>;
+};
+declare class Loop<T = unknown> extends TypedEmitterBase<T> {
+    private _state;
+    private timeoutId;
+    private delay;
+    private fn;
+    private startTime;
+    private remaining;
+    private run;
+    private clearTimer;
+    /**
+     * Creates an interval. If the function is async, it will wait for it to complete before scheduling the next run.
+     * @param fn The function to run.
+     * @param delay The delay between runs in milliseconds.
+     * @param immediate Whether to start the loop immediately. [default: true]
+     */
+    constructor(fn: (loop: Loop<T>) => Promise<T> | T, delay: number, immediate?: boolean);
+    get state(): LoopState;
+    /** Starts the loop. */
+    start(): void;
+    /** Resumes a paused loop. */
+    resume(): void;
+    /** Stops the loop. */
+    stop(): void;
+    /** Pauses the execution. */
+    pause(): void;
+    /**
+     * Sets the delay between runs
+     * @param ms The new delay in milliseconds.
+     */
+    setDelay(ms: number): void;
+    /** Manually trigger the function once without affecting the loop. */
+    execute(): Promise<void>;
+}
+
+/**
+ * Pipes a value through a series of functions.
+ * Each function takes the output of the previous one.
+ */
+declare function Pipe<A>(value: A): A;
+declare function Pipe<A, B>(value: A, fn1: (arg: A) => B): B;
+declare function Pipe<A, B, C>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C): C;
+declare function Pipe<A, B, C, D>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D): D;
+declare function Pipe<A, B, C, D, E>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E): E;
+declare function Pipe<A, B, C, D, E, F>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F): F;
+declare function Pipe<A, B, C, D, E, F, G>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G): G;
+declare function Pipe<A, B, C, D, E, F, G, H>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H): H;
+declare function Pipe<A, B, C, D, E, F, G, H, I>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I): I;
+declare function Pipe<A, B, C, D, E, F, G, H, I, J>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I, fn9: (arg: I) => J): J;
+declare function Pipe<A, B, C, D, E, F, G, H, I, J, K>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I, fn9: (arg: I) => J, fn10: (arg: J) => K): K;
+
+declare class Storage {
+    private isNode;
+    private filePath;
+    private memoryCache;
+    private loadFromFile;
+    private persist;
+    /**
+     * A lightweight, high-performant persistent storage system.
+     * Uses JSON files in Node.js, localStorage in the browser
+     * @param fileName Only used in Node.js to create a persistent .json file
+     * @param directory The directory for the file. Defaults to current working directory
+     */
+    constructor(fileName?: string, directory?: string);
+    has(key: string): boolean;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttl?: number): void;
+    remove(key: string): void;
+    clear(): void;
+}
+
+type SequentialMapContext<T, U> = {
+    index: number;
+    lastElement: U | undefined;
+    newArray: ReadonlyArray<U>;
+    originalArray: ReadonlyArray<T>;
+};
+/**
+ * Splits an array into sub-arrays (chunks) of a maximum size.
+ * @param array Array to process
+ * @param size The maximum size of each chunk
+ */
+declare function chunk<T>(array: ReadonlyArray<T>, size: number): T[][];
+/**
+ * Groups adjacent elements of an array together based on a predicate.
+ * @param array Array to process
+ * @param predicate A function that returns true if two adjacent elements belong in the same chunk
+ * @example
+ * // Group consecutive identical numbers
+ * chunkBy([1, 1, 2, 3, 3, 3], (a, b) => a === b);
+ * // [[1, 1], [2], [3, 3, 3]]
+ */
+declare function chunkAdj<T>(array: ReadonlyArray<T>, predicate: (prev: T, curr: T) => boolean): T[][];
+/**
+ * Groups elements by a key.
+ * @param array Array to process
+ * @param iteratee Function to determine the key to group by
+ * @param maxChunkSize Optionally chunk groups and flatten them (useful for pagination)
+ */
+declare function cluster<T>(array: ReadonlyArray<T>, iteratee: (item: T) => string | number, maxChunkSize?: number): T[][];
+/**
+ * Removes unwanted values from an array.
+ * @param array Array to process
+ * @param mode 'nullable' (default) removes null/undefined. 'falsy' removes null, undefined, 0, "", false, and NaN
+ */
+declare function compactArray<T>(array: ReadonlyArray<T>, mode?: "nullable"): NonNullable<T>[];
+declare function compactArray<T>(array: ReadonlyArray<T>, mode: "falsy"): Exclude<T, null | undefined | false | 0 | "">[];
+/**
+ * Forces a given item to be an array.
+ * @param item The item to force into an array.
+ */
+declare function forceArray<T>(item: T): T[];
+/**
+ * Searches a sorted array for a value using the binary search method.
+ * Returns the index if found, or the bitwise complement (~index) of the
+ * position where the value should be inserted to keep it sorted.
+ * @param array The array to process
+ * @param target The value to search for
+ * @param comparator Optional comparator function
+ */
+declare function searchSorted<T>(array: T[], target: T, comparator?: (a: T, b: T) => number): number;
+/**
+ * Maps over an array with access to the previously mapped elements.
+ * @param array Array to process
+ * @param callback Function to map over the array
+ */
+declare function seqMap<T, U>(array: ReadonlyArray<T>, callback: (item: T, context: SequentialMapContext<T, U>) => U): U[];
+/**
+ * Shuffles an array using the Fisher-Yates algorithm.
+ * @param array The array to shuffle
+ * @param seed Optional seed for RNG
+ */
+declare function shuffle<T>(array: ReadonlyArray<T>, seed?: number): T[];
+/**
+ * Sorts an array by a single property in order.
+ * @param order 'asc' for ascending (default) or 'desc' for descending
+ * @param array Array to process
+ * @param selector Function to determine the key to sort by
+ */
+declare function sortBy<T>(array: ReadonlyArray<T>, selector: (item: T) => any, order?: "asc" | "desc"): T[];
+/**
+ * Sorts an array by one or more properties in order.
+ * @param order 'asc' for ascending (default) or 'desc' for descending
+ * @param array Array to process
+ * @param selectors Functions to determine the keys to sort by
+ */
+declare function sortBy<T>(array: ReadonlyArray<T>, selectors: (item: T) => any[], order?: "asc" | "desc"): T[];
+/**
+ * Returns an array of unique elements from the given array.
+ * Uniqueness is determined by the given key function.
+ * @param array Array to process
+ * @param key Function to determine the keys to filter by
+ */
+declare function unique<T>(array: T[], key: (item: T) => any): T[];
+
+interface RetryOptions {
+    /** Maximum number of retry attempts. @default 3 */
+    attempts?: number;
+    /** Base retry delay in milliseconds. @default 500 */
+    delay?: number;
+    /** Timeout in milliseconds for each attempt. */
+    timeout?: number;
+    /** An AbortSignal to cancel the entire operation. */
+    signal?: AbortSignal;
+}
+/**
+ * Retries an async function until the maximum number of attempts is reached.
+ *
+ * Implements exponential backoff with random jitter.
+ * @param fn The asynchronous function to attempt
+ * @param options Options for the retry function
+ */
+declare function retryPromise<T>(fn: (signal?: AbortSignal) => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Returns a promise that resolves after the given number of milliseconds.
+ * @param ms The time to wait in milliseconds
+ */
+declare function wait(ms: number): Promise<boolean>;
+
+interface ParseTimeOptions {
+    /** Return value in seconds instead of milliseconds. */
+    unit?: "ms" | "s";
+    /** If true, returns the absolute Unix timestamp (Date.now() + result). */
+    fromNow?: boolean;
+}
+/**
+ * Calculates the age of a person based on their birthdate.
+ * @param birthdate The birthdate of the person
+ */
+declare function getAge(birthdate: Date): number;
+/**
+ * Parses shorthand strings (1h 30m) into milliseconds or seconds.
+ * @param str The string to parse
+ * @param options Parsing options
+ */
+declare function parseTime(str: string | number, options?: ParseTimeOptions): number;
+
+interface DebouncedFunction<T extends (...args: unknown[]) => unknown> {
+    (...args: Parameters<T>): void;
+    /** Cancels the debounced function. */
+    cancel: () => void;
+}
+/**
+ * Only executes after 'wait' ms have passed since the last call.
+ * @param fn The function to debounce
+ * @param wait The time to wait in milliseconds
+ * @param options Options for the debounce function
+ * @example
+ * const search = debounce((str) => console.log("Searching:", str), 500);
+ * // Even if called rapidly, it only logs once 500ms after the last call.
+ * search('a');
+ * search('ab');
+ * search('abc'); // Only 'abc' will be logged.
+ * // Cancel a pending execution
+ * search.cancel();
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, wait: number, options?: {
+    /** Calls the function immediately on the leading edge */
+    immediate?: boolean;
+}): DebouncedFunction<T>;
+/**
+ * Limits how often a function can be executed.
+ * @param fn The function to throttle
+ * @param limit The time to wait in milliseconds
+ * @example
+ * const logScroll = throttle(() => console.log('Scroll position:', window.scrollY), 200);
+ * // Even if the browser fires 100 scroll events per second,
+ * // this function will only execute once every 200ms.
+ * window.addEventListener('scroll', logScroll);
+ */
+declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
+
+interface MemoizedFunction<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): ReturnType<T>;
+    /** Clears the cache. */
+    clear: () => void;
+}
+/**
+ * Memoizes a function by caching its results based on the input arguments.
+ * A resolver function can be provided to customize the key generation.
+ * If no resolver is provided, the key will be generated by JSON stringify-ing the input arguments.
+ * @param fn The function to memoize
+ * @param resolver An optional resolver function to customize the key generation
+ * @example
+ * // 1. Basic usage
+ * const heavyCalc = memoize((n: number) => {
+ *     console.log('Calculating...');
+ *     return n * 2;
+ * });
+ * heavyCalc(5); // Logs 'Calculating...' and returns 10
+ * heavyCalc(5); // Returns 10 immediately from cache
+ * @example
+ * // 2. Using maxAge (TTL)
+ * const getStockPrice = memoize(fetchPrice, { maxAge: 60000 }); // 1 minute cache
+ * @example
+ * // 3. Using a custom resolver
+ * const getUser = memoize(
+ *     (user, theme) => render(user, theme),
+ *     { resolver: (user) => user.id } // Only cache based on ID, ignore theme
+ * );
+ * @example
+ * // 4. Manual cache clearing
+ * heavyCalc.clear();
+ */
+declare function memoize<T extends (...args: any[]) => any>(fn: T, options?: {
+    /** Function to generate a cache key from the input arguments. */
+    resolver?: (...args: Parameters<T>) => string;
+    /** The time to wait in milliseconds before expiring a cache entry. */
+    maxAge?: number;
+}): MemoizedFunction<T>;
+
+interface FormatDurationOptions {
+    /** The reference timestamp to calculate from. Defaults to Date.now() */
+    since?: number | Date;
+    /** If true, returns null if the target time is in the past. */
+    nullIfPast?: boolean;
+    /** If true, omits the " ago" suffix for past dates. */
+    ignorePast?: boolean;
+}
+/**
+ * Formats a number as a currency string using international standards.
+ * @param num - The number to process
+ * @param options - Formatting options
+ * @example
+ * currency(1234.5); // "$1,234.50"
+ * currency(1234.5, 'EUR', 'de-DE'); // "1.234,50 €"
+ * currency(500, 'JPY'); // "¥500" (Yen has no decimals)
+ */
+declare function formatCurrency(num: number, options?: {
+    /** The ISO currency code (e.g., 'USD', 'EUR', 'GBP'). */
+    currency?: string;
+    /** The BCP 47 language tag. */
+    locale?: Intl.LocalesArgument;
+}): string;
+/**
+ * Formats a number with thousands separators and optional decimal precision.
+ * @param num - The number to process
+ * @param options - Formatting options
+ * @example
+ * num(1000000); // "1,000,000" (en-US default)
+ * num(1000, { locale: 'de-DE' }); // "1.000"
+ * num(1234.567, { precision: 2 }); // "1,234.57"
+ */
+declare function formatNumber(num: number, options?: {
+    /** The BCP 47 language tag. */
+    locale?: Intl.LocalesArgument;
+    precision?: number;
+}): string;
+declare function formatMemory(bytes: number, decimals?: number, units?: string[]): string;
+/**
+ * Formats a number to an ordinal (e.g., 1st, 2nd, 3rd).
+ * @param num The number to process
+ * @param locale The BCP 47 language tag
+ */
+declare function formatOrdinal(num: number | string, locale?: Intl.LocalesArgument): string;
+/**
+ * Formats a number into a compact, human-readable string (e.g., 1.2k, 1M).
+ * @param num - The number to process
+ * @param locale - The BCP 47 language tag
+ */
+declare function FormatNumberCompact(num: number, locale?: Intl.LocalesArgument): string;
+/**
+ * Duration formatter.
+ *
+ * Available styles:
+ * - Digital (00:00)
+ * - HMS
+ * - YMDHMS.
+ * @param target The target time to calculate from
+ * @param style The output style to use
+ * @param options Formatting options
+ */
+declare function formatDuration(target: number | Date, style?: "digital" | "hms" | "ymdhms", options?: FormatDurationOptions): string | null;
+/**
+ * Formats a date or timestamp into a human-readable relative string (e.g., "3 days ago").
+ * @param date - The Date object or timestamp to compare
+ * @param locale - The BCP 47 language tag
+ */
+declare function formatETA(date: Date | number, locale?: Intl.LocalesArgument): string;
+
+interface ReadDirOptions {
+    /** Whether to scan subdirectories [default: true] */
+    recursive?: boolean;
+}
+/**
+ * Recursively (or shallowly) scans a directory and returns an array of relative file paths.
+ * @param path The path to the directory
+ * @param options Options for the readDir function
+ */
+declare function readDir(path: string, options?: ReadDirOptions): string[];
+
+/**
+ * Checks if a value is defined (not null or undefined).
+ * @param val The value to check
+ */
+declare function isDefined<T>(val: T | undefined | null): val is T;
+/**
+ * Checks if a value is an empty object, array, or string.
+ * @param val The value to check
+ */
+declare function isEmpty(val: unknown): boolean;
+/**
+ * Checks if a value is a plain object (not an array, null, or function).
+ * @param val The value to check
+ */
+declare function isObject(val: unknown): val is Record<string, any>;
+/**
+ * Checks if a value is a string.
+ * @param val The value to check
+ */
+declare function isString(val: unknown): val is string;
+/**
+ * Checks if a number is within a specified range.
+ * @param num The number to check
+ * @param min The minimum or maximum value of the range
+ * @param max The maximum value of the range (optional)
+ */
+declare function isInRange(num: number, max: number): boolean;
+declare function isInRange(num: number, min: number, max: number): boolean;
+/**
+ * Checks if an array is sorted.
+ * @param arr The array to check
+ * @param comparator Optional comparator function
+ */
+declare function isSortedArray<T>(arr: T[], comparator?: (a: T, b: T) => number): boolean;
+/**
+ * Checks if a date is today.
+ * @param date The date to check
+ */
+declare function isToday(date: number | Date): boolean;
+
+/**
+ * Clamps a number within a specified range.
+ * @param num The number to check
+ * @param min The minimum or maximum value of the range
+ * @param max The maximum value of the range (optional)
+ */
+declare function clampNumber(num: number, max: number): number;
+declare function clampNumber(num: number, min: number, max: number): number;
+/**
+ * Linearly interpolates between two values.
+ * @param start - The starting value (0%)
+ * @param end - The ending value (100%)
+ * @param t - The interpolation factor (0 to 1)
+ * @example
+ * lerpLinear(0, 100, 0.5); // 50
+ * lerpLinear(10, 20, 0.2); // 12
+ */
+declare function lerp(start: number, end: number, t: number): number;
+/**
+ * Calculates the interpolation factor (0-1) of a value between two points.
+ * @param start - The starting value (0%)
+ * @param end - The ending value (100%)
+ * @param value - The value to interpolate
+ * @example
+ * inverseLerp(0, 100, 50); // 0.5
+ */
+declare function inverseLerp(start: number, end: number, value: number): number;
+/**
+ * Converts milliseconds to seconds and rounds it to the nearest integer.
+ * @param num The number of milliseconds to convert
+ */
+declare function msToSecs(num: number): number;
+/**
+ * Converts seconds to milliseconds and rounds it to the nearest integer.
+ * @param num The number of seconds to convert
+ */
+declare function secsToMs(num: number): number;
+/**
+ * Calculates the percentage value between two numbers.
+ * @param a The numerator
+ * @param b The denominator
+ * @param round Whether to round the result to the nearest integer
+ * @example
+ * percent(50, 100) --> 50 // 50%
+ * percent(30, 40) --> 75 // 75%
+ */
+declare function percent(a: number, b: number, round?: boolean): number;
+/**
+ * Maps a value from one range to another.
+ * @param value - The value to map
+ * @param inMin - The minimum value of the input range
+ * @param inMax - The maximum value of the input range
+ * @param outMin - The minimum value of the output range
+ * @param outMax - The maximum value of the output range
+ * @example
+ * // Convert mouse X position (0-1920) to a volume level (0-1)
+ * const volume = remap(mouseX, 0, 1920, 0, 1);
+ */
+declare function remap(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
+/**
+ * Returns the sum of an array of numbers. Negative values subtract from the total.
+ * @param array The array to sum
+ * @param selector Function that selects the item's weight
+ * @param ignoreNaN If true, NaN values will not throw an error
+ */
+declare function sum(array: number[], selector?: (item: unknown) => number): number;
+/**
+ * Wraps a number into a modular range.
+ * @param num The value to wrap
+ * @param max The upper bound
+ * @example
+ * ```ts
+ * wrap(12, 10); // 2 (overflow)
+ * wrap(-1, 10); // 9 (max - 1)
+ * ```
+ */
+declare function wrap(num: number, max: number): number;
+
+/**
+ * Retrieves a nested property.
+ * @param obj The object to process
+ * @param path The path to retrieve (e.g., 'data.users[0].id')
+ * @param defaultValue The default value to return if the property does not exist
+ */
+declare function getProp<T = unknown>(obj: Record<string, unknown>, path: string, defaultValue?: T): T;
+/**
+ * Checks if a nested path exists within an object.
+ * @param obj The object to process
+ * @param path The path to check (e.g., 'data.users[0].id')
+ */
+declare function hasProp(obj: Record<string, unknown>, path: string): boolean;
+/**
+ * Sets a nested property value. Recursively creates missing objects/arrays along the path.
+ * @param obj The object to process
+ * @param path The path to set (e.g., 'data.users[0].id')
+ * @param value The value to inject
+ */
+declare function setProp(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Deep merges multiple objects.
+ * @param target - The base object to merge into
+ * @param sources - One or more objects to merge
+ */
+declare function merge<T, S1>(target: T, s1: S1): T & S1;
+declare function merge<T, S1, S2>(target: T, s1: S1, s2: S2): T & S1 & S2;
+declare function merge<T, S1, S2, S3>(target: T, s1: S1, s2: S2, s3: S3): T & S1 & S2 & S3;
+declare function merge(target: any, ...sources: any[]): unknown;
+/**
+ * Creates an object composed of the picked object properties.
+ * @param obj The object to process
+ * @param keys The keys to pick from the object
+ */
+declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * Creates an object composed of the omitted object properties.
+ * @param obj The object to process
+ * @param keys The keys to omit from the object
+ */
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+
+type AlphaCasing = "lower" | "upper" | "mixed";
+interface RndArrayOptions<T> {
+    /** Optional seed for RNG */
+    seed?: number;
+    /** Reroll if the result is equal to this value */
+    not?: ((item: T) => boolean) | (T | null | undefined);
+    /** Maximum number of times to reroll if `not` is specified [default: 10] */
+    maxRerolls?: number;
+}
+interface RndStrOptions {
+    /** Optional seed for RNG */
+    seed?: number;
+    /** Character casing mode */
+    casing?: AlphaCasing;
+    /** Custom character pool */
+    customChars?: string;
+    /** Characters to exclude from the pool */
+    exclude?: string | string[];
+}
+/**
+ * Returns true based on a percentage probability.
+ * @param percent A value between 0 and 1 [default: 0.5]
+ * @param seed Optional seed for RNG
+ */
+declare function rndChance(percent?: number, seed?: number): boolean;
+/**
+ * Returns a random item from the given array.
+ * @param array Array of items to choose from
+ * @param options Options for the choice function
+ */
+declare function rndChoice<T>(array: T[], options?: RndArrayOptions<T>): T;
+/**
+ * Returns a random item from the given array based on their corresponding weights.
+ * @param array Array of items to choose from
+ * @param predicate Predicate that selects the item's weight
+ * @param seed Optional seed for RNG
+ */
+declare function weightedRnd<T>(array: T[], predicate: (item: T) => number, seed?: number): T;
+/**
+ * Creates an O(1) sampler for weighted random selection.
+ * The probability of each item being picked is determined by the corresponding weight in the `weights` array.
+ * @param items Array of items to choose from
+ * @param predicate Predicate that selects the item's weight
+ * @param seed Optional seed for RNG
+ */
+declare function createSampler<T>(items: T[], predicate: (item: T) => number, seed?: number): {
+    /**
+     * Returns a random item from the given array in O(1) time
+     * @param seed Optional seed for RNG
+     */
+    pick: (seed?: number) => T | undefined;
+};
+/**
+ * Creates a deterministic pseudo-random number generator (PRNG) using the Mulberry32 algorithm.
+ * @param seed An integer seed value
+ * @example
+ * const rng = prng(123);
+ * const val1 = rng(); // Always the same for seed 123
+ */
+declare function prng(seed: number): () => number;
+/**
+ * Generates a random float between the given minimum and maximum values.
+ * @param min The minimum value (inclusive) for the random float
+ * @param max The maximum value (inclusive) for the random float
+ * @param seed Optional seed for RNG
+ */
+declare function rndFloat(min: number, max: number, seed?: number): number;
+/**
+ * Returns a random index from the given array.
+ * @param array The array to generate an index for
+ * @param options Options for the index function
+ */
+declare function rndIndex<T>(array: T[], options?: RndArrayOptions<number>): number;
+/**
+ * Generates a random integer between the given minimum and maximum values.
+ * @param min The minimum value (inclusive) for the random integer
+ * @param max The maximum value (inclusive) for the random integer
+ * @param seed Optional seed for RNG
+ */
+declare function rndInt(min: number, max: number, seed?: number): number;
+/**
+ * Generates a random string of the given length using the specified character pool.
+ * @param len The length of the random string
+ * @param mode The character pool to use
+ * @param options Options for the rndStr function
+ */
+declare function rndString(len: number, mode: "number" | "alpha" | "alphanumeric" | "custom", options?: RndStrOptions): string;
+
+/**
+ * Escapes regex characters in the given string.
+ * @param str The string to process
+ */
+declare function escapeRegex(str: string): string;
+/**
+ * Retrieves a substring following a specific flag.
+ * @param str The string to process
+ * @param flag A string or regex to look for
+ */
+declare function getFlag(str: string, flag: string | RegExp, length?: number): string | null;
+/**
+ * Checks if a string contains a specific flag.
+ * @param str The string to process
+ * @param flag A string or regex to look for
+ */
+declare function hasFlag(str: string, flag: string | RegExp): boolean;
+/**
+ * Returns the singular or plural form based on the given count.
+ * @param count The amount to compare against 1
+ * @param singular The word to use when count is exactly 1
+ * @param plural The word to use otherwise [default: `${singular}s`]
+ */
+declare function pluralize(count: number, singular: string, plural?: string): string;
+/**
+ * Formats a string to Title Case, optionally keeping acronyms and skipping minor words (the, and, of, etc.).
+ * @param str The string to process
+ * @param smart If true, will keep acronyms and skip minor words [default: true]
+ */
+declare function toTitleCase(str: string, smart?: boolean): string;
+
+export { type AlphaCasing, type AnyFunc, Cache, type DebouncedFunction, type DeepPartial, type FormatDurationOptions, FormatNumberCompact, Loop, type LoopEvents, type MemoizedFunction, type ParseTimeOptions, Pipe, type ReadDirOptions, type RetryOptions, type RndArrayOptions, type RndStrOptions, type SequentialMapContext, Storage, type TypedEmitter, chunk, chunkAdj, clampNumber, cluster, compactArray, createSampler, debounce, escapeRegex, forceArray, formatCurrency, formatDuration, formatETA, formatMemory, formatNumber, formatOrdinal, getAge, getFlag, getProp, hasFlag, hasProp, inverseLerp, isDefined, isEmpty, isInRange, isObject, isSortedArray, isString, isToday, lerp, memoize, merge, msToSecs, omit, parseTime, percent, pick, pluralize, prng, readDir, remap, retryPromise, rndChance, rndChoice, rndFloat, rndIndex, rndInt, rndString, searchSorted, secsToMs, seqMap, setProp, shuffle, sortBy, sum, throttle, toTitleCase, unique, wait, weightedRnd, wrap };