{"id":11112,"library":"isomorphic-timers-promises","title":"Isomorphic Timers Promises","description":"The `isomorphic-timers-promises` package provides a unified, promise-based API for handling asynchronous timers (`setTimeout`, `setImmediate`, `setInterval`) across both client-side browser environments and server-side Node.js runtimes. It serves as a polyfill and consistent interface for the `timers/promises` API introduced in Node.js, ensuring that code relying on these promise-returning timer functions works seamlessly regardless of the execution environment. Currently at stable version 1.0.1, the package is relatively new but offers a direct implementation of the Node.js specification, aiming for high compatibility. Its key differentiator is providing this modern timer API in contexts where it's not natively available, specifically browsers, or older Node.js versions, by abstracting away environmental differences. While it currently ships with version 1.0.1, its release cadence is expected to be stable after its initial minor updates.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/niksy/isomorphic-timers-promises","tags":["javascript","timers","promises","async","promise","settimeout","setinterval","setimmediate"],"install":[{"cmd":"npm install isomorphic-timers-promises","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic-timers-promises","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic-timers-promises","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is primarily designed for ESM usage. CommonJS `require` is generally not recommended as the primary import pattern.","wrong":"const { setTimeout } = require('isomorphic-timers-promises');","symbol":"setTimeout","correct":"import { setTimeout } from 'isomorphic-timers-promises';"},{"note":"All core timer functions are named exports; there is no default export.","wrong":"import setImmediate from 'isomorphic-timers-promises';","symbol":"setImmediate","correct":"import { setImmediate } from 'isomorphic-timers-promises';"},{"note":"The package automatically detects the environment (Node.js/browser), so explicit pathing for browser-specific code is not typically required.","wrong":"import { setInterval as browserSetInterval } from 'isomorphic-timers-promises/browser';","symbol":"setInterval","correct":"import { setInterval } from 'isomorphic-timers-promises';"}],"quickstart":{"code":"import { setTimeout, setImmediate, setInterval } from 'isomorphic-timers-promises';\n\n(async () => {\n\tconsole.log('--- setTimeout ---');\n\tconst result = await setTimeout(100, 'becky');\n\tconsole.log(result); // 'becky'\n})();\n\n(async () => {\n\tconsole.log('--- setImmediate ---');\n\tconst result = await setImmediate('maya');\n\tconsole.log(result); // 'maya'\n})();\n\n(async () => {\n\tconsole.log('--- setInterval (async iterator) ---');\n\tlet result = 0;\n\tfor await (const startTime of setInterval(100, Date.now())) {\n\t\tconst now = Date.now();\n\t\tresult = result + 1;\n\t\tif (now - startTime >= 300) { // Limit to 3 intervals for quick demo\n\t\t\tbreak;\n\t\t}\n\t}\n\tconsole.log(`Intervals completed: ${result}`); // Should be around 3\n})();","lang":"javascript","description":"Demonstrates asynchronous timer functions (`setTimeout`, `setImmediate`, `setInterval`) that return Promises or async iterators, providing consistent timing across Node.js and browser environments."},"warnings":[{"fix":"Configure your bundler's alias resolver (e.g., `resolve.alias` in Webpack, `@rollup/plugin-alias` in Rollup) to map `'timers/promises'` to `'isomorphic-timers-promises'`.","message":"Module bundlers (Webpack, Rollup) require explicit configuration to correctly alias `timers/promises` to `isomorphic-timers-promises` when targeting browser environments, as `timers/promises` is a Node.js built-in module.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Do not rely on `options.ref` when targeting browser environments; for client-side code, assume timers always keep the event loop active or use `AbortSignal` for explicit cancellation.","message":"The `options.ref` parameter, used to control whether a timer requires the event loop to remain active, is only effective in Node.js server environments and will be ignored in browser contexts.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `for await (const value of setInterval(...))` when using `setInterval` to iterate over emitted values in an asynchronous loop.","message":"Unlike `setTimeout` and `setImmediate` which return Promises, `setInterval` returns an async iterator. It must be consumed with `for await...of` to receive emitted values.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add an alias in your bundler configuration (e.g., `webpack.config.js` or `rollup.config.js`) to map `'timers/promises'` to `'isomorphic-timers-promises'`.","cause":"A module bundler (like Webpack or Rollup) is attempting to resolve the Node.js built-in module 'timers/promises' in a browser environment without an alias.","error":"Module not found: Error: Can't resolve 'timers/promises'"},{"fix":"Ensure you are using named imports: `import { setTimeout, setImmediate, setInterval } from 'isomorphic-timers-promises';`","cause":"This error often occurs when attempting to import named exports (like `setTimeout`) as a default export, or using CommonJS `require` syntax in an ESM-only context.","error":"TypeError: (0 , _isomorphicTimersPromises.setTimeout) is not a function"}],"ecosystem":"npm"}