DOM Lib Generator infra thread

[orta]

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. Add the ability to upload to @types/x #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. Replaces several DOM methods with weaker typings and closes microsoft/TypeScript#4689 #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 #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.

[saschanaz]

1. I wonder we can use "web" instead of "dom" in the names here. Things like WebXR have Web in their name because they are web APIs, and DOM is just a part of those web APIs: https://dom.spec.whatwg.org/.
   • Not sure what name webxr-specific package would have in this case. @types/web-webxr looks weird, @types/web-xr might make more sense...
2. From feat: add serviceworker and sharedworker libs #997 (comment): I also wonder we can split the current webworker into each worker type. The current one mixes things up and thus potentially confusing. With the upper suggestion, this would result @types/web-dedicatedworker instead of @types/dom-webworker.

[orta]

re: web vs dom - yeah, I think that's probably right- maybe we should call the 'main' export which replaces libdom @types/web-dom which can set the tone then (and perhaps we change this repo name eventually too.) MDN calls them all "Web APIs" which feels pretty accurate to me.

Yeah, #997 was kinda hitting my threshold for things we should be shipping with the TypeScript compiler - it's a natural fit for separate @types/web packages IMO.

[saschanaz]

maybe we should call the 'main' export which replaces libdom @types/web-dom which can set the tone then

web-dom sounds like its an additive package solely for DOM, I'd like to make it just @types/web. But since TS has long been using dom in the lib option, I can also accept web-dom blaming the historical reason.

Edit: Or alternatively it could be web-window matching web-serviceworker, but not sure I like it 😄

[orta]

I was figuring web-dom makes sense if you think as web as the namespace, and dom is as the core focus, but it does contain a lot of web APIs nowadays and I'm open to @types/web as the central name instead. I'm sure more folks think of these APIs as "the web" and not "the DOM".

Luckily all these small names don't have well used npm modules which we're not trampling on either.

[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.

[sandersn]

From our design meeting on Friday, I remember one issue is what DT packages like @types/jsdom, which extend DOM types, can do so that people can use @types/jsdom and @types/web-dom together. The compiler might need to add a special triple-slash comment for DOM replacements to identify themselves.

However, it's probably not a problem that needs to be solved immediately, since jsdom will continue to work with the built-in DOM types.

[saschanaz]

like early-stage proposals or Chrome only APIs which come from WIDLs.

BTW, I'm still not sure TS should promote such early ones in the field. There should at least be some warning that it's not well supported and the API form can still change.

[orta]

I think from our side we'll probably tell people about some of the biggies in the docs (dom/*worker/audiolet?) but change the README here to list all of them with some sort of 'and all these', so we won't be mentioning anything but the critical ones except very close to the source of truth

[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 microsoft/TypeScript#44684