Declaration merging in plain JS with JSDoc

🔍 Search Terms

jsdoc declaration merging

✅ 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

Ability to merge declarations.

📃 Motivating Example

For example, this is a declaration merge in TS:

export const Foo = makeFooClass()
export type Foo = InstanceType<typeof Foo>

In JS we can't do this. I was hoping for something similar to this to achieve the same:

export const Foo = makeFooClass() // returns a class
/** @export {InstanceType<typeof Foo>} Foo */

💻 Use Cases

1. What do you want to use this for? To merge declarations in certain cases.
2. What shortcomings exist with current approaches? There's no way to do it AFAICT
3. What workarounds are you using in the meantime? None

Start with the motivating TypeScript and plain JavaScript examples in the issue, then read the discussion to understand the proposed declaration-merging behavior and existing limitations. Done means agreeing on a viable JSDoc design and implementing declaration merging without changing emitted JavaScript or existing runtime behavior.