import { Func } from '../types.ts';
/**
 * Error thrown when a throttled function is called too frequently
 */
export declare class ThrottleError extends Error {
    constructor(message: string);
}
export declare const isThrottleError: (error: unknown) => error is ThrottleError;
/**
 * Enhanced function interface with cancel capability
 */
export interface ThrottledFunction<T extends Func> {
    (...args: Parameters<T>): ReturnType<T>;
    cancel(): void;
}
/**
 * Options for configuring throttle behavior
 */
export interface ThrottleOptions {
    /** Minimum delay in milliseconds between function calls */
    delay: number;
    /** Optional callback executed when throttling occurs */
    onThrottle?: (args: unknown[]) => void;
    /** Whether to throw an error when throttling occurs (default: false) */
    throws?: boolean;
}
/**
 * Throttle a function, calling it at most once every `delay` milliseconds.
 * The first call is executed immediately, subsequent calls within the delay
 * window return the cached result from the last execution.
 *
 * @param fn - The function to throttle
 * @param opts - Throttle configuration options
 * @returns A throttled function with cancel capability
 *
 * @throws {Error} When `fn` is not a function
 * @throws {Error} When `delay` is not a positive number
 * @throws {Error} When `onThrottle` is provided but not a function
 * @throws {Error} When `throws` is provided but not a boolean
 * @throws {ThrottleError} When throttling occurs and `throws` is true
 *
 * @example
 * ```typescript
 * const throttledFn = throttle(fn, {
 *     delay: 1000,
 *     onThrottle: (args) => {
 *         console.log('throttled', args);
 *     },
 * });
 *
 * throttledFn(); // calls fn immediately
 * throttledFn(); // returns cached result
 * await wait(500);
 * throttledFn(); // returns cached result
 *
 * // Cancel clears the throttle state
 * throttledFn.cancel();
 * throttledFn(); // calls fn immediately (state reset)
 * ```
 */
export declare const throttle: <T extends Func>(fn: T, opts: ThrottleOptions) => ThrottledFunction<T>;