TypeScript type resolution without probing

Supporting expressing resolution entirely in code

Problem

TypeScript’s module resolution for type definitions currently heavily relies on probing. Some examples of this are how node_modules/ folders are probed for @types/ packages when a bare specifier is imported that does not provide it’s own types, or how importing a file with a .js extension will resolve types to a sibling file with a .d.ts extension instead.

Probing is problematic for us at Deno, because we are unable to perform any kind of probing when importing files using https:// specifiers. This is because it is neither side-effect free to perform probing on https:// (ie it is observable), and it is incredibly slow because of network round trip times. Non Deno TypeScript users have also reported similar issues with probing due to reliance on network file systems (microsoft/TypeScript#11979). Additionally, probing has a performance impact for all users regardless of disk speed, because work needs to be performed that would not have to be if explicit resolution was used instead of probing.

While existing Node resolvers rely heavily on probing, Deno’s resolution behaviour, like browsers, does not rely on probing. Our TypeScript behaviour reflects this in multiple ways:

• Deno does not probe for sibling .d.ts files
• Deno does not auto-discover @types/ for packages imported with npm: specifiers
• Deno does not allow importing .ts files using .js extensions

This is a problem for Deno, because TypeScript does not currently provide any alternatives to probing for multiple of the behaviours outlined.

To work around this in Deno, we have two custom extensions to TypeScript in Deno that enable type resolution without probing:

• // @deno-types="...." to override the types of an import, at an import site
  • This is useful to specify the explicit @types/ package for a given runtime import without having to probe
• An overloaded /// <reference types="./foo.d.ts" /> that enables specifying the type declarations to use for a module, at that modules’ source declaration site.
  • If we could do this again, we would not have overloaded TypeScript semantics.
  • This is useful for specifying the .d.ts file to use for a .js source, especially when you have manually written a .js + .d.ts pair

We opened an issue about this many years ago, but we have not had traction on this so far: microsoft/TypeScript#33437.

Finally, with the new JSR project, we’d like to be able to generate .js and .d.ts pairs that will resolve consistently, regardless of the current position of these files (in node_modules/ or not), regardless of the moduleResolution used, and regardless of any external factors.

Proposed solution to override probing

We are proposing to upstream three separate new features into TypeScript that would eliminate the requirement on probing that TypeScript currently has. Additionally it would allow us to deprecate the existing Deno specific override comments proposed above.

We propose that these features are enabled in all moduleResolution modes, particularly so that they can be used in modules published and consumed via node_modules/ folders where the code author does not control the consumers moduleResolution mode.

We are very happy to put in the work to implement and write tests for this within TypeScript.

Add a // @ts-types="<specifier>" comment, enabling users to explicitly choose the type definition used for an import

This comment can be placed immediately above any import / export statement, or dynamic import() expression, following similar semantics to // @ts-ignore. Exact details about how dynamic imports are targeted and where a comment is valid are still TBD.

When specified above a import statement or dynamic import, TypeScript will use the specifier in this comment instead of the specifier in the import statement or dynamic import during type checking. During emit of JavaScript code this comment is ignored. The specifier in the import statement or dynamic import is not rewritten on emit - it is emitted as is.

During declaration emit, imports / exports annotated with this comment will be rewritten to use the specifier in the comment. Dynamic imports are never emitted into .d.ts file, so there is no risk of having to rewrite a dynamic specifier. If a dynamic import needs to turn into a type import expression, this expression will use the specifier from the // @ts-types comment.

The comment is not valid on import type or export type statements.

If no comment is specified, the current behaviour is preserved.

Example TS input:

// @ts-types="./index.d.ts"
export * from "./dist/index.js";

// @ts-types="./foo.d.ts"
const foo = await import("./dist/foo.js");

// @ts-types="./bar.d.ts"
import { Bar, bar } from "./dist/bar.js";
export const barred: Bar = bar();

JavaScript emit:

export * from "./dist/index.js";

export const foo = await import("./dist/foo.js");

import { bar } from "./dist/bar.js";
export const barred = bar();

TypeScript declaration emit:

export * from "./index.d.ts";

export declare const foo: import("./foo.d.ts");

import { Bar } from "./dist/bar.js";
export declare const barred: Bar;

Add a // @ts-placeholder-replace-file-types="<specifier>" comment, which can be placed at the top of the file

Name very much open to bikeshedding.

This comment can be placed at the top of a file, and is valid in the same positions as @jsx pragma comments. Only one comment per file is allowed.

When specified at the top of a .js file, TypeScript will use the specifier in this comment as the type definitions for this file, instead of the inferred type definitions that are based on the file’s source code.

Example JS input:

// @ts-placeholder-replace-file-types="./index.d.ts"

export function bar() {
	console.log("bar");
}

JavaScript emit:

// @ts-placeholder-replace-file-types="./index.d.ts"

export function bar() {
	console.log("bar");
}

No TypeScript declaration emit, because input is JS.

In order to maintain backwards compatibility, and not regress performance for probing resolvers, the comment is only respected if the (probing) resolver found the .js and would attempt to generate type declarations from the JS code using inference. Specifically this means that probing resolvers will prefer type declarations found through probing. For example if a index.js file has a // @ts-placeholder-replace-file-types="./other-index.d.ts", but a index.d.ts file also exists as a sibling of this file, and a third file foo.ts contains import import "./index.js", and a probing resolver such as moduleResolution: nodenext or moduleResolution: bundler is used, the types imported from foo.ts will still be ./index.d.ts, because the probing behaviour found this file before finding the JS source code.

Add a jsxImportSourceTypes option to compilerOptions, and a // @jsxImportSourceTypes ... pragma

This option is required because otherwise without @types/ probing, you can not easially specify types for react.

When specified, TypeScript will not use at the jsxImportSource compiler option or pragma during type checking. During emit of JavaScript code, TypeScript will still emit the specifier in jsxImportSource to import the JSX factory. During emit of declaration files, TypeScript will emit the specifier in the jsxImportSourceTypes if it needs to reference JSX related types. If no jsxImportSourceTypes option / pragma is specified, the current behaviour is preserved (jsxImportSource used for both runtime and type emit / type checking).

Example input:

/* @jsxRuntime automatic */
/* @jsxImportSource react */
/* @jsxImportSourceTypes @types/react */
export default <div>Hello World!</div>

During type checking, JSX types are loaded from @types/react

JavaScript emit:

import { jsx as _jsx } from "react/jsx-runtime";
/* @jsxRuntime automatic */
/* @jsxImportSource react */
/* @jsxImportSourceTypes @types/react */
export default _jsx("div", { children: "Hello World!" });

TypeScript declaration emit:

declare const _default: import("@types/react/jsx-runtime").JSX.Element;
export default _default;

FAQ

Is this “explicit module resolution”?

This does not propose adding a moduleResolution: "explicit" or moduleResolution: "minimal" from microsoft/TypeScript#50152 yet. This adds all the features that are required to make this useful in the future.

We think that moduleResolution: "bundler" + a linter can handle many of the same cases as an explicit module resolution mode.

We are not opposed to an explicit module resolution mode, but do not think this anywhere near as high of a priority as the features proposed here.

If TypeScript were to add this resolution mode, we think that together with the three features proposed here, one could express any module resolution configuration TypeScript has right now using the minimal resolution mode + explicit resolution comments. This would make an ideal compile target, and we’d ensure that code emitted by JSR would work in this configuration.