@addr/debouncer
v0.8.4
Published
This library provides a class that creates a recursive timer. You can specify the time and a callback to be executed after that time. The instance won't start the timer unless you call the right function. It also provides several events to help you trace
Downloads
22
Readme
Debouncer
This library provides a class that creates a recursive timer. You can specify the time and a callback to be executed after that time. The instance won't start the timer unless you call the right function. It also provides several events to help you trace your code.
How to use it
There are many things you can do with this library, but I'll begin explaning the basic usage.
First you need to create an instance of the Debouncer, then you'll be able to start the timer and the timer won't stop until some conditions are satisfied.
In short, this Debouncer is like a setInterval
but every iteration waits for the execution of your callback (and also has other cool options).
const Debouncer = require('@addr/debouncer');
const instance = new Debouncer(
4000,
myData => console.log("I'm being executed after 4s with", myData)
);
instance.debounce('My data');
// After 4 seconds your callback will be executed
// The timer will still be running but after 8 seconds it won't execute your callback
// It won't execute it because the data has not changed
// The purpose of this debouncer is that you can change your data as many times as you want, but it will be processed
// only if the data changed and after the time you passed.
That code will run for 16 seconds. After the first 4 seconds it will execute your callback. After the second 4 seconds it won't execute
your callback, but this iteration is called a null iteration
. It will run another 4 seconds without executing your callback 2 times (4*4 = 16).
The code will be executed for 16 seconds because these are the default options of the Debouncer:
const baseOptions = {
nullIterationsToShutdown: 3,
onlyCountContiguousIterations: true,
shutdownAfterError: true,
events: [
'shutdown',
'shutdownAfterCurrentIteration',
'errorInCurrentIteration',
'activeIteration',
'nullIteration',
'reboot',
'responseFromCallback'
]
};
So, atfter 3 null iterations
it will shutdown, but only if those iterations are contiguous (one followed by another one).
If you want to modify those options, you can pass new options like this:
const Debouncer = require('@addr/debouncer');
const instance = new Debouncer(
4000,
myData => console.log("I'm being executed after 4s with", myData),
{
nullIterationsToShutdown: 5,
onlyCountContiguousIterations: false,
shutdownAfterError: false
}
);
Now, the Debouncer will shutdown after 5 null iterations
, but they can be separated. Also, it won't shutdown if there's an error.
You can change any of those options (even the events
option). If you don't specify an option, it will be replaced by a default option.
const Debouncer = require('@addr/debouncer');
// This instance will have the following options:
/*
const baseOptions = {
nullIterationsToShutdown: 5,
onlyCountContiguousIterations: false,
shutdownAfterError: false,
events: [
'shutdown',
'shutdownAfterCurrentIteration',
'errorInCurrentIteration',
'activeIteration',
'nullIteration',
'reboot',
'responseFromCallback'
]
};
*/
const instance = new Debouncer(
4000,
myData => console.log("I'm being executed after 4s with", myData),
{
nullIterationsToShutdown: 5,
onlyCountContiguousIterations: false,
shutdownAfterError: false
}
);
Available functions
You can manipulate the behavior of your Debouncer by calling these functions:
debounce(data);
shutdownNow();
shutdownAfterCurrentIteration();
reboot(time = 1000, callback = () => {}, options = {});
changeTime(newTime = 1000);
changeCallback(newCallback = () => {});
changeOptions(newOptions = {});
debounce
This function will start the timer and receives the data you want to receive in your callback.
shutdownNow
This function will shutdown the timer even if there's a pending iteration to be executed.
shutdownAfterCurrentIteration
This function will shutdown the timer after the next pending iteration (even null iterations
);
reboot
If your Debouncer got shutted down, you can use this function to restart it. It will shutdown any previous timer and iterations.
Note: If you shutdown a Debouncer, you must call this function in order to use it again.
changeTime
This function will allow you to change the time of your Debouncer. Any pending iterations will still use the previous time.
changeCallback
This function will allow you to change the callback of your Debouncer. Any pending iterations will use the new callback.
changeOptions
This function will allow you to change the options of your Debouncer. Any pending iterations will use the new options.
Note: Please be aware when you call this function and change the events. If you change those, then be sure to reomve all the listeners registered before.
Advanced usage
The
events
option is an array so you can use whatever names for those events. You only need to maintain the same order for those events. The purpose is to be flexible for already started and big projects. So, if you have already declared any of those names for another Emitter, then you can use another name.The
shutdownAfterCurrentIteration
will also start the timer. So, if you want to only do one iteration, then you can do something like:
const Debouncer = require('@addr/debouncer');
const instance = new Debouncer(
4000,
myData => console.log("I'm being executed after 4s with", myData)
);
instance.shutdownAfterCurrentIteration();
This will shutdown the timer right after the iteration, but can't pass any data. The data received in your callback will be undefined
.
- You can also call these 3 functions by emitting events like so:
instance.emit('shutdown'); // Same as instance.shutdownNow();
instance.emit('shutdownAfterCurrentIteration'); // Same as instance.shutdownAfterCurrentIteration();
instance.emit('reboot'); // Same as instance.reboot();
The purpose is to have the abillity to listen for these events. So, if you have many places in which you do instance.shutdownNow()
and you want to trace
the one tha is being executed, you can replace the calls for instance.emit('shutdown')
and listen to that event as follows:
instance.on('shutdown', () => {
console.trace();
})
And it will print the precise line that emits the event.
- Your callback can return a promise. To get the response (returned value) of your callback, you can listen to the event called
responseFromCallback
like this:
const Debouncer = require('@addr/debouncer');
const instance = new Debouncer(
4000,
myData => new Promise(resolve => resolve("I'm being executed after 4s with " + myData))
);
instance.on('responseFromCallback', console.log); // this will print I'm being executed after 4s with My data
instance.debounce('My data');
- You can prevent the Debouncer from shutting down atomatically by passing
nullIterationsToShutdown
in0
or any falsy value. Example:
const Debouncer = require('@addr/debouncer');
const instance = new Debouncer(
4000,
myData => new Promise(resolve => resolve("I'm being executed after 4s with " + myData)),
{ nullIterationsToShutdown: null } // Any falsy value....undefined, null, 0, '', "", etc
);
instance.debounce('My data');
// This will never stop
Tests
To run the tests you just need to run this command:
$> npm test
Note: Currently I'm still working on the tests. This note will disappear once I have finished all tests.
Examples of use
This library is really useful for auto saving forms. So, if you need an auto save strategy for your app, then you could use this library.