await-timeout

A Promise-based API for setTimeout / clearTimeout

Contents

* Installation
* Usage
* API
* new Timeout()
* .set()
* .wrap()
* .clear()
* .id
* .delay
* Motivation
* Related resources
* License

Installation

``bash
npm install await-timeout --save
`

Usage

1. Just wait some time:
`js
import Timeout from 'await-timeout';

// wait 1000 ms and resolve
await Timeout.set(1000);

// wait 1000 ms and reject with 'Timeout!'
await Timeout.set(1000, 'Timeout!');
`

2. Use Timeout instance inside try...finally block to make proper cleanup:
`js
import Timeout from 'await-timeout';

const timer = new Timeout();
try {
await Promise.race([
fetch('https://example.com'),
timer.set(1000, 'Timeout!')
]);
} finally {
timer.clear();
}
`
> Without a timer cleanup you may get unexpected effects in you code - as all promises in Promise.race
> are get fulfilled.

API

$3

Constructs new timeout instance. It does not start timer but creates variable for timer manipulation.
`js
const timer = new Timeout();
`
> Note: having separate timer variable is useful for clearing timeout in finally block

$3

Starts new timer like setTimeout() and returns promise. The promise will be resolved after delay milliseconds:
`js
const timer = new Timeout();
timer.set(1000)
.then(() => console.log('1000 ms passed.'));
`

If you provide rejectReason - a timer promise will be rejected with specified reason:
`js
// rejects with Error: Timeout after 1000 ms:
timer.set(1000, 'Timeout after 1000 ms');

// above is actually shortcut for:
timer.set(1000).then(() => Promise.reject(new Error('Timeout after 1000 ms')));
`

If you need to just wait some time - use static version of .set():
`js
await Timeout.set(1000);
`

$3

Wraps existing promise with timeout:
* returned promise automatically rejected after timeout
* timeout automatically cleared if main promise resolves first
`js
async function fetchWithTimeout() {
const promise = fetch('https://example.com');
return Timeout.wrap(promise, 1000, 'Timeout');
}
`
Actually it is a shortcut for:
`js
async function fetchWithTimeout() {
const timer = new Timeout();
try {
const promise = fetch('https://example.com');
return await Promise.race([
promise,
timer.set(1000, 'Timeout')
]);
} finally {
timer.clear();
}
}
`

$3

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

With [ES7 async / await] .clear() can be used in finally block:
`js
async function foo() {
const timer = new Timeout();
try {
// some async stuff
} finally {
timer.clear();
}
}
`

$3

Returns result of setTimeout call. That is Number timeout id in browser
and Timeout instance in Node.js.

$3

Returns last delay value used. Delay is useful for generating reject reason:
`js
const timer = new Timeout();
timer.set(1000, () => new Error(Timeout: ${timer.delay}));
`

Motivation

Before making this library I've researched several 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 resolved 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

* The right way to clear timeout in Promise.race()
* Applying a timeout to your promises
* How to make a promise from setTimeout
* Is there a version of setTimeout that returns an ES6 promise?

License

MIT @ Vitaliy Potapov

[Promise]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
[Promise.race()]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race
[ES7 async / await]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function