Isomorphic Timers Promises

Common errors

• Module not found: Error: Can't resolve '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.
  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'`.

• TypeError: (0 , _isomorphicTimersPromises.setTimeout) is not a function

  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.
  fix Ensure you are using named imports: `import { setTimeout, setImmediate, setInterval } from 'isomorphic-timers-promises';`

Warnings

• gotcha 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.
  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'`.
• gotcha 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.
  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.
• gotcha Unlike `setTimeout` and `setImmediate` which return Promises, `setInterval` returns an async iterator. It must be consumed with `for await...of` to receive emitted values.
  Fix: Always use `for await (const value of setInterval(...))` when using `setInterval` to iterate over emitted values in an asynchronous loop.

Install

• npm install isomorphic-timers-promises npm
• yarn add isomorphic-timers-promises yarn
• pnpm add isomorphic-timers-promises pnpm

Imports

• setTimeout
  wrong:

  const { setTimeout } = require('isomorphic-timers-promises');

  correct:

  import { setTimeout } from 'isomorphic-timers-promises';

  The package is primarily designed for ESM usage. CommonJS `require` is generally not recommended as the primary import pattern.
• setImmediate
  wrong:

  import setImmediate from 'isomorphic-timers-promises';

  correct:

  import { setImmediate } from 'isomorphic-timers-promises';

  All core timer functions are named exports; there is no default export.
• setInterval
  wrong:

  import { setInterval as browserSetInterval } from 'isomorphic-timers-promises/browser';

  correct:

  import { setInterval } from 'isomorphic-timers-promises';

  The package automatically detects the environment (Node.js/browser), so explicit pathing for browser-specific code is not typically required.

Quickstart

Demonstrates asynchronous timer functions (`setTimeout`, `setImmediate`, `setInterval`) that return Promises or async iterators, providing consistent timing across Node.js and browser environments.

import { setTimeout, setImmediate, setInterval } from 'isomorphic-timers-promises';

(async () => {
	console.log('--- setTimeout ---');
	const result = await setTimeout(100, 'becky');
	console.log(result); // 'becky'
})();

(async () => {
	console.log('--- setImmediate ---');
	const result = await setImmediate('maya');
	console.log(result); // 'maya'
})();

(async () => {
	console.log('--- setInterval (async iterator) ---');
	let result = 0;
	for await (const startTime of setInterval(100, Date.now())) {
		const now = Date.now();
		result = result + 1;
		if (now - startTime >= 300) { // Limit to 3 intervals for quick demo
			break;
		}
	}
	console.log(`Intervals completed: ${result}`); // Should be around 3
})();