kontroll/dist/index.d.mts

kontroll ("control") is a tiny, dead-simple package for function behavior controls like debounce, countdown, throttle (limit).

type Fn<T = void> = () => T;
type FnWithArgs<T = void> = (...args: any) => T;
interface KontrollStore {
    [x: PropertyKey]: KontrollInstance;
}
interface KontrollInstance {
    timer: ReturnType<typeof setTimeout>;
    callback: Fn<any | Promise<any>>;
    trailing?: [FnWithArgs, ...any];
    finishing?: boolean;
}
declare function clear(callback: Fn): void;
declare function clear(key: keyof KontrollStore): void;
/**
 * Returns the {@link KontrollInstance} for the given key, if exists.
 *
 * Could be useful to check if a promise is executing and not settled.
 *
 * ---
 *
 * Example
 * ```
 * debounce(1, async => await sleep(1000), { key: '1sec' })
 * // 500ms passed
 * getInstance('1sec')
 * // Result: `KontrollInstance` ({ timer: Timeout, callback: <fn>, finishing: true })
 * ```
 */
declare function getInstance(key: keyof KontrollStore): KontrollInstance | undefined;
type KontrollClearer = Fn;
interface KontrollBaseOptions {
    /**
     * Specify a known key if needed
     * @default string // .toString() of the inputted callback
     */
    key?: keyof KontrollStore;
}
interface KontrollCountdownOptions extends KontrollBaseOptions {
    /**
     * Replaces the current timed callback
     * @default false
     */
    replace?: boolean;
}
/**
 * Countdown for a period of ms then execute the first/replaced callback, based on `options.replace`.
 *
 * Calls while the timer haven't finished are dropped.
 *
 * ---
 *
 * Example
 * ```
 * countdown(1000, doSum(1), { key: 'eg' })
 * // 500ms passed
 * countdown(1000, doSum(2))
 * // 500ms passed
 * // Result: 1
 * ```
 *
 * ---
 *
 * Example with `options.replace=true`:
 * ```
 * countdown(1000, doSum(1))
 * // 500ms passed
 * countdown(1000, doSum(2), { replace: true })
 * // 500ms passed
 * // Result: 2
 * ```
 */
declare function countdown(ms: number, callback: Fn, { key, replace }?: KontrollCountdownOptions): KontrollClearer;
interface KontrollDebounceOptions extends KontrollBaseOptions {
    /**
     * Avoiding initial wait for first call
     * @default false
     */
    leading?: boolean;
}
/**
 * Creates a timer that will execute the callback upon finish, calls while the timer haven't finished recreates the timer.
 *
 * If `options.leading`, execute callback immediately for initial call.
 *
 * ---
 *
 * Example:
 * ```
 * debounce(1000, doSum(1))
 * // 500ms passed
 * debounce(1000, doSum(2))
 * // 1000ms passed
 * // Result: 2
 * ```
 *
 * ---
 *
 * Example with `options.leading`:
 * ```
 * debounce(1000, doSum(1), { leading: true })
 * // Result: 1
 * // 500ms passed
 * debounce(1000, doSum(2), { leading: true }) // leading doesn't matter anymore in this timer scope
 * // 500ms passed
 * debounce(1000, doSum(3))
 * // 1000ms passed
 * // Result: 3
 * ```
 */
declare function debounce(ms: number, callback: Fn, { key, leading }?: KontrollDebounceOptions): KontrollClearer;
interface KontrollThrottleOptions extends KontrollBaseOptions {
    /**
     * Perform additional execution with last received arguments
     * @default false
     */
    trailing?: boolean;
}
/**
 * Executes the callback, and bypass any subsequent calls for a period of ms.
 *
 * Calls while the timer haven't finished are dropped.
 *
 * If `options.trailing` and calls while the timer haven't finished are received,
 *
 * an additional execution with last received arguments is performed.
 *
 * ---
 *
 * Example:
 * ```
 * throttle(1000, doSum(1))
 * // Result: 1
 * // 500ms passed
 * throttle(1000, doSum(2))
 * // 9999ms passed
 * // (Nothing)
 * ```
 *
 * ---
 *
 * Example with `options.trailing`:
 * ```
 * throttle(1000, doSum(1))
 * // Result: 1
 * // 500ms passed
 * throttle(1000, doSum(2), { trailing: true })
 * // 500ms passed
 * // Result: 2
 * // A timer is also created, so calls after that are still dropped:
 * throttle(1000, doSum(3))
 * // 9999ms passed
 * // (Nothing)
 * ```
 *
 */
declare function throttle(ms: number, callback: Fn, { key, trailing }?: KontrollThrottleOptions): KontrollClearer;

export { clear, countdown, debounce, getInstance, throttle };
export type { KontrollBaseOptions, KontrollClearer, KontrollCountdownOptions, KontrollDebounceOptions, KontrollInstance, KontrollStore, KontrollThrottleOptions };