p-debounce/index.d.ts

Debounce promise-returning & async functions

export type Options = {
	/**
	Call the `fn` on the [leading edge of the timeout](https://css-tricks.com/debouncing-throttling-explained-examples/#article-header-id-1). Meaning immediately, instead of waiting for `wait` milliseconds.

	@default false
	*/
	readonly before?: boolean;

	/**
	An `AbortSignal` to cancel the debounced function.
	*/
	readonly signal?: AbortSignal;
};

declare const pDebounce: {
	/**
	[Debounce](https://css-tricks.com/debouncing-throttling-explained-examples/) promise-returning & async functions.

	@param fn - Promise-returning/async function to debounce.
	@param wait - Milliseconds to wait before calling `fn`.
	@returns A function that delays calling `fn` until after `wait` milliseconds have elapsed since the last time it was called.

	@example
	```
	import pDebounce from 'p-debounce';

	const expensiveCall = async input => input;

	const debouncedFunction = pDebounce(expensiveCall, 200);

	for (const number of [1, 2, 3]) {
		(async () => {
			console.log(await debouncedFunction(number));
		})();
	}
	//=> 3
	//=> 3
	//=> 3
	```
	*/
	<This, ArgumentsType extends unknown[], ReturnType>(
		fn: (this: This, ...arguments: ArgumentsType) => PromiseLike<ReturnType> | ReturnType,
		wait: number,
		options?: Options
	): (this: This, ...arguments: ArgumentsType) => Promise<ReturnType>;

	/**
	Execute `function_` unless a previous call is still pending, in which case, return the pending promise. Useful, for example, to avoid processing extra button clicks if the previous one is not complete.

	@param function_ - Promise-returning/async function to debounce.

	@example
	```
	import {setTimeout as delay} from 'timers/promises';
	import pDebounce from 'p-debounce';

	const expensiveCall = async value => {
		await delay(200);
		return value;
	};

	const debouncedFunction = pDebounce.promise(expensiveCall);

	for (const number of [1, 2, 3]) {
		(async () => {
			console.log(await debouncedFunction(number));
		})();
	}
	//=> 1
	//=> 1
	//=> 1
	```
	*/
	promise<This, ArgumentsType extends unknown[], ReturnType>(
		function_: (this: This, ...arguments: ArgumentsType) => PromiseLike<ReturnType> | ReturnType
	): (this: This, ...arguments: ArgumentsType) => Promise<ReturnType>;
};

export default pDebounce;