perfect-debounce

Improved debounce function with Promise support.

Features

Well tested debounce implementation
Native Promise support
Avoid duplicate calls while promise is being resolved
Configurable trailing and leading behavior
Control methods

Usage

Install package:

npx nypm i perfect-debounce

Import:

import { debounce } from "perfect-debounce";

Debounce function:

const debounced = debounce(async () => {
  // Some heavy stuff
}, 25);

When calling debounced, it will wait at least for 25ms as configured before actually calling your function. This helps to avoid multiple calls.

Control Methods

The returned debounced function provides additional control methods:

debounced.cancel(): Cancel any pending invocation that has not yet occurred.
await debounced.flush(): Immediately invoke the pending function call (if any) and return its result.
debounced.isPending(): Returns true if there is a pending invocation waiting to be called, otherwise false.

debounced.cancel(); // Cancel any pending call
await debounced.flush(); // Immediately invoke pending call (if any)
debounced.isPending(); // Returns true if a call is pending

Example

const debounced = debounce(async (value) => {
  // Some async work
  return value * 2;
}, 100);

debounced(1);
debounced(2);
debounced(3);

// Check if a call is pending
console.log(debounced.isPending()); // true

// Immediately invoke the pending call
const result = await debounced.flush();
console.log(result); // 6

// Cancel any further pending calls
debounced.cancel();

To avoid initial wait, we can set leading: true option. It will cause function to be immediately called if there is no other call:

const debounced = debounce(
  async () => {
    // Some heavy stuff
  },
  25,
  { leading: true },
);

If executing async function takes longer than debounce value, duplicate calls will be still prevented a last call will happen. To disable this behavior, we can set trailing: false option:

const debounced = debounce(
  async () => {
    // Some heavy stuff
  },
  25,
  { trailing: false },
);

???? Development

Clone this repository
Enable Corepack using corepack enable (use npm i -g corepack for Node.js < 16.10)
Install dependencies using pnpm install
Run interactive tests using pnpm dev

License

Based on sindresorhus/p-debounce.

Made with ???? Published under MIT License.

Current Tags

2.1.0 ... latest (3 months ago)