Implement a JSDoc @import tag

Background

#22158 tracks referencing types from a given module using JSDoc-style namepaths. Given that the syntax is somewhat unintuitive and predates the concept of ECMAScript modules, we would like to support a more ergonomic form if we feel it would be helpful.

Options

Bikeshedding time. 🚲 🏠

@from @import

/**
 * @from "express"
 * @import { Request, Response as CoolResponse } from
 * @import Default
 * @import * as ns
 */

Pros

• Allowing @from to precede named import clauses would be easier for completions (this is one of our oldest-duped requests #2371)
• Can have multiple import clauses
• Could hypothetically support @from before @import and vice versa.

Cons

• Doesn’t totally look like ESModule syntax which is just extra cognitive overhead.

ECMAScript Import-based

/**
 * @import { x, y as z, default as Default } from "express"
 */

Pros

• Nothing to learn if you already know ECMAScript syntax.

Cons

• Less optimal for completions

Issues with the Above

The options above don’t make it explicit that only types are being imported. We could play around with keyword/tag placement (e.g. @importtype, @import type, etc.)

[nojvek]

Been many months on this now. Is there any progress on this issue? I’d really love to see /** @import { x, y as z, default as Default } from "express" */

We’re adding jsdoc types to half a million line codebase and we feel the pain of the verbose syntax every single day.

Please please please please please make a decision on this. I’d be happy to work on a PR.

[rjgotten]

I like the way we can do it with TypeScript now.

On the contrary; I hate the way you have to do it now.

It’s extremely verbose, which breaks down into an unreadable mess quickly. Like when you have to import a generic type and also have to import its type constraints. E.g.

/**
 * @param {value:import('./other/a').GenericA<import('./other/b').ConstraintB, import('./other/c').ConstraintC>}
 */

To avoid creating that kind of mess, you have to import types up front and create local aliases for them with @typedef instructions. If you need multiple types you cannot bulk import them. You need to do it one by one and alias each one with its own @typedef inflating the JS file with a lot of noise.

You’d think you’d be able to use namespaces, but that’s not supported properly. At the very least it’s buggy. I tried aforementioned typeof approach and it didn’t work for me.

Just being able to put a single comment block at the top of a JS file, before or after the block of ES6 imports, with a conceptual @import JSDoc equivalent to import all needed types in addition to implementations handled by the normal imports seems a major; MAJOR improvement.

It would probably also solve one other big pain point: Currently if you author JS with split .d.ts definition files for typing said JS file itself is not typed with its own .d.ts file. All other files that import the JS apply the .d.ts typings, but not the file itself.

With a proper import styled after ES6 you could do something like:

/** @import * from "." */

And have the JS file’s d.ts declared typings applied to itself that way.