Suggestion

🔍 Search Terms

@implements jsdoc import export

✅ 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

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.