timeout-raf
Version:
Bare-bones animation-friendly cancelable timeouts via requestAnimationFrame
98 lines (67 loc) • 2.4 kB
Markdown
# timeout-raf
> Bare-bones animation-friendly cancelable timeouts via requestAnimationFrame
Provides the familiarity of `setTimeout`, but via `requestAnimationFrame`.
Deferred callbacks can be fired immediately or killed.
See "usage" below.
#### Important to consider
The `requestAnimationFrame` approach means your callbacks will likely not fire exactly when you originally instructed.
If things are running at a smooth 60fps, callbacks should generally fire within 16ms of being told to.
Run the tests to see typical results.
## Installation
Install via npm.
```sh
$ npm i timeout-raf
```
## Usage
Require the module - it exposes a single factory function (so there's no need to instantiate instances).
Call as you would `window.setTimeout`, passing a callback and duration.
```js
var timeout = require('timeout-raf');
// typical usage; console.log is called after 1s
timeout(function () {
console.log('1 second later...');
}, 1000);
```
### Passing context as a parameter
You can pass context via an optional third parameter, allowing you to define the context of the callback.
```js
var awesomeObject = {awesome: 'clearly'};
// logs `clearly` after (about) 1 second
timeout(function () {
console.log(this.awesome);
}, 1000, awesomeObject);
```
### Passing context normally
You can also pass context per usual by binding the callback to any object.
```js
var awesomeObject = {awesome: 'clearly'};
// also logs `clearly` after (about) 1 second
timeout(function () {
console.log(this.awesome);
}.bind(awesomeObject), 1000);
```
### Killing a timeout
Keep a reference to the timeout and then call its `kill()` method to prevent it from ever firing its callback.
```js
// never writes to the console...
var to = timeout(function () {
console.log('I am never heard from again');
}, 1000);
to.kill();
```
### Impatient-friendly
You can tell a timeout to fire its callback at any time earlier than originally requested.
Keep a reference to the timeout and call its `fire` method if you get antsy.
The callback will fire immediately, and never again.
```js
// fired after 1 second and never again
var to = timeout(function () {
console.log('I could only wait a second!');
}, 2000);
timeout(function () {
to.fire();
}, 1000);
```
## Tests
Tests can be run in-browser via `npm test`.