GitHub - vitalets/await-timeout: A Promise-based API for setTimeout / clearTimeo...
source link: https://github.com/vitalets/await-timeout
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
README.md
await-timeout
A Promise-based API for setTimeout / clearTimeout
Contents
Installation
npm install await-timeout --save
Usage
-
Just wait some time:
import Timeout from 'await-timeout'; // wait 1000 ms and resolve await Timeout.set(1000); // wait 1000 ms and reject with 'Error' await Timeout.set(1000, 'Error');
-
Use
Timeout
instance insidetry...finally
block to make proper cleanup:import Timeout from 'await-timeout'; const timer = new Timeout(); try { await Promise.race([ fetch('https://example.com'), timer.set(1000) .then(() => Promise.reject('Timeout')) ]); } finally { timer.clear(); }
API
new Timeout()
Constructs new timeout instance. It does not start timer but creates variable for timer manipulation.
const timer = new Timeout();
Note: having separate variable is useful for clearing timeout in
finally
block
.set(delay, [rejectReason]) ⇒ Promise
Starts new timer like setTimeout()
and returns promise. The promise will be resolved after delay
milliseconds:
const timer = new Timeout(); timer.set(1000) .then(() => console.log('1000 ms passed.'));
If you need to reject after timeout:
timer.set(1000) .then(() => {throw new Error('Timeout')});
Or reject with custom error:
timer.set(1000) .then(() => {throw new MyTimeoutError()});
The second parameter message
is just convenient way to reject with new Error(message)
:
timer.set(1000, 'Timeout'); // is equivalent to timer.set(1000).then(() => {throw new Error('Timeout')});
If you need to just wait some time - use static version of .set()
:
await Timeout.set(1000);
.wrap(promise, delay, [rejectReason]) ⇒ Promise
Wraps existing promise with timeout:
- promise automatically rejected after timeout
- timeout automatically cleared if promise fulfills first
const promise = fetch('https://example.com'); const timeoutedPromise = Timeout.wrap(promise, 1000, 'Timeout');
Actually it is a shortcut for:
const promise = fetch('https://example.com'); const timer = new Timeout(); try { const timeoutedPromise = await Promise.race([ promise, timer.set(1000, 'Timeout') ]); } finally { timer.clear(); }
.clear()
Clears existing timeout like clearTimeout()
.
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:
async function foo() { const timer = new Timeout(); try { // some async stuff } finally { timer.clear(); } }
.id ⇒ ?Number|?Timeout
Returns result of setTimeout
call. That is Number
timeout id in browser
and Timeout instance in Node.js.
.delay ⇒ ?Number
Returns last delay value used. Delay is useful for generating reject reason:
const timer = new Timeout(); timer.set(1000, () => new Error(`Timeout: ${timer.delay}`));
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
- 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
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK