Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sindresorhus/p-wait-for
Wait for a condition to be true
https://github.com/sindresorhus/p-wait-for
Last synced: about 2 months ago
JSON representation
Wait for a condition to be true
- Host: GitHub
- URL: https://github.com/sindresorhus/p-wait-for
- Owner: sindresorhus
- License: mit
- Created: 2016-10-21T06:52:18.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2023-06-11T11:18:05.000Z (about 1 year ago)
- Last Synced: 2024-04-14T00:32:39.557Z (3 months ago)
- Language: JavaScript
- Size: 32.2 KB
- Stars: 149
- Watchers: 8
- Forks: 19
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Funding: .github/funding.yml
- License: license
- Security: .github/security.md
Lists
- awesome-promises - p-wait-for - Wait for a condition to be true (Convenience Utilities / sindresorhus's many Promise utilities ([see notes](https://github.com/sindresorhus/promise-fun)))
- promise-fun - p-wait-for
- awesome-stars - p-wait-for
- awesome-stars - p-wait-for
README
# p-wait-for
> Wait for a condition to be true
Can be useful for polling.
## Install
```sh
npm install p-wait-for
```
## Usage
```js
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`.
#### 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`.
```js
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()`](https://sinonjs.org/releases/latest/fake-timers/).
###### fallback
Type: `Function`
Do something other than rejecting with an error on timeout.
Example:
```js
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.
```js
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](https://github.com/sindresorhus/p-whilst) - Calls a function repeatedly while a condition returns true and then resolves the promise
- [More…](https://github.com/sindresorhus/promise-fun)