Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: wider compat TS types and CI checks to ensure correct type defs #6855

Merged
merged 14 commits into from Feb 10, 2021

Conversation

jackfranklin
Copy link
Collaborator

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.

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.
.github/workflows/main.yml Show resolved Hide resolved
.github/workflows/publish-on-tag.yml Outdated Show resolved Hide resolved
scripts/test-ts-definition-files.ts Outdated Show resolved Hide resolved
scripts/test-ts-definition-files.ts Outdated Show resolved Hide resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants