fix: extends ElementHandle to Nodes (#8552)

* fix: extends `ElementHandle` to `Node`s (#8552)
puppeteer · Jul 6, 2022 · 5ff205d · 5ff205d
1 parent b49d530
commit 5ff205d
Show file tree

Hide file tree

Showing 93 changed files with 598 additions and 1,096 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -1,6 +1,39 @@
-assets/
+## [START] Keep in sync with .gitignore
+# Dependencies
+node_modules
+
+# Production
 build/
-coverage/
-lib
+lib/
+
+# Generated files
 tsconfig.tsbuildinfo
+puppeteer.api.json
+puppeteer*.tgz
+yarn.lock
+.docusaurus/
+.cache-loader
+.local-chromium/
+.local-firefox/
+test/output-*/
+.dev_profile*
+coverage/
+
+# IDE Artifacts
+.vscode
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+## [END] Keep in sync with .gitignore
+
+# ESLint ignores.
+assets/
 vendor/
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -140,6 +140,8 @@ module.exports = {
         'arrow-body-style': ['error', 'always'],
         // Error if comments do not adhere to `tsdoc`.
         'tsdoc/syntax': 2,
+        // Keeps array types simple only when they are simple for readability.
+        '@typescript-eslint/array-type': ['error', {default: 'array-simple'}],
         'no-unused-vars': 0,
         '@typescript-eslint/no-unused-vars': [
           'error',

diff --git a/.gitignore b/.gitignore
@@ -16,6 +16,7 @@ yarn.lock
 .local-firefox/
 test/output-*/
 .dev_profile*
+coverage/
 
 # IDE Artifacts
 .vscode

diff --git a/.prettierignore b/.prettierignore
@@ -1,5 +1,4 @@
-# Keep in sync with .gitignore
-
+## [START] Keep in sync with .gitignore
 # Dependencies
 node_modules
 
@@ -18,6 +17,7 @@ yarn.lock
 .local-firefox/
 test/output-*/
 .dev_profile*
+coverage/
 
 # IDE Artifacts
 .vscode
@@ -32,6 +32,7 @@ test/output-*/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+## [END] Keep in sync with .gitignore
 
 # Prettier-only ignores.
 assets/
@@ -41,4 +42,4 @@ package.json
 test/assets/
 vendor/
 docs/
-versioned_*/
+versioned_*/
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -155,6 +155,7 @@ sidebar_label: API
 | [KeyInput](./puppeteer.keyinput.md)                                       | All the valid keys that can be passed to functions that take user input, such as [keyboard.press](./puppeteer.keyboard.press.md)                        |
 | [LowerCasePaperFormat](./puppeteer.lowercasepaperformat.md)               |                                                                                                                                                         |
 | [MouseButton](./puppeteer.mousebutton.md)                                 |                                                                                                                                                         |
+| [NodeFor](./puppeteer.nodefor.md)                                         |                                                                                                                                                         |
 | [PaperFormat](./puppeteer.paperformat.md)                                 | All the valid paper format types when printing a PDF.                                                                                                   |
 | [Permission](./puppeteer.permission.md)                                   |                                                                                                                                                         |
 | [Platform](./puppeteer.platform.md)                                       | Supported platforms.                                                                                                                                    |

diff --git a/docs/api/puppeteer.customqueryhandler.md b/docs/api/puppeteer.customqueryhandler.md
@@ -14,7 +14,7 @@ export interface CustomQueryHandler
 
 ## Properties
 
-| Property                                                | Modifiers | Type                                                                                            | Description       |
-| ------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | ----------------- |
-| [queryAll?](./puppeteer.customqueryhandler.queryall.md) |           | (element: Element \| Document, selector: string) =&gt; Element\[\] \| NodeListOf&lt;Element&gt; | <i>(Optional)</i> |
-| [queryOne?](./puppeteer.customqueryhandler.queryone.md) |           | (element: Element \| Document, selector: string) =&gt; Element \| null                          | <i>(Optional)</i> |
+| Property                                                | Modifiers | Type                                                 | Description       |
+| ------------------------------------------------------- | --------- | ---------------------------------------------------- | ----------------- |
+| [queryAll?](./puppeteer.customqueryhandler.queryall.md) |           | (element: Node, selector: string) =&gt; Node\[\]     | <i>(Optional)</i> |
+| [queryOne?](./puppeteer.customqueryhandler.queryone.md) |           | (element: Node, selector: string) =&gt; Node \| null | <i>(Optional)</i> |
diff --git a/docs/api/puppeteer.customqueryhandler.queryall.md b/docs/api/puppeteer.customqueryhandler.queryall.md
@@ -8,9 +8,6 @@ sidebar_label: CustomQueryHandler.queryAll
 
 ```typescript
 interface CustomQueryHandler {
-  queryAll?: (
-    element: Element | Document,
-    selector: string
-  ) => Element[] | NodeListOf<Element>;
+  queryAll?: (element: Node, selector: string) => Node[];
 }
 ```
diff --git a/docs/api/puppeteer.customqueryhandler.queryone.md b/docs/api/puppeteer.customqueryhandler.queryone.md
@@ -8,6 +8,6 @@ sidebar_label: CustomQueryHandler.queryOne
 
 ```typescript
 interface CustomQueryHandler {
-  queryOne?: (element: Element | Document, selector: string) => Element | null;
+  queryOne?: (element: Node, selector: string) => Node | null;
 }
 ```
diff --git a/docs/api/puppeteer.elementhandle._.md b/docs/api/puppeteer.elementhandle._.md
@@ -10,9 +10,9 @@ Runs `element.querySelector` within the page.
 
 ```typescript
 class ElementHandle {
-  $<Selector extends keyof HTMLElementTagNameMap>(
+  $<Selector extends string>(
     selector: Selector
-  ): Promise<ElementHandle<HTMLElementTagNameMap[Selector]> | null>;
+  ): Promise<ElementHandle<NodeFor<Selector>> | null>;
 }
 ```
 
@@ -24,7 +24,7 @@ class ElementHandle {
 
 **Returns:**
 
-Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;HTMLElementTagNameMap\[Selector\]&gt; \| null&gt;
+Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;[NodeFor](./puppeteer.nodefor.md)&lt;Selector&gt;&gt; \| null&gt;
 
 `null` if no element matches the selector.
 

diff --git a/docs/api/puppeteer.elementhandle.__.md b/docs/api/puppeteer.elementhandle.__.md
@@ -10,9 +10,9 @@ Runs `element.querySelectorAll` within the page.
 
 ```typescript
 class ElementHandle {
-  $$<Selector extends keyof HTMLElementTagNameMap>(
+  $$<Selector extends string>(
     selector: Selector
-  ): Promise<ElementHandle<HTMLElementTagNameMap[Selector]>[]>;
+  ): Promise<Array<ElementHandle<NodeFor<Selector>>>>;
 }
 ```
 
@@ -24,7 +24,7 @@ class ElementHandle {
 
 **Returns:**
 
-Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;HTMLElementTagNameMap\[Selector\]&gt;\[\]&gt;
+Promise&lt;Array&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;[NodeFor](./puppeteer.nodefor.md)&lt;Selector&gt;&gt;&gt;&gt;
 
 `[]` if no element matches the selector.
 

diff --git a/docs/api/puppeteer.elementhandle.__1.md b/docs/api/puppeteer.elementhandle.__1.md
diff --git a/docs/api/puppeteer.elementhandle.___1.md b/docs/api/puppeteer.elementhandle.___1.md
diff --git a/docs/api/puppeteer.elementhandle.__eval.md b/docs/api/puppeteer.elementhandle.__eval.md
@@ -13,11 +13,11 @@ If `pageFunction` returns a Promise, then `frame.$$eval` would wait for the prom
 ```typescript
 class ElementHandle {
   $$eval<
-    Selector extends keyof HTMLElementTagNameMap,
+    Selector extends string,
     Params extends unknown[],
     Func extends EvaluateFunc<
-      [HTMLElementTagNameMap[Selector][], ...Params]
-    > = EvaluateFunc<[HTMLElementTagNameMap[Selector][], ...Params]>
+      [Array<NodeFor<Selector>>, ...Params]
+    > = EvaluateFunc<[Array<NodeFor<Selector>>, ...Params]>
   >(
     selector: Selector,
     pageFunction: Func | string,

diff --git a/docs/api/puppeteer.elementhandle.__eval_1.md b/docs/api/puppeteer.elementhandle.__eval_1.md
diff --git a/docs/api/puppeteer.elementhandle._eval.md b/docs/api/puppeteer.elementhandle._eval.md
@@ -13,11 +13,11 @@ If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promi
 ```typescript
 class ElementHandle {
   $eval<
-    Selector extends keyof HTMLElementTagNameMap,
+    Selector extends string,
     Params extends unknown[],
     Func extends EvaluateFunc<
-      [HTMLElementTagNameMap[Selector], ...Params]
-    > = EvaluateFunc<[HTMLElementTagNameMap[Selector], ...Params]>
+      [ElementHandle<NodeFor<Selector>>, ...Params]
+    > = EvaluateFunc<[ElementHandle<NodeFor<Selector>>, ...Params]>
   >(
     selector: Selector,
     pageFunction: Func | string,

diff --git a/docs/api/puppeteer.elementhandle._eval_1.md b/docs/api/puppeteer.elementhandle._eval_1.md
diff --git a/docs/api/puppeteer.elementhandle._x.md b/docs/api/puppeteer.elementhandle._x.md
@@ -10,7 +10,7 @@ The method evaluates the XPath expression relative to the elementHandle. If ther
 
 ```typescript
 class ElementHandle {
-  $x(expression: string): Promise<ElementHandle[]>;
+  $x(expression: string): Promise<Array<ElementHandle<Node>>>;
 }
 ```
 
@@ -22,4 +22,4 @@ class ElementHandle {
 
 **Returns:**
 
-Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)\[\]&gt;
+Promise&lt;Array&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;Node&gt;&gt;&gt;
diff --git a/docs/api/puppeteer.elementhandle.click.md b/docs/api/puppeteer.elementhandle.click.md
@@ -10,15 +10,16 @@ This method scrolls element into view if needed, and then uses [Page.mouse](./pu
 
 ```typescript
 class ElementHandle {
-  click(options?: ClickOptions): Promise<void>;
+  click(this: ElementHandle<Element>, options?: ClickOptions): Promise<void>;
 }
 ```
 
 ## Parameters
 
-| Parameter | Type                                        | Description       |
-| --------- | ------------------------------------------- | ----------------- |
-| options   | [ClickOptions](./puppeteer.clickoptions.md) | <i>(Optional)</i> |
+| Parameter | Type                                                         | Description       |
+| --------- | ------------------------------------------------------------ | ----------------- |
+| this      | [ElementHandle](./puppeteer.elementhandle.md)&lt;Element&gt; |                   |
+| options   | [ClickOptions](./puppeteer.clickoptions.md)                  | <i>(Optional)</i> |
 
 **Returns:**
 

diff --git a/docs/api/puppeteer.elementhandle.drag.md b/docs/api/puppeteer.elementhandle.drag.md
@@ -10,15 +10,19 @@ This method creates and captures a dragevent from the element.
 
 ```typescript
 class ElementHandle {
-  drag(target: Point): Promise<Protocol.Input.DragData>;
+  drag(
+    this: ElementHandle<Element>,
+    target: Point
+  ): Promise<Protocol.Input.DragData>;
 }
 ```
 
 ## Parameters
 
-| Parameter | Type                          | Description |
-| --------- | ----------------------------- | ----------- |
-| target    | [Point](./puppeteer.point.md) |             |
+| Parameter | Type                                                         | Description |
+| --------- | ------------------------------------------------------------ | ----------- |
+| this      | [ElementHandle](./puppeteer.elementhandle.md)&lt;Element&gt; |             |
+| target    | [Point](./puppeteer.point.md)                                |             |
 
 **Returns:**