worker-timers

What is worker-timers?

The worker-timers npm package provides timer functions (setTimeout, setInterval, and clearTimeout) that run in Web Workers. This allows for more accurate timing and less interference from the main thread, which can be beneficial for performance-sensitive applications.

What are worker-timers's main functionalities?

setTimeout

The setTimeout function schedules a function to be executed after a specified delay, in milliseconds. This is similar to the native setTimeout but runs in a Web Worker for more accurate timing.

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

setTimeout(() => {
  console.log('This runs after 1000ms');
}, 1000);

setInterval

The setInterval function repeatedly calls a function with a fixed time delay between each call. This is similar to the native setInterval but runs in a Web Worker for more consistent intervals.

const { setInterval } = require('worker-timers');

setInterval(() => {
  console.log('This runs every 1000ms');
}, 1000);

clearTimeout

The clearTimeout function cancels a timeout previously established by calling setTimeout. This is similar to the native clearTimeout but works with the worker-timers setTimeout.

const { setTimeout, clearTimeout } = require('worker-timers');

const timeoutId = setTimeout(() => {
  console.log('This will not run');
}, 1000);

clearTimeout(timeoutId);

clearInterval

The clearInterval function cancels a repeated action which was established by a call to setInterval. This is similar to the native clearInterval but works with the worker-timers setInterval.

const { setInterval, clearInterval } = require('worker-timers');

const intervalId = setInterval(() => {
  console.log('This will not run');
}, 1000);

clearInterval(intervalId);

Other packages similar to worker-timers

worker-timer

The worker-timer package provides similar functionality by running timer functions in Web Workers. It aims to provide more accurate timing and less interference from the main thread, similar to worker-timers.

README

worker-timers

A replacement for setInterval() and setTimeout() which works in unfocused windows.

Motivation

For scripts that rely on WindowTimers like setInterval() or setTimeout() things get confusing when the site which the script is running on loses focus. Chrome, Firefox and maybe others throttle the frequency of firing those timers to a maximum of once per second in such a situation. However this is only true for the main thread and does not affect the behavior of Web Workers. Therefore it is possible to avoid the throttling by using a worker to do the actual scheduling. This is exactly what WorkerTimers do.

Getting Started

WorkerTimers are available as a package on npm. Simply run the following command to install it:

npm install worker-timers

You can then require the workerTimers instance from within your code like this:

import * as workerTimers from 'worker-timers';

The usage is exactly the same (despite of the error handling and the differentiation between intervals and timeouts) as with the corresponding functions on the global scope.

var intervalId = workerTimers.setInterval(() => {
    // do something many times
}, 100);

workerTimers.clearInterval(intervalId);

var timeoutId = workerTimers.setTimeout(() => {
    // do something once
}, 100);

workerTimers.clearTimeout(timeoutId);

Error Handling

The native WindowTimers are very forgiving. Calling clearInterval() or clearTimeout() without a value or with an id which doesn't exist will just get ignored. In contrast to that workerTimers will throw an error when doing so.

// This will just return undefined.
window.clearTimeout('not-an-timeout-id');

// This will throw an error.
workerTimers.clearTimeout('not-an-timeout-id');

Differentiation between Intervals and Timeouts

Another difference between workerTimers and WindowTimers is that this package maintains two separate lists to store the ids of intervals and timeouts internally. WindowTimers do only have one list which allows intervals to be cancelled by calling clearTimeout() and the other way round. This is not possible with workerTimers. As mentioned above workerTimers will throw an error when provided with an unknown id.

const periodicWork = () => {};

// This will stop the interval.
const windowId = window.setInterval(periodicWork, 100);
window.clearTimeout(windowId);

// This will throw an error.
const workerId = workerTimers.setInterval(periodicWork, 100);
workerTimers.clearTimeout(workerId);

Server-Side Rendering

This package is intended to be used in the browser and requires the browser to have support for Web Workers. It does not contain any fallback which would allow it to run in another environment like Node.js which doesn't know about Web Workers. This is to prevent this package from silently failing in an unsupported browser. But it also means that it needs to be replaced when used in a web project which also supports server-side rendering. That should be easy, at least in theory, because each function has the exact same signature as its corresponding builtin function. But the configuration of a real-life project can of course be tricky. For a concrete example, please have a look at the worker-timers-ssr-example provided by @newyork-anthonyng. It shows the usage inside of a server-side rendered React app.

Angular (& zone.js)

If WorkerTimers are used inside of an Angular App and Zones are used to detect changes, the behavior of WorkerTimers can be confusing. Angular is using a Zone which is patching the native setInterval() and setTimeout() functions to get notified about the execution of their callback functions. But Angular (more specifically zone.js) is not aware of WorkerTimers and doesn't patch them. Therefore Angular needs to be notified manually about state changes that occur inside of a callback function which was scheduled with the help of WorkerTimers.