Support import types in JSDoc @implements

[spalger]

Suggestion

🔍 Search Terms

@implements jsdoc import export

✅ Viability Checklist

My suggestion meets these guidelines:

• [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [x] This wouldn't change the runtime behavior of existing JavaScript code
• [x] This could be implemented without emitting different JS based on the types of the expressions
• [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• [x] This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

We're using JSDoc comments in a package so that we can avoid a build process but still have type validation. We've found current JSDoc support to be very usable, but there is one specific scenario which isn't ideal. When we want to declare an interface that a class should implement we use @implements but unlike all of the other tags we're using we can't use an import('..').Type node as the implements type. This means we have to use a @typedef before hand, which isn't terrible, but also re-exports the type from this module. For commonly used types this leads to massive pollution of the suggestions you get when VSCode is trying to help you automatically import a type.

Ideally there would be some way to import a type for local use, or the import().Type syntax would be supported by @implements tags.

📃 Motivating Example

SomeLog.ts

export interface SomeLog {
  foo(): void
}

Log.mjs

/** @typedef {import('./SomeLog')} SomeLog */

/**
 * @implements {SomeLog}
 */
export class Log {
  foo() { }
}

With this setup SomeLog is "exported" from both SomeLog.ts and Log.mjs which is undesirable and leads to accidentally importing code from the wrong place.

💻 Use Cases

I think I explained this in my suggestion pretty well.

[RyanCavanaugh]

I don't see any technical hurdles to allowing

 * @implements {import('./SomeLog')}

IIRC the parser in other positions only consumes an Identifier / Dotted Name, but this is mostly due to the grammatical position of implements in a normal class declaration. In a JS Doc tag there's no corresponding problem and we can just parse and evaluate any legal type node

[jaydenseric]

What's excruciating is you can't use in the JSDoc tag @implements things imported via the JSDoc tag @import either:

// @ts-check

/** @import { ESLint } from "eslint" */

// Error…
/** @implements {ESLint.Plugin} */
class EslintPluginA {}

// Error…
/** @implements {ESLint["Plugin"]} */
class EslintPluginB {}

// Workaround TypeScript bugs:
// https://github.com/microsoft/TypeScript/issues/49905
// https://github.com/microsoft/TypeScript/issues/58542
/** @typedef {import("eslint").ESLint.Plugin} ESLintPlugin */

// No error…
/** @implements {ESLintPlugin} */
class EslintPluginC {}