@pavelhudau/de-bouncer NPM

de-bouncer

TypeScript and JavaScript De-Bouncer implementation.

100% ZERO dependencies;
Written for UIs, e.g., Single Page web applications;
Verified to work with React (See example app);

!TIP More details and motivation on the implementation can be found in the De-Bouncer blog post.

Features

Exponential Debouncing: Prevents rapid and repetitive user actions while maintaining a snappy user experience.
Customizable Strategies: Choose from multiple built-in strategies or create your own.
Lightweight: Zero dependencies for fast and efficient performance.
Test-Friendly: Includes a no-delay strategy for testing purposes.

Installation

Install the package via npm:

npm install @pavelhudau/de-bouncer

How to Use DeBouncer

Import DeBouncer.
Import a strategy you would like to use. Supported strategies are:
- ExponentialDebounceStrategy: Default strategy. Helps prevent rapid user actions while keeping the application responsive.
- ConstDebouncerStrategy: Keeps the delay constant at all times.
- NoDelayDebounceStrategy: Primarily for testing, removes the time component.
Create a DeBouncer instance and wrap the backend call you'd like to protect with it.
Done!

Example

The example below demonstrates how to debounce a handleFooButtonClick event handler that makes a backend call to a weather API.

import DeBouncer from '@pavelhudau/de-bouncer';
import { ExponentialDebounceStrategy } from '@pavelhudau/de-bouncer/debounce-strategies';

const fooButtonDeBouncer = new DeBouncer(new ExponentialDebounceStrategy());

const handleFooButtonClick = async () => {
    // Await for DeBouncer delay.
    // Keep the latest clicked token for further use.
    const currentToken = await fooButtonDeBouncer.debounce();

    // Has currentToken been cancelled while waiting for DeBouncer delay to expire?
    // The token is cancelled when FooButton is clicked again.
    if (currentToken.isCancelled) return;

    // Logic that you'd like to protect (de-bounce), for example, a service call.
    const weather = await fetch('http://api.weatherapi.com/v1/current.json');

    // Has currentToken been cancelled while awaiting the service call,
    // e.g., FooButton was clicked again before the delay expired.
    if (currentToken.isCancelled) return;

    // Logic to display the service response.
    showWeather(weather);
};

Strategies

ExponentialDebounceStrategy

Increases debounce delay exponentially with the frequency of calls.
Prevents backend flooding while keeping the application responsive.

ConstDebouncerStrategy

Maintains a constant delay regardless of call frequency.

NoDelayDebounceStrategy

Removes all delays, useful for testing scenarios.

Example React App

An example application can be found in examples/my-react-app. The application implements a simple click counter.

See DeBouncer in Action

Click the button rapidly multiple times. The counter will increment immediately after the first click and after the last click only.
Click slowly to see how every click increments the counter.

Start the Example App

To initialize and start the example app:

Navigate to the example app directory:
```
cd examples/my-react-app
```
Run the initialization script to build and install the local version of the de-bouncer package into the example app:
```
./initialize.sh
```
Start the example application:
```
npm run start
```