Use and import as types.d.ts

[saschanaz]

I don't understand the reason behind https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/2108#discussion_r2257439305, this works perfectly?

[github-actions[bot]]

Thanks for the PR!

This section of the codebase is owned by @saschanaz - if they write a comment saying "LGTM" then it will be merged.

[HolgerJeromin]

Reducing to a type import is nice.

From @jakebailey

Note that the PR moved the file to .ts; you can't import a .d.ts file straight up like that without also enabling flags that allow importing TS files.

Has this flag been set?

But changing to an .d.ts import feels fishy because TS compiler will search for a corresponding .d.ts file when importing stuff (types or not) from a .js file (with or without the extension).

[saschanaz]

We are not adding a TypeScript file import in runtime (which would require node.js experimental flag), or I'm still confused what he tried to say...

[HolgerJeromin]

We are not adding a TypeScript file import in runtime (which would require node.js experimental flag), or I'm still confused what he tried to say...

Jake's comment:

Note that the PR moved the file to .ts; you can't import a .d.ts file straight up like that without also enabling flags that allow importing TS files.

I think he meant the TS flag/config allowImportingTsExtensions which allows importing .ts files. Which is otherwise not valid even for type-only imports.

[jakebailey]

This is pretty atypical. Auto imports will never suggest these paths, and for more real published packages, you'd want to avoid this because you'd end up with files that are unimportable because there's no JS file left to do it. I don't even remember if these d.ts input files are even written back out to the output...

We are not adding a TypeScript file import in runtime (which would require node.js experimental flag), or I'm still confused what he tried to say...

FWIW running TS directly is no longer experimental in 22/24, so I would honestly consider just using a higher minimum in the repo and just use that feature (with requisite tsconfig options). It works well.

[saschanaz]

This is pretty atypical.

I find it also atypical to have a type-only library but not use d.ts.

Auto imports will never suggest these paths

Sounds like a bug.

and for more real published packages, you'd want to avoid this because you'd end up with files that are unimportable because there's no JS file left to do it.

Real published packages would have a separate compiled d.ts library.

I don't even remember if these d.ts input files are even written back out to the output... FWIW running TS directly is no longer experimental in 22/24, so I would honestly consider just using a higher minimum in the repo and just use that feature (with requisite tsconfig options). It works well.

And if we want to target Node.js native typescript syntax support, then such type-only import should be removed/ignored by Node.js or it would be a bug.

[jakebailey]

Maybe it's more clear to say ".d.ts files describe actual importable modules on disk". It is not advised by the TS team to write .d.ts files for any other purpose. Irritatingly I can't find the doc that says "don't put helper types in declaration files".

Auto import suggests the paths because it thinks that the declaration files accurately describe that the import will work. The type import "working" is really just a technicality.

[saschanaz]

Maybe it's more clear to say ".d.ts files describe actual importable modules on disk". It is not advised by the TS team to write .d.ts files for any other purpose. Irritatingly I can't find the doc that says "don't put helper types in declaration files".

Auto import suggests the paths because it thinks that the declaration files accurately describe that the import will work. The type import "working" is really just a technicality.

Maybe the work item is to have a documented guideline with reasons? It's fine if the official stance is that it's not a supported feature (and it can break anytime), but it should really be documented in that case.

[saschanaz]

I still don't understand this, import declarations are silently removed from the emitted JS regardless of being import type or not, so I don't see why using d.ts is wrong.

[jakebailey]

The existence of ./types.d.ts file implies you are allowed to write import "./types.js" (or the CJS equivalent), that is, a runtime import. This is guaranteed to crash if there is no actual JS file backing it.