2017-05-11 07:06:41 +00:00
|
|
|
{
|
|
|
|
|
"name": "puppeteer",
|
2022-02-10 15:26:20 +00:00
|
|
|
"version": "13.3.1-post",
|
2017-08-16 05:30:56 +00:00
|
|
|
"description": "A high-level API to control headless Chrome over the DevTools Protocol",
|
2020-06-25 13:24:46 +00:00
|
|
|
"main": "./cjs-entry.js",
|
fix: much better TypeScript definitions (#6837)
This PR aims to vastly improve our TS types and how we ship them.
Our previous attempt at shipping TypeScript was unfortunately flawed for
many reasons when compared to the @types/puppeteer package:
* It only worked if you needed the default export. If you wanted to
import a type that Puppeteer uses, you'd have to do `import type X
from 'puppeteer/lib/...'`. This is not something we want to encourage
because that means our internal file structure becomes almost public
API.
* It gave absolutely no help to CommonJS users in JS files because it
would warn people they needed to do `const pptr =
require('puppeteer').default, which is not correct.
* I found a bug in the `evaluate` types which mean't you couldn't
override the types to provide more info, and TS would insist the types
were all `unknown`.
The goal of this PR is to support:
1. In a `ts` file, `import puppeteer from 'puppeteer'`
1. In a `ts` file, `import type {ElementHandle} from 'puppeteer'`
1. In a `ts` file, referencing a type as `puppeteer.ElementHandle`
1. In a `ts` file, you can get good type inference when running
`foo.evaluate(x => x.clientHeight)`.
1. In a `js` file using CJS, you can do `const puppeteer =
require('puppeteer')` and get good type help from VSCode.
To test this I created a new empty repository with two test files in,
one `.ts` file with this in:
https://gist.github.com/jackfranklin/22ba2f390f97c7312cd70025a2096fc8,
and a `js` file with this in:
https://gist.github.com/jackfranklin/06bed136fdb22419cb7a8a9a4d4ef32f.
These files included enough code to check that the types were behaving
as I expected.
The fix for our types was to make use of API Extractor, which we already
use for our docs, to "rollup" all the disparate type files that TS
generates into one large `types.d.ts` which contains all the various
types that we define, such as:
```ts
export declare class ElementHandle {...}
export type EvaluateFn ...
```
If we then update our `package.json` `types` field to point to that file
in `lib/types.d.ts`, this then allows a developer to write:
```
import type {ElementHandle} from 'puppeteer'
```
And get the correct type definitions. However, what the `types.d.ts`
file doesn't do out of the box is declare the default export, so
importing Puppeteer's default export to call a method such as `launch`
on it will get you an error.
That's where the `script/add-default-export-to-types.ts` comes in. It
appends the following to the auto-generated `types.d.ts` file:
```ts
declare const puppeteer: PuppeteerNode;
export = puppeteer;
```
This tells TypeScript what the default export is, and by using the
`export =` syntax, we make sure TS understands both in a TS ESM
environment and in a JS CJS environment.
Now the `build` step, which is run by GitHub Actions when we release,
will generate the `.d.ts` file and then extend it with the default
export code.
To ensure that I was generating a valid package, I created a new
repository locally with the two code samples linked in Gists above. I
then ran:
```
npm init -y
npm install --save-dev typescript
npx tsc --init
```
Which gives me a base to test from. In Puppeteer, I ran `npm pack`,
which packs the module into a tar that's almost identical to what would
be published, so I can be confident that the .d.ts files in there are
what would be published.
I then installed it:
```
npm install --save-dev ../../puppeteer/puppeteer-7.0.1-post.tgz
```
And then reloaded VSCode in my dummy project. By deliberately making
typos and hovering over the code, I could confirm that all the goals
listed above were met, and this seems like a vast improvement on our
types.
2021-02-09 08:00:42 +00:00
|
|
|
"types": "lib/types.d.ts",
|
2019-11-26 12:12:25 +00:00
|
|
|
"repository": "github:puppeteer/puppeteer",
|
2017-06-19 22:01:14 +00:00
|
|
|
"engines": {
|
2020-03-10 20:55:32 +00:00
|
|
|
"node": ">=10.18.1"
|
2017-06-19 22:01:14 +00:00
|
|
|
},
|
2017-05-11 07:06:41 +00:00
|
|
|
"scripts": {
|
2020-07-22 11:14:35 +00:00
|
|
|
"test-browser": "wtr",
|
|
|
|
|
"test-browser-watch": "wtr --watch",
|
2020-07-13 09:22:26 +00:00
|
|
|
"unit": "npm run tsc-cjs && mocha --config mocha-config/puppeteer-unit-tests.js",
|
2020-09-11 08:10:25 +00:00
|
|
|
"unit-debug": "npm run tsc-cjs && mocha --inspect-brk --config mocha-config/puppeteer-unit-tests.js",
|
2020-04-30 12:00:41 +00:00
|
|
|
"unit-with-coverage": "cross-env COVERAGE=1 npm run unit",
|
|
|
|
|
"assert-unit-coverage": "cross-env COVERAGE=1 mocha --config mocha-config/coverage-tests.js",
|
2021-03-05 09:00:56 +00:00
|
|
|
"funit": "cross-env PUPPETEER_PRODUCT=firefox npm run unit",
|
2020-09-25 10:44:34 +00:00
|
|
|
"test": "npm run tsc && npm run lint --silent && npm run unit-with-coverage && npm run test-browser",
|
2021-10-27 21:12:10 +00:00
|
|
|
"prepare": "node typescript-if-required.js && husky install",
|
2021-02-09 11:34:21 +00:00
|
|
|
"prepublishOnly": "npm run build",
|
2020-04-02 14:25:19 +00:00
|
|
|
"dev-install": "npm run tsc && node install.js",
|
2017-06-19 21:43:05 +00:00
|
|
|
"install": "node install.js",
|
2020-04-21 09:40:04 +00:00
|
|
|
"eslint": "([ \"$CI\" = true ] && eslint --ext js --ext ts --quiet -f codeframe . || eslint --ext js --ext ts .)",
|
2020-05-07 13:54:33 +00:00
|
|
|
"eslint-fix": "eslint --ext js --ext ts --fix .",
|
2020-10-08 10:04:15 +00:00
|
|
|
"commitlint": "commitlint --from=HEAD~1",
|
2021-05-12 12:47:27 +00:00
|
|
|
"markdownlint": "prettier --check **/README.md docs/troubleshooting.md",
|
|
|
|
|
"markdownlint-fix": "prettier --write **/README.md docs/troubleshooting.md",
|
2022-02-04 19:42:15 +00:00
|
|
|
"lint": "npm run eslint && npm run build && npm run doc && npm run markdownlint",
|
2017-07-27 23:16:37 +00:00
|
|
|
"doc": "node utils/doclint/cli.js",
|
2021-04-27 08:32:15 +00:00
|
|
|
"clean-lib": "rimraf lib",
|
2022-02-10 13:34:36 +00:00
|
|
|
"build": "npm run tsc && npm run generate-d-ts",
|
|
|
|
|
"tsc": "npm run clean-lib && tsc --version && npm run tsc-cjs && npm run tsc-esm",
|
2020-07-14 15:57:29 +00:00
|
|
|
"tsc-cjs": "tsc -b src/tsconfig.cjs.json",
|
|
|
|
|
"tsc-esm": "tsc -b src/tsconfig.esm.json",
|
2018-09-13 19:08:51 +00:00
|
|
|
"apply-next-version": "node utils/apply_next_version.js",
|
2020-06-04 10:47:13 +00:00
|
|
|
"test-install": "scripts/test-install.sh",
|
2021-08-05 10:01:25 +00:00
|
|
|
"clean-docs": "rimraf website/docs && rimraf docs-api-json",
|
2021-12-10 08:02:28 +00:00
|
|
|
"generate-d-ts": "npm run clean-docs && api-extractor run --local --verbose",
|
2021-08-04 09:00:48 +00:00
|
|
|
"generate-docs": "npm run generate-d-ts && api-documenter markdown -i docs-api-json -o website/docs && node utils/remove-tag.js",
|
2020-10-29 09:53:51 +00:00
|
|
|
"ensure-correct-devtools-protocol-revision": "ts-node -s scripts/ensure-correct-devtools-protocol-package",
|
2021-05-14 11:02:36 +00:00
|
|
|
"ensure-pinned-deps": "ts-node -s scripts/ensure-pinned-deps",
|
fix: wider compat TS types and CI checks to ensure correct type defs (#6855)
* fix: wider compat TS types and CI checks to ensure correct type defs
This PR improves our TS types further to make sure they are usable in a
TS environment where ES Modules are the target output. Our use of
`export =` is problematic this environment as TypeScript does not allow
`export =` to be used and it errors.
The fix for the type issues to avoid `export =` is to instead define the
functions that you gain access to when you import Puppeteer as top level
functions in our `types.d.ts` file. We can do this by declaring them
explicitly in `src/node.ts`. These are then rolled into `lib/types.d.ts`
at build time. The downside to this is that we have to keep those
declarations in sync with the Puppeteer API; should we add a new method
to the `Puppeteer` class, we must add it to the `nodes.ts` declarations.
However, this could easily be automated by a small script that walks the
AST and generates these. I will do that in a follow-up PR, but I
consider this low risk given how rarely the very top level API of
Puppeteer changes. The nice thing about this approach is we no longer
need our script that hacks on changes to `lib/types.d.ts`.
To avoid yet more releases to fix issues in one particular TS
environment, this PR also includes a suite of example setups that we
test on each CI run. Each sample folder contains `good.ts`, which should
have no TS errors, and `bad.ts`, which should have some errors. The test
first packs Puppeteer into a tar, and then installs it from that tar
into each project. This should replicate how the published package
behaves when it is installed. We then check that we get no errors on
`good.ts`, and the expected errors on `bad.ts`.
We have a variety of test projects that cover both TS and JS source
code, and CJS and ESM imports and outputs.
2021-02-10 12:04:36 +00:00
|
|
|
"test-types-file": "ts-node -s scripts/test-ts-definition-files.ts",
|
2021-07-26 11:52:25 +00:00
|
|
|
"release": "node utils/remove_version_suffix.js && standard-version --commit-all",
|
|
|
|
|
"build-docs-production": "cd website && npm install && npm run build"
|
2017-05-11 07:06:41 +00:00
|
|
|
},
|
2020-04-17 09:32:25 +00:00
|
|
|
"files": [
|
2021-02-09 08:44:23 +00:00
|
|
|
"lib/types.d.ts",
|
2021-02-08 16:21:41 +00:00
|
|
|
"lib/**/*.d.ts",
|
|
|
|
|
"lib/**/*.d.ts.map",
|
|
|
|
|
"lib/**/*.js",
|
|
|
|
|
"lib/**/*.js.map",
|
2020-04-22 14:33:36 +00:00
|
|
|
"install.js",
|
2020-06-25 13:24:46 +00:00
|
|
|
"typescript-if-required.js",
|
2020-06-29 15:13:24 +00:00
|
|
|
"cjs-entry.js",
|
fix: much better TypeScript definitions (#6837)
This PR aims to vastly improve our TS types and how we ship them.
Our previous attempt at shipping TypeScript was unfortunately flawed for
many reasons when compared to the @types/puppeteer package:
* It only worked if you needed the default export. If you wanted to
import a type that Puppeteer uses, you'd have to do `import type X
from 'puppeteer/lib/...'`. This is not something we want to encourage
because that means our internal file structure becomes almost public
API.
* It gave absolutely no help to CommonJS users in JS files because it
would warn people they needed to do `const pptr =
require('puppeteer').default, which is not correct.
* I found a bug in the `evaluate` types which mean't you couldn't
override the types to provide more info, and TS would insist the types
were all `unknown`.
The goal of this PR is to support:
1. In a `ts` file, `import puppeteer from 'puppeteer'`
1. In a `ts` file, `import type {ElementHandle} from 'puppeteer'`
1. In a `ts` file, referencing a type as `puppeteer.ElementHandle`
1. In a `ts` file, you can get good type inference when running
`foo.evaluate(x => x.clientHeight)`.
1. In a `js` file using CJS, you can do `const puppeteer =
require('puppeteer')` and get good type help from VSCode.
To test this I created a new empty repository with two test files in,
one `.ts` file with this in:
https://gist.github.com/jackfranklin/22ba2f390f97c7312cd70025a2096fc8,
and a `js` file with this in:
https://gist.github.com/jackfranklin/06bed136fdb22419cb7a8a9a4d4ef32f.
These files included enough code to check that the types were behaving
as I expected.
The fix for our types was to make use of API Extractor, which we already
use for our docs, to "rollup" all the disparate type files that TS
generates into one large `types.d.ts` which contains all the various
types that we define, such as:
```ts
export declare class ElementHandle {...}
export type EvaluateFn ...
```
If we then update our `package.json` `types` field to point to that file
in `lib/types.d.ts`, this then allows a developer to write:
```
import type {ElementHandle} from 'puppeteer'
```
And get the correct type definitions. However, what the `types.d.ts`
file doesn't do out of the box is declare the default export, so
importing Puppeteer's default export to call a method such as `launch`
on it will get you an error.
That's where the `script/add-default-export-to-types.ts` comes in. It
appends the following to the auto-generated `types.d.ts` file:
```ts
declare const puppeteer: PuppeteerNode;
export = puppeteer;
```
This tells TypeScript what the default export is, and by using the
`export =` syntax, we make sure TS understands both in a TS ESM
environment and in a JS CJS environment.
Now the `build` step, which is run by GitHub Actions when we release,
will generate the `.d.ts` file and then extend it with the default
export code.
To ensure that I was generating a valid package, I created a new
repository locally with the two code samples linked in Gists above. I
then ran:
```
npm init -y
npm install --save-dev typescript
npx tsc --init
```
Which gives me a base to test from. In Puppeteer, I ran `npm pack`,
which packs the module into a tar that's almost identical to what would
be published, so I can be confident that the .d.ts files in there are
what would be published.
I then installed it:
```
npm install --save-dev ../../puppeteer/puppeteer-7.0.1-post.tgz
```
And then reloaded VSCode in my dummy project. By deliberately making
typos and hovering over the code, I could confirm that all the goals
listed above were met, and this seems like a vast improvement on our
types.
2021-02-09 08:00:42 +00:00
|
|
|
"cjs-entry-core.js"
|
2020-04-17 09:32:25 +00:00
|
|
|
],
|
2017-05-11 07:06:41 +00:00
|
|
|
"author": "The Chromium Authors",
|
2017-08-31 18:16:28 +00:00
|
|
|
"license": "Apache-2.0",
|
2017-05-11 07:06:41 +00:00
|
|
|
"dependencies": {
|
2022-02-09 14:49:25 +00:00
|
|
|
"cross-fetch": "3.1.5",
|
2022-02-01 09:18:38 +00:00
|
|
|
"debug": "4.3.3",
|
2022-02-04 11:18:53 +00:00
|
|
|
"devtools-protocol": "0.0.960912",
|
2021-05-14 11:02:36 +00:00
|
|
|
"extract-zip": "2.0.1",
|
|
|
|
|
"https-proxy-agent": "5.0.0",
|
|
|
|
|
"pkg-dir": "4.2.0",
|
2021-10-07 12:22:33 +00:00
|
|
|
"progress": "2.0.3",
|
2021-05-14 11:02:36 +00:00
|
|
|
"proxy-from-env": "1.1.0",
|
|
|
|
|
"rimraf": "3.0.2",
|
2021-10-14 15:08:03 +00:00
|
|
|
"tar-fs": "2.1.1",
|
2021-10-08 12:20:02 +00:00
|
|
|
"unbzip2-stream": "1.4.3",
|
2022-02-09 14:49:25 +00:00
|
|
|
"ws": "8.5.0"
|
2017-05-11 07:06:41 +00:00
|
|
|
},
|
2017-05-12 23:36:37 +00:00
|
|
|
"devDependencies": {
|
2022-02-09 14:49:25 +00:00
|
|
|
"@commitlint/cli": "16.1.0",
|
2022-01-31 13:52:36 +00:00
|
|
|
"@commitlint/config-conventional": "16.0.0",
|
2022-02-10 08:14:13 +00:00
|
|
|
"@microsoft/api-documenter": "7.15.2",
|
2022-02-09 14:49:25 +00:00
|
|
|
"@microsoft/api-extractor": "7.19.4",
|
2021-10-11 07:50:28 +00:00
|
|
|
"@types/debug": "4.1.7",
|
2021-05-14 11:02:36 +00:00
|
|
|
"@types/mime": "2.0.3",
|
2022-02-09 14:49:25 +00:00
|
|
|
"@types/mocha": "9.1.0",
|
2022-02-10 08:35:12 +00:00
|
|
|
"@types/node": "17.0.17",
|
2022-01-28 09:38:36 +00:00
|
|
|
"@types/progress": "2.0.5",
|
2021-05-14 11:02:36 +00:00
|
|
|
"@types/proxy-from-env": "1.0.1",
|
2021-10-07 14:40:23 +00:00
|
|
|
"@types/rimraf": "3.0.2",
|
2022-02-09 14:49:25 +00:00
|
|
|
"@types/sinon": "10.0.11",
|
2021-10-11 08:48:26 +00:00
|
|
|
"@types/tar-fs": "2.0.1",
|
2022-02-09 14:49:25 +00:00
|
|
|
"@types/ws": "8.2.2",
|
|
|
|
|
"@typescript-eslint/eslint-plugin": "5.11.0",
|
|
|
|
|
"@typescript-eslint/parser": "5.11.0",
|
|
|
|
|
"@web/test-runner": "0.13.27",
|
|
|
|
|
"commonmark": "0.30.0",
|
2021-05-14 11:02:36 +00:00
|
|
|
"cross-env": "7.0.3",
|
2022-02-09 14:49:25 +00:00
|
|
|
"eslint": "8.8.0",
|
2021-05-12 14:48:30 +00:00
|
|
|
"eslint-config-prettier": "8.3.0",
|
2022-02-09 14:49:25 +00:00
|
|
|
"eslint-plugin-import": "2.25.4",
|
|
|
|
|
"eslint-plugin-mocha": "10.0.3",
|
2021-10-08 15:44:22 +00:00
|
|
|
"eslint-plugin-prettier": "4.0.0",
|
2022-02-09 14:49:25 +00:00
|
|
|
"eslint-plugin-unicorn": "40.1.0",
|
2021-10-18 13:22:59 +00:00
|
|
|
"esprima": "4.0.1",
|
2021-05-14 11:02:36 +00:00
|
|
|
"expect": "25.2.7",
|
2022-02-09 14:49:25 +00:00
|
|
|
"husky": "7.0.4",
|
2022-01-28 10:03:36 +00:00
|
|
|
"jpeg-js": "0.4.3",
|
2022-02-09 14:49:25 +00:00
|
|
|
"mime": "3.0.0",
|
2022-01-28 10:23:44 +00:00
|
|
|
"minimist": "1.2.5",
|
2022-02-09 14:49:25 +00:00
|
|
|
"mocha": "9.2.0",
|
2021-05-14 11:02:36 +00:00
|
|
|
"ncp": "2.0.0",
|
2021-10-25 09:56:39 +00:00
|
|
|
"pixelmatch": "5.2.1",
|
2021-10-18 12:45:03 +00:00
|
|
|
"pngjs": "6.0.0",
|
2022-02-09 14:49:25 +00:00
|
|
|
"prettier": "2.5.1",
|
|
|
|
|
"sinon": "13.0.1",
|
|
|
|
|
"source-map-support": "0.5.21",
|
2021-10-27 21:34:56 +00:00
|
|
|
"standard-version": "9.3.2",
|
2021-05-14 11:02:36 +00:00
|
|
|
"text-diff": "1.0.1",
|
2022-02-09 14:49:25 +00:00
|
|
|
"ts-node": "10.5.0",
|
2021-10-14 15:44:45 +00:00
|
|
|
"typescript": "4.4.4"
|
2017-05-11 07:06:41 +00:00
|
|
|
}
|
|
|
|
|
}
|
