diff --git a/.gitignore b/.gitignore index d720887a..88c2cec2 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ yarn.lock /utils/browser/puppeteer-web.js /lib test/coverage.json +temp/ diff --git a/api-extractor.json b/api-extractor.json new file mode 100644 index 00000000..76afa3db --- /dev/null +++ b/api-extractor.json @@ -0,0 +1,42 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "mainEntryPointFilePath": "/lib/api-docs-entry.d.ts", + "bundledPackages": [ ], + + "apiReport": { + "enabled": false + }, + + "docModel": { + "enabled": true + }, + + "dtsRollup": { + "enabled": false + }, + + "tsdocMetadata": { + "enabled": false + }, + + "messages": { + "compilerMessageReporting": { + "default": { + "logLevel": "warning" + } + }, + + "extractorMessageReporting": { + "default": { + "logLevel": "warning" + } + }, + + "tsdocMessageReporting": { + "default": { + "logLevel": "warning" + } + } + } + +} diff --git a/package.json b/package.json index fad0a2dc..5fbe2793 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,8 @@ "apply-next-version": "node utils/apply_next_version.js", "update-protocol-d-ts": "node utils/protocol-types-generator update", "compare-protocol-d-ts": "node utils/protocol-types-generator compare", - "test-install": "scripts/test-install.sh" + "test-install": "scripts/test-install.sh", + "generate-docs": "npm run tsc && api-extractor run --local --verbose && api-documenter markdown -i temp -o new-docs" }, "files": [ "lib/", @@ -56,6 +57,8 @@ "ws": "^7.2.3" }, "devDependencies": { + "@microsoft/api-documenter": "^7.8.8", + "@microsoft/api-extractor": "^7.8.8", "@types/debug": "0.0.31", "@types/mime": "^2.0.0", "@types/node": "^10.17.14", diff --git a/src/Browser.ts b/src/Browser.ts index 2b23e22e..2dcf3572 100644 --- a/src/Browser.ts +++ b/src/Browser.ts @@ -22,7 +22,7 @@ import Protocol from './protocol'; import { Connection } from './Connection'; import { Page } from './Page'; import { ChildProcess } from 'child_process'; -import type { Viewport } from './PuppeteerViewport'; +import { Viewport } from './PuppeteerViewport'; type BrowserCloseCallback = () => Promise | void; diff --git a/src/Connection.ts b/src/Connection.ts index e2e15b83..0e95582a 100644 --- a/src/Connection.ts +++ b/src/Connection.ts @@ -19,7 +19,7 @@ import * as debug from 'debug'; const debugProtocol = debug('puppeteer:protocol'); import Protocol from './protocol'; -import type { ConnectionTransport } from './ConnectionTransport'; +import { ConnectionTransport } from './ConnectionTransport'; import * as EventEmitter from 'events'; interface ConnectionCallback { diff --git a/src/EmulationManager.ts b/src/EmulationManager.ts index 58711783..8ff36b46 100644 --- a/src/EmulationManager.ts +++ b/src/EmulationManager.ts @@ -14,7 +14,7 @@ * limitations under the License. */ import { CDPSession } from './Connection'; -import type { Viewport } from './PuppeteerViewport'; +import { Viewport } from './PuppeteerViewport'; import Protocol from './protocol'; export class EmulationManager { diff --git a/src/Launcher.ts b/src/Launcher.ts index 11a132da..f6e90eae 100644 --- a/src/Launcher.ts +++ b/src/Launcher.ts @@ -24,14 +24,14 @@ import { BrowserFetcher } from './BrowserFetcher'; import { Connection } from './Connection'; import { Browser } from './Browser'; import { helper, assert, debugError } from './helper'; -import type { ConnectionTransport } from './ConnectionTransport'; +import { ConnectionTransport } from './ConnectionTransport'; import { WebSocketTransport } from './WebSocketTransport'; import { BrowserRunner } from './launcher/BrowserRunner'; const mkdtempAsync = helper.promisify(fs.mkdtemp); const writeFileAsync = helper.promisify(fs.writeFile); -import type { +import { ChromeArgOptions, LaunchOptions, BrowserOptions, diff --git a/src/Page.ts b/src/Page.ts index e569f894..974f6fd6 100644 --- a/src/Page.ts +++ b/src/Page.ts @@ -30,7 +30,7 @@ import { WebWorker } from './WebWorker'; import { Browser, BrowserContext } from './Browser'; import { Target } from './Target'; import { createJSHandle, JSHandle, ElementHandle } from './JSHandle'; -import type { Viewport } from './PuppeteerViewport'; +import { Viewport } from './PuppeteerViewport'; import { Credentials } from './NetworkManager'; import { HTTPRequest } from './HTTPRequest'; import { HTTPResponse } from './HTTPResponse'; diff --git a/src/PipeTransport.ts b/src/PipeTransport.ts index 7adf79a3..71cdc889 100644 --- a/src/PipeTransport.ts +++ b/src/PipeTransport.ts @@ -14,7 +14,7 @@ * limitations under the License. */ import { helper, debugError, PuppeteerEventListener } from './helper'; -import type { ConnectionTransport } from './ConnectionTransport'; +import { ConnectionTransport } from './ConnectionTransport'; export class PipeTransport implements ConnectionTransport { _pipeWrite: NodeJS.WritableStream; diff --git a/src/Puppeteer.ts b/src/Puppeteer.ts index 794d8566..0e92a2ec 100644 --- a/src/Puppeteer.ts +++ b/src/Puppeteer.ts @@ -14,21 +14,31 @@ * limitations under the License. */ import Launcher from './Launcher'; -import type { +import { LaunchOptions, ChromeArgOptions, BrowserOptions, } from './launcher/LaunchOptions'; -import type { ProductLauncher } from './Launcher'; +import { ProductLauncher } from './Launcher'; import { BrowserFetcher, BrowserFetcherOptions } from './BrowserFetcher'; import { puppeteerErrors, PuppeteerErrors } from './Errors'; -import type { ConnectionTransport } from './ConnectionTransport'; +import { ConnectionTransport } from './ConnectionTransport'; import { devicesMap } from './DeviceDescriptors'; -import type { DevicesMap } from './/DeviceDescriptors'; +import { DevicesMap } from './/DeviceDescriptors'; import { Browser } from './Browser'; -import * as QueryHandler from './QueryHandler'; +import { + registerCustomQueryHandler, + unregisterCustomQueryHandler, + customQueryHandlers, + clearQueryHandlers, + QueryHandler, +} from './QueryHandler'; +/** + * The main Puppeteer class + * @public + */ export class Puppeteer { _projectRoot: string; _preferredRevision: string; @@ -135,23 +145,23 @@ export class Puppeteer { // eslint-disable-next-line @typescript-eslint/camelcase __experimental_registerCustomQueryHandler( name: string, - queryHandler: QueryHandler.QueryHandler + queryHandler: QueryHandler ): void { - QueryHandler.registerCustomQueryHandler(name, queryHandler); + registerCustomQueryHandler(name, queryHandler); } // eslint-disable-next-line @typescript-eslint/camelcase __experimental_unregisterCustomQueryHandler(name: string): void { - QueryHandler.unregisterCustomQueryHandler(name); + unregisterCustomQueryHandler(name); } // eslint-disable-next-line @typescript-eslint/camelcase - __experimental_customQueryHandlers(): Map { - return QueryHandler.customQueryHandlers(); + __experimental_customQueryHandlers(): Map { + return customQueryHandlers(); } // eslint-disable-next-line @typescript-eslint/camelcase __experimental_clearQueryHandlers(): void { - QueryHandler.clearQueryHandlers(); + clearQueryHandlers(); } } diff --git a/src/QueryHandler.ts b/src/QueryHandler.ts index ca8cc6b4..7f86c242 100644 --- a/src/QueryHandler.ts +++ b/src/QueryHandler.ts @@ -74,11 +74,3 @@ export function getQueryHandlerAndSelector( queryHandler, }; } - -module.exports = { - registerCustomQueryHandler, - unregisterCustomQueryHandler, - customQueryHandlers, - getQueryHandlerAndSelector, - clearQueryHandlers, -}; diff --git a/src/Target.ts b/src/Target.ts index 8fe0df7c..b4c71b19 100644 --- a/src/Target.ts +++ b/src/Target.ts @@ -19,7 +19,7 @@ import { Page } from './Page'; import { WebWorker } from './WebWorker'; import { CDPSession } from './Connection'; import { Browser, BrowserContext } from './Browser'; -import type { Viewport } from './PuppeteerViewport'; +import { Viewport } from './PuppeteerViewport'; import Protocol from './protocol'; export class Target { diff --git a/src/WebSocketTransport.ts b/src/WebSocketTransport.ts index f1305599..d7faf45a 100644 --- a/src/WebSocketTransport.ts +++ b/src/WebSocketTransport.ts @@ -14,7 +14,7 @@ * limitations under the License. */ import * as NodeWebSocket from 'ws'; -import type { ConnectionTransport } from './ConnectionTransport'; +import { ConnectionTransport } from './ConnectionTransport'; export class WebSocketTransport implements ConnectionTransport { static create(url: string): Promise { diff --git a/src/api-docs-entry.ts b/src/api-docs-entry.ts new file mode 100644 index 00000000..d9d3b379 --- /dev/null +++ b/src/api-docs-entry.ts @@ -0,0 +1,47 @@ +/** + * Copyright 2020 Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * This file re-exports any APIs that we want to have documentation generated for. + * It is used by API Extractor to determine what parts of the system to document. + * + * We also have src/api.ts. This is used in `index.js` and by the legacy DocLint system. + * src/api-docs-entry.ts is ONLY used by API Extractor. + * + * Once we have migrated to API Extractor and removed DocLint we can remove the duplication and use this file. + */ +export * from './Accessibility'; +export * from './Browser'; +export * from './BrowserFetcher'; +export * from './Connection'; +export * from './ConsoleMessage'; +export * from './Coverage'; +export * from './Dialog'; +export * from './JSHandle'; +export * from './ExecutionContext'; +export * from './FileChooser'; +export * from './FrameManager'; +export * from './JSHandle'; +export * from './Input'; +export * from './Page'; +export * from './Puppeteer'; +export * from './HTTPRequest'; +export * from './HTTPResponse'; +export * from './SecurityDetails'; +export * from './Target'; +export * from './Errors'; +export * from './Tracing'; +export * from './WebWorker'; diff --git a/src/launcher/BrowserRunner.ts b/src/launcher/BrowserRunner.ts index 2d6a629b..d225de0c 100644 --- a/src/launcher/BrowserRunner.ts +++ b/src/launcher/BrowserRunner.ts @@ -19,7 +19,7 @@ import * as debug from 'debug'; import * as removeFolder from 'rimraf'; import * as childProcess from 'child_process'; import { helper, assert, debugError } from '../helper'; -import type { LaunchOptions } from './LaunchOptions'; +import { LaunchOptions } from './LaunchOptions'; import { Connection } from '../Connection'; import { WebSocketTransport } from '../WebSocketTransport'; import { PipeTransport } from '../PipeTransport'; diff --git a/tsconfig.json b/tsconfig.json index baf9d96a..08e9ba92 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -5,7 +5,9 @@ "outDir": "./lib", "target": "ESNext", "moduleResolution": "node", - "module": "CommonJS" + "module": "CommonJS", + "declaration": true, + "declarationMap": true }, "include": [ "src"