chore(types): generate a d.ts file for protocol types (#2325)

This uses the `/json/protocol` endpoint to generate type definitions for the protocol.

Currently it is lacking protocol events and commands, but I will add those later.

.gitignore

@@ -10,3 +10,4 @@
 package-lock.json
 yarn.lock
 /node6
+/lib/protocol.d.ts

.npmignore

@@ -2,6 +2,10 @@
 test
 utils/node6-transform
 
+# exclude internal type definition files
+/lib/*.d.ts
+/node6/lib/*.d.ts
+
 # repeats from .gitignore
 node_modules
 .local-chromium

lib/ElementHandle.js

@@ -21,7 +21,7 @@ class ElementHandle extends JSHandle {
   /**
    * @param {!Puppeteer.ExecutionContext} context
    * @param {!Puppeteer.CDPSession} client
-   * @param {!Object} remoteObject
+   * @param {!Protocol.Runtime.RemoteObject} remoteObject
    * @param {!Puppeteer.Page} page
    * @param {!Puppeteer.FrameManager} frameManager
    */

lib/ExecutionContext.js

@@ -19,7 +19,7 @@ const {helper} = require('./helper');
 class ExecutionContext {
   /**
    * @param {!Puppeteer.CDPSession} client
-   * @param {!Object} contextPayload
+   * @param {!Protocol.Runtime.ExecutionContextDescription} contextPayload
    * @param {function(*):!JSHandle} objectHandleFactory
    * @param {?Puppeteer.Frame} frame
    */
@@ -127,7 +127,7 @@ class JSHandle {
   /**
    * @param {!ExecutionContext} context
    * @param {!Puppeteer.CDPSession} client
-   * @param {!Object} remoteObject
+   * @param {!Protocol.Runtime.RemoteObject} remoteObject
    */
   constructor(context, client, remoteObject) {
     this._context = context;

lib/FrameManager.js

@@ -111,7 +111,7 @@ class FrameManager extends EventEmitter {
   }
 
   /**
-   * @param {!Object} framePayload
+   * @param {!Protocol.Page.Frame} framePayload
    */
   _onFrameNavigated(framePayload) {
     const isMainFrame = !framePayload.parentId;
@@ -743,7 +743,7 @@ class Frame {
   }
 
   /**
-   * @param {!Object} framePayload
+   * @param {!Protocol.Page.Frame} framePayload
    */
   _navigated(framePayload) {
     this._name = framePayload.name;

lib/NetworkManager.js

@@ -202,7 +202,7 @@ class NetworkManager extends EventEmitter {
    * @param {?string} interceptionId
    * @param {string} url
    * @param {string} resourceType
-   * @param {!Object} requestPayload
+   * @param {!Protocol.Network.Request} requestPayload
    * @param {?string} frameId
    * @param {!Array<!Request>} redirectChain
    */
@@ -306,7 +306,7 @@ class Request {
    * @param {boolean} allowInterception
    * @param {string} url
    * @param {string} resourceType
-   * @param {!Object} payload
+   * @param {!Protocol.Network.Request} payload
    * @param {?Puppeteer.Frame} frame
    * @param {!Array<!Request>} redirectChain
    */
@@ -630,7 +630,7 @@ class Response {
 helper.tracePublicAPI(Response);
 
 /**
- * @param {!Object} request
+ * @param {!Protocol.Network.Request} request
  * @return {string}
  */
 function generateRequestHash(request) {

lib/Page.js

@@ -391,7 +391,7 @@ class Page extends EventEmitter {
   }
 
   /**
-   * @param {?Array<!{name: string, value: number}>} metrics
+   * @param {?Array<!Protocol.Performance.Metric>} metrics
    * @return {!Object}
    */
   _buildMetricsObject(metrics) {

lib/helper.js

@@ -56,7 +56,7 @@ class Helper {
   }
 
   /**
-   * @param {!Object} exceptionDetails
+   * @param {!Protocol.Runtime.ExceptionDetails} exceptionDetails
    * @return {string}
    */
   static getExceptionMessage(exceptionDetails) {
@@ -74,7 +74,7 @@ class Helper {
   }
 
   /**
-   * @param {!Object} remoteObject
+   * @param {!Protocol.Runtime.RemoteObject} remoteObject
    * @return {*}
    */
   static valueFromRemoteObject(remoteObject) {
@@ -98,7 +98,7 @@ class Helper {
 
   /**
    * @param {!Puppeteer.CDPSession} client
-   * @param {!Object} remoteObject
+   * @param {!Protocol.Runtime.RemoteObject} remoteObject
    */
   static async releaseObject(client, remoteObject) {
     if (!remoteObject.objectId)

package.json

@@ -19,7 +19,7 @@
     "test-node6-transformer": "node utils/node6-transform/test/test.js",
     "build": "node utils/node6-transform/index.js",
     "unit-node6": "node node6/test/test.js",
-    "tsc": "tsc -p .",
+    "tsc": "node utils/protocol-types-generator && tsc -p .",
     "prepublishOnly": "npm run build",
     "apply-next-version": "node utils/apply_next_version.js"
   },

utils/protocol-types-generator/index.js

@@ -0,0 +1,54 @@
+const puppeteer = require('../..');
+puppeteer.launch({
+  pipe: false,
+  executablePath: process.env.CHROME,
+  args: ['--no-sandbox', '--disable-dev-shm-usage']
+}).then(async browser => {
+  const origin = browser.wsEndpoint().match(/ws:\/\/([0-9A-Za-z:\.]*)\//)[1];
+  const page = await browser.newPage();
+  await page.goto(`http://${origin}/json/protocol`);
+  const json = JSON.parse(await page.evaluate(() => document.documentElement.innerText));
+  await browser.close();
+  const output = `// This is generated from /utils/protocol-types-generator/index.js
+declare global {
+  module Protocol {
+    ${json.domains.map(domain => `${domain.description ? `
+    /**
+     * ${domain.description}
+     */` : ''}
+    export module ${domain.domain} {
+      ${(domain.types || []).map(type => `${type.description ? `
+        /**
+         * ${type.description}
+         */` : ''}${type.properties ? `
+          export interface ${type.id} {
+          ${(type.properties || []).map(property => `${property.description ? `
+            /**
+             * ${property.description}
+             */` : ''}
+            ${property.name}${property.optional ? '?' : ''}: ${typeOfProperty(property)};
+          `).join(``)}
+        }` : `
+        export type ${type.id} = ${typeOfProperty(type)};`}
+      `).join('')}
+    }
+    `).join('')}
+  }
+}
+// empty export to keep file a module
+export {}
+`;
+  require('fs').writeFileSync(require('path').join(__dirname, '..', '..', 'lib', 'protocol.d.ts'), output);
+});
+
+function typeOfProperty(property) {
+  if (property.$ref) return property.$ref;
+  if (property.enum) return property.enum.map(value => JSON.stringify(value)).join('|');
+  switch (property.type) {
+    case 'array':
+      return typeOfProperty(property.items) + '[]';
+    case 'integer':
+      return 'number';
+  }
+  return property.type;
+}