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

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

• https://github.com/microsoft/TypeScript/issues/31535
• https://github.com/DefinitelyTyped/DefinitelyTyped/issues/34960
• https://github.com/Azure/azure-sdk-for-js/issues/10498#issuecomment-678236271
• https://github.com/DefinitelyTyped/DefinitelyTyped/issues/19799

Start by examining lib.dom.d.ts and the existing lib configuration conventions. Determine how shared APIs such as URL, TextEncoder, and TextDecoder could be separated without changing the full DOM definitions, then verify that granular library selection works for Node-oriented projects while existing DOM users remain unaffected.