p-wait-for
Wait for a condition to be true
Can be useful for polling.
Install
npm install p-wait-for
Usage
import pWaitFor from 'p-wait-for';
import {pathExists} from 'path-exists';
await pWaitFor(() => pathExists('unicorn.png'));
console.log('Yay! The file now exists.');
API
pWaitFor(condition, options?)
Returns a Promise that resolves when condition returns true. Rejects if condition throws or returns a Promise that rejects.
condition
Type: Function
Expected to return Promise<boolean> | boolean.
options
Type: object
interval
Type: number
Default: 20
Number of milliseconds to wait after condition resolves to false before calling it again.
timeout
Type: number | TimeoutOptions
Default: Infinity
Number of milliseconds to wait before automatically rejecting with a TimeoutError.
You can customize the timeout Error by specifying TimeoutOptions.
import pWaitFor from 'p-wait-for';
import {pathExists} from 'path-exists';
const originalSetTimeout = setTimeout;
const originalClearTimeout = clearTimeout;
sinon.useFakeTimers();
await pWaitFor(() => pathExists('unicorn.png'), {
timeout: {
milliseconds: 100,
message: new MyError('Time’s up!'),
customTimers: {
setTimeout: originalSetTimeout,
clearTimeout: originalClearTimeout
}
}
});
console.log('Yay! The file now exists.');
milliseconds
Type: number
Default: Infinity
Milliseconds before timing out.
Passing Infinity will cause it to never time out.
message
Type: string | Error
Default: 'Promise timed out after 50 milliseconds'
Specify a custom error message or error.
If you do a custom error, it's recommended to sub-class TimeoutError.
customTimers
Type: object with function properties setTimeout and clearTimeout
Custom implementations for the setTimeout and clearTimeout functions.
Useful for testing purposes, in particular to work around sinon.useFakeTimers().
fallback
Type: Function
Do something other than rejecting with an error on timeout.
Example:
import pWaitFor from 'p-wait-for';
import {pathExists} from 'path-exists';
await pWaitFor(() => pathExists('unicorn.png'), {
timeout: {
milliseconds: 50,
fallback: () => {
console.log('Time’s up! executed the fallback function!');
},
}
});
before
Type: boolean
Default: true
Whether to run the check immediately rather than starting by waiting interval milliseconds.
Useful for when the check, if run immediately, would likely return false. In this scenario, set before to false.
resolveWith(value)
Resolve the main promise with a custom value.
import pWaitFor from 'p-wait-for';
import pathExists from 'path-exists';
const path = await pWaitFor(async () => {
const path = getPath();
return await pathExists(path) && pWaitFor.resolveWith(path);
});
console.log(path);
TimeoutError
Exposed for instance checking.
Related
- p-whilst - Calls a function repeatedly while a condition returns true and then resolves the promise
- More…
