A polyfill for the setImmediate efficient script yielding API

npm install immediate
259 downloads in the last day
1 218 downloads in the last week
5 470 downloads in the last month

testling status


immediate.js is a setImmediate polyfill, based on NobleJS's setImmediate, but stealing the best ideas from Cujo's When and RSVP.

immediate takes the tricks from setImmedate and RSVP and combines them with the schedualer from when to make a low latency polyfill.

The Tricks


Node.js has had a working version of setImmediate since version 0.9, so on Node.js we use that. But in Internet Explorer 10 which has a broken version of setImmediate we avoid using this.


In Node.js versions below 0.9, setImmediate is not available, but process.nextTick is, so we use it to shim support for a global setImmediate. In Node.js 0.9 and above, setImmediate is available.

Note that we check for actual Node.js environments, not emulated ones like those produced by browserify or similar. Such emulated environments often already include a process.nextTick shim that's not as browser-compatible as setImmediate.js.


This is what RSVP uses, it's very fast, details on MDN


In Firefox 3+, Internet Explorer 9+, all modern WebKit browsers, and Opera 9.5+, postMessage is available and provides a good way to queue tasks on the event loop. It's quite the abuse, using a cross-document messaging protocol within the same document simply to get access to the event loop task queue, but until there are native implementations, this is the best option.

Note that Internet Explorer 8 includes a synchronous version of postMessage. We detect this, or any other such synchronous implementation, and fall back to another trick.


Unfortunately, postMessage has completely different semantics inside web workers, and so cannot be used there. So we turn to MessageChannel, which has worse browser support, but does work inside a web worker.

<script> onreadystatechange

For our last trick, we pull something out to make things fast in Internet Explorer versions 6 through 8: namely, creating a <script> element and firing our calls in its onreadystatechange event. This does execute in a future turn of the event loop, and is also faster than setTimeout(…, 0), so hey, why not?


In the browser, include it with a <script> tag; pretty simple. Creates a global called immediate which should act like setImmediate. It also has a method called clear which should act like clearImmediate.

In Node.js, do

npm install immediate


var immediate = require("immediate");

somewhere early in your app; it attaches to the global.

Reference and Reading

npm loves you