[FeatureRequest] Document request on `.d.mts` `.d.cts`

[loynoir]

Suggestion

Document on new typescript file pattern .d.mts .d.cts

1. Can .d.mts .d.cts just be treated like .d.ts?
   https://github.com/rollup/plugins/pull/1033/files

2. A spec defining these file extensions

3. ...

🔍 Search Terms

.d.mts .d.cts rollup

✅ Viability 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, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

📃 Motivating Example

1. Can .d.mts .d.cts just be treated as .d.ts?
   Crash on new typescript file pattern .d.mts .d.cts rollup/plugins#1032 (comment)

2. Related rollup PR
   Add .d.mts .d.cts compact rollup/plugins#1033

💻 Use Cases

[fatcerberus]

Is that 100% compact to deal them like previous .d.ts?

What?

[loynoir]

Is that 100% compact to deal them like previous .d.ts?

What?

Maybe I changed to?

Can .d.mts .d.cts just be treated like .d.ts?

[andrewbranch]

Documentation is here https://www.typescriptlang.org/docs/handbook/esm-node.html#new-file-extensions

[Pyrolistical]

This is still extremely confusing.

I was trying to add types to an existing js project and used .d.ts. This allowed me to use jsdocs and fix all the type errors, however typescript complained that vanilla js exports didn't exist, when they clearly did.

What was happening was typescript was only looking at .d.ts for the exported members and ignored the real .js exports.

I fixed this by renaming .d.ts to .d.mts, however, this is extremely confusing!

My project is already using node 16 with "type": "module" in package.json. No where do I ever need to use .mjs. All my files are .js and node knows they are all modules.

Typescript needs to have the same behaviour and not require me to use this special .d.mts extension

[andrewbranch]

TypeScript always ignores JS when there is an identically named .d.ts file beside it. What you did by renaming them to .d.mts is equivalent to deleting them. If you don’t use .mjs files, you shouldn’t use .d.mts files. If you write a .d.ts file for a colocated JS file, it needs to be complete and accurate. TypeScript will never look at a .d.ts file and a .js file together and try to come up with a mashup of the two. It’s one or the other, and when they both exist, the .d.ts wins.

[Pyrolistical]

@andrewbranch thanks for the clarification. this make more sense now. there needs to be a lot more documentation around allowjs + checkjs + jsdoc + .d.mjs + "type": "module"

After I renamed .d.ts to .d.mjs, I also had to fix all the jsdoc imports

// before
@typedef {import('./grammar').NoMatch} NoMatch

// after 
@typedef {import('./grammar.mjs').NoMatch} NoMatch

That is also confusing, as no such file exists! Its typescript magic that picks up grammar.d.mjs

[andrewbranch]

That is also confusing, as no such file exists!

That’s the same thing happening as when TypeScript was picking up the incomplete .d.ts and ignoring your .js. The .d.ts was implying the existence and shape of a .js file by the same name, and so we didn’t even look at the JS. When you renamed the declaration file to .d.mts, it was then implying the existence and shape of a .mjs file by the same name, which is why you were suddenly allowed to import from that (actually non-existent) file.

Some additional notes that might help:

• .mjs and .cjs files do not support extensionless resolution like .js files do (this is not a TS thing, it’s a Node thing)
• "type": "module" has no effect on TS behavior unless you’re running the TS nightly and using "moduleResolution": "nodenext" (see Concerns with TypeScript 4.5's Node 12+ ESM Support #46452)
• Hand-authoring .d.ts files alongside your JS files can be done, and is the right choice for some libraries, but it’s an advanced workflow. As you’re finding out, it requires a bit of knowledge about how the compiler thinks about input and output files, because it violates the default assumption that .js and .d.ts files are the direct outputs of running tsc --declaration on .ts (or .js with JSDoc) files.

[andrewbranch]

(You might be better off autogenerating your declaration files from your JSDoc.)