tylerjpeterson / timeout-raf

Bare-bones animation-friendly cancelable timeouts via requestAnimationFrame

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.

$ 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.

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.

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.

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.

// 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.

// 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.