Consider allowing packages to define multiple canonical names for their modules

Suggestion

This is based on a change in the NodeJS definitions: https://github.com/DefinitelyTyped/DefinitelyTyped/pull/51107. For Node's ESM support, you can import NodeJS core packages (i.e., fs, path, etc.) using a fully-qualified URN with the node: prefix. The approach taken in https://github.com/DefinitelyTyped/DefinitelyTyped/pull/51107 is to re-export a module like fs using another ambient module:

declare module "node:fs" {
  export * from "fs";
}
declare module "fs" {
 ...
}

However, this belies the actual behavior of the import. "node:fs" is not a different module that happens to re-export "fs", it is actually the same module, and ideally would be handled in a way similar to how we currently handle symbolic links. With the above definitions, any module augmentations must always be made against the non-prefixed form of the module. Augmentations of the prefixed-form would be missing when importing the non-prefixed form.

We already have some mechanisms for handling this in your own project (i.e., via "paths", etc.), but not when importing from an external package (such as is the case with "fs", "path", etc.).

Should we consider adding a mechanism, be it either via syntax or via configuration (stored in package.json)?

Syntax

We can bikeshed on syntax, but I've presented a few options below:

// 1) variation of `export as namespace ...`
declare module "fs" {
  export as module "node:fs"; // essentially a symbolic link from `"node:fs"` to `"fs"`
}

// 2) declare a module with multiple names
declare module "fs", "node:fs" {
}

Configuration

If we consider approaching this problem from a configuration standpoint there are a number of directions we could take. I can update this section as we discuss this issue.

🔍 Search Terms

NodeJS, ESM, prefix, symlink

No files, tests, or entry points are named. Start by tracing TypeScript's module-resolution and ambient-module handling, then compare the existing paths and symbolic-link behavior with the fs and node:fs examples. Done means a defined mechanism lets external packages assign multiple canonical names to one module while preserving augmentations across those names.