debounce-promise

What is debounce-promise?

The debounce-promise npm package is used to debounce promises, ensuring that a function is not called too frequently. This is particularly useful in scenarios where you want to limit the rate at which a function is executed, such as in search input fields or API calls.

What are debounce-promise's main functionalities?

Basic Debouncing

This feature allows you to debounce a function that returns a promise. In this example, the fetchData function is debounced with a delay of 300 milliseconds. This means that if fetchData is called multiple times within 300 milliseconds, it will only execute once.

const debounce = require('debounce-promise');
const fetchData = () => fetch('https://api.example.com/data');
const debouncedFetchData = debounce(fetchData, 300);

debouncedFetchData().then(response => response.json()).then(data => console.log(data));

Leading Edge Execution

This feature allows the debounced function to be executed immediately on the leading edge of the timeout, rather than waiting for the delay to pass. In this example, fetchData is executed immediately the first time it is called, and then debounced for subsequent calls.

const debounce = require('debounce-promise');
const fetchData = () => fetch('https://api.example.com/data');
const debouncedFetchData = debounce(fetchData, 300, { leading: true });

debouncedFetchData().then(response => response.json()).then(data => console.log(data));

Trailing Edge Execution

This feature ensures that the debounced function is executed at the trailing edge of the timeout. In this example, fetchData will be executed after the 300 milliseconds delay if no new calls are made within that period.

const debounce = require('debounce-promise');
const fetchData = () => fetch('https://api.example.com/data');
const debouncedFetchData = debounce(fetchData, 300, { trailing: true });

debouncedFetchData().then(response => response.json()).then(data => console.log(data));

Other packages similar to debounce-promise

lodash

Lodash is a popular utility library that provides a wide range of functions, including debouncing. The debounce function in Lodash can be used to debounce any function, not just those returning promises. However, it does not provide built-in support for promises like debounce-promise does.

underscore

Underscore is another utility library similar to Lodash, offering a variety of functions including debouncing. Like Lodash, it can debounce any function but does not have built-in support for promises.

p-debounce

p-debounce is a package specifically designed for debouncing promise-returning functions. It is similar to debounce-promise in functionality but offers a slightly different API. It is a good alternative if you are looking for a lightweight solution focused on promises.

README

debounce-promise

Create a debounced version of a promise returning function

Install

npm i -S debounce-promise

Usage example

var debounce = require('debounce-promise')

function expensiveOperation(value) {
  return Promise.resolve(value)
}

var saveCycles = debounce(expensiveOperation, 100);

[1, 2, 3, 4].forEach(num => {
  return saveCycles('call no #' + num).then(value => {
    console.log(value)
  })
})

// Will only call expensiveOperation once with argument `4` and print:
//=> call no #4
//=> call no #4
//=> call no #4
//=> call no #4

With leading=true

var debounce = require('debounce-promise')

function expensiveOperation(value) {
  return Promise.resolve(value)
}

var saveCycles = debounce(expensiveOperation, 100, {leading: true});

[1, 2, 3, 4].forEach(num => {
  return saveCycles('call no #' + num).then(value => {
    console.log(value)
  })
})

//=> call no #1
//=> call no #4
//=> call no #4
//=> call no #4

With accumulate=true

var debounce = require('debounce-promise')

function squareValues (values) {
  return Promise.all(values.map(val => val * val))
}

var square = debounce(squareValues, 100, {accumulate: true});

[1, 2, 3, 4].forEach(num => {
  return square(num).then(value => {
    console.log(value)
  })
})

//=> 1
//=> 4
//=> 9
//=> 16

Api

debounce(func, [wait=0], [{leading: true|false, accumulate: true|false})

Returns a debounced version of func that delays invoking until after wait milliseconds.

Set leading: true if you want to call func and return its promise immediately.

Set accumulate: true if you want the debounced function to be called with an array of all the arguments received while waiting.

Supports passing a function as the wait parameter, which provides a way to lazily or dynamically define a wait timeout.

Example timeline illustration

function refresh() {
  return fetch('/my/api/something')
}
const debounced = debounce(refresh, 100)

time (ms) ->   0 ---  10  ---  50  ---  100 ---
-----------------------------------------------
debounced()    | --- P(1) --- P(1) --- P(1) ---
refresh()      | --------------------- P(1) ---

const debounced = debounce(refresh, 100, {leading: true})

time (ms) ->   0 ---  10  ---  50  ---  100 ---  110 ---
--------------------------------------------------------
debounced()    | --- P(1) --- P(2) --- P(2) --- P(2) ---
refresh()      | --- P(1) --------------------- P(2) ---