Limit JSDoc typedefs to file, opt-in to exporting them

[sdegutis]

Suggestion

🔍 Search Terms

jsdoc typedef 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

Keep @typedef and @type local to file (or scope?) unless exported (at top-level of file).

📃 Motivating Example

I've come to find JSDoc + VS Code the best way to use TypeScript:

• There's no compile-phase
  • Code is always valid as-is
  • Forgetting to build isn't fatal
  • Often vastly simplifies tool chain
• You just use it within VS Code
  • Let it show in-IDE errors
  • Let it install/run TypeScript for you
  • Still provides autocompletion and everything
• Encourages avoiding insanely complex types
  • You can still make complex types via index.d.ts if really necessary
• You usually already want to document function parameters anyway, might as well use JSDoc
• Function declaration lines don't end up being 500 characters, since you can put each parameter on each line

It's overall a pretty good alternative to TypeScript in small/medium projects.

But it has this one big caveat: All types/typedefs in any files are visible in all files.

• This means you can't cleanly have helper types encapsulated to a file.
• And you can't mark types as being exportable, which means you can't have multiple types with the same name.

Fixing this would make JSDoc an extremely useful way to use TypeScript with the "almost zero config" VS Code approach.

(There's also #42949 which is unrelated to this except that it's one small but fixable thing making JSDoc support not as useful as TypeScript syntax.)

💻 Use Cases

^

[sdegutis]

Never mind, looks like this is already how it behaves. Not sure why I thought otherwise.

[kungfooman]

Never mind, looks like this is already how it behaves. Not sure why I thought otherwise.

They will definitely be exported as you can see from this error: #46011 (comment)

Anyone happens to know which PR changed this behaviour then? That would be a starting point to fix the behaviour, personally I would like a possible @private field on @typedef's.

[ljharb]

I'm running into this now; I have a CJS file with JSDoc comments that's generating types, and the resulting types have export = (as they should) for the CJS value, and also export type for the typedef, despite not explicitly exporting it.

This should be reopened.