Extract APIs that are common to Node and the DOM to their own namespace

[matthieubosquet]

Search Terms

Cannot find name 'URL', Cannot find name 'TextEncoder', Cannot find name 'TextDecoder', WHATWG URL API, Node JS URL API, URL type, common APIs, universal APIs, node and browser compatibility, dom lib types node.

Suggestion

Move APIs that are common to node and the browser out of lib.dom.d.ts into their own file and import them from lib.dom.d.ts. For example, in the case of the URL Web API, move it to lib.dom.url.d.ts.

Which would allow in tsconfig to add dom.url to the lib entry of the compilerOptions instead of the whole dom namespace, which is probably a bad idea for projects targeting Node.js:

{
    "extends": "@tsconfig/node12/tsconfig.json",
    "compilerOptions": {
        "declaration": true,
        "outDir": "dist",
        "sourceMap": true,
        "lib": ["DOM.URL", "ES2018"],
        "noUnusedLocals": true,
        "noUnusedParameters": true,
    },
    "include": [
        "src/index.ts"
    ]
}

Note: this wouldn't even affect people requiring the DOM type definitions, only allow more granular control. I would probably like to add two layers: 1. lib.common.d.ts for all APIs that are present in both environment; and 2. lib.dom.url.d.ts, lib.dom.textencoder.d.ts, lib.dom.textdecoder.d.ts... for each relevant feature that may not be present in all Node versions.

Use Cases

There is a growing list of dom APIs which are being implemented in node, it seems necessary to have a proper targeting solution that doesn't lead to misleading autocompletion or weird workarounds (I haven't found anything satisfying in that area).

Examples

Anyone using APIs common to Node.js and the browser wanting to add the APIs present in their node global namespace (but not all of the dom APIs). For example using Node's WHATWG URL API instead of the legacy URL API and avoiding the Cannot find name 'URL' errors.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Linked issues

• Move TextEncoder out of lib.dom.d.ts. #31535
• [node] Missing global URL and URLSearchParams typings DefinitelyTyped/DefinitelyTyped#34960
• Cannot find name 'URL' Azure/azure-sdk-for-js#10498 (comment)
• [got] error TS2304: Cannot find name 'URL' DefinitelyTyped/DefinitelyTyped#19799

[RyanCavanaugh]

There's a growing Venn diagram here with Webworkers; the truth is that we don't even like maintaining the DOM types and sent Node to community management, so our appetite for tackling this is quite low. Maybe someone can automate a process that produces good lib files based on intersection -- if that required a few tweaks on our side to make work right, we'd be interested to help out.

[matthieubosquet]

@RyanCavanaugh I'm sorry, I miss a little bit of context here.

I assume when you say "we sent Node to community management", you mean that Node types are currently contributed/maintained by people that are not members of the TypeScript team at Microsoft. Is it correct?

If yes, can you identify people or groups that are currently taking responsibility for those?

Same question for the DOM, do you know which people or groups might be best suited to take responsibility or that currently do and might want help?

Any pointer to organise an hypothetical effort very welcome!

Also, do you currently have any automated type generation tool for the DOM or Node? Have you ideas about suitable sources of data to base a generator on?

[RyanCavanaugh]

I assume when you say "we sent Node to community management", you mean that Node types are currently contributed/maintained by people that are not members of the TypeScript team at Microsoft. Is it correct?

Correct

If yes, can you identify people or groups that are currently taking responsibility for those?

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/index.d.ts

For the DOM, the project is https://github.com/microsoft/TypeScript-DOM-lib-generator and it's maintained by us.

Node doesn't have a machine-readable spec AFAIK so there's nothing to generate from.

[pauldraper]

IMO (and these aren't necessarily dependent on each other)

1. W3C/WHATWG types ought to be separated as well, like Node.js types. I think some already are like W3C Browser Extension (?)
2. Node.js types should selectively reference whatever W3C types it implements.

However it's not clear the best way to do that.

[matthieusieben]

I would like to second this with another use case as example. When you want to write an isomorphic library that runs both in the browser and in node, there is not a single lib/types files that you can use to make your code actually type safe.

Let' say you want your lib to use URL, fetch, etc. you either need to use lib: ["dom"] or types: ["node"], which means that you might end-up depending on variables that will not be available at runtime. The only actually safe way to write this kind of library is to use lib: ["dom"] and make sure you have 100% test coverage on a NodeJS test runner. Or use noLib and write your own...

It would be very helpful if, as a TS user, I could easily target environments using lib: ["es2022", "whatwg.url", "whatwg.fetch"].

• Since the Whatwg standard is what dictates the spec, Typescript's implementation of these lib does not need to worry about compatibility with Node's implementation.
• The entire community would benefit from the superior quality of Typescript's lib over @types/node for overlapping types (e.g. new URL(u as URL) results in an error with @types/node, although it should be allowed)

There should be little added work in the TS repo ("just" a file split) but a huge benefit for the community ❤️

[matthieusieben]

See microsoft/TypeScript-DOM-lib-generator#1685