From e59172de837a156ca2df9c50c191bb571e14ebcb Mon Sep 17 00:00:00 2001 From: JoelEinbinder Date: Mon, 9 Oct 2017 22:31:40 -0700 Subject: [PATCH] chore: Use Typescript to lint JSDoc annotations (#986) This patch starts using typescript to lint JSDoc annotations. Note: this uses typescript's bleeding edge. We should migrate to stable once it has all the necessary bugfixes. References #65. --- lib/Browser.js | 6 +-- lib/Connection.js | 4 +- lib/Dialog.js | 4 +- lib/ElementHandle.js | 8 ++-- lib/EmulationManager.js | 15 ++++++- lib/ExecutionContext.js | 8 ++-- lib/FrameManager.js | 27 ++++++------- lib/Input.js | 12 +++--- lib/Launcher.js | 7 ++-- lib/Multimap.js | 42 -------------------- lib/NavigatorWatcher.js | 2 +- lib/NetworkManager.js | 19 +++++---- lib/Page.js | 43 +++++++++++--------- lib/Puppeteer.js | 6 +-- lib/Tracing.js | 2 +- lib/externs.d.ts | 28 +++++++++++++ lib/helper.js | 15 ++++--- package.json | 14 +++++-- tsconfig.json | 11 ++++++ utils/ChromiumDownloader.js | 8 +++- utils/doclint/check_public_api/JSBuilder.js | 4 +- yarn.lock | 44 +++++++++++++++++++++ 22 files changed, 198 insertions(+), 131 deletions(-) create mode 100644 lib/externs.d.ts create mode 100644 tsconfig.json diff --git a/lib/Browser.js b/lib/Browser.js index 1c516b81..98f4505d 100644 --- a/lib/Browser.js +++ b/lib/Browser.js @@ -20,9 +20,9 @@ const EventEmitter = require('events'); class Browser extends EventEmitter { /** - * @param {!Connection} connection + * @param {!Puppeteer.Connection} connection * @param {!Object=} options - * @param {function():Promise=} closeCallback + * @param {(function():Promise)=} closeCallback */ constructor(connection, options = {}, closeCallback) { super(); @@ -63,7 +63,6 @@ class Browser extends EventEmitter { } } -module.exports = Browser; helper.tracePublicAPI(Browser); class TaskQueue { @@ -81,3 +80,4 @@ class TaskQueue { return result; } } +module.exports = { Browser, TaskQueue }; diff --git a/lib/Connection.js b/lib/Connection.js index c99584c3..fa4501b0 100644 --- a/lib/Connection.js +++ b/lib/Connection.js @@ -173,7 +173,7 @@ class Session extends EventEmitter { if (!this._callbacks.has(id)) return; const callback = this._callbacks.get(id); - this._callbacks.delete(object.id); + this._callbacks.delete(id); callback.reject(e); }); return new Promise((resolve, reject) => { @@ -212,4 +212,4 @@ class Session extends EventEmitter { } } -module.exports = Connection; +module.exports = {Connection, Session}; diff --git a/lib/Dialog.js b/lib/Dialog.js index ebac447c..55ff5e11 100644 --- a/lib/Dialog.js +++ b/lib/Dialog.js @@ -18,8 +18,8 @@ const {helper} = require('./helper'); class Dialog { /** - * @param {!Session} client - * @param {!Dialog.Type} type + * @param {!Puppeteer.Session} client + * @param {string} type * @param {string} message * @param {(string|undefined)} defaultValue */ diff --git a/lib/ElementHandle.js b/lib/ElementHandle.js index d04ebf24..dace1b04 100644 --- a/lib/ElementHandle.js +++ b/lib/ElementHandle.js @@ -19,10 +19,10 @@ const {helper} = require('./helper'); class ElementHandle extends JSHandle { /** - * @param {!ExecutionContext} context - * @param {!Session} client + * @param {!Puppeteer.ExecutionContext} context + * @param {!Puppeteer.Session} client * @param {!Object} remoteObject - * @param {!Page} page + * @param {!Puppeteer.Page} page */ constructor(context, client, remoteObject, page) { super(context, client, remoteObject); @@ -47,7 +47,7 @@ class ElementHandle extends JSHandle { const error = await this.executionContext().evaluate(element => { if (!element.ownerDocument.contains(element)) return 'Node is detached from document'; - if (element.nodeType !== HTMLElement.ELEMENT_NODE) + if (element.nodeType !== Node.ELEMENT_NODE) return 'Node is not of type HTMLElement'; element.scrollIntoViewIfNeeded(); }, this); diff --git a/lib/EmulationManager.js b/lib/EmulationManager.js index 23b1e80a..a1c2c598 100644 --- a/lib/EmulationManager.js +++ b/lib/EmulationManager.js @@ -16,7 +16,7 @@ class EmulationManager { /** - * @param {!Session} client + * @param {!Puppeteer.Session} client */ constructor(client) { this._client = client; @@ -25,7 +25,7 @@ class EmulationManager { } /** - * @param {!Page.Viewport} viewport + * @param {!EmulationManager.Viewport} viewport * @return {Promise} */ async emulateViewport(client, viewport) { @@ -61,6 +61,7 @@ class EmulationManager { function injectedTouchEventsFunction() { const touchEvents = ['ontouchstart', 'ontouchend', 'ontouchmove', 'ontouchcancel']; + // @ts-ignore const recepients = [window.__proto__, document.__proto__]; for (let i = 0; i < touchEvents.length; ++i) { for (let j = 0; j < recepients.length; ++j) { @@ -75,4 +76,14 @@ class EmulationManager { } } +/** + * @typedef {Object} EmulationManager.Viewport + * @property {number} width + * @property {number} height + * @property {number=} deviceScaleFactor + * @property {boolean=} isMobile + * @property {boolean=} isLandscape + * @property {boolean=} hasTouch + */ + module.exports = EmulationManager; diff --git a/lib/ExecutionContext.js b/lib/ExecutionContext.js index 7f10eb0b..7753d153 100644 --- a/lib/ExecutionContext.js +++ b/lib/ExecutionContext.js @@ -18,7 +18,7 @@ const {helper} = require('./helper'); class ExecutionContext { /** - * @param {!Session} client + * @param {!Puppeteer.Session} client * @param {string} contextId * @param {function(*):!JSHandle} objectHandleFactory */ @@ -100,7 +100,7 @@ class ExecutionContext { class JSHandle { /** * @param {!ExecutionContext} context - * @param {!Session} client + * @param {!Puppeteer.Session} client * @param {!Object} remoteObject */ constructor(context, client, remoteObject) { @@ -134,7 +134,7 @@ class JSHandle { } /** - * @return {!Property>} + * @return {!Promise>} */ async getProperties() { const response = await this._client.send('Runtime.getProperties', { @@ -162,7 +162,7 @@ class JSHandle { } /** - * @return {?ElementHandle} + * @return {?Puppeteer.ElementHandle} */ asElement() { return null; diff --git a/lib/FrameManager.js b/lib/FrameManager.js index 8e6cf6c8..0b03e54c 100644 --- a/lib/FrameManager.js +++ b/lib/FrameManager.js @@ -22,8 +22,8 @@ const ElementHandle = require('./ElementHandle'); class FrameManager extends EventEmitter { /** - * @param {!Session} client - * @param {!Page} page + * @param {!Puppeteer.Session} client + * @param {!Puppeteer.Page} page */ constructor(client, page) { super(); @@ -87,7 +87,7 @@ class FrameManager extends EventEmitter { if (isMainFrame) { if (frame) { // Update frame id to retain frame identity on cross-process navigation. - this._frames.delete(frame._id, frame); + this._frames.delete(frame._id); frame._id = framePayload.id; } else { // Initial main frame navigation. @@ -154,7 +154,6 @@ class FrameManager extends EventEmitter { } /** - * @param {!Frame} frame * @return {boolean} */ isMainFrameLoadingFailed() { @@ -174,7 +173,7 @@ FrameManager.Events = { */ class Frame { /** - * @param {!Session} client + * @param {!Puppeteer.Session} client * @param {?Frame} parentFrame * @param {string} frameId */ @@ -202,9 +201,9 @@ class Frame { } /** - * @param {function()|string} pageFunction + * @param {Function|string} pageFunction * @param {!Array<*>} args - * @return {!Promise<(!Object|undefined)>} + * @return {!Promise<*>} */ async evaluate(pageFunction, ...args) { return this._context.evaluate(pageFunction, ...args); @@ -225,7 +224,7 @@ class Frame { /** * @param {string} selector - * @param {function()|string} pageFunction + * @param {Function|string} pageFunction * @param {!Array<*>} args * @return {!Promise<(!Object|undefined)>} */ @@ -344,14 +343,14 @@ class Frame { } /** - * @param {(string|number|function())} selectorOrTimeout + * @param {(string|number|Function)} selectorOrFunctionOrTimeout * @param {!Object=} options * @param {!Array<*>} args * @return {!Promise} */ waitFor(selectorOrFunctionOrTimeout, options = {}, ...args) { if (helper.isString(selectorOrFunctionOrTimeout)) - return this.waitForSelector(selectorOrFunctionOrTimeout, options); + return this.waitForSelector(/** @type {string} */(selectorOrFunctionOrTimeout), options); if (helper.isNumber(selectorOrFunctionOrTimeout)) return new Promise(fulfill => setTimeout(fulfill, selectorOrFunctionOrTimeout)); if (typeof selectorOrFunctionOrTimeout === 'function') @@ -387,7 +386,7 @@ class Frame { } /** - * @param {function()} pageFunction + * @param {Function} pageFunction * @param {!Object=} options * @return {!Promise} */ @@ -429,7 +428,7 @@ class WaitTask { /** * @param {!Frame} frame * @param {string} predicateBody - * @param {string} polling + * @param {string|number} polling * @param {number} timeout */ constructor(frame, predicateBody, polling, timeout) { @@ -524,7 +523,7 @@ async function waitForPredicatePageFunction(predicateBody, polling, timeout) { return !timedOut; /** - * @return {!Promise} + * @return {!Promise} */ function pollMutation() { if (predicate()) @@ -582,4 +581,4 @@ async function waitForPredicatePageFunction(predicateBody, polling, timeout) { } } -module.exports = FrameManager; +module.exports = {FrameManager, Frame}; diff --git a/lib/Input.js b/lib/Input.js index a6968167..b14992bf 100644 --- a/lib/Input.js +++ b/lib/Input.js @@ -18,7 +18,7 @@ const {helper} = require('./helper'); class Keyboard { /** - * @param {!Session} client + * @param {!Puppeteer.Session} client */ constructor(client) { this._client = client; @@ -28,10 +28,10 @@ class Keyboard { /** * @param {string} key - * @param {{text: (string|undefined)}} options + * @param {{text: string}=} options */ - async down(key, options = {}) { - const text = options.text; + async down(key, options = {text: ''}) { + const {text} = options; const autoRepeat = this._pressedKeys.has(key); this._pressedKeys.add(key); this._modifiers |= this._modifierBit(key); @@ -118,7 +118,7 @@ class Keyboard { class Mouse { /** - * @param {!Session} client + * @param {Puppeteer.Session} client * @param {!Keyboard} keyboard */ constructor(client, keyboard) { @@ -197,7 +197,7 @@ class Mouse { class Touchscreen { /** - * @param {Session} client + * @param {Puppeteer.Session} client * @param {Keyboard} keyboard */ constructor(client, keyboard) { diff --git a/lib/Launcher.js b/lib/Launcher.js index a6e8cd9d..152afdf8 100644 --- a/lib/Launcher.js +++ b/lib/Launcher.js @@ -18,11 +18,12 @@ const path = require('path'); const removeSync = require('rimraf').sync; const childProcess = require('child_process'); const Downloader = require('../utils/ChromiumDownloader'); -const Connection = require('./Connection'); -const Browser = require('./Browser'); +const {Connection} = require('./Connection'); +const {Browser} = require('./Browser'); const readline = require('readline'); const fs = require('fs'); const {helper} = require('./helper'); +// @ts-ignore const ChromiumRevision = require('../package.json').puppeteer.chromium_revision; const CHROME_PROFILE_PATH = path.join(os.tmpdir(), 'puppeteer_dev_profile-'); @@ -178,7 +179,7 @@ class Launcher { } /** - * @param {!ChildProcess} chromeProcess + * @param {!Puppeteer.ChildProcess} chromeProcess * @param {number} timeout * @return {!Promise} */ diff --git a/lib/Multimap.js b/lib/Multimap.js index 213a782c..6e9c0769 100644 --- a/lib/Multimap.js +++ b/lib/Multimap.js @@ -14,19 +14,11 @@ * limitations under the License. */ -/** - * @template K, V - */ class Multimap { constructor() { - /** @type {!Map>} */ this._map = new Map(); } - /** - * @param {K} key - * @param {V} value - */ set(key, value) { let set = this._map.get(key); if (!set) { @@ -36,10 +28,6 @@ class Multimap { set.add(value); } - /** - * @param {K} key - * @return {!Set} - */ get(key) { let result = this._map.get(key); if (!result) @@ -47,19 +35,10 @@ class Multimap { return result; } - /** - * @param {K} key - * @return {boolean} - */ has(key) { return this._map.has(key); } - /** - * @param {K} key - * @param {V} value - * @return {boolean} - */ hasValue(key, value) { const set = this._map.get(key); if (!set) @@ -74,11 +53,6 @@ class Multimap { return this._map.size; } - /** - * @param {K} key - * @param {V} value - * @return {boolean} - */ delete(key, value) { const values = this.get(key); const result = values.delete(value); @@ -87,17 +61,10 @@ class Multimap { return result; } - /** - * @param {K} key - */ deleteAll(key) { this._map.delete(key); } - /** - * @param {K} key - * @return {?V} value - */ firstValue(key) { const set = this._map.get(key); if (!set) @@ -105,16 +72,10 @@ class Multimap { return set.values().next().value; } - /** - * @return {K} - */ firstKey() { return this._map.keys().next().value; } - /** - * @return {!Array} - */ valuesArray() { const result = []; for (const key of this._map.keys()) @@ -122,9 +83,6 @@ class Multimap { return result; } - /** - * @return {!Array} - */ keysArray() { return Array.from(this._map.keys()); } diff --git a/lib/NavigatorWatcher.js b/lib/NavigatorWatcher.js index 808e9bce..5f8b6580 100644 --- a/lib/NavigatorWatcher.js +++ b/lib/NavigatorWatcher.js @@ -18,7 +18,7 @@ const {helper} = require('./helper'); class NavigatorWatcher { /** - * @param {!Session} client + * @param {!Puppeteer.Session} client * @param {boolean} ignoreHTTPSErrors * @param {!Object=} options */ diff --git a/lib/NetworkManager.js b/lib/NetworkManager.js index a37fe777..1b790c86 100644 --- a/lib/NetworkManager.js +++ b/lib/NetworkManager.js @@ -20,7 +20,7 @@ const url = require('url'); class NetworkManager extends EventEmitter { /** - * @param {!Session} client + * @param {Puppeteer.Session} client */ constructor(client) { super(); @@ -38,9 +38,9 @@ class NetworkManager extends EventEmitter { this._attemptedAuthentications = new Set(); this._userRequestInterceptionEnabled = false; this._protocolRequestInterceptionEnabled = false; - /** @type {!Multimap} */ + /** @type {!Multimap} */ this._requestHashToRequestIds = new Multimap(); - /** @type {!Multimap} */ + /** @type {!Multimap} */ this._requestHashToInterceptions = new Multimap(); this._client.on('Network.requestWillBeSent', this._onRequestWillBeSent.bind(this)); @@ -116,7 +116,7 @@ class NetworkManager extends EventEmitter { response = 'ProvideCredentials'; this._attemptedAuthentications.add(event.interceptionId); } - const {username, password} = this._credentials || {}; + const {username, password} = this._credentials || {username: undefined, password: undefined}; this._client.send('Network.continueInterceptedRequest', { interceptionId: event.interceptionId, authChallengeResponse: { response, username, password } @@ -192,7 +192,6 @@ class NetworkManager extends EventEmitter { /** * @param {string} requestHash - * @param {!{requestEvent: ?Object, interceptionEvent: ?Object}} interception */ _maybeResolveInterception(requestHash) { const requestId = this._requestHashToRequestIds.firstValue(requestHash); @@ -252,10 +251,10 @@ class NetworkManager extends EventEmitter { class Request { /** - * @param {!Connection} client + * @param {!Puppeteer.Session} client * @param {string} requestId * @param {string} interceptionId - * @param {string} allowInterception + * @param {boolean} allowInterception * @param {string} url * @param {string} resourceType * @param {!Object} payload @@ -331,9 +330,9 @@ helper.tracePublicAPI(Request); class Response { /** - * @param {!Session} client + * @param {!Puppeteer.Session} client * @param {!Request} request - * @param {integer} status + * @param {number} status * @param {!Object} headers */ constructor(client, request, status, headers) { @@ -381,7 +380,7 @@ class Response { } /** - * @return {!Response} + * @return {!Request} */ request() { return this._request; diff --git a/lib/Page.js b/lib/Page.js index f369dc3d..6df0fd1f 100644 --- a/lib/Page.js +++ b/lib/Page.js @@ -21,18 +21,17 @@ const NetworkManager = require('./NetworkManager'); const NavigatorWatcher = require('./NavigatorWatcher'); const Dialog = require('./Dialog'); const EmulationManager = require('./EmulationManager'); -const FrameManager = require('./FrameManager'); +const {FrameManager} = require('./FrameManager'); const {Keyboard, Mouse, Touchscreen} = require('./Input'); const Tracing = require('./Tracing'); const {helper, debugError} = require('./helper'); class Page extends EventEmitter { /** - * @param {!Session} client - * @param {string} sessionId + * @param {!Puppeteer.Session} client * @param {boolean} ignoreHTTPSErrors * @param {boolean} appMode - * @param {!TaskQueue} screenshotTaskQueue + * @param {!Puppeteer.TaskQueue} screenshotTaskQueue * @return {!Promise} */ static async create(client, ignoreHTTPSErrors, appMode, screenshotTaskQueue) { @@ -53,9 +52,9 @@ class Page extends EventEmitter { } /** - * @param {!Session} client + * @param {!Puppeteer.Session} client * @param {boolean} ignoreHTTPSErrors - * @param {!TaskQueue} screenshotTaskQueue + * @param {!Puppeteer.TaskQueue} screenshotTaskQueue */ constructor(client, ignoreHTTPSErrors, screenshotTaskQueue) { super(); @@ -67,7 +66,7 @@ class Page extends EventEmitter { this._networkManager = new NetworkManager(client); this._emulationManager = new EmulationManager(client); this._tracing = new Tracing(client); - /** @type {!Map} */ + /** @type {!Map} */ this._pageBindings = new Map(); this._ignoreHTTPSErrors = ignoreHTTPSErrors; @@ -95,7 +94,7 @@ class Page extends EventEmitter { } /** - * @return {!Frame} + * @return {!Puppeteer.Frame} */ mainFrame() { return this._frameManager.mainFrame(); @@ -133,7 +132,7 @@ class Page extends EventEmitter { } /** - * @return {!Array} + * @return {!Array} */ frames() { return this._frameManager.frames(); @@ -160,17 +159,16 @@ class Page extends EventEmitter { /** * @param {string} selector - * @return {!Promise} + * @return {!Promise} */ async $(selector) { return this.mainFrame().$(selector); } /** - * @param {string} selector * @param {function()|string} pageFunction * @param {!Array<*>} args - * @return {!Promise} + * @return {!Promise} */ async evaluateHandle(pageFunction, ...args) { return this.mainFrame().executionContext().evaluateHandle(pageFunction, ...args); @@ -188,7 +186,7 @@ class Page extends EventEmitter { /** * @param {string} selector - * @return {!Promise>} + * @return {!Promise>} */ async $$(selector) { return this.mainFrame().$$(selector); @@ -385,7 +383,7 @@ class Page extends EventEmitter { } /** - * @param {string} html + * @param {string} url * @param {!Object=} options * @return {!Promise} */ @@ -518,7 +516,7 @@ class Page extends EventEmitter { /** * @param {function()} pageFunction * @param {!Array<*>} args - * @return {!Promise<(!Object|undefined)>} + * @return {!Promise<*>} */ async evaluate(pageFunction, ...args) { return this._frameManager.mainFrame().evaluate(pageFunction, ...args); @@ -749,7 +747,7 @@ class Page extends EventEmitter { } /** - * @param {(string|number|function())} selectorOrTimeout + * @param {(string|number|Function)} selectorOrFunctionOrTimeout * @param {!Object=} options * @param {!Array<*>} args * @return {!Promise} @@ -811,7 +809,7 @@ function convertPrintParameterToInches(parameter) { // Treat numbers as pixel values to be aligned with phantom's paperSize. pixels = /** @type {number} */ (parameter); } else if (helper.isString(parameter)) { - const text = parameter; + const text = /** @type {string} */ (parameter); let unit = text.substring(text.length - 2).toLowerCase(); let valueText = ''; if (unitToPixels.hasOwnProperty(unit)) { @@ -848,8 +846,15 @@ Page.Events = { Load: 'load', }; -/** @typedef {{width: number, height: number, deviceScaleFactor: number|undefined, isMobile: boolean|undefined, isLandscape: boolean, hasTouch: boolean|undefined}} */ -Page.Viewport; +/** + * @typedef {Object} Page.Viewport + * @property {number} width + * @property {number} height + * @property {number=} deviceScaleFactor + * @property {boolean=} isMobile + * @property {boolean=} isLandscape + * @property {boolean=} hasTouch + */ /** * @typedef {Object} Network.Cookie diff --git a/lib/Puppeteer.js b/lib/Puppeteer.js index 2caa58be..0a44db1d 100644 --- a/lib/Puppeteer.js +++ b/lib/Puppeteer.js @@ -19,15 +19,15 @@ const Launcher = require('./Launcher'); class Puppeteer { /** * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ static launch(options) { return Launcher.launch(options); } /** - * @param {string} options - * @return {!Promise} + * @param {{browserWSEndpoint: string, ignoreHTTPSErrors: boolean}} options + * @return {!Promise} */ static connect(options) { return Launcher.connect(options); diff --git a/lib/Tracing.js b/lib/Tracing.js index 583fe48b..1732164a 100644 --- a/lib/Tracing.js +++ b/lib/Tracing.js @@ -18,7 +18,7 @@ const {helper} = require('./helper'); class Tracing { /** - * @param {!Session} client + * @param {!Puppeteer.Session} client */ constructor(client) { this._client = client; diff --git a/lib/externs.d.ts b/lib/externs.d.ts new file mode 100644 index 00000000..dcadfdb2 --- /dev/null +++ b/lib/externs.d.ts @@ -0,0 +1,28 @@ +import { Connection as RealConnection, Session as RealSession } from './Connection.js'; +import {Browser as RealBrowser, TaskQueue as RealTaskQueue} from './Browser.js'; +import * as RealPage from './Page.js'; +import {Mouse as RealMouse, Keyboard as RealKeyboard, Touchscreen as RealTouchscreen} from './Input.js'; +import {Frame as RealFrame, FrameManager as RealFrameManager} from './FrameManager.js'; +import {JSHandle as RealJSHandle, ExecutionContext as RealExecutionContext} from './ExecutionContext.js'; +import * as RealElementHandle from './ElementHandle.js'; +import * as RealNetworkManager from './NetworkManager.js'; +import * as child_process from 'child_process'; +export as namespace Puppeteer; + +export class Connection extends RealConnection {} +export class Session extends RealSession {} +export class Mouse extends RealMouse {} +export class Keyboard extends RealKeyboard {} +export class Touchscreen extends RealTouchscreen {} +export class TaskQueue extends RealTaskQueue {} +export class Browser extends RealBrowser {} +export class Frame extends RealFrame {} +export class FrameManager extends RealFrameManager {} +export class NetworkManager extends RealNetworkManager {} +export class ElementHandle extends RealElementHandle {} +export class JSHandle extends RealJSHandle {} +export class ExecutionContext extends RealExecutionContext {} +export class Page extends RealPage {} + + +export interface ChildProcess extends child_process.ChildProcess {} diff --git a/lib/helper.js b/lib/helper.js index 4245fad4..ad14533c 100644 --- a/lib/helper.js +++ b/lib/helper.js @@ -19,14 +19,14 @@ const debugError = require('debug')(`puppeteer:error`); let apiCoverage = null; class Helper { /** - * @param {function()|string} fun + * @param {Function|string} fun * @param {!Array<*>} args * @return {string} */ static evaluationString(fun, ...args) { if (Helper.isString(fun)) { console.assert(args.length === 0, 'Cannot evaluate a string with arguments'); - return fun; + return /** @type {string} */ (fun); } return `(${fun})(${args.map(serializeArgument).join(',')})`; @@ -60,9 +60,8 @@ class Helper { } /** - * @param {!Session} client * @param {!Object} remoteObject - * @return {!Promise} + * @return {*} */ static valueFromRemoteObject(remoteObject) { console.assert(!remoteObject.objectId, 'Cannot extract value when objectId is given'); @@ -84,7 +83,7 @@ class Helper { } /** - * @param {!Session} client + * @param {!Puppeteer.Session} client * @param {!Object} remoteObject */ static async releaseObject(client, remoteObject) { @@ -165,10 +164,10 @@ class Helper { } /** - * @param {!EventEmitter} emitter + * @param {!NodeJS.EventEmitter} emitter * @param {string} eventName * @param {function(?)} handler - * @return {{emitter: !EventEmitter, eventName: string, handler: function(?)}} + * @return {{emitter: !NodeJS.EventEmitter, eventName: string, handler: function(?)}} */ static addEventListener(emitter, eventName, handler) { emitter.on(eventName, handler); @@ -176,7 +175,7 @@ class Helper { } /** - * @param {!Array<{emitter: !EventEmitter, eventName: string, handler: function(?)}>} + * @param {!Array<{emitter: !NodeJS.EventEmitter, eventName: string, handler: function(?)}>} listeners */ static removeEventListeners(listeners) { for (const listener of listeners) diff --git a/package.json b/package.json index 77be8a1f..23811393 100644 --- a/package.json +++ b/package.json @@ -13,12 +13,13 @@ "test-doclint": "jasmine utils/doclint/check_public_api/test/test.js && jasmine utils/doclint/preprocessor/test.js", "test": "npm run lint --silent && npm run coverage && npm run test-doclint && npm run test-node6-transformer", "install": "node install.js", - "lint": "([ \"$CI\" = true ] && eslint --quiet -f codeframe . || eslint .) && npm run doc", + "lint": "([ \"$CI\" = true ] && eslint --quiet -f codeframe . || eslint .) && npm run tsc && npm run doc", "doc": "node utils/doclint/cli.js", "coverage": "COVERAGE=true npm run unit", "test-node6-transformer": "jasmine utils/node6-transform/test/test.js", "build": "node utils/node6-transform/index.js", - "unit-node6": "jasmine node6-test/test.js" + "unit-node6": "jasmine node6-test/test.js", + "tsc": "tsc -p ." }, "author": "The Chromium Authors", "license": "Apache-2.0", @@ -36,6 +37,12 @@ "chromium_revision": "503964" }, "devDependencies": { + "@types/debug": "0.0.30", + "@types/extract-zip": "^1.6.2", + "@types/mime": "^1.3.1", + "@types/node": "^8.0.26", + "@types/rimraf": "^2.0.2", + "@types/ws": "^3.0.2", "commonmark": "^0.27.0", "eslint": "^4.0.0", "esprima": "^4.0.0", @@ -46,6 +53,7 @@ "pdfjs-dist": "^1.8.595", "pixelmatch": "^4.0.2", "pngjs": "^3.2.0", - "text-diff": "^1.0.1" + "text-diff": "^1.0.1", + "typescript": "next" } } diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 00000000..b5b9516c --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,11 @@ +{ + "compilerOptions": { + "noEmit": true, + "allowJs": true, + "checkJs": true, + "target": "es2017" + }, + "include": [ + "lib" + ] +} diff --git a/utils/ChromiumDownloader.js b/utils/ChromiumDownloader.js index 6992d991..a0e6237a 100644 --- a/utils/ChromiumDownloader.js +++ b/utils/ChromiumDownloader.js @@ -22,7 +22,9 @@ const extract = require('extract-zip'); const util = require('util'); const URL = require('url'); const removeRecursive = require('rimraf'); +// @ts-ignore const ProxyAgent = require('https-proxy-agent'); +// @ts-ignore const getProxyForUrl = require('proxy-from-env').getProxyForUrl; const DOWNLOADS_FOLDER = path.join(__dirname, '..', '.local-chromium'); @@ -144,7 +146,7 @@ module.exports = { else if (platform === 'win32' || platform === 'win64') executablePath = path.join(folderPath, 'chrome-win32', 'chrome.exe'); else - throw 'Unsupported platfrom: ' + platfrom; + throw 'Unsupported platfrom: ' + platform; return { executablePath, folderPath, @@ -202,7 +204,7 @@ function downloadFile(url, destinationPath, progressCallback) { file.on('finish', () => fulfill()); file.on('error', error => reject(error)); response.pipe(file); - const totalBytes = parseInt(response.headers['content-length'], 10); + const totalBytes = parseInt(/** @type {string} */ (response.headers['content-length']), 10); if (progressCallback) response.on('data', onData.bind(null, totalBytes)); }); @@ -224,11 +226,13 @@ function extractZip(zipPath, folderPath) { } function requestOptions(url, method = 'GET') { + /** @type {Object} */ const result = URL.parse(url); result.method = method; const proxyURL = getProxyForUrl(url); if (proxyURL) { + /** @type {Object} */ const parsedProxyURL = URL.parse(proxyURL); parsedProxyURL.secureProxy = parsedProxyURL.protocol === 'https:'; diff --git a/utils/doclint/check_public_api/JSBuilder.js b/utils/doclint/check_public_api/JSBuilder.js index 26c77a79..8bec50b3 100644 --- a/utils/doclint/check_public_api/JSBuilder.js +++ b/utils/doclint/check_public_api/JSBuilder.js @@ -86,13 +86,13 @@ class JSOutline { } const args = []; for (const param of node.value.params) { - if (param.type === 'AssignmentPattern') + if (param.type === 'AssignmentPattern' && param.left.name) args.push(new Documentation.Argument(param.left.name)); else if (param.type === 'RestElement') args.push(new Documentation.Argument('...' + param.argument.name)); else if (param.type === 'Identifier') args.push(new Documentation.Argument(param.name)); - else if (param.type === 'ObjectPattern') + else if (param.type === 'ObjectPattern' || param.type === 'AssignmentPattern') args.push(new Documentation.Argument('options')); else this.errors.push(`JS Parsing issue: unsupported syntax to define parameter in ${this._currentClassName}.${methodName}(): ${this._extractText(param)}`); diff --git a/yarn.lock b/yarn.lock index 507e65c5..fde13bed 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2,6 +2,46 @@ # yarn lockfile v1 +"@types/debug@0.0.30": + version "0.0.30" + resolved "https://registry.yarnpkg.com/@types/debug/-/debug-0.0.30.tgz#dc1e40f7af3b9c815013a7860e6252f6352a84df" + +"@types/extract-zip@^1.6.2": + version "1.6.2" + resolved "https://registry.yarnpkg.com/@types/extract-zip/-/extract-zip-1.6.2.tgz#5c7eb441c41136167a42b88b64051e6260c29e86" + +"@types/glob@*": + version "5.0.32" + resolved "https://registry.yarnpkg.com/@types/glob/-/glob-5.0.32.tgz#aec5cfe987c72f099fdb1184452986aa506d5e8f" + dependencies: + "@types/minimatch" "*" + "@types/node" "*" + +"@types/mime@^1.3.1": + version "1.3.1" + resolved "https://registry.yarnpkg.com/@types/mime/-/mime-1.3.1.tgz#2cf42972d0931c1060c7d5fa6627fce6bd876f2f" + +"@types/minimatch@*": + version "3.0.1" + resolved "https://registry.yarnpkg.com/@types/minimatch/-/minimatch-3.0.1.tgz#b683eb60be358304ef146f5775db4c0e3696a550" + +"@types/node@*", "@types/node@^8.0.26": + version "8.0.26" + resolved "https://registry.yarnpkg.com/@types/node/-/node-8.0.26.tgz#4d58be925306fd22b1141085535a0268b8beb189" + +"@types/rimraf@^2.0.2": + version "2.0.2" + resolved "https://registry.yarnpkg.com/@types/rimraf/-/rimraf-2.0.2.tgz#7f0fc3cf0ff0ad2a99bb723ae1764f30acaf8b6e" + dependencies: + "@types/glob" "*" + "@types/node" "*" + +"@types/ws@^3.0.2": + version "3.0.2" + resolved "https://registry.yarnpkg.com/@types/ws/-/ws-3.0.2.tgz#b538b6a16daee454ac04054991271f3da38772de" + dependencies: + "@types/node" "*" + acorn-jsx@^3.0.0: version "3.0.1" resolved "https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-3.0.1.tgz#afdf9488fb1ecefc8348f6fb22f464e32a58b36b" @@ -1070,6 +1110,10 @@ typedarray@^0.0.6: version "0.0.6" resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777" +typescript@next: + version "2.6.0-dev.20171007" + resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.6.0-dev.20171007.tgz#feead6b2bd906771c95fb8ae27e146d5b5ff6cd6" + ultron@~1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/ultron/-/ultron-1.1.0.tgz#b07a2e6a541a815fc6a34ccd4533baec307ca864"