/**
 * Function-focused utility helpers.
 *
 * @module bquery/core/utils/function
 */
/** Options for the enhanced {@link debounce} signature. */
export interface DebounceOptions {
    /** Invoke on the leading edge of the timeout (default: false). */
    leading?: boolean;
    /** Invoke on the trailing edge of the timeout (default: true). */
    trailing?: boolean;
    /** Maximum time `fn` may be delayed before being forced to run. */
    maxWait?: number;
}
/** A debounced function with `cancel()` and `flush()` controls. */
export interface DebouncedFn<TArgs extends unknown[]> {
    (...args: TArgs): void;
    /** Cancels the pending debounced invocation. */
    cancel(): void;
    /**
     * Immediately invokes any pending call with the most recent arguments,
     * if a trailing call is scheduled. No-op when nothing is pending.
     */
    flush(): void;
}
/** Options for the enhanced {@link throttle} signature. */
export interface ThrottleOptions {
    /** Invoke on the leading edge of the interval (default: true). */
    leading?: boolean;
    /** Invoke on the trailing edge of the interval (default: false). */
    trailing?: boolean;
}
/** A throttled function with `cancel()` and `flush()` controls. */
export interface ThrottledFn<TArgs extends unknown[]> {
    (...args: TArgs): void;
    /** Resets the throttle timer, allowing the next call to execute immediately. */
    cancel(): void;
    /** Immediately invokes any pending trailing call with the most recent arguments. */
    flush(): void;
}
/**
 * Creates a debounced function that delays execution until after
 * the specified delay has elapsed since the last call.
 *
 * Backward-compatible: `debounce(fn, ms)` keeps the trailing-only semantics
 * and synchronous `cancel()` of earlier releases. Pass
 * `{ leading, trailing, maxWait }` to opt in to enhanced behavior.
 *
 * @example
 * ```ts
 * const search = debounce((query: string) => doSearch(query), 300);
 * const leading = debounce(fn, 200, { leading: true, trailing: false });
 * const capped = debounce(fn, 500, { maxWait: 1500 });
 * capped.flush(); // run pending trailing call immediately
 * ```
 */
export declare function debounce<TArgs extends unknown[]>(fn: (...args: TArgs) => void, delayMs: number, options?: DebounceOptions): DebouncedFn<TArgs>;
/**
 * Creates a throttled function that runs at most once per interval.
 *
 * Backward-compatible: `throttle(fn, ms)` continues to execute on the
 * leading edge and ignore subsequent calls within the interval (no trailing
 * call), matching earlier releases. Pass `{ leading, trailing }` to opt in
 * to leading/trailing edge control.
 */
export declare function throttle<TArgs extends unknown[]>(fn: (...args: TArgs) => void, intervalMs: number, options?: ThrottleOptions): ThrottledFn<TArgs>;
/**
 * Ensures a function only runs once. Subsequent calls return the first result.
 */
export declare function once<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
/**
 * A no-operation function.
 */
export declare function noop(): void;
/** A memoized function with cache controls. */
export interface MemoizedFn<TArgs extends unknown[], TResult> {
    (...args: TArgs): TResult;
    /** Clear the entire cache. */
    clear(): void;
    /** Delete a single cached entry by its computed key. */
    delete(key: string): boolean;
}
/**
 * Caches the result of `fn` keyed by `JSON.stringify(args)` (or a custom
 * `keyFn`). The cache is unbounded; use `keyFn` and `clear()` for control.
 *
 * @example
 * ```ts
 * const factorial = memoize((n: number) => (n <= 1 ? 1 : n * factorial(n - 1)));
 * factorial.clear();
 * ```
 */
export declare function memoize<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult, keyFn?: (...args: TArgs) => string): MemoizedFn<TArgs, TResult>;
/**
 * Right-to-left function composition. `compose(f, g)(x) === f(g(x))`.
 * Returns an identity function with no arguments.
 */
export declare function compose<T>(...fns: Array<(value: T) => T>): (value: T) => T;
/**
 * Left-to-right function composition. `pipe(f, g)(x) === g(f(x))`.
 */
export declare function pipe<T>(...fns: Array<(value: T) => T>): (value: T) => T;
/**
 * Curries a function of fixed arity, returning a chain of single-argument
 * functions that collect arguments until the original arity is satisfied.
 *
 * @example
 * ```ts
 * const add = (a: number, b: number, c: number) => a + b + c;
 * const curried = curry(add);
 * curried(1)(2)(3); // 6
 * curried(1, 2)(3); // 6
 * ```
 */
export declare function curry<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult): (...args: Partial<TArgs>) => unknown;
/**
 * Returns a partially-applied function with the given preset arguments
 * baked in as the leading parameters.
 */
export declare function partial<TPreset extends unknown[], TRest extends unknown[], TResult>(fn: (...args: [...TPreset, ...TRest]) => TResult, ...preset: TPreset): (...args: TRest) => TResult;
/** Options for {@link retry}. */
export interface RetryOptions {
    /** Maximum attempt count (default: 3). */
    attempts?: number;
    /** Initial delay between attempts in ms (default: 100). */
    baseDelay?: number;
    /** Exponential backoff factor (default: 2). */
    factor?: number;
    /** Maximum delay between attempts, in ms (default: 30_000). */
    maxDelay?: number;
    /** Random jitter ratio in [0, 1) added to each delay (default: 0). */
    jitter?: number;
    /** Optional `AbortSignal` to cancel retrying. */
    signal?: AbortSignal;
    /**
     * Predicate to decide whether to retry on a given error. Default: always
     * retry until attempts are exhausted.
     */
    shouldRetry?: (error: unknown, attempt: number) => boolean;
    /** Optional hook invoked before each delay. */
    onRetry?: (error: unknown, attempt: number, nextDelayMs: number) => void;
}
/**
 * Runs an async function with exponential-backoff retries.
 *
 * @example
 * ```ts
 * const value = await retry(() => fetchJSON('/api/v1'), {
 *   attempts: 5,
 *   baseDelay: 200,
 *   factor: 2,
 *   jitter: 0.25,
 * });
 * ```
 */
export declare function retry<T>(fn: () => T | Promise<T>, options?: RetryOptions): Promise<T>;
//# sourceMappingURL=function.d.ts.map