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.
121 lines
2.9 KiB
Markdown
121 lines
2.9 KiB
Markdown
# @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.1 (August 25, 2019)
|
|
|
|
- Fixed documentation formatting.
|
|
|
|
### 1.0.0 (August 25, 2019)
|
|
|
|
Initial release.
|