Add JSDoc `@export` tag

[remcohaszing]

🔍 Search Terms

jsdoc @export

✅ 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

TypeScript 5.5 added the @import JSDoc tag which can be used for type-only imports. It would be useful to add an analogous @export tag for type-only exports.

📃 Motivating Example

Let’s say you maintain a library that contains the following file:

// types.js
/**
 * @typedef {string} Username
 */

/**
 * @typedef {number} UserId
 */

Maybe you want to expose these types in the main entry point. You can now do this with the JSDoc @export tag. It works the same as type-only exports in TypeScript files.

// index.js
/**
 * @import { Username } from './types.js'
 */

/**
 * @export { Username }
 * @export { UserId } from './types.js'
 */

💻 Use Cases

This is useful to have full control over exports in a library. Also this is just parity between JSDoc based types and TypeScript files.

I can think of 3 workarounds, all of which are not great.

1. Define a new type in the index file using @typedef

   // index.js
   /**
    * @typedef {import('./types.js').Username} Username
    * @typedef {import('./types.js').UserId} UserId
    */

   Pros:

   • It works

   Cons:

   • It defines a new type
   • Hover/autocompletion information is lost (Resolve documentation for type aliases #55572)
   • Type parameters must be redefined

2. In addition to index.js, create a TypeScript file, e.g. exports.ts. Then in exports.ts write something along the lines of:

   export { someValue, anotherValue } from './index.js'
   export { Username, UserId } from './types.js'

   and in package.json, write something like:

   {
     "types": "./types/exports.d.ts",
     "exports": {
       "types": "./types/exports.d.ts",
       "default": "./lib/index.js",
     }
   }

   Pros:

   • It works
   • No new types are defined, but actual exports
   • Hover information is preserved
   • Type parameters are preserved

   Cons:

   • Exports from index.js need to be synced to exports.ts manually.
   • You’re essentially tricking TypeScript into thinking exports.ts is the main entry, whereas in reality it’s index.js

3. Manually write the declaration file.

   Pros:

   • It works
   • No new types are defined

   Cons:

   • You need to author the declaration files manually.

[MartinJohns]

Duplicate of #22126. Used search terms: export tag in:title

[remcohaszing]

No, it’s not a duplicate. That issue also proposes a JSDoc tag named @export, but behaves different. The two issues conflict even.

Somehow I didn’t find that issue though, so good find.