You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
115 lines
2.8 KiB
Markdown
115 lines
2.8 KiB
Markdown
5 years ago
|
# @joepie91/timer
|
||
|
|
||
|
A resettable timer abstraction, with cancellation events. Typical usecases might include handling screen display timeouts, debouncing actions, and so on.
|
||
|
|
||
|
Calling the function exported by this module will get you a timer object, which can be started/stopped as needed. Starting an already-running timer first stops it (triggering the cancellation handler) and then starts it again.
|
||
|
|
||
|
The timeout and handlers can be defined both in the initial function call that creates the object, as well as in the arguments to the `start(...)` method.
|
||
|
|
||
|
The full API documentation can be found below the usage examples.
|
||
|
|
||
|
## Examples
|
||
|
|
||
|
A simple example:
|
||
|
|
||
|
```js
|
||
|
"use strict";
|
||
|
|
||
|
const timer = require("@joepie91/timer");
|
||
|
|
||
|
let someTimer = timer({
|
||
|
timeout: 500,
|
||
|
onFire: () => {
|
||
|
console.log("Fired 1");
|
||
|
},
|
||
|
onCancel: () => {
|
||
|
console.log("Cancelled 1");
|
||
|
}
|
||
|
});
|
||
|
|
||
|
someTimer.start();
|
||
|
/*
|
||
|
After 500ms:
|
||
|
Fired 1
|
||
|
*/
|
||
|
```
|
||
|
|
||
|
A more complex example, demonstrating resettability and cancellation handlers:
|
||
|
|
||
|
```js
|
||
|
"use strict";
|
||
|
|
||
|
const timer = require("@joepie91/timer");
|
||
|
|
||
|
let someTimer = timer({
|
||
|
timeout: 500,
|
||
|
onFire: () => {
|
||
|
console.log("Fired 1");
|
||
|
|
||
|
someTimer.start({
|
||
|
onFire: () => {
|
||
|
console.log("Fired 2");
|
||
|
}
|
||
|
});
|
||
|
|
||
|
setTimeout(() => {
|
||
|
someTimer.start({
|
||
|
timeout: 600,
|
||
|
onFire: () => {
|
||
|
console.log("Fired 3");
|
||
|
}
|
||
|
});
|
||
|
}, 200);
|
||
|
},
|
||
|
onCancel: () => {
|
||
|
console.log("Cancelled!");
|
||
|
}
|
||
|
});
|
||
|
|
||
|
someTimer.start();
|
||
|
/*
|
||
|
After 500ms:
|
||
|
Fired 1
|
||
|
200ms later:
|
||
|
Cancelled!
|
||
|
600ms later:
|
||
|
Fired 3
|
||
|
*/
|
||
|
```
|
||
|
|
||
|
## API
|
||
|
|
||
|
### timer(options)
|
||
|
|
||
|
Returns a new `timerObject`. The returned timer does *not* start running until you call its `start` method!
|
||
|
|
||
|
Arguments:
|
||
|
- __options:__
|
||
|
- __timeout:__ The timeout, in milliseconds, after which the timer should 'fire' by default.
|
||
|
- __onFire:__ A callback that will be called when the timer fires (ie. hits the timeout).
|
||
|
- __onCancel:__ *Optional.* A callback that will be called when the timer is cancelled (ie. stopped prematurely).
|
||
|
|
||
|
### timerObject.start([options])
|
||
|
|
||
|
Starts the timer (anew), first stopping it if it's already running.
|
||
|
|
||
|
Arguments:
|
||
|
- __options:__ *Optional.* These settings will override the options that were used to create the `timerObject`, but *only* for this run.
|
||
|
- __timeout:__ *Optional.* The timeout, in milliseconds, after which the timer should 'fire' on *this run*.
|
||
|
- __onFire:__ *Optional.* A callback that will be called when the timer fires on *this run*.
|
||
|
- __onCancel:__ *Optional.* A callback that will be called when *this run* of the timer is cancelled.
|
||
|
|
||
|
### timerObject.stop()
|
||
|
|
||
|
Attempts to stop the timer, triggering the cancellation handler if the timer was still running. If the timer was already stopped, this does nothing.
|
||
|
|
||
|
### timerObject.isRunning()
|
||
|
|
||
|
Returns a boolean indicating whether the timer is currently running or not.
|
||
|
|
||
|
## Changelog
|
||
|
|
||
|
### 1.0.0 (August 25, 2019)
|
||
|
|
||
|
Initial release.
|