@darkobits/sleep

This package provides a means to pause JavaScript execution.

Install

npm install @darkobits/sleep

Use

The most common way to use this tool is asynchronously using async / await. This will pause the execution of code within the current function without blocking the main thread.

If a second parameter is provided, the following rules will be followed:

1. If the value is an instance of Error (including anything that subclasses it), reject with the error after the provided delay.
2. If any other value is provided, resolve after the provided delay with the value.

import sleep from '@darkobits/sleep';

// Wait for 5 seconds:
await sleep(5000);

// Or, wait for 5 seconds:
await sleep('5 seconds');

// Or, wait for 5 seconds:
await sleep('5s');

// Or, wait for 5 seconds and resolve with a value:
const foo = await sleep('5 seconds', 'foo');

// Or, wait for 5 seconds and reject with an error:
try {
  await sleep('5s', new Error('Barnacles!'));
} catch (err) {
  console.error(err.message) // 'Barnacles!'
}

Synchronous Usage

This package provides a means to pause execution of the main JavaScript thread using SharedArrayBuffer and Atomics.wait, which will not spike CPU usage like while loops and other approaches.

import sleep from '@darkobits/sleep';

// Wait for 5 seconds:
sleep.sync(5000);

// Or, wait for 5 seconds:
sleep.sync('5 seconds');

// Or, wait for 5 seconds:
sleep.sync('5s');

// Or, wait for 5 seconds and return a value:
const foo = sleep.sync('5 seconds', 'foo');

// Or, wait for 5 seconds and throw an error:
try {
  sleep.sync('5s', new Error('Barnacles!'));
} catch (err) {
  console.error(err.message) // 'Barnacles!'
}

Caveats

• The APIs required for sleep.sync to work (specifically SharedArrayBuffer) may not be available in all browser contexts. For more information, see this article.
• The maximum timeout value that can be passed to setTimeout is 2_147_483_647 milliseconds; the maximum value that can be represented in a signed 32-bit integer. Passing a value larger than this will cause a TimeoutOverflowWarning and the timeout will be set to 1. This value turns out to be just under 25 days, and is therefore far longer than any reasonable use should require. However, since this is primarily a tool for debugging and development, any timeout value that exceeds the maximum will be coerced to the maximum value so that things like sleep(Infinity) will not violate the Principle of Least Astonishment.