A Promise-based API for setTimeout / clearTimeout
npm install await-timeout --save
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);
});
}
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
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(...);
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();
}
}
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.
- 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
MIT @ Vitaliy Potapov