@newdash/newdash/debounce.d.ts

javascript/typescript utility library

/**
 * @ignore
 */
interface Options {
    /**
     * Specify invoking on the leading edge of the timeout.
     */
    leading?: boolean;
    /**
     * The maximum time `func` is allowed to be delayed before it's invoked.
     */
    maxWait?: number;
    /**
     * Specify invoking on the trailing edge of the timeout.
     */
    trailing?: boolean;
}
/**
 * @ignore
 */
type DebouncedFunction<F extends (...args: any[]) => any> = {
    (...args: Parameters<F>): ReturnType<F>;
    cancel: () => void;
    flush: () => any;
    pending: () => boolean;
};
/**
 * Creates a debounced function that delays invoking `func` until after `wait`
 * milliseconds have elapsed since the last time the debounced function was
 * invoked, or until the next browser frame is drawn. The debounced function
 * comes with a `cancel` method to cancel delayed `func` invocations and a
 * `flush` method to immediately invoke them. Provide `options` to indicate
 * whether `func` should be invoked on the leading and/or trailing edge of the
 * `wait` timeout. The `func` is invoked with the last arguments provided to the
 * debounced function. Subsequent calls to the debounced function return the
 * result of the last `func` invocation.
 *
 * **Note:** If `leading` and `trailing` options are `true`, `func` is
 * invoked on the trailing edge of the timeout only if the debounced function
 * is invoked more than once during the `wait` timeout.
 *
 * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
 * until the next tick, similar to `setTimeout` with a timeout of `0`.
 *
 * If `wait` is omitted in an environment with `requestAnimationFrame`, `func`
 * invocation will be deferred until the next frame is drawn (typically about
 * 16ms).
 *
 * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
 * for details over the differences between `debounce` and `throttle`.
 *
 * @since 5.3.0
 * @category Function
 * @param func The function to debounce.
 * @param wait The number of milliseconds to delay; if omitted, `requestAnimationFrame` is used (if available).
 * @param options The options object.
 * @returns {Function} Returns the new debounced function.
 * @example
 *
 * ```js
 *
 * // Avoid costly calculations while the window size is in flux.
 * jQuery(window).on('resize', debounce(calculateLayout, 150))
 *
 * // Invoke `sendMail` when clicked, debouncing subsequent calls.
 * jQuery(element).on('click', debounce(sendMail, 300, {
 *   'leading': true,
 *   'trailing': false
 * }))
 *
 * // Ensure `batchLog` is invoked once after 1 second of debounced calls.
 * const debounced = debounce(batchLog, 250, { 'maxWait': 1000 })
 * const source = new EventSource('/stream')
 * jQuery(source).on('message', debounced)
 *
 * // Cancel the trailing debounced invocation.
 * jQuery(window).on('popstate', debounced.cancel)
 *
 * // Check for pending invocations.
 * const status = debounced.pending() ? "Pending..." : "Ready"
 *
 * ```
 */
export declare function debounce<F extends (...args: any[]) => any>(func: F, wait?: number, options?: Options): DebouncedFunction<F>;
export default debounce;