JSDoc export type support

[xiaoxiangmoe]

Suggestion

🔍 Search Terms

JSDoc

✅ Viability Checklist

My suggestion meets these guidelines:

• [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [x] This wouldn't change the runtime behavior of existing JavaScript code
• [x] This could be implemented without emitting different JS based on the types of the expressions
• [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• [x] This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

📃 Motivating Example

/**
 * @typedef { { loading: boolean, data: any } } AjaxStatus  
 */

Can we export AjaxStatus to other files?

such as

/**
 * @export type { AjaxStatus, AjaxStatus as AjaxStatus2 , AjaxStatus as default }
 */

💻 Use Cases

Used for JavaScript development using the TypeScript language service.

[hildjj]

Use case:

class Foo {
  /**
   * @typedef {object} FooOptions
   * @prop {boolean} [verbose]
   */
  /**
   * @param {FooOptions} opts
   */
  constructor(opts = {}) {
    /** @type {Required<FooOptions>} */
    this.opts = {
      verbose: false,
      ...opts,
    };
  }
}

In the project containing Foo, typedoc complains that FooOptions isn't exported, and can't generate any documentation other than the type name.

Next, I'd like to subclass Foo in another project. I'd like to pass a FooOptions into that subclass. I can get there with ConstructorParameters<typeof Foo>[0], but that's pretty difficult to document. I suppose I could also copy in the definition of FooOptions, but then I'm just back to the first problem.

[hildjj]

A suggestion for an approach that might work, different from the one suggested in the original issue might be:

• A JSDoc tag @export
• Does not conflict with the JSDoc @exports tag, which is mostly useless currently
• Matches the Typescript and JS keyword export
• Cannot do export default (I don't feel strongly about this, but it's not worth adding more syntax, in my opinion)
• Only applies to types, not things that you can export using JS syntax
• As such, applies only to @typedef, @callback, and perhaps some @template blocks
• Causes export type to be generated into the .d.ts file
• Uses the type alias in the generated .d.ts file, instead of expanding the type before generation.
• @export is not required if the type is otherwise exposed. For example, if it is used as a parameter to an exported function or method.

For the example above, instead of generating this:

export class Foo {
    constructor(opts?: {
        verbose?: boolean | undefined;
    });
    opts: Required<{
        verbose?: boolean | undefined;
    }>;
}

You would get this:

export interface FooOptions {
  verbose?: boolean | undefined;
}
export class Foo {
    constructor(opts?: FooOptions);
    opts: Required<FooOptions>;
}

[nmss]

Now that typescript 5.5 have brought the @import syntax, it would be nice to have the @export syntax

also it does not seem possible to use @typedef to re-export a type imported with @import

use case exemple

/** @import {MyType} from 'my-module' */
/** @export MyType */

example corresponding typescript syntax

import type {MyType} from 'my-module'
export type {MyType}