thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(new-docs): add tsdoc comments to WebWorker (#6029)

Browse Source 
* feat(new-docs): add TSDoc comments to `WebWorker`

Co-authored-by: martinsplitt <martin@geekonaut.de>
This commit is contained in:
Martin Splitt 2020-06-17 17:26:10 +02:00 committed by GitHub
parent 64c9c709c3
commit 44402b75a0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 89 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
new-docs/puppeteer.md
View File

@ -35,7 +35,7 @@
| [TimeoutError](./puppeteer.timeouterror.md) | |
| [Touchscreen](./puppeteer.touchscreen.md) | |
| [Tracing](./puppeteer.tracing.md) | |
| [WebWorker](./puppeteer.webworker.md) | |
| [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)<!-- -->. |
## Enumerations

23
new-docs/puppeteer.webworker._constructor_.md
View File

@ -1,23 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WebWorker](./puppeteer.webworker.md) &gt; [(constructor)](./puppeteer.webworker._constructor_.md)
## WebWorker.(constructor)
Constructs a new instance of the `WebWorker` class
<b>Signature:</b>
```typescript
constructor(client: CDPSession, url: string, consoleAPICalled: ConsoleAPICalledCallback, exceptionThrown: ExceptionThrownCallback);
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| client | [CDPSession](./puppeteer.cdpsession.md) | |
| url | string | |
| consoleAPICalled | ConsoleAPICalledCallback | |
| exceptionThrown | ExceptionThrownCallback | |

8
new-docs/puppeteer.webworker.evaluate.md
View File

@ -4,6 +4,8 @@
## WebWorker.evaluate() method
If the function passed to the `worker.evaluate` returns a Promise, then `worker.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `worker.evaluate` returns a non-serializable value, then `worker.evaluate` resolves to `undefined`<!-- -->. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`<!-- -->: `-0`<!-- -->, `NaN`<!-- -->, `Infinity`<!-- -->, `-Infinity`<!-- -->, and bigint literals. Shortcut for `await worker.executionContext()).evaluate(pageFunction, ...args)`<!-- -->.
<b>Signature:</b>
```typescript
@ -14,10 +16,12 @@ evaluate<ReturnType extends any>(pageFunction: Function | string, ...args: any[]
| Parameter | Type | Description |
| --- | --- | --- |
| pageFunction | Function \| string | |
| args | any\[\] | |
| pageFunction | Function \| string | Function to be evaluated in the worker context. |
| args | any\[\] | Arguments to pass to <code>pageFunction</code>. |
<b>Returns:</b>
Promise&lt;ReturnType&gt;
Promise which resolves to the return value of `pageFunction`<!-- -->.

8
new-docs/puppeteer.webworker.evaluatehandle.md
View File

@ -4,6 +4,8 @@
## WebWorker.evaluateHandle() method
The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns in-page object (JSHandle). If the function passed to the `worker.evaluateHandle` returns a \[Promise\], then `worker.evaluateHandle` would wait for the promise to resolve and return its value. Shortcut for \[(await worker.executionContext()).evaluateHandle(pageFunction, ...args)\](\#executioncontextevaluatehandlepagefunction-args).
<b>Signature:</b>
```typescript
@ -14,10 +16,12 @@ evaluateHandle(pageFunction: Function | string, ...args: any[]): Promise<JSHandl
| Parameter | Type | Description |
| --- | --- | --- |
| pageFunction | Function \| string | |
| args | any\[\] | |
| pageFunction | Function \| string | Function to be evaluated in the page context. |
| args | any\[\] | Arguments to pass to <code>pageFunction</code>. |
<b>Returns:</b>
Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
Promise which resolves to the return value of `pageFunction`<!-- -->.

4
new-docs/puppeteer.webworker.executioncontext.md
View File

@ -4,6 +4,8 @@
## WebWorker.executionContext() method
Returns the ExecutionContext the WebWorker runs in
<b>Signature:</b>
```typescript
@ -13,3 +15,5 @@ executionContext(): Promise<ExecutionContext>;
Promise&lt;[ExecutionContext](./puppeteer.executioncontext.md)<!-- -->&gt;
The ExecutionContext the web worker runs in.

30
new-docs/puppeteer.webworker.md
View File

@ -4,17 +4,33 @@
## WebWorker class
The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)<!-- -->.
<b>Signature:</b>
```typescript
export declare class WebWorker extends EventEmitter
```
## Constructors
## Remarks
| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(client, url, consoleAPICalled, exceptionThrown)](./puppeteer.webworker._constructor_.md) | | Constructs a new instance of the <code>WebWorker</code> class |
The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle.
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `WebWorker` class.
## Example
```js
page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));
console.log('Current workers:');
for (const worker of page.workers()) {
console.log(' ' + worker.url());
}
```
## Properties
@ -29,8 +45,8 @@ export declare class WebWorker extends EventEmitter
| Method | Modifiers | Description |
| --- | --- | --- |
| [evaluate(pageFunction, args)](./puppeteer.webworker.evaluate.md) | | |
| [evaluateHandle(pageFunction, args)](./puppeteer.webworker.evaluatehandle.md) | | |
| [executionContext()](./puppeteer.webworker.executioncontext.md) | | |
| [evaluate(pageFunction, args)](./puppeteer.webworker.evaluate.md) | | If the function passed to the <code>worker.evaluate</code> returns a Promise, then <code>worker.evaluate</code> would wait for the promise to resolve and return its value. If the function passed to the <code>worker.evaluate</code> returns a non-serializable value, then <code>worker.evaluate</code> resolves to <code>undefined</code>. DevTools Protocol also supports transferring some additional values that are not serializable by <code>JSON</code>: <code>-0</code>, <code>NaN</code>, <code>Infinity</code>, <code>-Infinity</code>, and bigint literals. Shortcut for <code>await worker.executionContext()).evaluate(pageFunction, ...args)</code>. |
| [evaluateHandle(pageFunction, args)](./puppeteer.webworker.evaluatehandle.md) | | The only difference between <code>worker.evaluate</code> and <code>worker.evaluateHandle</code> is that <code>worker.evaluateHandle</code> returns in-page object (JSHandle). If the function passed to the <code>worker.evaluateHandle</code> returns a \[Promise\], then <code>worker.evaluateHandle</code> would wait for the promise to resolve and return its value. Shortcut for \[(await worker.executionContext()).evaluateHandle(pageFunction, ...args)\](\#executioncontextevaluatehandlepagefunction-args). |
| [executionContext()](./puppeteer.webworker.executioncontext.md) | | Returns the ExecutionContext the WebWorker runs in |
| [url()](./puppeteer.webworker.url.md) | | |

2
new-docs/puppeteer.webworker.url.md
View File

@ -13,3 +13,5 @@ url(): string;
string
The URL of this web worker.

47
src/WebWorker.ts
View File

@ -30,12 +30,35 @@ type ExceptionThrownCallback = (
) => void;
type JSHandleFactory = (obj: Protocol.Runtime.RemoteObject) => JSHandle;
/**
* The WebWorker class represents a {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker}.
*
* @remarks
* The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle.
*
* @example
* ```js
* page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
* page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));
*
* console.log('Current workers:');
* for (const worker of page.workers()) {
* console.log(' ' + worker.url());
* }
* ```
*
* @public
*/
export class WebWorker extends EventEmitter {
_client: CDPSession;
_url: string;
_executionContextPromise: Promise<ExecutionContext>;
_executionContextCallback: (value: ExecutionContext) => void;
/**
*
* @internal
*/
constructor(
client: CDPSession,
url: string,
@ -76,14 +99,30 @@ export class WebWorker extends EventEmitter {
);
}
/**
* @returns The URL of this web worker.
*/
url(): string {
return this._url;
}
/**
* Returns the ExecutionContext the WebWorker runs in
* @returns The ExecutionContext the web worker runs in.
*/
async executionContext(): Promise<ExecutionContext> {
return this._executionContextPromise;
}
/**
* If the function passed to the `worker.evaluate` returns a Promise, then `worker.evaluate` would wait for the promise to resolve and return its value.
* If the function passed to the `worker.evaluate` returns a non-serializable value, then `worker.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
* Shortcut for `await worker.executionContext()).evaluate(pageFunction, ...args)`.
*
* @param pageFunction - Function to be evaluated in the worker context.
* @param args - Arguments to pass to `pageFunction`.
* @returns Promise which resolves to the return value of `pageFunction`.
*/
async evaluate<ReturnType extends any>(
pageFunction: Function | string,
...args: any[]
@ -94,6 +133,14 @@ export class WebWorker extends EventEmitter {
);
}
/**
* The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns in-page object (JSHandle).
* If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for the promise to resolve and return its value.
* Shortcut for [(await worker.executionContext()).evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args).
* @param pageFunction - Function to be evaluated in the page context.
* @param args - Arguments to pass to `pageFunction`.
* @returns Promise which resolves to the return value of `pageFunction`.
*/
async evaluateHandle(
pageFunction: Function | string,
...args: any[]