@ayonli/jsext/types/throttle.d.ts

A JavaScript extension package for building strong and modern applications.

/**
 * Throttles function calls for frequent access.
 * @module
 */
/**
 * Options for the {@link throttle} function.
 */
export interface ThrottleOptions {
    duration: number;
    /**
     * Use the throttle strategy `for` the given key, this will keep the
     * result in a global cache, binding new `handler` function for the same
     * key will result in the same result as the previous, unless the
     * duration has passed. This mechanism guarantees that both creating the
     * throttled function in function scopes and overwriting the handler are
     * possible.
     */
    for?: any;
    /**
     * When turned on, respond with the last cache (if available)
     * immediately, even if it has expired, and update the cache in the
     * background.
     */
    noWait?: boolean;
}
/**
 * Creates a throttled function that will only be run once in a certain amount
 * of time.
 *
 * If a subsequent call happens within the `duration` (in milliseconds), the
 * previous result will be returned and the `handler` function will not be
 * invoked.
 *
 * @example
 * ```ts
 * import throttle from "@ayonli/jsext/throttle";
 * import { sleep } from "@ayonli/jsext/async";
 *
 * const fn = throttle((input: string) => input, 1_000);
 * console.log(fn("foo")); // foo
 * console.log(fn("bar")); // foo
 *
 * await sleep(1_000);
 * console.log(fn("bar")); // bar
 * ```
 */
export default function throttle<I, Fn extends (this: I, ...args: any[]) => any>(handler: Fn, duration: number): Fn;
/**
 * @example
 * ```ts
 * import throttle from "@ayonli/jsext/throttle";
 * import { sleep } from "@ayonli/jsext/async";
 *
 * const out1 = await throttle(() => Promise.resolve("foo"), {
 *     duration: 1_000,
 *     for: "example",
 * })();
 * console.log(out1); // foo
 *
 * const out2 = await throttle(() => Promise.resolve("bar"), {
 *     duration: 1_000,
 *     for: "example",
 * })();
 * console.log(out2); // foo
 *
 * await sleep(1_000);
 * const out3 = await throttle(() => Promise.resolve("bar"), {
 *     duration: 1_000,
 *     for: "example",
 * })();
 * console.log(out3); // bar
 * ```
 */
export default function throttle<I, Fn extends (this: I, ...args: any[]) => any>(handler: Fn, options: ThrottleOptions): Fn;