Suggestion

Ref #49970 and confusion therein.

⭐ Suggestion

Today, TS will only load declaration files for .js, .cjs, and .mjs files (and TS+jsx equivalents). There is no actual mechanism for specifying type definitions for a relative import for files with another extension - nonrelative imports can be defined using an ambient module declaration (see the widely used declare module "*.css";), or via import or export map entry, while relative imports have no mechanism available.

In traditional cjs resolution, this wasn't obviously a problem, since if you wrote require("./style.css"), we would fail to load the .css file (it's not a javascript or typescript extension so we wouldn't even try), and fall back to cjs directory and extension resolution - meaning we'd eventually look for "./style.css.js" and accompanying "./style.css.d.ts", which was close enough for most people's purposes. Now, we have a prominent runtime that does not have extension searching (esm in node/some bundlers/browsers), where there's no mechanism to provide types for the specifier, but in some conditions do support importing non-js extension files.

📃 Motivating Example

import {whatever} from "./stylesheet.css";
import {whatever} from "./mod.wasm";
import {whatever} from "./component.html";
import {whatever} from "./db.json";

💻 Use Cases

Mostly bundlers and potentially browsers for css/html imports, but also node for the potential to type relative imports of .wasm/.json/.node via declaration file, or other extensions as allowed via custom loader.

📃 Proposal

Generally speaking, we want to keep a 1:1 mapping of runtime file extension to declaration file extension, this way we can always do a simple side-by-side lookup for the declarations for a file imported, a relatively simple mapping of output declaration path back to input filepath, and also capture any important format information implied by the original extension in the declaration filename (eg, if .wasm imports end up being importable as uninstantiated modules in the future, and other modules aren't). As such, any mechanism needs to be fairly unambiguous.

Given that, I'd have to propose that a

filename.ext

maps to a

filename.d.ext.ts

which is a declaration file (we'd have to update our definition of declarations to be .d.ts, .d.cts, .d.mts, and .d.*.ts).

This does a few things:

1. It allows any ext to have a unique TS equivalent
2. Unlike a filename.d.ts, it doesn't also ambiguously map to a filename.js or filename.otherext
3. Unlike a filename.ext.d.ts, it doesn't already map to a filename.ext.js
4. Unlike a filename.d.ext, it retains a well-known .ts final extension, for relatively painless tooling and editor support

There are some considerations:

• You could already have a filename.d.ext.ts source file today - it would be a TS source file (that emits a filename.d.ext.js and a filename.d.ext.d.ts) and not a declaration file, making this a technically breaking change. Such a filename is so unwieldy as to be unlikely in my view though, so I don't think this break should be too bad. In some ways, this is an upside, since external tooling will already recognize and parse these files as TS without modification, even if they don't see them as declarations yet.
• Unfortunately, unless we specify otherwise, this does imply you should be able to have a filename.d.js.ts, which behaves identically to a filename.d.ts, and we'd have to prioritize one of the two during lookup. Tentatively, I'd say we should just forbid ts and js extension patterns like this, so .d.js.ts, .d.mjs.ts, .d.cjs.ts, .d.jsx.ts, .d.ts.ts, .d.tsx.ts, .d.mts.ts, and .d.cts.ts shouldn't be looked up - the existing short forms take their place.
• In a multi-module-format situation like in modern node, it's also an open question what format these modules should be interpreted as, which at runtime depends on if the loader used injects the module into the cjs require cache or only synthesizes an esm dynamic module. Because of that distinction (and the inability to import an esm-format-only thing from a cjs format thing), it may be important to encode the expected runtime format into the declaration name as well. For that reason, it would be tempting to reuse the mts and cts extensions; unfortunately this introduces some ambiguity, as all of filename.d.ext.ts, filename.d.ext.mts, and filename.d.ext.cts would map to the same original filename.ext, rather than only one canonical one (and looking up the input filepath from an output declaration file is critical for scenarios like project references, which is why unambiguousness is so helpful here). We could just assume these declaration files are formatless, like ambient modules, and provide the same interface to both cjs and esm callers. That might be good enough to get by. Failing that, the only thing I can think of that preserves filename uniqueness would be some kind of in-declaration-file pragma for asserting the format of the containing file, or a compiler option specifying a global mapping of extension to format (though the later doesn't hold up well with redistributable libraries). But all that may be unnecessary, since, with the exception of potentially .json, these should largely be authored by hand, so protection from format misuse is maybe less important than with JS files writ large.
• These mappings should be enabled and looked up in all resolution modes - classic, node, node16, nodenext. It may, however, be appropriate to add an error on non-js non-declaration imports than is only suppressed with a compiler option (eg, allowNonJsImports, in the same vein as resolveJsonModule).
• Alongside this change, we should also be able to enable our long-supported-but-disabled declaration emit for json documents when resolveJsonModule is set, since it would canonicalize filename.d.json.ts as the declaration path for the json (and thus canonicalize loading such a declaration file at higher priority than the original json document in a wildcard include pattern).

Thoughts?