Support for opting out of jsdoc @typedef exports

[jespertheend]

Suggestion

🔍 Search Terms

jsdoc typedef export #43207 #23692

✅ 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

Currently when using /** @typedef {Number} Num */ the type Num is automatically exported when the comment is in the root scope. I'd like to prevent this from happening.

📃 Motivating Example 💻 Use Cases

My problem:
FileA.js declares /** @typedef {Number} Num */
FileB.js uses this type a bunch of times, so instead of using /** @type {import("./FileA.js").Num} */ everywhere, it declares it once at the top of the file: /** @typedef {import("./FileA.js").Num} Num */ and then uses Num everywhere in the file.

The problem is that doing it this way in all files creates a lot of exports of the same type and it's not always clear which one is the original export. This creates a rather big list with Intellisense:

A woraround is to wrap the type in parentheses, this causes the typedef to be limited to that scope, but this is not always feasible. I.e:

{
 /** @typedef {import("./FileA.js").Num} Num */
 /**
 * @param {Num}
 */
 export default function foo(x) { // <-- error, export needs to be top level
 
 }
}

[andrewbranch]

Agreed this is not ideal. Not sure how best to indicate that it shouldn’t be exported. Maybe another JSDoc tag on the comment:

/**
 * @typedef {import("./FileA.js").Num} Num
 * @local
 */

@local isn’t something listed on https://jsdoc.app. @private or something? We kind of try not to just make up JSDoc things willy nilly, but this feels like a problem we made so the solution will probably have to be made by us too. /cc Nathan Shively-Sanders (@sandersn)?

[jespertheend]

I'm guessing this would no longer be an issue if #22160 is fixed.
That would allow you to import Num without exporting it.

[sandersn]

I think the closest tag is @module.

jsdoc.app and Closure must have the problem to some degree since they have the concept of scope. What do they do? Are @typedef exportable somehow? I'd like to know how those two systems handle it before changing ours.

[jespertheend]

It seems JSDoc.app is having a similar issue jsdoc/jsdoc#1537
I think both JSDoc.app and Closure are both exporting @typedef to file scope just like TypeScript is currently doing.

[brendankenny]

jsdoc.app and Closure must have the problem to some degree since they have the concept of scope. What do they do? Are @typedef exportable somehow? I'd like to know how those two systems handle it before changing ours.

For Closure Compiler, at least, typedefs are attached to a real value-space declaration. For example:

/** @typedef {(string|Element|Text|Array<Element>|Array<Text>)} */
goog.ElementContent;

Types in the Closure Type System - Typedefs

(it's been a few years since I regularly wrote Closure-able code, but I don't believe anything has changed)

As a result, export/import for typedefs is explicit and the same as bringing in any dependency (though from google/closure-compiler#3041 it's clear this can lead to the same issues that lead to import type in TypeScript)

[jespertheend]

I suppose this might be a duplicate of #22160
At least that would solve the same issue.