Package Exports
- await-timeout
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (await-timeout) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme

await-timeout
A Promise-based API for setTimeout / clearTimeout
Contents
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:
- 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.
- API similar to
setTimeout
/clearTimeout
. I get used to these functions and would like to have mirror syntax. - Easy rejection of timeout promise. Passing error message should be enough.
- No monkey-patching of Promise object.
- 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