Explicit module resolution

Search Terms

explicit module resolution

Semi-Related: #11979

Suggestion

Have the ability to specify a pragma/directive that provides a definitive resolution to a module to use at compiler time in place of one that is specified at runtime. During transpilation, the directive could be elided, leaving the module specifier it was overriding untouched.

Use Cases

Specifically in Deno, we don't use any form of "magic" resolution (like Node.js resolution logic), and we include a fully qualified module specifier. This information would change the resolved module for the purposes of the compiler, but not change the runtime module specifier. The logic applied to the module specifier in the pragma/directive could be applied "as normal", it simply would indicate there is a compile time only substitution to be made.

Examples

Currently in Deno we utilise a special directive to accomplish this: @deno-types="...". We parse a source file as the module is being resolved by the TypeScript compiler, parse out any instances of the directive and apply that substitution to any import/export between that point and the next directive or the end of the file.

So to load prettier, we would do something like this:

// @deno-types="./prettier/standalone.d.ts"
import "./prettier/standalone.js";

Or if we load lo-dash:

// @deno-types="https://unpkg.com/@types/lodash@^4.0.0/index.d.ts"
import * as _ from 'https://cdn.pika.dev/lodash-es/v4';

So while we have something that works for us, we think that if solving this problem was done in the TypeScript compiler, it would be something that could benefit a wider community as we go more to situations people might not rely upon Node.js module resolution to resolve the compile time and runtime paths and expect the compiler to magically know what their intent is, but also it would be part of the parse of a source file and therefore TypeScript's understanding of the file, instead of having to "trick" the compiler.

There maybe other ways to solve this than some sort of positional directive, so thoughts, feedback are more than welcome. The intent is "the module specifier says X, which is important at runtime, but TypeScript needs to be told to resolve to Y instead".

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.

Start by reviewing TypeScript's module-resolution and source-parsing paths, then compare them with the existing @deno-types directive behavior described in the issue. Define how a compile-time-only substitution would interact with import and export specifiers, and establish tests covering the directive's scope and unchanged runtime module specifier.