await-timeout

A Promise-based API for setTimeout / clearTimeout

Contents

• Installation
• Usage
• API
  • new Timeout()
  • .set()
  • .clear()
• Motivation
• Related resources
• License

Installation

npm install await-timeout --save

Usage

The example below shows usage of timeout with ES7 async / await in try...finally block. It guarantees that timeout will be cleared in case of fetch success or any error:

import Timeout from 'await-timeout';

async function foo() {
  const timeout = new Timeout();
  try {
    const fetchPromise = fetch('https://example.com');
    const timerPromise = timeout.set(1000, 'Timeout!');
    const response = await Promise.race([fetchPromise, timerPromise]);
  } catch (e) {
    console.error(e);
  } finally {
    timeout.clear();
  }
}

The same example using .then:

function foo() {
  const timeout = new Timeout();
  return Promise.race([
    fetch('https://example.com'), 
    timeout.set(1000, 'Timeout!')
  ])
  .then(result => {
    timeout.clear();
    return result;
  })
  .catch(e => {
    timeout.clear();
    console.error(e);
  });
}

API

new Timeout()

Constructs new timeout instance. It does not start timer but creates variable for timer manipulation.

const timeout = new Timeout();

Note: having separate variable is useful for clearing timeout in finally block

.set(ms, [message]) ⇒ Promise

Starts new timer like setTimeout() and returns promise. The promise will be resolved after ms milliseconds:

const timeout = new Timeout();
timeout.set(1000)
  .then(() => console.log('1000 ms passed.'));

If you need to reject after timeout:

timeout.set(1000)
  .then(() => {throw new Error('Timeout')});

Or reject with custom error:

timeout.set(1000)
  .then(() => {throw new MyTimeoutError()});

The second parameter message is just convenient way to reject with new Error(message):

timeout.set(1000, 'Timeout');
// equivalent to
timeout.set(1000).then(() => {throw new Error('Timeout')});

If you need to just wait some time - use static version of .set():

Timeout.set(1000).then(...);

.clear()

Clears existing timeout like clearTimeout().

const timeout = new Timeout();
timeout.set(1000)
  .then(() => console.log('This will never be called, because timeout is cleared on the next line'));
timeout.clear();

With ES7 async / await .clear() can be used in finally block:

async function foo() {
  const timeout = new Timeout();
  try {
    // some async stuff
  } finally {
    timeout.clear();
  }
}

Motivation

Before making this library I've researched many similar packages on Npm. But no one satisfied all my needs together:

1. Convenient way to cancel timeout. I typically use it with Promise.race() and don't want timer to trigger if main promise is fulfilled first.
2. API similar to setTimeout / clearTimeout. I get used to these functions and would like to have mirror syntax.
3. Easy rejection of timeout promise. Passing error message should be enough.
4. No monkey-patching of Promise object.
5. Zero dependencies.

Related resources

• https://italonascimento.github.io/applying-a-timeout-to-your-promises/
• https://stackoverflow.com/questions/22707475/how-to-make-a-promise-from-settimeout
• https://stackoverflow.com/questions/34255351/is-there-a-version-of-settimeout-that-returns-an-es6-promise

License

MIT @ Vitaliy Potapov