Skip to content

Commit

Permalink
Meta tweaks
Browse files Browse the repository at this point in the history
  • Loading branch information
sindresorhus committed Apr 19, 2020
1 parent 3bc427f commit 5116832
Show file tree
Hide file tree
Showing 5 changed files with 21 additions and 31 deletions.
2 changes: 1 addition & 1 deletion index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ declare const pEvent: {
): pEvent.CancelablePromise<EmittedType[]>;

/**
@returns An [async iterator](http://2ality.com/2016/10/asynchronous-iteration.html) that lets you asynchronously iterate over events of `event` emitted from `emitter`. The iterator ends when `emitter` emits an event matching any of the events defined in `resolutionEvents`, or rejects if `emitter` emits any of the events defined in the `rejectionEvents` option.
@returns An [async iterator](https://2ality.com/2016/10/asynchronous-iteration.html) that lets you asynchronously iterate over events of `event` emitted from `emitter`. The iterator ends when `emitter` emits an event matching any of the events defined in `resolutionEvents`, or rejects if `emitter` emits any of the events defined in the `rejectionEvents` option.
@example
```
Expand Down
2 changes: 1 addition & 1 deletion index.js
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ module.exports.iterator = (emitter, event, options) => {
}

// Allow multiple events
const events = normalizeEvents(event);
const events = toArray(event);

options = {
rejectionEvents: ['error'],
Expand Down
2 changes: 1 addition & 1 deletion license
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

Expand Down
5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@
"description": "Promisify an event by waiting for it to be emitted",
"license": "MIT",
"repository": "sindresorhus/p-event",
"funding": "https://github.com/sponsors/sindresorhus",
"author": {
"name": "Sindre Sorhus",
"email": "sindresorhus@gmail.com",
"url": "sindresorhus.com"
"url": "https://sindresorhus.com"
},
"engines": {
"node": ">=8"
Expand Down Expand Up @@ -49,7 +50,7 @@
"@types/node": "^12.0.2",
"ava": "^1.4.1",
"delay": "^4.1.0",
"tsd": "^0.7.3",
"tsd": "^0.11.0",
"xo": "^0.24.0"
}
}
41 changes: 15 additions & 26 deletions readme.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# p-event [![Build Status](https://travis-ci.org/sindresorhus/p-event.svg?branch=master)](https://travis-ci.org/sindresorhus/p-event)
# p-event [![Build Status](https://travis-ci.com/sindresorhus/p-event.svg?branch=master)](https://travis-ci.com/sindresorhus/p-event)

> Promisify an event by waiting for it to be emitted
Expand All @@ -8,14 +8,12 @@ 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, you can use the `pEvent.iterator()` method. [Observables](https://medium.com/@benlesh/learning-observable-by-building-observable-d5da57405d87) can be useful too.


## Install

```
$ npm install p-event
```


## Usage

In Node.js:
Expand Down Expand Up @@ -65,10 +63,9 @@ const emitter = require('./some-event-emitter');
})();
```


## API

### pEvent(emitter, event, [options])
### pEvent(emitter, event, options?)
### pEvent(emitter, event, filter)

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.
Expand All @@ -80,7 +77,7 @@ The returned promise has a `.cancel()` method, which when called, removes the ev

#### emitter

Type: `Object`
Type: `object`

Event emitter object.

Expand All @@ -96,18 +93,18 @@ If the same event is defined both here and in `rejectionEvents`, this one takes

#### options

Type: `Object`
Type: `object`

##### rejectionEvents

Type: `string[]`<br>
Type: `string[]`\
Default: `['error']`

Events that will reject the promise.

##### multiArgs

Type: `boolean`<br>
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.
Expand All @@ -125,7 +122,7 @@ const emitter = require('./some-event-emitter');

##### timeout

Type: `number`<br>
Type: `number`\
Default: `Infinity`

Time in milliseconds before timing out.
Expand Down Expand Up @@ -154,18 +151,18 @@ This method has the same arguments and options as `pEvent()` with the addition o

#### options

Type: `Object`
Type: `object`

##### count

*Required*<br>
*Required*\
Type: `number`

The number of times the event needs to be emitted before the promise resolves.

##### resolveImmediately

Type: `boolean`<br>
Type: `boolean`\
Default: `false`

Whether to resolve the promise immediately. Emitting one of the `rejectionEvents` won't throw an error.
Expand Down Expand Up @@ -204,32 +201,31 @@ console.log(result);
//=> ['Jack', 'Mark']
```

### pEvent.iterator(emitter, event, [options])
### pEvent.iterator(emitter, event, options?)
### pEvent.iterator(emitter, event, filter)

Returns an [async iterator](http://2ality.com/2016/10/asynchronous-iteration.html) that lets you asynchronously iterate over events of `event` emitted from `emitter`. The iterator ends when `emitter` emits an event matching any of the events defined in `resolutionEvents`, or rejects if `emitter` emits any of the events defined in the `rejectionEvents` option.
Returns an [async iterator](https://2ality.com/2016/10/asynchronous-iteration.html) that lets you asynchronously iterate over events of `event` emitted from `emitter`. The iterator ends when `emitter` emits an event matching any of the events defined in `resolutionEvents`, or rejects if `emitter` emits any of the events defined in the `rejectionEvents` option.

This method has the same arguments and options as `pEvent()` with the addition of the following options:

#### options

Type: `Object`
Type: `object`

##### limit

Type: `number` *(non-negative integer)*<br>
Type: `number` *(non-negative integer)*\
Default: `Infinity`

Maximum number of events for the iterator before it ends. When the limit is reached, the iterator will be marked as `done`. This option is useful to paginate events, for example, fetching 10 events per page.

##### resolutionEvents

Type: `string[]`<br>
Type: `string[]`\
Default: `[]`

Events that will end the iterator.


## Before and after

```js
Expand Down Expand Up @@ -275,7 +271,6 @@ async function getOpenReadStream(file) {
})().catch(console.error);
```


## Tip

### Dealing with calls that resolve with an error code
Expand Down Expand Up @@ -304,14 +299,8 @@ const emitter = require('./some-event-emitter');
})();
```


## Related

- [pify](https://github.com/sindresorhus/pify) - Promisify a callback-style function
- [p-map](https://github.com/sindresorhus/p-map) - Map over promises concurrently
- [More…](https://github.com/sindresorhus/promise-fun)


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)

0 comments on commit 5116832

Please sign in to comment.