Support `@import` JSDoc tag for auto-imports

[tobloef]

🔍 Search Terms

"jsdoc @import", "@import auto-import", "jsdoc auto-import"

✅ Viability Checklist

• 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Since #57207 it is possible to use the JSDoc @import tag.

/** @import { Foo } from 'foo.js'; */

/** @type {Foo} */
const foo = ...;

However, auto-imports still only use the old inline syntax:

/** @type {import('foo.js').Foo} */
const foo = ...;

It would be nice to also have the option to chose the new @import syntax for the auto-imports, either by configuring an option somewhere or simply by adding another action that can be exposed in IDEs.

📃 Motivating Example

I believe this falls in line with the ergonomics goals outlined by the original issue about having a nicer syntax for JSDoc imports #22160.

I will not repeat the arguments made therein, but suffice to say that it produces more readable code.

💻 Use Cases

Having the auto-import work with this syntax would:

• Save time, not having to write import statements by hand.
• Avoid mistakes due to typos, etc.
• Help people adopt the existing feature.

---

(I have opened the issue here instead of over in vscode. Based on my understanding, this behavior is exposed by the TypeScript Language Server and not by the individual IDEs. Please correct me if I'm wrong.)

[rossrobino]

This would be really nice!

[alexharri]

+1 from me. The inline import style (import("...").SomeType) is very verbose, even for relatively short module paths:

/**
 * @param {import("common/model/reference.ts").RangeReference} range
 */
function* iterValues(range) {
  // ...
}

And when there are multiple imported types things quickly get noisy:

/**
 * @template {T}
 * @param {import("common/model/reference.ts").RangeReference} range
 * @returns {IterableIterator<
 *    import("common/model/reference.ts").ValueReference<T>
 *    | import("common/model/value.ts").BoxedValue<T>
 *    | T
 *  >}
 */
function* iterValues(range) {
  // ...
}

The @import syntax makes things much cleaner (and reduces duplication by combining imports):

/** @import { RangeReference, ValueReference } from "common/model/reference.ts" */
/** @import { BoxedValue } from "common/model/value.ts" */

/**
 * @template {T}
 * @param {RangeReference} range
 * @returns {IterableIterator<ValueReference<T> | BoxedValue<T> | T>}
 */
function* iterValues(range) {
  // ...
}

I'd always refactor the former to the latter. The auto-import feature using @import by default would save me the chore, which would be awesome