perfect-debounce

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.