DOM Lib Generator infra thread

We would like to stop forcing the DOM dts files from being tied directly to a version of TypeScript, making migrations easier. In addition, we would like to give @saschanaz more control on this repo (they are doing a lot of work, and we should respect that)

With some of these constraints in mind, we think we’ve got a few ideas which work to address these:

1. We treat this repo a bit like a mini-DefinitelyTyped. Giving it automation to ship packages to @types/xyz - specifically, today with the repo in the current state, we should be able to ship: @types/dom, @types/dom-webworker and @types/dom-serviceworker. All of these @types/x can be deployed automatically from master/main. #1025

   Because all the packages can live in the same repo, that makes it possible for us to expand to @types/dom-strict for example which would have some of the changes which were too breaking to apply across the entire ecosystem. e.g. https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/885

   Unsure if it’s something we want to explore, but this does also open up the potential for DOM lib generator to ship types for things which may never pass our heuristics, like early-stage proposals or Chrome only APIs which come from WIDLs. Today we tell people to put those on DT. Some examples might have been @types/dom-web-vr (which never made it to a standard) or @types/dom-web-xr (which is still just chrome.)

2. We add OSS-Docs-Tools/code-owner-self-merge to the repo for @saschanaz - covering src, baselines, input files & README.md (that seems to cover most PRs) - I’m also open to exploring something similar for issues. For repo security, we can keep the deployment infra in a separate folder and the code being shipped by default in TypeScript still need a manual PR to the TypeScript repo, where it can get audited for larger ecosystem impact there.

What this means for users

With these changes you:

• Switch to a locked version of the DOM APIs
• Get nightly builds as your PRs are merged
• Potentially have a stricter version of the DOM apis
• Potentially have a version of the DOM API with more fancy generics/template literals etc

Because we ship the dom APIs as a default in TypeScript, you would need to set your lib to be something like "lib": ["es2019"] (with es2019 being your target) instead of having lib missing (meaning dom won’t be added by default) and then yarn add @types/dom.

How does this affect breaking changes?

The main dependency libdom.d.ts and @types/web have the same goals of backwards compatibility as prior to this work. We don’t want to use @types/web as a way to ignore breaking changes. We already have tests that run the full TypeScript compiler test suite on every PR, and WIP for running DefinitelyTyped tests https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1039 and an idea how to test against the Deno stdlib in #1027.

There is sufficiently good reason to ship larger breaking changes (for example using the template literal syntax in the DOM query APIs like #885 ) and these could live inside a 2nd DOM deploy.

How does this affect the security of @types?

Deploys are npm packages which are auto-generated from .d.tsfiles, which this repo creates. Any changes to the build and deploy infra require a TypeScript admin to accept the PRs.

What is a release?

As @types/web is released on every commit, eventually a specific version of the d.ts files in @types/web make their way into TypeScript. We can note the version of @types/web which corresponds to a specific release in TypeScript in the release notes, and in a table in the repo README here.

Backwards compatability

So far, I’ve stated that 4.4 is the minimum version of TypeScript which supports @types/web in part because I’m hoping to get the support for switching dom with @types/web in natively then. We can start a similar 2 year window to DT if we want, using downlevel-dts to support older syntax if needed.

[orta]

So far, we have:

• A PR to TypeScript adding types_web as the default dom.d.ts
• Shipped @types/web 0.0.1 which represents TypeScript-DOM-lib-generator master (which is basically 4.3 libdom with a few additions)
• Sent a bunch of PRs to types_web adding backwards compat types for changes which affect some of the biggest players I the ecosystem (react/angular/et al)
• Sent a bunch of DT PRs which fix individual DT modules which had removed properties or types

All linked to https://github.com/microsoft/TypeScript/pull/44684

[sandersn]

It’s worth pointing out that this will be opt-in – the DOM types will still ship with Typescript and using @types/web-dom will require an explicit lib entry to exclude the built-in ones.