robojerk/codeql-action

Upgrade Ava to v4

Browse source
This commit is contained in:
Henry Mercer 2022-02-01 18:01:11 +00:00
parent 9a40cc5274
commit ce89f1b611
1153 changed files with 27264 additions and 95308 deletions
Download patch file Download diff file Expand all files Collapse all files

442
node_modules/p-event/index.d.ts generated vendored
View file

@ -1,265 +1,237 @@
/// <reference lib="esnext"/>
export type AddRemoveListener<EventName extends string | symbol, Arguments extends unknown[]> = (
event: EventName,
listener: (...arguments: Arguments) => void
) => void;
declare class TimeoutErrorClass extends Error {
readonly name: 'TimeoutError';
constructor(message?: string);
export interface Emitter<EventName extends string | symbol, EmittedType extends unknown[]> {
on?: AddRemoveListener<EventName, EmittedType>;
addListener?: AddRemoveListener<EventName, EmittedType>;
addEventListener?: AddRemoveListener<EventName, EmittedType>;
off?: AddRemoveListener<EventName, EmittedType>;
removeListener?: AddRemoveListener<EventName, EmittedType>;
removeEventListener?: AddRemoveListener<EventName, EmittedType>;
}
declare namespace pEvent {
type TimeoutError = TimeoutErrorClass;
export type FilterFunction<ElementType extends unknown | unknown[]> = (
value: ElementType
) => boolean;
type AddRemoveListener<EventName extends string | symbol, Arguments extends unknown[]> = (
event: EventName,
listener: (...arguments: Arguments) => void
) => void;
interface Emitter<EventName extends string | symbol, EmittedType extends unknown[]> {
on?: AddRemoveListener<EventName, EmittedType>;
addListener?: AddRemoveListener<EventName, EmittedType>;
addEventListener?: AddRemoveListener<EventName, EmittedType>;
off?: AddRemoveListener<EventName, EmittedType>;
removeListener?: AddRemoveListener<EventName, EmittedType>;
removeEventListener?: AddRemoveListener<EventName, EmittedType>;
}
type FilterFunction<ElementType extends unknown[]> = (
...arguments: ElementType
) => boolean;
interface CancelablePromise<ResolveType> extends Promise<ResolveType> {
cancel(): void;
}
interface Options<EmittedType extends unknown[]> {
/**
Events that will reject the promise.
@default ['error']
*/
readonly rejectionEvents?: ReadonlyArray<string | symbol>;
/**
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.
@default false
@example
```
import pEvent = require('p-event');
import emitter from './some-event-emitter';
(async () => {
const [foo, bar] = await pEvent(emitter, 'finish', {multiArgs: true});
})();
```
*/
readonly multiArgs?: boolean;
/**
Time in milliseconds before timing out.
@default Infinity
*/
readonly timeout?: number;
/**
Filter function for accepting an event.
@example
```
import pEvent = require('p-event');
import emitter from './some-event-emitter';
(async () => {
const result = await pEvent(emitter, '🦄', value => value > 3);
// Do something with first 🦄 event with a value greater than 3
})();
```
*/
readonly filter?: FilterFunction<EmittedType>;
}
interface MultiArgumentsOptions<EmittedType extends unknown[]>
extends Options<EmittedType> {
readonly multiArgs: true;
}
interface MultipleOptions<EmittedType extends unknown[]>
extends Options<EmittedType> {
/**
The number of times the event needs to be emitted before the promise resolves.
*/
readonly count: number;
/**
Whether to resolve the promise immediately. Emitting one of the `rejectionEvents` won't throw an error.
__Note__: The returned array will be mutated when an event is emitted.
@example
```
import pEvent = require('p-event');
const emitter = new EventEmitter();
const promise = pEvent.multiple(emitter, 'hello', {
resolveImmediately: true,
count: Infinity
});
const result = await promise;
console.log(result);
//=> []
emitter.emit('hello', 'Jack');
console.log(result);
//=> ['Jack']
emitter.emit('hello', 'Mark');
console.log(result);
//=> ['Jack', 'Mark']
// Stops listening
emitter.emit('error', new Error('😿'));
emitter.emit('hello', 'John');
console.log(result);
//=> ['Jack', 'Mark']
```
*/
readonly resolveImmediately?: boolean;
}
interface MultipleMultiArgumentsOptions<EmittedType extends unknown[]>
extends MultipleOptions<EmittedType> {
readonly multiArgs: true;
}
interface IteratorOptions<EmittedType extends unknown[]>
extends Options<EmittedType> {
/**
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.
@default Infinity
*/
limit?: number;
/**
Events that will end the iterator.
@default []
*/
resolutionEvents?: ReadonlyArray<string | symbol>;
}
interface IteratorMultiArgumentsOptions<EmittedType extends unknown[]>
extends IteratorOptions<EmittedType> {
multiArgs: true;
}
export interface CancelablePromise<ResolveType> extends Promise<ResolveType> {
cancel(): void;
}
declare const pEvent: {
export interface Options<EmittedType extends unknown | unknown[]> {
/**
Promisify an event by waiting for it to be emitted.
Events that will reject the promise.
@param emitter - Event emitter object. Should have either a `.on()`/`.addListener()`/`.addEventListener()` and `.off()`/`.removeListener()`/`.removeEventListener()` method, like the [Node.js `EventEmitter`](https://nodejs.org/api/events.html) and [DOM events](https://developer.mozilla.org/en-US/docs/Web/Events).
@param event - Name of the event or events to listen to. If the same event is defined both here and in `rejectionEvents`, this one takes priority.*Note**: `event` is a string for a single event type, for example, `'data'`. To listen on multiple events, pass an array of strings, such as `['started', 'stopped']`.
@returns Fulfills 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.
@default ['error']
*/
readonly rejectionEvents?: ReadonlyArray<string | symbol>;
/**
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.
@default false
@example
```
// In Node.js:
import pEvent = require('p-event');
import {pEvent} from 'p-event';
import emitter from './some-event-emitter';
(async () => {
try {
const result = await pEvent(emitter, 'finish');
// `emitter` emitted a `finish` event
console.log(result);
} catch (error) {
// `emitter` emitted an `error` event
console.error(error);
}
})();
// In the browser:
(async () => {
await pEvent(document, 'DOMContentLoaded');
console.log('😎');
})();
const [foo, bar] = await pEvent(emitter, 'finish', {multiArgs: true});
```
*/
<EventName extends string | symbol, EmittedType extends unknown[]>(
emitter: pEvent.Emitter<EventName, EmittedType>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: pEvent.MultiArgumentsOptions<EmittedType>
): pEvent.CancelablePromise<EmittedType>;
<EventName extends string | symbol, EmittedType>(
emitter: pEvent.Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
filter: pEvent.FilterFunction<[EmittedType]>
): pEvent.CancelablePromise<EmittedType>;
<EventName extends string | symbol, EmittedType>(
emitter: pEvent.Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
options?: pEvent.Options<[EmittedType]>
): pEvent.CancelablePromise<EmittedType>;
readonly multiArgs?: boolean;
/**
Wait for multiple event emissions. Returns an array.
The time in milliseconds before timing out.
@default Infinity
*/
multiple<EventName extends string | symbol, EmittedType extends unknown[]>(
emitter: pEvent.Emitter<EventName, EmittedType>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: pEvent.MultipleMultiArgumentsOptions<EmittedType>
): pEvent.CancelablePromise<EmittedType[]>;
multiple<EventName extends string | symbol, EmittedType>(
emitter: pEvent.Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: pEvent.MultipleOptions<[EmittedType]>
): pEvent.CancelablePromise<EmittedType[]>;
readonly timeout?: number;
/**
@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.
A filter function for accepting an event.
@example
```
import pEvent = require('p-event');
import {pEvent} from 'p-event';
import emitter from './some-event-emitter';
(async () => {
const asyncIterator = pEvent.iterator(emitter, 'data', {
resolutionEvents: ['finish']
});
for await (const event of asyncIterator) {
console.log(event);
}
})();
const result = await pEvent(emitter, '🦄', value => value > 3);
// Do something with first 🦄 event with a value greater than 3
```
*/
iterator<EventName extends string | symbol, EmittedType extends unknown[]>(
emitter: pEvent.Emitter<EventName, EmittedType>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: pEvent.IteratorMultiArgumentsOptions<EmittedType>
): AsyncIterableIterator<EmittedType>;
iterator<EventName extends string | symbol, EmittedType>(
emitter: pEvent.Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
filter: pEvent.FilterFunction<[EmittedType]>
): AsyncIterableIterator<EmittedType>;
iterator<EventName extends string | symbol, EmittedType>(
emitter: pEvent.Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
options?: pEvent.IteratorOptions<[EmittedType]>
): AsyncIterableIterator<EmittedType>;
readonly filter?: FilterFunction<EmittedType>;
}
// TODO: Remove this for the next major release
default: typeof pEvent;
export interface MultiArgumentsOptions<EmittedType extends unknown[]>
extends Options<EmittedType> {
readonly multiArgs: true;
}
TimeoutError: typeof TimeoutErrorClass;
};
export interface MultipleOptions<EmittedType extends unknown | unknown[]>
extends Options<EmittedType> {
/**
The number of times the event needs to be emitted before the promise resolves.
*/
readonly count: number;
export = pEvent;
/**
Whether to resolve the promise immediately. Emitting one of the `rejectionEvents` won't throw an error.
__Note__: The returned array will be mutated when an event is emitted.
@example
```
import {pEventMultiple} from 'p-event';
const emitter = new EventEmitter();
const promise = pEventMultiple(emitter, 'hello', {
resolveImmediately: true,
count: Infinity
});
const result = await promise;
console.log(result);
//=> []
emitter.emit('hello', 'Jack');
console.log(result);
//=> ['Jack']
emitter.emit('hello', 'Mark');
console.log(result);
//=> ['Jack', 'Mark']
// Stops listening
emitter.emit('error', new Error('😿'));
emitter.emit('hello', 'John');
console.log(result);
//=> ['Jack', 'Mark']
```
*/
readonly resolveImmediately?: boolean;
}
export interface MultipleMultiArgumentsOptions<EmittedType extends unknown[]>
extends MultipleOptions<EmittedType> {
readonly multiArgs: true;
}
export interface IteratorOptions<EmittedType extends unknown | unknown[]>
extends Options<EmittedType> {
/**
The 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.
@default Infinity
*/
readonly limit?: number;
/**
Events that will end the iterator.
@default []
*/
readonly resolutionEvents?: ReadonlyArray<string | symbol>;
}
export interface IteratorMultiArgumentsOptions<EmittedType extends unknown[]>
extends IteratorOptions<EmittedType> {
multiArgs: true;
}
/**
Promisify an event by waiting for it to be emitted.
@param emitter - Event emitter object. Should have either a `.on()`/`.addListener()`/`.addEventListener()` and `.off()`/`.removeListener()`/`.removeEventListener()` method, like the [Node.js `EventEmitter`](https://nodejs.org/api/events.html) and [DOM events](https://developer.mozilla.org/en-US/docs/Web/Events).
@param event - Name of the event or events to listen to. If the same event is defined both here and in `rejectionEvents`, this one takes priority.*Note**: `event` is a string for a single event type, for example, `'data'`. To listen on multiple events, pass an array of strings, such as `['started', 'stopped']`.
@returns Fulfills 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.
@example
```
import {pEvent} from 'p-event';
import emitter from './some-event-emitter';
// In Node.js:
try {
const result = await pEvent(emitter, 'finish');
// `emitter` emitted a `finish` event
console.log(result);
} catch (error) {
// `emitter` emitted an `error` event
console.error(error);
}
// In the browser:
await pEvent(document, 'DOMContentLoaded');
console.log('😎');
```
*/
export function pEvent<EventName extends string | symbol, EmittedType extends unknown[]>(
emitter: Emitter<EventName, EmittedType>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: MultiArgumentsOptions<EmittedType>
): CancelablePromise<EmittedType>;
export function pEvent<EventName extends string | symbol, EmittedType>(
emitter: Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
filter: FilterFunction<EmittedType>
): CancelablePromise<EmittedType>;
export function pEvent<EventName extends string | symbol, EmittedType>(
emitter: Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
options?: Options<EmittedType>
): CancelablePromise<EmittedType>;
/**
Wait for multiple event emissions.
*/
export function pEventMultiple<EventName extends string | symbol, EmittedType extends unknown[]>(
emitter: Emitter<EventName, EmittedType>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: MultipleMultiArgumentsOptions<EmittedType>
): CancelablePromise<EmittedType[]>;
export function pEventMultiple<EventName extends string | symbol, EmittedType>(
emitter: Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: MultipleOptions<EmittedType>
): CancelablePromise<EmittedType[]>;
/**
@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
```
import {pEventIterator} from 'p-event';
import emitter from './some-event-emitter';
const asyncIterator = pEventIterator(emitter, 'data', {
resolutionEvents: ['finish']
});
for await (const event of asyncIterator) {
console.log(event);
}
```
*/
export function pEventIterator<EventName extends string | symbol, EmittedType extends unknown[]>(
emitter: Emitter<EventName, EmittedType>,
event: string | symbol | ReadonlyArray<string | symbol>,
options: IteratorMultiArgumentsOptions<EmittedType>
): AsyncIterableIterator<EmittedType>;
export function pEventIterator<EventName extends string | symbol, EmittedType>(
emitter: Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
filter: FilterFunction<EmittedType>
): AsyncIterableIterator<EmittedType>;
export function pEventIterator<EventName extends string | symbol, EmittedType>(
emitter: Emitter<EventName, [EmittedType]>,
event: string | symbol | ReadonlyArray<string | symbol>,
options?: IteratorOptions<EmittedType>
): AsyncIterableIterator<EmittedType>;
export {TimeoutError} from 'p-timeout';

92
node_modules/p-event/index.js generated vendored
View file

@ -1,7 +1,4 @@
'use strict';
const pTimeout = require('p-timeout');
const symbolAsyncIterator = Symbol.asyncIterator || '@@asyncIterator';
import pTimeout from 'p-timeout';
const normalizeEmitter = emitter => {
const addListener = emitter.on || emitter.addListener || emitter.addEventListener;
@ -13,35 +10,34 @@ const normalizeEmitter = emitter => {
return {
addListener: addListener.bind(emitter),
removeListener: removeListener.bind(emitter)
removeListener: removeListener.bind(emitter),
};
};
const toArray = value => Array.isArray(value) ? value : [value];
const multiple = (emitter, event, options) => {
export function pEventMultiple(emitter, event, options) {
let cancel;
const ret = new Promise((resolve, reject) => {
const returnValue = new Promise((resolve, reject) => {
options = {
rejectionEvents: ['error'],
multiArgs: false,
resolveImmediately: false,
...options
...options,
};
if (!(options.count >= 0 && (options.count === Infinity || Number.isInteger(options.count)))) {
if (!(options.count >= 0 && (options.count === Number.POSITIVE_INFINITY || Number.isInteger(options.count)))) {
throw new TypeError('The `count` option should be at least 0 or more');
}
// Allow multiple events
const events = toArray(event);
const events = [event].flat();
const items = [];
const {addListener, removeListener} = normalizeEmitter(emitter);
const onItem = (...args) => {
const value = options.multiArgs ? args : args[0];
const onItem = (...arguments_) => {
const value = options.multiArgs ? arguments_ : arguments_[0];
// eslint-disable-next-line unicorn/no-array-callback-reference
if (options.filter && !options.filter(value)) {
return;
}
@ -82,18 +78,18 @@ const multiple = (emitter, event, options) => {
}
});
ret.cancel = cancel;
returnValue.cancel = cancel;
if (typeof options.timeout === 'number') {
const timeout = pTimeout(ret, options.timeout);
const timeout = pTimeout(returnValue, options.timeout);
timeout.cancel = cancel;
return timeout;
}
return ret;
};
return returnValue;
}
const pEvent = (emitter, event, options) => {
export function pEvent(emitter, event, options) {
if (typeof options === 'function') {
options = {filter: options};
}
@ -101,40 +97,34 @@ const pEvent = (emitter, event, options) => {
options = {
...options,
count: 1,
resolveImmediately: false
resolveImmediately: false,
};
const arrayPromise = multiple(emitter, event, options);
const arrayPromise = pEventMultiple(emitter, event, options);
const promise = arrayPromise.then(array => array[0]); // eslint-disable-line promise/prefer-await-to-then
promise.cancel = arrayPromise.cancel;
return promise;
};
}
module.exports = pEvent;
// TODO: Remove this for the next major release
module.exports.default = pEvent;
module.exports.multiple = multiple;
module.exports.iterator = (emitter, event, options) => {
export function pEventIterator(emitter, event, options) {
if (typeof options === 'function') {
options = {filter: options};
}
// Allow multiple events
const events = toArray(event);
const events = [event].flat();
options = {
rejectionEvents: ['error'],
resolutionEvents: [],
limit: Infinity,
limit: Number.POSITIVE_INFINITY,
multiArgs: false,
...options
...options,
};
const {limit} = options;
const isValidLimit = limit >= 0 && (limit === Infinity || Number.isInteger(limit));
const isValidLimit = limit >= 0 && (limit === Number.POSITIVE_INFINITY || Number.isInteger(limit));
if (!isValidLimit) {
throw new TypeError('The `limit` option should be a non-negative integer or Infinity');
}
@ -148,9 +138,9 @@ module.exports.iterator = (emitter, event, options) => {
async next() {
return {
done: true,
value: undefined
value: undefined,
};
}
},
};
}
@ -164,11 +154,11 @@ module.exports.iterator = (emitter, event, options) => {
let eventCount = 0;
let isLimitReached = false;
const valueHandler = (...args) => {
const valueHandler = (...arguments_) => {
eventCount++;
isLimitReached = eventCount === limit;
const value = options.multiArgs ? args : args[0];
const value = options.multiArgs ? arguments_ : arguments_[0];
if (nextQueue.length > 0) {
const {resolve} = nextQueue.shift();
@ -191,6 +181,7 @@ module.exports.iterator = (emitter, event, options) => {
const cancel = () => {
isDone = true;
for (const event of events) {
removeListener(event, valueHandler);
}
@ -209,8 +200,8 @@ module.exports.iterator = (emitter, event, options) => {
}
};
const rejectHandler = (...args) => {
error = options.multiArgs ? args : args[0];
const rejectHandler = (...arguments_) => {
error = options.multiArgs ? arguments_ : arguments_[0];
if (nextQueue.length > 0) {
const {reject} = nextQueue.shift();
@ -222,9 +213,10 @@ module.exports.iterator = (emitter, event, options) => {
cancel();
};
const resolveHandler = (...args) => {
const value = options.multiArgs ? args : args[0];
const resolveHandler = (...arguments_) => {
const value = options.multiArgs ? arguments_ : arguments_[0];
// eslint-disable-next-line unicorn/no-array-callback-reference
if (options.filter && !options.filter(value)) {
return;
}
@ -252,7 +244,7 @@ module.exports.iterator = (emitter, event, options) => {
}
return {
[symbolAsyncIterator]() {
[Symbol.asyncIterator]() {
return this;
},
async next() {
@ -260,7 +252,7 @@ module.exports.iterator = (emitter, event, options) => {
const value = valueQueue.shift();
return {
done: isDone && valueQueue.length === 0 && !isLimitReached,
value
value,
};
}
@ -272,20 +264,22 @@ module.exports.iterator = (emitter, event, options) => {
if (isDone) {
return {
done: true,
value: undefined
value: undefined,
};
}
return new Promise((resolve, reject) => nextQueue.push({resolve, reject}));
return new Promise((resolve, reject) => {
nextQueue.push({resolve, reject});
});
},
async return(value) {
cancel();
return {
done: isDone,
value
value,
};
}
},
};
};
}
module.exports.TimeoutError = pTimeout.TimeoutError;
export {TimeoutError} from 'p-timeout';

18
node_modules/p-event/package.json generated vendored
View file

@ -1,6 +1,6 @@
{
"name": "p-event",
"version": "4.2.0",
"version": "5.0.1",
"description": "Promisify an event by waiting for it to be emitted",
"license": "MIT",
"repository": "sindresorhus/p-event",
@ -10,8 +10,10 @@
"email": "sindresorhus@gmail.com",
"url": "https://sindresorhus.com"
},
"type": "module",
"exports": "./index.js",
"engines": {
"node": ">=8"
"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
},
"scripts": {
"test": "xo && ava && tsd"
@ -44,13 +46,13 @@
"bluebird"
],
"dependencies": {
"p-timeout": "^3.1.0"
"p-timeout": "^5.0.2"
},
"devDependencies": {
"@types/node": "^12.0.2",
"ava": "^1.4.1",
"delay": "^4.1.0",
"tsd": "^0.11.0",
"xo": "^0.24.0"
"@types/node": "^16.11.6",
"ava": "^3.15.0",
"delay": "^5.0.0",
"tsd": "^0.18.0",
"xo": "^0.45.0"
}
}

133
node_modules/p-event/readme.md generated vendored
View file

@ -1,17 +1,17 @@
# p-event [![Build Status](https://travis-ci.com/sindresorhus/p-event.svg?branch=master)](https://travis-ci.com/sindresorhus/p-event)
# p-event
> 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).
It 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.
If you want multiple individual events as they are emitted, you can use the `pEventIterator()` method. [Observables](https://medium.com/@benlesh/learning-observable-by-building-observable-d5da57405d87) can be useful too.
## Install
```
$ npm install p-event
```sh
npm install p-event
```
## Usage
@ -19,48 +19,42 @@ $ npm install p-event
In Node.js:
```js
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
import {pEvent} from 'p-event';
import emitter from './some-event-emitter';
(async () => {
try {
const result = await pEvent(emitter, 'finish');
try {
const result = await pEvent(emitter, 'finish');
// `emitter` emitted a `finish` event
console.log(result);
} catch (error) {
// `emitter` emitted an `error` event
console.error(error);
}
})();
// `emitter` emitted a `finish` event
console.log(result);
} catch (error) {
// `emitter` emitted an `error` event
console.error(error);
}
```
In the browser:
```js
const pEvent = require('p-event');
import {pEvent} from 'p-event';
(async () => {
await pEvent(document, 'DOMContentLoaded');
console.log('😎');
})();
await pEvent(document, 'DOMContentLoaded');
console.log('😎');
```
Async iteration:
```js
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
import {pEventIterator} from 'p-event';
import emitter from './some-event-emitter';
(async () => {
const asyncIterator = pEvent.iterator(emitter, 'data', {
resolutionEvents: ['finish']
});
const asyncIterator = pEventIterator(emitter, 'data', {
resolutionEvents: ['finish']
});
for await (const event of asyncIterator) {
console.log(event);
}
})();
for await (const event of asyncIterator) {
console.log(event);
}
```
## API
@ -112,12 +106,10 @@ By default, the promisified function will only return the first argument from th
Example:
```js
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
import {pEvent} from 'p-event';
import emitter from './some-event-emitter';
(async () => {
const [foo, bar] = await pEvent(emitter, 'finish', {multiArgs: true});
})();
const [foo, bar] = await pEvent(emitter, 'finish', {multiArgs: true});
```
##### timeout
@ -131,19 +123,17 @@ Time in milliseconds before timing out.
Type: `Function`
Filter function for accepting an event.
A filter function for accepting an event.
```js
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
import {pEvent} from 'p-event';
import emitter from './some-event-emitter';
(async () => {
const result = await pEvent(emitter, '🦄', value => value > 3);
// Do something with first 🦄 event with a value greater than 3
})();
const result = await pEvent(emitter, '🦄', value => value > 3);
// Do something with first 🦄 event with a value greater than 3
```
### pEvent.multiple(emitter, event, options)
### pEventMultiple(emitter, event, options)
Wait for multiple event emissions. Returns an array.
@ -172,11 +162,11 @@ Whether to resolve the promise immediately. Emitting one of the `rejectionEvents
Example:
```js
const pEvent = require('p-event');
import {pEventMultiple} from 'p-event';
const emitter = new EventEmitter();
const promise = pEvent.multiple(emitter, 'hello', {
const promise = pEventMultiple(emitter, 'hello', {
resolveImmediately: true,
count: Infinity
});
@ -201,8 +191,8 @@ console.log(result);
//=> ['Jack', 'Mark']
```
### pEvent.iterator(emitter, event, options?)
### pEvent.iterator(emitter, event, filter)
### pEventIterator(emitter, event, options?)
### pEventIterator(emitter, event, filter)
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.
@ -217,7 +207,7 @@ Type: `object`
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.
The 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
@ -226,14 +216,14 @@ Default: `[]`
Events that will end the iterator.
### pEvent.TimeoutError
### TimeoutError
Exposed for instance checking and sub-classing.
Example:
```js
const pEvent = require('p-event');
import {pEvent} from 'p-event';
try {
await pEvent(emitter, 'finish');
@ -247,7 +237,7 @@ try {
## Before and after
```js
const fs = require('fs');
import fs from 'node:fs';
function getOpenReadStream(file, callback) {
const stream = fs.createReadStream(file);
@ -273,8 +263,8 @@ getOpenReadStream('unicorn.txt', (error, stream) => {
```
```js
const fs = require('fs');
const pEvent = require('p-event');
import fs from 'node:fs';
import {pEvent} from 'p-event';
async function getOpenReadStream(file) {
const stream = fs.createReadStream(file);
@ -286,7 +276,8 @@ async function getOpenReadStream(file) {
const stream = await getOpenReadStream('unicorn.txt');
console.log('File descriptor:', stream.fd);
stream.pipe(process.stdout);
})().catch(console.error);
})()
.catch(console.error);
```
## Tip
@ -296,25 +287,23 @@ async function getOpenReadStream(file) {
Some functions might use a single event for success and for certain errors. Promises make it easy to have combined error handler for both error events and successes containing values which represent errors.
```js
const pEvent = require('p-event');
const emitter = require('./some-event-emitter');
import {pEvent} from 'p-event';
import emitter from './some-event-emitter';
(async () => {
try {
const result = await pEvent(emitter, 'finish');
try {
const result = await pEvent(emitter, 'finish');
if (result === 'unwanted result') {
throw new Error('Emitter finished with an error');
}
// `emitter` emitted a `finish` event with an acceptable value
console.log(result);
} catch (error) {
// `emitter` emitted an `error` event or
// emitted a `finish` with 'unwanted result'
console.error(error);
if (result === 'unwanted result') {
throw new Error('Emitter finished with an error');
}
})();
// `emitter` emitted a `finish` event with an acceptable value
console.log(result);
} catch (error) {
// `emitter` emitted an `error` event or
// emitted a `finish` with 'unwanted result'
console.error(error);
}
```
## Related