debounce-async

A debounced function that delays invoking asynchronous functions.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
debounce-async
2440.0.25 years ago6 years agoMinified + gzip package size for debounce-async in KB

Readme

debounce-async #
!Build Statustravisimgtravissite !NPM Packagenpmimgnpmsite !Dependency statusdavidimgdavidsite !devDependency statusdaviddevimgdaviddevsite
!NPMnodeiimgnodeisite
A debounced function that delays invoking asynchronous functions.

Preliminaries ##

A debounced function groups sequential calls to a function within a period. Only the last call in the group is executed. The others are simply ignored as if no calls to them ever happened.
Say d is a debounced function of f, var d = debounce(f, 400);, and d is called evenly during the first and the third seconds as the timeline below.
seconds elapsed 0 1 2 3 4 d called d d d d d - - - - - d d d d d - - - - - f called f f
Only the last of the five sequential calls to d actually invokes f. The rest four are simply ignored.
When it comes to promise-based asynchronous functions, this package ignores function calls by rejecting the promises. The original fullfillment is bypassed, and simply rejected with a customizable object for the sake of telling which/when an ignorance occurs.

Installation ##

npm install debounce-async --save

Usage ##

var debounce = require( 'debounce-async' );

/**
  * debounce(func, [wait=0], [options={}])
  *
  * @param {Function} func The function to debounce.
  * @param {number} [wait=0] The number of milliseconds to delay.
  * @param {Object} [options={}] The options object.
  * @param {boolean} [options.leading=false] Specify invoking on the leading edge of the timeout.
  * @param {cancelObj} [options.cancelObj='canceled'] Specify the error object to be rejected.
  * @returns {Function} Returns the new debounced function.
  */

This package aims at maintaining the same signature of the debounce function from lodash. Please report if there is discrenency.

Example ##

Promise ###

var debounce = require( 'debounce-async' );

var f = value => new Promise( resolve => setTimeout( () => resolve( value ), 50 ) );
var debounced = debounce( f, 100 );

var promises = [ 'foo', 'bar' ].map( debounced );
promises.forEach( promise => {
  promise
    .then( res => {
      console.log( 'resolved:', res );
    })
    .catch( err => {
      console.log( 'rejected:', err );
    });
});

// Output:
// rejected: canceled
// resolved: bar

In the example above, f is an asynchronous function which returns a promise. The promise is resolved with the input after 50ms. debounced is a debounced function of f with a delay of 100ms.
The debounced function is called twice consecutively by the callback of Array.proptotype.map, with 'foo' and 'bar' being the input value respectively. The two returned promises are next fullfilled by printing the resolved result or rejected error on the console.
This snippet results in the given output. The first promise was rejected while the second one was resolved. It is because the second call comes before the delay of 100ms since the first call fired.

async/await ###

Same thing when it comes to asynchronous ES7 async/await functions. Take the prior example and transform the f into an ES7 async function.
var f = async value => await new Promise( resolve => setTimeout( () => resolve( value ), 50 ) );

Same output can be expected after execution.

Test ##

npm test

License ##

MIT. See LICENSE.mdlicense for details.