ts-debounce

What is ts-debounce?

The ts-debounce npm package provides a simple and efficient way to debounce functions in TypeScript. Debouncing is a programming practice used to ensure that time-consuming tasks do not fire so often, improving performance and user experience.

What are ts-debounce's main functionalities?

Basic Debounce

This feature allows you to debounce a function, ensuring it only executes after a specified delay. In this example, the `saveInput` function will only be called 300 milliseconds after the last input event.

const { debounce } = require('ts-debounce');

function saveInput() {
  console.log('Saving data');
}

const debouncedSaveInput = debounce(saveInput, 300);

document.getElementById('input').addEventListener('input', debouncedSaveInput);

Debounce with Immediate Execution

This feature allows you to debounce a function but execute it immediately on the first call. Subsequent calls within the delay period will be ignored. In this example, `fetchData` will be called immediately on the first input event, and then debounced for 300 milliseconds.

const { debounce } = require('ts-debounce');

function fetchData() {
  console.log('Fetching data');
}

const debouncedFetchData = debounce(fetchData, 300, { isImmediate: true });

document.getElementById('input').addEventListener('input', debouncedFetchData);

Cancel Debounce

This feature allows you to cancel a debounced function call. In this example, the `logMessage` function will be debounced for 300 milliseconds, but if the cancel button is clicked, the debounce will be cancelled.

const { debounce } = require('ts-debounce');

function logMessage() {
  console.log('Logging message');
}

const debouncedLogMessage = debounce(logMessage, 300);

document.getElementById('input').addEventListener('input', debouncedLogMessage);

document.getElementById('cancelButton').addEventListener('click', () => {
  debouncedLogMessage.cancel();
  console.log('Debounce cancelled');
});

Other packages similar to ts-debounce

lodash.debounce

The lodash.debounce package provides similar functionality to ts-debounce, allowing you to debounce functions. It is part of the larger Lodash library, which offers a wide range of utility functions for JavaScript. Compared to ts-debounce, lodash.debounce is more widely used and has more features, but it also comes with the overhead of the entire Lodash library if not used selectively.

debounce

The debounce package is a lightweight alternative for debouncing functions. It offers similar functionality to ts-debounce but is more minimalistic. It is a good choice if you need a simple debounce solution without additional features or dependencies.

throttle-debounce

The throttle-debounce package provides both throttling and debouncing functionalities. It is a versatile library that can be used for both purposes, making it a good alternative to ts-debounce if you need both throttling and debouncing in your project.

README

TypeScript implementation of debounce function

Debounce create a new function g, which when called will delay the invocation of the original function f until n milliseconds after it was last called.

It's very useful for scenarios where it's better to limit the number of times the function is called. E.g. think of search input which fetches data from API. It's enough display search results after user stopped entering characters for some time.

Function arguments

import { debounce } from 'ts-debounce';

const debouncedFunction = debounce(originalFunction, waitMilliseconds, options);

• originalFunction
  • the function which we want to debounce
• waitMilliseconds
  • how many seconds must pass after most recent function call, for the original function to be called
• options
  • options object supports now one argument
  • isImmediate (boolean)
    • if set to true then originalFunction will be called immediately, but on subsequent calls of the debounced function original function won't be called, unless waitMilliseconds passed after last call
  • maxWait (number)
    • if defined it will call the originalFunction after maxWait time has passed, even if the debounced function is called in the meantime
      • e.g. if wait is set to 100 and maxWait to 200, then if the debounced function is called every 50ms, then the original function will be called after 200ms anyway

Cancellation

The returned debounced function can be cancelled but by calling cancel() on it.

const debouncedFunction = debounce(originalFunction, waitMilliseconds, options);

debouncedFunction.cancel();

Credits & inspiration

This implementation is based upon following sources:

• JavaScript Debounce Function by David Walsh
• Lodash implementation

Compability

• version 2 - TypeScript 3.3
• version 1 - TypeScript 2.0

Contributors

Zac 💻

Karol Majewski 💻

Fabien Rogeret 💻

Iman 💻

• Project tries to adhere to all-contributors specification

Changelog

2021-01-10 [2.2.0]

• ✨ [new] maxWait option added