Promisify an event by waiting for it to be emitted
Useful when you need only one event emission and want to use it with promises or await it in an async function.
It's works with any event API in Node.js and the browser (using a bundler).
If you want multiple individual events as they are emitted, this module is not for you, as a Promise is a single value. Instead, just continue using event callback or use Observables.
$ npm install p-event
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
(async () => {
try {
await pEvent(emitter, 'finish');
// `emitter` emitted a `finish` event
console.log(result);
} catch (error) {
// `emitter` emitted an `error` event
console.error(error);
}
})();const pEvent = require('p-event');
(async () => {
await pEvent(document, 'DOMContentLoaded');
console.log('😎');
})();Returns a Promise that is fulfilled when emitter emits an event matching event, or rejects if emitter emits any of the events defined in the rejectionEvents option.
The returned promise has a .cancel() method, which when called, removes the event listeners and causes the promise to never be settled.
Type: Object
Event emitter object.
Should have either a .on()/.addListener()/.addEventListener() and .off()/.removeListener()/.removeEventListener() method, like the Node.js EventEmitter and DOM events.
Type: string
Name of the event to listen to.
If the same event is defined both here and in rejectionEvents, this one takes priority.
Type: Object
Type: Array
Default: ['error']
Events that will reject the promise.
Type: boolean
Default: false
By default, the promisified function will only return the first argument from the event callback, which works fine for most APIs. This option can be useful for APIs that return multiple arguments in the callback. Turning this on will make it return an array of all arguments from the callback, instead of just the first argument. This also applies to rejections.
Example:
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
(async () => {
const [foo, bar] = await pEvent(emitter, 'finish', {multiArgs: true});
})();Type: Number
Default: Infinity
Time in milliseconds before timing out.
Type: Function
Filter function for accepting an event.
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
(async () => {
const result = await pEvent(emitter, '🦄', value => value > 3);
// Do something with first 🦄 event with a value greater than 3
})();const fs = require('fs');
function getOpenReadStream(file, callback) {
const stream = fs.crea
735B
teReadStream(file);
stream.on('open', () => {
callback(null, stream);
});
stream.on('error', error => {
callback(error);
});
}
getOpenReadStream('unicorn.txt', (error, stream) => {
if (error) {
console.error(error);
return;
}
console.log('File descriptor:', stream.fd);
stream.pipe(process.stdout);
});const fs = require('fs');
const pEvent = require('p-event');
async function getOpenReadStream(file) {
const stream = fs.createReadStream(file);
await pEvent(stream, 'open');
return stream;
}
(async () => {
const stream = await getOpenReadStream('unicorn.txt');
console.log('File descriptor:', stream.fd);
stream.pipe(process.stdout);
})().catch(console.error);MIT © Sindre Sorhus