feat: export public types only (#8584)

.eslintignore

@@ -5,4 +5,4 @@ doclint/
 lib/
 test-ts-types/
 tsconfig.tsbuildinfo
-vendor/
+vendor/

.gitignore

@@ -13,6 +13,7 @@ docs/api.html
 lib/
 node_modules/
 package-lock.json
+puppeteer.api.json
 puppeteer*.tgz
 test-ts-types/**/dist/
 test-ts-types/**/node_modules

.prettierignore

@@ -5,7 +5,6 @@ build/
 CHANGELOG.md
 coverage/
 doclint/
-docs-api-json/
 lib/
 node_modules/
 package-lock.json
@@ -14,4 +13,5 @@ test-ts-types/
 test/assets/
 tsconfig.tsbuildinfo
 vendor/
-yarn.lock
+yarn.lock
+puppeteer.api.json

api-extractor.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  "mainEntryPointFilePath": "<projectFolder>/lib/cjs/puppeteer/api-docs-entry.d.ts",
+  "mainEntryPointFilePath": "<projectFolder>/lib/esm/puppeteer/types.d.ts",
   "bundledPackages": [],
 
   "apiReport": {
@@ -9,12 +9,13 @@
 
   "docModel": {
     "enabled": true,
-    "apiJsonFilePath": "<projectFolder>/docs-api-json/<unscopedPackageName>.api.json"
+    "apiJsonFilePath": "<projectFolder>/docs/<unscopedPackageName>.api.json"
   },
 
   "dtsRollup": {
     "enabled": true,
-    "untrimmedFilePath": "lib/types.d.ts"
+    "untrimmedFilePath": "",
+    "alphaTrimmedFilePath": "lib/types.d.ts"
   },
 
   "tsdocMetadata": {

compat/cjs/compat.ts

@@ -1,5 +1,8 @@
 import {dirname} from 'path';
 
+/**
+ * @internal
+ */
 let puppeteerDirname: string;
 
 try {

compat/esm/compat.ts

@@ -4,6 +4,9 @@ import {fileURLToPath} from 'url';
 
 const require = createRequire(import.meta.url);
 
+/**
+ * @internal
+ */
 let puppeteerDirname: string;
 
 try {

package.json

@@ -44,15 +44,14 @@
     "lint:eslint": "([ \"$CI\" = true ] && eslint --ext js --ext ts --quiet -f codeframe . || eslint --ext js --ext ts .)",
     "lint:eslint:fix": "eslint --ext js --ext ts --fix .",
     "install": "node install.js",
-    "generate:types": "npm run clean:docs && api-extractor run --local --verbose",
+    "generate:types": "node utils/export_all.js && api-extractor run --local --verbose",
     "generate:esm-package-json": "echo '{\"type\": \"module\"}' > lib/esm/package.json",
     "generate:docs": "npm run generate:types && node utils/remove-tag.js",
     "generate:docs:testing": "commonmark docs/api.md > docs/api.html",
     "format": "prettier --write .",
     "doc": "node utils/doclint/cli.js",
     "commitlint": "commitlint --from=HEAD~1",
     "clean:lib": "rimraf lib",
-    "clean:docs": "rimraf docs-api-json",
     "build": "npm run build:tsc && npm run generate:types && npm run generate:esm-package-json",
     "build:test": "tsc -b test",
     "build:tsc": "npm run clean:lib && tsc --version && (npm run build:tsc:cjs && npm run build:tsc:esm)",

src/common/BrowserWebSocketTransport.ts

@@ -15,6 +15,9 @@
  */
 import {ConnectionTransport} from './ConnectionTransport.js';
 
+/**
+ * @internal
+ */
 export class BrowserWebSocketTransport implements ConnectionTransport {
   static create(url: string): Promise<BrowserWebSocketTransport> {
     return new Promise((resolve, reject) => {

src/common/DOMWorld.ts

@@ -24,7 +24,7 @@ import {Frame, FrameManager} from './FrameManager.js';
 import {MouseButton} from './Input.js';
 import {JSHandle} from './JSHandle.js';
 import {LifecycleWatcher, PuppeteerLifeCycleEvent} from './LifecycleWatcher.js';
-import {_getQueryHandlerAndSelector} from './QueryHandler.js';
+import {getQueryHandlerAndSelector} from './QueryHandler.js';
 import {TimeoutSettings} from './TimeoutSettings.js';
 import {EvaluateFunc, HandleFor} from './types.js';
 import {
@@ -653,7 +653,7 @@ export class DOMWorld {
     options: WaitForSelectorOptions
   ): Promise<ElementHandle | null> {
     const {updatedSelector, queryHandler} =
-      _getQueryHandlerAndSelector(selector);
+      getQueryHandlerAndSelector(selector);
     assert(queryHandler.waitFor, 'Query handler does not support waiting');
     return queryHandler.waitFor(this, updatedSelector, options);
   }

src/common/Debug.ts

@@ -25,14 +25,10 @@ declare global {
  * A debug function that can be used in any environment.
  *
  * @remarks
- *
  * If used in Node, it falls back to the
  * {@link https://www.npmjs.com/package/debug | debug module}. In the browser it
  * uses `console.log`.
  *
- * @param prefix - this will be prefixed to each log.
- * @returns a function that can be called to log to that debug channel.
- *
  * In Node, use the `DEBUG` environment variable to control logging:
  *
  * ```
@@ -56,6 +52,11 @@ declare global {
  * log('new page created')
  * // logs "Page: new page created"
  * ```
+ *
+ * @param prefix - this will be prefixed to each log.
+ * @returns a function that can be called to log to that debug channel.
+ *
+ * @internal
  */
 export const debug = (prefix: string): ((...args: unknown[]) => void) => {
   if (isNode) {

src/common/DeviceDescriptors.ts

@@ -30,7 +30,7 @@ export interface Device {
   };
 }
 
-const devices: Device[] = [
+const deviceArray: Device[] = [
   {
     name: 'Blackberry PlayBook',
     userAgent:
@@ -1536,10 +1536,30 @@ export type DevicesMap = {
 };
 
 /**
- * @internal
+ * A list of devices to be used with `page.emulate(options)`. Actual list of devices can be found in {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts | src/common/DeviceDescriptors.ts}.
+ *
+ * @example
+ *
+ * ```js
+ * const puppeteer = require('puppeteer');
+ * const iPhone = puppeteer.devices['iPhone 6'];
+ *
+ * (async () => {
+ *   const browser = await puppeteer.launch();
+ *   const page = await browser.newPage();
+ *   await page.emulate(iPhone);
+ *   await page.goto('https://www.google.com');
+ *   // other actions...
+ *   await browser.close();
+ * })();
+ * ```
+ *
+ * @public
  */
-export const _devicesMap: DevicesMap = {};
+const devices: DevicesMap = {};
 
-for (const device of devices) {
-  _devicesMap[device.name] = device;
+for (const device of deviceArray) {
+  devices[device.name] = device;
 }
+
+export {devices};