setimmediate

library1.0.5jsnpmunverified

The `setImmediate.js` package provides a robust, cross-browser polyfill and shim for the `setImmediate` and `clearImmediate` APIs, originally proposed by Microsoft to the Web Performance Working Group. On its current stable version 1.0.5 (last updated in 2016), it bridges the gap for efficient, non-blocking asynchronous execution, especially in older or less-spec-compliant environments. Unlike `setTimeout(..., 0)` or `process.nextTick` (in newer Node.js), `setImmediate` queues a task on the *macrotask* queue, yielding control back to the event loop before execution, allowing for rendering or I/O to occur. It differentiates itself by employing various "clever tricks" such as `postMessage`, `MessageChannel`, and historical browser-specific hacks (`<script> onreadystatechange`, `process.nextTick` in older Node) to achieve optimal performance and correct macrotask semantics across IE6+, Firefox 3+, WebKit, Opera 9.5+, and Node.js. In environments where these tricks aren't viable, it gracefully falls back to `setTimeout`, ensuring universal compatibility.

serialization

npm install setimmediate

github ↗package ↗

INSTALL

IMPORT

SIG · SETIMMEDIATE

setimmediate

serializationjavascriptv1.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

setImmediate

✓ // In Node.js: require('setimmediate'); // In browser: Include <script src="setimmediate.js"></script> // (setImmediate becomes a global function)

✗ import { setImmediate } from 'setimmediate';

This package primarily operates by patching the global scope, making `setImmediate` available globally without explicit named imports in the consumer's module. The `require('setimmediate')` statement in Node.js is for its side effect of polyfilling the global object.

clearImmediate

✓ // No explicit import needed; `clearImmediate` is made global.

✗ import { clearImmediate } from 'setimmediate';

Similar to `setImmediate`, `clearImmediate` is exposed globally as a side effect of loading the package, without requiring a specific module import for the function itself.

(Module side effect)

✓ require('setimmediate');

✗ import * as setimmediate from 'setimmediate';

This CommonJS `require` statement is the intended way to load the polyfill in Node.js environments. Its primary purpose is to execute the module's code, which then patches the global scope with `setImmediate` and `clearImmediate`.

Demonstrates how to use the globally available `setImmediate` for non-blocking asynchronous execution, highlighting its macrotask semantics compared to microtasks like Promises or `process.nextTick`.

require('setimmediate'); console.log('Start script'); let count = 0; function processNextItem() { if (count < 3) { console.log(`Processing item ${count}`); count++; // Use setImmediate to yield to the event loop, then continue processing. // This allows I/O, rendering, or other macrotasks to run between calls. setImmediate(processNextItem); } else { console.log('Finished processing items.'); } } setImmediate(processNextItem); // Kick off the first task console.log('Script end (synchronous part)'); // Demonstrating macrotask vs. microtask execution order: Promise.resolve().then(() => console.log('Promise microtask executed')); process.nextTick(() => console.log('process.nextTick microtask executed')); // setImmediate will run *after* all microtasks are exhausted and before the next rendering/I/O turn.

Debug

Known issues

gotchaThe `setImmediate` API operates on the macrotask queue, which is fundamentally different from the microtask queue used by `Promise.then()`, `queueMicrotask()`, and `process.nextTick()` (in Node.js v0.9+). Misunderstanding this distinction can lead to unexpected execution order and race conditions when mixing macrotask and microtask scheduling.

fix

Always be explicit about whether macrotask (e.g., `setImmediate`, `setTimeout`, I/O events) or microtask (e.g., Promises, `process.nextTick`) semantics are required for your asynchronous operations. If you need immediate execution within the same event loop tick, use a microtask-based solution.

affects: >=1.0.0

breakingVersion 1.0.4 reverted the `<img> onerror` trick used in 1.0.3 and earlier versions for browser-based scheduling, because it was found not to be reliably asynchronous. This change impacts environments where that specific trick was used, ensuring more correct async behavior.

fix

Upgrade to `setimmediate@1.0.4` or newer to ensure robust and correctly asynchronous behavior across all supported browser environments.

affects: =1.0.3

gotchaOlder versions of `setimmediate.js` (pre-1.0.3) used `eval` to obtain the global object when `setImmediate` was invoked with string arguments, which could lead to Content Security Policy (CSP) violations in strict environments.

fix

Update to `setimmediate@1.0.3` or newer. If upgrading is not an option, avoid using string arguments with `setImmediate` (e.g., `setImmediate("myFunction()")`); instead, pass a direct function reference (e.g., `setImmediate(myFunction)`).

affects: <1.0.3

Errors

Common errors & fixes

ReferenceError: setImmediate is not defined

The `setImmediate` polyfill was not loaded or executed in the current environment before `setImmediate` was called.

fix

In Node.js, ensure `require('setimmediate');` is called at the application's entry point. In browser environments, verify that the `<script>` tag loading `setimmediate.js` is correctly placed and loaded before any calls to `setImmediate`.

Content Security Policy: The page’s settings blocked the loading of a resource at inline (‘script-src’...)

Using an older version of `setimmediate.js` (prior to 1.0.3) and passing string arguments to `setImmediate` in a browser environment with a strict Content Security Policy.

fix

Upgrade the `setimmediate` package to version 1.0.3 or newer. If an upgrade is not feasible, ensure that `setImmediate` is always called with a function reference, never with a string that would require `eval`.

Error: Calling `setImmediate` inside a Promise.then() handler results in unexpected ordering.

Misunderstanding the execution order difference between microtasks (like `Promise.then()` and `process.nextTick()`) and macrotasks (`setImmediate`, `setTimeout`). `setImmediate` will always run after all microtasks have been exhausted within a given event loop turn.

fix

Rethink the asynchronous flow. If an operation needs to run immediately after a Promise resolves, it should be chained with another `.then()`. If it explicitly needs to yield to the event loop for I/O or rendering before executing, `setImmediate` is correct, but be aware of its position in the task queue relative to microtasks.

Upgrade

Version history

1.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/yuzujs/setImmediate ↗

packagehttps://www.npmjs.com/package/setimmediate ↗