qznt 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,952 @@
+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 compact<T>(array: ReadonlyArray<T>, mode?: "nullable"): NonNullable<T>[];
+declare function compact<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 search<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[];
+declare const arr: {
+    chunk: typeof chunk;
+    chunkAdj: typeof chunkAdj;
+    cluster: typeof cluster;
+    compact: typeof compact;
+    forceArray: typeof forceArray;
+    search: typeof search;
+    seqMap: typeof seqMap;
+    shuffle: typeof shuffle;
+    sortBy: typeof sortBy;
+    unique: typeof unique;
+};
+
+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>;
+declare const fn: {
+    memoize: typeof memoize;
+};
+
+interface DateOptions {
+    /** 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;
+}
+interface ParseOptions {
+    /** Return value in seconds instead of milliseconds. */
+    unit?: "ms" | "s";
+    /** If true, returns the absolute Unix timestamp (Date.now() + result). */
+    fromNow?: boolean;
+}
+/**
+ * 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 duration(target: number | Date, style?: "digital" | "hms" | "ymdhms", options?: DateOptions): 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 eta(date: Date | number, locale?: Intl.LocalesArgument): string;
+/**
+ * Parses shorthand strings (1h 30m) into milliseconds or seconds.
+ */
+declare function parse(str: string | number, options?: ParseOptions): number;
+declare const date: {
+    duration: typeof duration;
+    eta: typeof eta;
+    parse: typeof parse;
+};
+
+type AlphaCasing = "lower" | "upper" | "mixed";
+interface RndStrOptions {
+    casing?: AlphaCasing;
+    seed?: number;
+    customChars?: string;
+    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 chance(percent?: number, seed?: number): boolean;
+/**
+ * Returns a random item from the given array.
+ * @param array Array of items to choose from.
+ * @param seed Optional seed for RNG.
+ */
+declare function choice<T>(array: T[], seed?: number): T;
+/**
+ * Returns a random item from the given array based on their corresponding weights.
+ * @param array Array of items to choose from.
+ * @param selector Function that selects the item's weight.
+ * @param seed Optional seed for RNG.
+ */
+declare function weighted<T>(array: T[], selector: (item: T) => number, seed?: number): T;
+/**
+ * Returns an object with a single method, `pick`, which returns a random item from the given array in O(1) time.
+ * 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 selector Function that selects the item's weight.
+ * @param seed Optional seed for RNG.
+ */
+declare function sampler<T>(items: T[], selector: (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 float(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 seed Optional seed for RNG.
+ */
+declare function index(array: any[], seed?: 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 int(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. Can be "number", "alpha", "alphanumeric", or "custom".
+ * @param options Options for the rndStr function.
+ */
+declare function str$1(len: number, mode: "number" | "alpha" | "alphanumeric" | "custom", options?: RndStrOptions): string;
+declare const rnd: {
+    chance: typeof chance;
+    choice: typeof choice;
+    weighted: typeof weighted;
+    sampler: typeof sampler;
+    prng: typeof prng;
+    float: typeof float;
+    index: typeof index;
+    int: typeof int;
+    str: typeof str$1;
+};
+
+interface DebouncedFunction<T extends (...args: any[]) => any> {
+    (...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: any[]) => any>(fn: T, wait: number, options?: {
+    /** Calls the function immediately on the leading edge. */
+    immediate?: boolean;
+}): DebouncedFunction<T>;
+/**
+ * Executes at most once every 'limit' ms.
+ * @param fn The function to throttle.
+ * @param limit The time to wait in milliseconds.
+ * @example
+ * const handleScroll = 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', handleScroll);
+ */
+declare function throttle<T extends (...args: any[]) => any>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * 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>;
+declare const timing: {
+    debounce: typeof debounce;
+    throttle: typeof throttle;
+    wait: typeof wait;
+};
+
+type ToRecordContext<T, V> = {
+    index: number;
+    lastValue: V | undefined;
+    newRecord: Readonly<Record<string | number, V>>;
+    originalArray: ReadonlyArray<T>;
+};
+/**
+ * Transforms an array into a object record with access to the object as it's being built.
+ * @param array Array to process.
+ * @param callback Function to map over the array.
+ */
+declare function record<T, V>(array: ReadonlyArray<T>, callback: (item: T, context: ToRecordContext<T, V>) => {
+    key: string | number;
+    value: V;
+}): Record<string | number, V>;
+declare const to: {
+    record: typeof record;
+};
+
+/**
+ * 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;
+}
+
+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: any];
+}
+declare const TypedEmitterBase: {
+    new <T>(): TypedEmitter<LoopEvents<T>>;
+};
+declare class Loop<T = any> 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>;
+}
+
+/**
+ * Retries an async function with exponential backoff.
+ * @param fn The async function to attempt.
+ * @param retries Maximum number of retry attempts. [default: 3]
+ * @param delay Initial delay in milliseconds. [default: 500ms]
+ */
+declare function retry<T>(fn: () => Promise<T>, retries?: number, delay?: number): Promise<T>;
+declare const async: {
+    retry: typeof retry;
+};
+
+/**
+ * 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 currency(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 number(num: number, options?: {
+    /** The BCP 47 language tag. */
+    locale?: Intl.LocalesArgument;
+    precision?: number;
+}): string;
+declare function memory(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 ordinal(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 compactNumber(num: number, locale?: Intl.LocalesArgument): string;
+declare const format: {
+    currency: typeof currency;
+    number: typeof number;
+    memory: typeof memory;
+    ordinal: typeof ordinal;
+    compactNumber: typeof compactNumber;
+};
+
+/**
+ * Checks if a value is defined (not null or undefined).
+ */
+declare function defined<T>(val: T | undefined | null): val is T;
+/**
+ * Checks if a value is an empty object, array, or string.
+ */
+declare function empty(val: unknown): boolean;
+/**
+ * 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 inRange(num: number, max: number): boolean;
+declare function inRange(num: number, min: number, max: number): boolean;
+/**
+ * Checks if a value is a plain object (not an array, null, or function).
+ */
+declare function object(val: unknown): val is Record<string, any>;
+/**
+ * Checks if an array is sorted.
+ */
+declare function sorted<T>(arr: T[], comparator?: (a: T, b: T) => number): boolean;
+/**
+ * Checks if a value is a string.
+ */
+declare function string(val: unknown): val is string;
+/**
+ * Checks if a date is today.
+ */
+declare function today(date: number | Date): boolean;
+declare const is: {
+    defined: typeof defined;
+    empty: typeof empty;
+    inRange: typeof inRange;
+    object: typeof object;
+    sorted: typeof sorted;
+    string: typeof string;
+    today: typeof today;
+};
+
+/**
+ * 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
+ * invLerp(0, 100, 50); // 0.5
+ */
+declare function invLerp(start: number, end: number, value: 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
+ * lerp(0, 100, 0.5); // 50
+ * lerp(10, 20, 0.2); // 12
+ */
+declare function lerp(start: number, end: number, t: number): number;
+/**
+ * Converts seconds to milliseconds and rounds it to the nearest integer.
+ * @param num The number of seconds to convert.
+ */
+declare function ms(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;
+/**
+ * Converts milliseconds to seconds and rounds it to the nearest integer.
+ * @param num The number of milliseconds to convert.
+ */
+declare function secs(num: 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<T>(array: T[], selector: (item: T) => number, ignoreNaN?: boolean): number;
+declare const math: {
+    invLerp: typeof invLerp;
+    lerp: typeof lerp;
+    ms: typeof ms;
+    percent: typeof percent;
+    remap: typeof remap;
+    secs: typeof secs;
+    sum: typeof sum;
+};
+
+/**
+ * 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 clamp(num: number, max: number): number;
+declare function clamp(num: number, min: number, max: number): number;
+declare const num: {
+    clamp: typeof clamp;
+};
+
+/**
+ * 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 get<T = any>(obj: Record<string, any>, path: string, defaultValue?: T): T;
+/**
+ * Checks if a nested path exists within an object.
+ * @param obj The object to process.
+ * @param path The path string (e.g., 'data.users[0].id').
+ */
+declare function has(obj: Record<string, any>, path: string): boolean;
+/**
+ * Sets a nested property value. 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 set(obj: Record<string, any>, path: string, value: any): 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[]): any;
+/**
+ * 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>;
+declare const obj: {
+    get: typeof get;
+    has: typeof has;
+    set: typeof set;
+    merge: typeof merge;
+    pick: typeof pick;
+    omit: typeof omit;
+};
+
+/**
+ * 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;
+/**
+ * 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;
+declare const str: {
+    escapeRegex: typeof escapeRegex;
+    getFlag: typeof getFlag;
+    hasFlag: typeof hasFlag;
+    toTitleCase: typeof toTitleCase;
+};
+
+declare const $: {
+    Pipe: typeof Pipe;
+    Storage: typeof Storage;
+    Cache: typeof Cache;
+    Loop: typeof Loop;
+    to: {
+        record: <T, V>(array: ReadonlyArray<T>, callback: (item: T, context: ToRecordContext<T, V>) => {
+            key: string | number;
+            value: V;
+        }) => Record<string | number, V>;
+    };
+    str: {
+        escapeRegex: (str: string) => string;
+        getFlag: (str: string, flag: string | RegExp, length?: number) => string | null;
+        hasFlag: (str: string, flag: string | RegExp) => boolean;
+        toTitleCase: (str: string, smart?: boolean) => string;
+    };
+    rnd: {
+        chance: (percent?: number, seed?: number) => boolean;
+        choice: <T>(array: T[], seed?: number) => T;
+        weighted: <T>(array: T[], selector: (item: T) => number, seed?: number) => T;
+        sampler: <T>(items: T[], selector: (item: T) => number, seed?: number) => {
+            pick: (seed?: number) => T | undefined;
+        };
+        prng: (seed: number) => () => number;
+        float: (min: number, max: number, seed?: number) => number;
+        index: (array: any[], seed?: number) => number;
+        int: (min: number, max: number, seed?: number) => number;
+        str: (len: number, mode: "number" | "alpha" | "alphanumeric" | "custom", options?: RndStrOptions) => string;
+    };
+    timing: {
+        debounce: <T extends (...args: any[]) => any>(fn: T, wait: number, options?: {
+            immediate?: boolean;
+        }) => DebouncedFunction<T>;
+        throttle: <T extends (...args: any[]) => any>(fn: T, limit: number) => (...args: Parameters<T>) => void;
+        wait: (ms: number) => Promise<boolean>;
+    };
+    obj: {
+        get: <T = any>(obj: Record<string, any>, path: string, defaultValue?: T) => T;
+        has: (obj: Record<string, any>, path: string) => boolean;
+        set: (obj: Record<string, any>, path: string, value: any) => void;
+        merge: {
+            <T, S1>(target: T, s1: S1): T & S1;
+            <T, S1, S2>(target: T, s1: S1, s2: S2): T & S1 & S2;
+            <T, S1, S2, S3>(target: T, s1: S1, s2: S2, s3: S3): T & S1 & S2 & S3;
+            (target: any, ...sources: any[]): any;
+        };
+        pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+        omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+    };
+    num: {
+        clamp: {
+            (num: number, max: number): number;
+            (num: number, min: number, max: number): number;
+        };
+    };
+    math: {
+        invLerp: (start: number, end: number, value: number) => number;
+        lerp: (start: number, end: number, t: number) => number;
+        ms: (num: number) => number;
+        percent: (a: number, b: number, round?: boolean) => number;
+        remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number;
+        secs: (num: number) => number;
+        sum: <T>(array: T[], selector: (item: T) => number, ignoreNaN?: boolean) => number;
+    };
+    is: {
+        defined: <T>(val: T | undefined | null) => val is T;
+        empty: (val: unknown) => boolean;
+        inRange: {
+            (num: number, max: number): boolean;
+            (num: number, min: number, max: number): boolean;
+        };
+        object: (val: unknown) => val is Record<string, any>;
+        sorted: <T>(arr: T[], comparator?: (a: T, b: T) => number) => boolean;
+        string: (val: unknown) => val is string;
+        today: (date: number | Date) => boolean;
+    };
+    format: {
+        currency: (num: number, options?: {
+            currency?: string;
+            locale?: Intl.LocalesArgument;
+        }) => string;
+        number: (num: number, options?: {
+            locale?: Intl.LocalesArgument;
+            precision?: number;
+        }) => string;
+        memory: (bytes: number, decimals?: number, units?: string[]) => string;
+        ordinal: (num: number | string, locale?: Intl.LocalesArgument) => string;
+        compactNumber: (num: number, locale?: Intl.LocalesArgument) => string;
+    };
+    date: {
+        duration: (target: number | Date, style?: "digital" | "hms" | "ymdhms", options?: DateOptions) => string | null;
+        eta: (date: Date | number, locale?: Intl.LocalesArgument) => string;
+        parse: (str: string | number, options?: ParseOptions) => number;
+    };
+    fn: {
+        memoize: <T extends (...args: any[]) => any>(fn: T, options?: {
+            resolver?: (...args: Parameters<T>) => string;
+            maxAge?: number;
+        }) => MemoizedFunction<T>;
+    };
+    async: {
+        retry: <T>(fn: () => Promise<T>, retries?: number, delay?: number) => Promise<T>;
+    };
+    arr: {
+        chunk: <T>(array: ReadonlyArray<T>, size: number) => T[][];
+        chunkAdj: <T>(array: ReadonlyArray<T>, predicate: (prev: T, curr: T) => boolean) => T[][];
+        cluster: <T>(array: ReadonlyArray<T>, iteratee: (item: T) => string | number, maxChunkSize?: number) => T[][];
+        compact: {
+            <T>(array: ReadonlyArray<T>, mode?: "nullable"): NonNullable<T>[];
+            <T>(array: ReadonlyArray<T>, mode: "falsy"): Exclude<T, null | undefined | false | 0 | "">[];
+        };
+        forceArray: <T>(item: T) => T[];
+        search: <T>(array: T[], target: T, comparator?: (a: T, b: T) => number) => number;
+        seqMap: <T, U>(array: ReadonlyArray<T>, callback: (item: T, context: SequentialMapContext<T, U>) => U) => U[];
+        shuffle: <T>(array: ReadonlyArray<T>, seed?: number) => T[];
+        sortBy: {
+            <T>(array: ReadonlyArray<T>, selector: (item: T) => any, order?: "asc" | "desc"): T[];
+            <T>(array: ReadonlyArray<T>, selectors: (item: T) => any[], order?: "asc" | "desc"): T[];
+        };
+        unique: <T>(array: T[], key: (item: T) => any) => T[];
+    };
+};
+declare const qznt: {
+    Pipe: typeof Pipe;
+    Storage: typeof Storage;
+    Cache: typeof Cache;
+    Loop: typeof Loop;
+    to: {
+        record: <T, V>(array: ReadonlyArray<T>, callback: (item: T, context: ToRecordContext<T, V>) => {
+            key: string | number;
+            value: V;
+        }) => Record<string | number, V>;
+    };
+    str: {
+        escapeRegex: (str: string) => string;
+        getFlag: (str: string, flag: string | RegExp, length?: number) => string | null;
+        hasFlag: (str: string, flag: string | RegExp) => boolean;
+        toTitleCase: (str: string, smart?: boolean) => string;
+    };
+    rnd: {
+        chance: (percent?: number, seed?: number) => boolean;
+        choice: <T>(array: T[], seed?: number) => T;
+        weighted: <T>(array: T[], selector: (item: T) => number, seed?: number) => T;
+        sampler: <T>(items: T[], selector: (item: T) => number, seed?: number) => {
+            pick: (seed?: number) => T | undefined;
+        };
+        prng: (seed: number) => () => number;
+        float: (min: number, max: number, seed?: number) => number;
+        index: (array: any[], seed?: number) => number;
+        int: (min: number, max: number, seed?: number) => number;
+        str: (len: number, mode: "number" | "alpha" | "alphanumeric" | "custom", options?: RndStrOptions) => string;
+    };
+    timing: {
+        debounce: <T extends (...args: any[]) => any>(fn: T, wait: number, options?: {
+            immediate?: boolean;
+        }) => DebouncedFunction<T>;
+        throttle: <T extends (...args: any[]) => any>(fn: T, limit: number) => (...args: Parameters<T>) => void;
+        wait: (ms: number) => Promise<boolean>;
+    };
+    obj: {
+        get: <T = any>(obj: Record<string, any>, path: string, defaultValue?: T) => T;
+        has: (obj: Record<string, any>, path: string) => boolean;
+        set: (obj: Record<string, any>, path: string, value: any) => void;
+        merge: {
+            <T, S1>(target: T, s1: S1): T & S1;
+            <T, S1, S2>(target: T, s1: S1, s2: S2): T & S1 & S2;
+            <T, S1, S2, S3>(target: T, s1: S1, s2: S2, s3: S3): T & S1 & S2 & S3;
+            (target: any, ...sources: any[]): any;
+        };
+        pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+        omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+    };
+    num: {
+        clamp: {
+            (num: number, max: number): number;
+            (num: number, min: number, max: number): number;
+        };
+    };
+    math: {
+        invLerp: (start: number, end: number, value: number) => number;
+        lerp: (start: number, end: number, t: number) => number;
+        ms: (num: number) => number;
+        percent: (a: number, b: number, round?: boolean) => number;
+        remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number;
+        secs: (num: number) => number;
+        sum: <T>(array: T[], selector: (item: T) => number, ignoreNaN?: boolean) => number;
+    };
+    is: {
+        defined: <T>(val: T | undefined | null) => val is T;
+        empty: (val: unknown) => boolean;
+        inRange: {
+            (num: number, max: number): boolean;
+            (num: number, min: number, max: number): boolean;
+        };
+        object: (val: unknown) => val is Record<string, any>;
+        sorted: <T>(arr: T[], comparator?: (a: T, b: T) => number) => boolean;
+        string: (val: unknown) => val is string;
+        today: (date: number | Date) => boolean;
+    };
+    format: {
+        currency: (num: number, options?: {
+            currency?: string;
+            locale?: Intl.LocalesArgument;
+        }) => string;
+        number: (num: number, options?: {
+            locale?: Intl.LocalesArgument;
+            precision?: number;
+        }) => string;
+        memory: (bytes: number, decimals?: number, units?: string[]) => string;
+        ordinal: (num: number | string, locale?: Intl.LocalesArgument) => string;
+        compactNumber: (num: number, locale?: Intl.LocalesArgument) => string;
+    };
+    date: {
+        duration: (target: number | Date, style?: "digital" | "hms" | "ymdhms", options?: DateOptions) => string | null;
+        eta: (date: Date | number, locale?: Intl.LocalesArgument) => string;
+        parse: (str: string | number, options?: ParseOptions) => number;
+    };
+    fn: {
+        memoize: <T extends (...args: any[]) => any>(fn: T, options?: {
+            resolver?: (...args: Parameters<T>) => string;
+            maxAge?: number;
+        }) => MemoizedFunction<T>;
+    };
+    async: {
+        retry: <T>(fn: () => Promise<T>, retries?: number, delay?: number) => Promise<T>;
+    };
+    arr: {
+        chunk: <T>(array: ReadonlyArray<T>, size: number) => T[][];
+        chunkAdj: <T>(array: ReadonlyArray<T>, predicate: (prev: T, curr: T) => boolean) => T[][];
+        cluster: <T>(array: ReadonlyArray<T>, iteratee: (item: T) => string | number, maxChunkSize?: number) => T[][];
+        compact: {
+            <T>(array: ReadonlyArray<T>, mode?: "nullable"): NonNullable<T>[];
+            <T>(array: ReadonlyArray<T>, mode: "falsy"): Exclude<T, null | undefined | false | 0 | "">[];
+        };
+        forceArray: <T>(item: T) => T[];
+        search: <T>(array: T[], target: T, comparator?: (a: T, b: T) => number) => number;
+        seqMap: <T, U>(array: ReadonlyArray<T>, callback: (item: T, context: SequentialMapContext<T, U>) => U) => U[];
+        shuffle: <T>(array: ReadonlyArray<T>, seed?: number) => T[];
+        sortBy: {
+            <T>(array: ReadonlyArray<T>, selector: (item: T) => any, order?: "asc" | "desc"): T[];
+            <T>(array: ReadonlyArray<T>, selectors: (item: T) => any[], order?: "asc" | "desc"): T[];
+        };
+        unique: <T>(array: T[], key: (item: T) => any) => T[];
+    };
+};
+
+export { type AlphaCasing, type AnyFunc, Cache, type DateOptions, type DebouncedFunction, type DeepPartial, Loop, type MemoizedFunction, type ParseOptions, Pipe, type RndStrOptions, type SequentialMapContext, Storage, type ToRecordContext, type TypedEmitter, arr, async, date, $ as default, fn, format, is, math, num, obj, qznt, rnd, str, timing, to };