Registry / web-framework / isomorphic-timers-promises

isomorphic-timers-promises

library1.0.1jsnpmunverified

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.

web-framework http-networking

npm install isomorphic-timers-promises

github ↗package ↗

INSTALL

IMPORT

SIG · ISOMORPHIC-TIMERS-

isomorphic-timers-promises

web-frameworkjavascriptv1.0.1

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.

setTimeout

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

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

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

setImmediate

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

✗ import setImmediate from 'isomorphic-timers-promises';

All core timer functions are named exports; there is no default export.

setInterval

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

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

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

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 })();

Debug

Known issues

gotchaModule 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'`.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaUnlike `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.

affects: >=1.0.0

Errors

Common errors & fixes

Module not found: Error: Can't resolve 'timers/promises'

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

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';`

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/niksy/isomorphic-timers-promises ↗

packagehttps://www.npmjs.com/package/isomorphic-timers-promises ↗