Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: migrate away from Node's EventEmitter #5979

Merged
merged 12 commits into from
Jun 15, 2020
70 changes: 63 additions & 7 deletions docs/api.md
Expand Up @@ -336,6 +336,15 @@
* [coverage.stopCSSCoverage()](#coveragestopcsscoverage)
* [coverage.stopJSCoverage()](#coveragestopjscoverage)
- [class: TimeoutError](#class-timeouterror)
- [class: EventEmitter](#class-eventemitter)
* [eventEmitter.addListener(event, handler)](#eventemitteraddlistenerevent-handler)
* [eventEmitter.emit(event, [eventData])](#eventemitteremitevent-eventdata)
* [eventEmitter.listenerCount(event)](#eventemitterlistenercountevent)
* [eventEmitter.off(event, handler)](#eventemitteroffevent-handler)
* [eventEmitter.on(event, handler)](#eventemitteronevent-handler)
* [eventEmitter.once(event, handler)](#eventemitteronceevent-handler)
* [eventEmitter.removeAllListeners([event])](#eventemitterremovealllistenersevent)
* [eventEmitter.removeListener(event, handler)](#eventemitterremovelistenerevent-handler)
<!-- GEN:stop -->

### Overview
Expand Down Expand Up @@ -657,7 +666,7 @@ The method initiates a GET request to download the revision from the host.

### class: Browser

* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
* extends: [EventEmitter](#class-eventemitter)

A Browser is created when Puppeteer connects to a Chromium instance, either through [`puppeteer.launch`](#puppeteerlaunchoptions) or [`puppeteer.connect`](#puppeteerconnectoptions).

Expand Down Expand Up @@ -819,7 +828,7 @@ You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/versio

### class: BrowserContext

* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
* extends: [EventEmitter](#class-eventemitter)

BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has
a single BrowserContext used by default. The method `browser.newPage()` creates a page in the default browser context.
Expand Down Expand Up @@ -949,7 +958,7 @@ const newWindowTarget = await browserContext.waitForTarget(target => target.url(

### class: Page

* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
* extends: [EventEmitter](#class-eventemitter)

Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] instance might have multiple [Page] instances.

Expand All @@ -966,22 +975,24 @@ const puppeteer = require('puppeteer');
})();
```

The Page class emits various events (described below) which can be handled using any of Node's native [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or `removeListener`.
The Page class emits various events (described below) which can be handled using
any of the [`EventEmitter`](#class-eventemitter) methods, such as `on`, `once`
or `off`.

This example logs a message for a single page `load` event:
```js
page.once('load', () => console.log('Page loaded!'));
```

To unsubscribe from events use the `removeListener` method:
To unsubscribe from events use the `off` method:

```js
function logRequest(interceptedRequest) {
console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.removeListener('request', logRequest);
page.off('request', logRequest);
```

#### event: 'close'
Expand Down Expand Up @@ -3869,7 +3880,7 @@ If the target is not of type `"service_worker"` or `"shared_worker"`, returns `n

### class: CDPSession

* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
* extends: [EventEmitter](#class-eventemitter)

The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:
- protocol methods can be called with `session.send` method.
Expand Down Expand Up @@ -3975,7 +3986,51 @@ reported.

TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) or [puppeteer.launch([options])](#puppeteerlaunchoptions).

### class: EventEmitter

A small EventEmitter class backed by [Mitt](https://github.com/developit/mitt/).

#### eventEmitter.addListener(event, handler)
- `event` <[string]|[symbol]> the event to remove the handler from.
- `handler` <[Function]> the event listener that will be added.
- returns: `this` so you can chain method calls

This method is identical to `on` and maintained for compatibility with Node's EventEmitter. We recommend using `on` by default.

#### eventEmitter.emit(event, [eventData])
- `event` <[string]|[symbol]> the event to trigger.
- `eventData` <[Object]> additional data to send with the event.
- returns: `boolean`; `true` if there are any listeners for the event, `false` if there are none.

#### eventEmitter.listenerCount(event)
- `event` <[string]|[symbol]> the event to check for listeners.
- returns: <[number]> the number of listeners for the given event.

#### eventEmitter.off(event, handler)
- `event` <[string]|[symbol]> the event to remove the handler from.
- `handler` <[Function]> the event listener that will be removed.
- returns: `this` so you can chain method calls

#### eventEmitter.on(event, handler)
- `event` <[string]|[symbol]> the event to add the handler to.
- `handler` <[Function]> the event listener that will be added.
- returns: `this` so you can chain method calls

#### eventEmitter.once(event, handler)
- `event` <[string]|[symbol]> the event to add the handler to.
- `handler` <[Function]> the event listener that will be added.
- returns: `this` so you can chain method calls

#### eventEmitter.removeAllListeners([event])
- `event` <[string]|[symbol]> optional argument to remove all listeners for the given event. If it's not given this method will remove all listeners for all events.
- returns: `this` so you can chain method calls

#### eventEmitter.removeListener(event, handler)
- `event` <[string]|[symbol]> the event to remove the handler from.
- `handler` <[Function]> the event listener that will be removed.
- returns: `this` so you can chain method calls

This method is identical to `off` and maintained for compatibility with Node's EventEmitter. We recommend using `off` by default.
jackfranklin marked this conversation as resolved.
Show resolved Hide resolved

[AXNode]: #accessibilitysnapshotoptions "AXNode"
[Accessibility]: #class-accessibility "Accessibility"
Expand Down Expand Up @@ -4024,4 +4079,5 @@ TimeoutError is emitted whenever certain operations are terminated due to timeou
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
[stream.Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "stream.Readable"
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String"
[symbol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Symbol_type "Symbol"
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
30 changes: 30 additions & 0 deletions new-docs/puppeteer.eventemitter.addlistener.md
@@ -0,0 +1,30 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [addListener](./puppeteer.eventemitter.addlistener.md)

## EventEmitter.addListener() method

> Warning: This API is now obsolete.
>
> please use `on` instead.
>

Add an event listener.

<b>Signature:</b>

```typescript
addListener(event: EventType, handler: Handler): EventEmitter;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | |
| handler | Handler | |

<b>Returns:</b>

[EventEmitter](./puppeteer.eventemitter.md)

27 changes: 27 additions & 0 deletions new-docs/puppeteer.eventemitter.emit.md
@@ -0,0 +1,27 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [emit](./puppeteer.eventemitter.emit.md)

## EventEmitter.emit() method

Emit an event and call any associated listeners.

<b>Signature:</b>

```typescript
emit(event: EventType, eventData?: any): boolean;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | the event you'd like to emit |
| eventData | any | any data you'd like to emit with the event |

<b>Returns:</b>

boolean

`true` if there are any listeners, `false` if there are not.

26 changes: 26 additions & 0 deletions new-docs/puppeteer.eventemitter.listenercount.md
@@ -0,0 +1,26 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [listenerCount](./puppeteer.eventemitter.listenercount.md)

## EventEmitter.listenerCount() method

Gets the number of listeners for a given event.

<b>Signature:</b>

```typescript
listenerCount(event: EventType): number;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | the event to get the listener count for |

<b>Returns:</b>

number

the number of listeners bound to the given event

33 changes: 33 additions & 0 deletions new-docs/puppeteer.eventemitter.md
@@ -0,0 +1,33 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md)

## EventEmitter class

The EventEmitter class that many Puppeteer classes extend.

<b>Signature:</b>

```typescript
export declare class EventEmitter implements CommonEventEmitter
```

## Remarks

This allows you to listen to events that Puppeteer classes fire and act accordingly. Therefore you'll mostly use [on](./puppeteer.eventemitter.on.md) and [off](./puppeteer.eventemitter.off.md) to bind and unbind to event listeners.

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `EventEmitter` class.

## Methods

| Method | Modifiers | Description |
| --- | --- | --- |
| [addListener(event, handler)](./puppeteer.eventemitter.addlistener.md) | | Add an event listener. |
| [emit(event, eventData)](./puppeteer.eventemitter.emit.md) | | Emit an event and call any associated listeners. |
| [listenerCount(event)](./puppeteer.eventemitter.listenercount.md) | | Gets the number of listeners for a given event. |
| [off(event, handler)](./puppeteer.eventemitter.off.md) | | Remove an event listener from firing. |
| [on(event, handler)](./puppeteer.eventemitter.on.md) | | Bind an event listener to fire when an event occurs. |
| [once(event, handler)](./puppeteer.eventemitter.once.md) | | Like <code>on</code> but the listener will only be fired once and then it will be removed. |
| [removeAllListeners(event)](./puppeteer.eventemitter.removealllisteners.md) | | Removes all listeners. If given an event argument, it will remove only listeners for that event. |
| [removeListener(event, handler)](./puppeteer.eventemitter.removelistener.md) | | Remove an event listener. |

27 changes: 27 additions & 0 deletions new-docs/puppeteer.eventemitter.off.md
@@ -0,0 +1,27 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [off](./puppeteer.eventemitter.off.md)

## EventEmitter.off() method

Remove an event listener from firing.

<b>Signature:</b>

```typescript
off(event: EventType, handler: Handler): EventEmitter;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | the event type you'd like to stop listening to. |
| handler | Handler | the function that should be removed. |

<b>Returns:</b>

[EventEmitter](./puppeteer.eventemitter.md)

`this` to enable you to chain calls.

27 changes: 27 additions & 0 deletions new-docs/puppeteer.eventemitter.on.md
@@ -0,0 +1,27 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [on](./puppeteer.eventemitter.on.md)

## EventEmitter.on() method

Bind an event listener to fire when an event occurs.

<b>Signature:</b>

```typescript
on(event: EventType, handler: Handler): EventEmitter;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | the event type you'd like to listen to. Can be a string or symbol. |
| handler | Handler | the function to be called when the event occurs. |

<b>Returns:</b>

[EventEmitter](./puppeteer.eventemitter.md)

`this` to enable you to chain calls.

27 changes: 27 additions & 0 deletions new-docs/puppeteer.eventemitter.once.md
@@ -0,0 +1,27 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [once](./puppeteer.eventemitter.once.md)

## EventEmitter.once() method

Like `on` but the listener will only be fired once and then it will be removed.

<b>Signature:</b>

```typescript
once(event: EventType, handler: Handler): EventEmitter;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | the event you'd like to listen to |
| handler | Handler | the handler function to run when the event occurs |

<b>Returns:</b>

[EventEmitter](./puppeteer.eventemitter.md)

`this` to enable you to chain calls.

26 changes: 26 additions & 0 deletions new-docs/puppeteer.eventemitter.removealllisteners.md
@@ -0,0 +1,26 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [removeAllListeners](./puppeteer.eventemitter.removealllisteners.md)

## EventEmitter.removeAllListeners() method

Removes all listeners. If given an event argument, it will remove only listeners for that event.

<b>Signature:</b>

```typescript
removeAllListeners(event?: EventType): EventEmitter;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | the event to remove listeners for. |

<b>Returns:</b>

[EventEmitter](./puppeteer.eventemitter.md)

`this` to enable you to chain calls.

30 changes: 30 additions & 0 deletions new-docs/puppeteer.eventemitter.removelistener.md
@@ -0,0 +1,30 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EventEmitter](./puppeteer.eventemitter.md) &gt; [removeListener](./puppeteer.eventemitter.removelistener.md)

## EventEmitter.removeListener() method

> Warning: This API is now obsolete.
>
> please use `off` instead.
>

Remove an event listener.

<b>Signature:</b>

```typescript
removeListener(event: EventType, handler: Handler): EventEmitter;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| event | EventType | |
| handler | Handler | |

<b>Returns:</b>

[EventEmitter](./puppeteer.eventemitter.md)