UNPKG

event-to-promise

Version:
190 lines (126 loc) 4.36 kB
# event-to-promise [![Build Status](https://img.shields.io/travis/JsCommunity/event-to-promise/master.svg)](http://travis-ci.org/JsCommunity/event-to-promise) [![Dependency Status](https://david-dm.org/JsCommunity/event-to-promise/status.svg?theme=shields.io)](https://david-dm.org/JsCommunity/event-to-promise) [![devDependency Status](https://david-dm.org/JsCommunity/event-to-promise/dev-status.svg?theme=shields.io)](https://david-dm.org/JsCommunity/event-to-promise#info=devDependencies) > Create a promise waiting for an event ## Installation ### Node & [Browserify](http://browserify.org/)/[Webpack](https://webpack.js.org/) Installation of the [npm package](https://npmjs.org/package/event-to-promise): ``` > npm install --save event-to-promise ``` Then require the package: ```javascript var eventToPromise = require('event-to-promise'); ``` ### Browser You can directly use the build provided at [unpkg.com](https://unpkg.com): ```html <script src="https://unpkg.com/event-to-promise@0.8/dist/event-to-promise.js"></script> ``` ## Example ```javascript function createServer (port) { var server = require('http').createServer() server.listen(port) // The server will be returned once it has started listening. // // If an error happened, it will be forwarded instead. return eventToPromise(server, 'listening').then(function () { return server }) } // Using plain promise. createServer(80).then(function (server) { console.log('Server listening on http://localhost:80/') }).catch(function (error) { console.error('Server could not start:', error) }) ``` Event better using [ES2016 asynchronous functions](https://github.com/tc39/ecmascript-asyncawait): ```js async function createServer (port) { var server = require('http').createServer() server.listen(port) await eventToPromise(server, 'listening') return server } async function main () { try { const server = await createServer(80); console.log('Server listening on http://localhost:80/'); } catch (error) { console.error('Server could not start:', error); } } main() ``` ## API This library requires promises support, for Node versions prior to 0.12 [see this page](https://github.com/JsCommunity/js-promise-toolbox#usage) to enable them. ### eventToPromise(emitter, event, [options]) => Promise > Wait for one event. The first parameter of the emitted event is used > to resolve/reject the promise. The returned promise has a `cancel()` method which can be used to remove the event listeners. Note that the promise will never settled if canceled. ```js const promise = eventToPromise(emitter, 'foo') promise.cancel() ``` #### emitter *Required* Type: `Object` The event emitter you want to watch an event on. #### event *Required* Type: `string` The name of the event you want to watch. #### options ##### array Type: `boolean` Default: `false` If true, all parameters of the emitted events are put in an array which is used to resolve/reject the promise. ##### error Type: `string` Default: `"error"` The name of the event which rejects the promise. ##### ignoreErrors Type: `boolean` Default: `false` Whether the error event should be ignored and not reject the promise. ### eventToPromise.multi(emitter, successEvents, errorEvents) => Promise > Wait for one of multiple events. The array of all the parameters of > the emitted event is used to resolve/reject the promise. > > The array also has an `event` property indicating which event has > been emitted. The returned promise has a `cancel()` method which can be used to remove the event listeners. Note that the promise will never settled if canceled. ```js const promise = eventToPromise(emitter, 'foo') promise.cancel() ``` #### emitter *Required* Type: `Object` The event emitter you want to watch an event on. #### successEvents *Required* Type: `Array<string>` The names of the events which resolve the promise. #### errorEvents Type: `Array<string>` Default: `[ 'error' ]` The names of the events which reject the promise. ## Contributing Contributions are *very* welcome, either on the documentation or on the code. You may: - report any [issue](https://github.com/JsCommunity/event-to-promise/issues) you've encountered; - fork and create a pull request. ## License ISC © [Julien Fontanet](http://julien.isonoe.net)