Feature request: allow using JSDoc types inside .ts files

[trusktr]

Search Terms

typescript jsdoc inside ts files

Suggestion

It would be great if JSDoc comments in .ts files worked the same as in .js files.

I believe this change is fairly simple to make (because TypeScript already has the implementation to understand JSDoc types).

Use Cases

This brings consistency: JSDoc syntax is already supported in both .ts and .js files, but in .ts files JSDoc comments do not work (do not define types) like they do in .js files.

Examples

This would make it easy for users to choose which form they want to use to define types of things.

It would also give users more flexibility in choosing (or developing) JSDoc tooling without writing WET code.

For example, if a developer wants to document TS code with a non-TS JSDoc tool (for any reason, and there are valid reasons), then they need to define types in both TS and JSDoc, like this:

/** @typedef {{ name: string, age: number }} Bar - A Bar thing of sorts. */ // <-- This is for documentation tooling
export type Bar = { // <-- but we still need to define the type for TS to understand it (WET)
  name: string
  age: number
}

/** @typedef {Bar & { color: string }} Foo - A Foo type of thing. */ // <-- This is for documentation tooling
export type Foo = Bar & { // <-- but we still need to define the type for TS to understand it (WET)
  color: string
}

// This does not need to be documented, it is used only by the library code.
type _PrivateImplementationThing = { hasA: Foo }

However, if the user could use JSDoc comments to define types within a .ts file (just like they can in .js files) for things that specifically need to be documented, then they could write the previous example like the following more DRY code:

/** @typedef {{ name: string, age: number }} Bar - A Bar thing of sorts. */ // <-- This is for documentation tooling, and TS understand it.

/** @typedef {Bar & { color: string }} Foo - A Foo type of thing. */ // <-- This is for documentation tooling, and TS understand it.

// This does not (necessarily) need to be documented, it is used only by the library code.
type _PrivateImplementationThing = { hasA: Foo } // same as before

The same thing applies to functions, for example. The following is what we currently have to write in order to support non-TSDoc tooling while still declaring types for TypeScript:

/**
 * @function foo
 * @param {string} a
 * @param {number} b
 * @return {void}
 */
export function foo(a: string, b: number): void {/*...*/}

// not documented
function bar(a: boolean): boolean {}

but with the requested feature in place we could write the following more DRY code:

/**
 * @function foo
 * @param {string} a
 * @param {number} b
 * @return {void}
 */
export function foo(a, b) {/*...*/}

// not documented
function bar(a: boolean): boolean {}

This would be very supportive of JSDoc tooling that isn't specifically TSDoc. This also gives developers choices (for example, the choice to only document whatever is in JSDoc form, and otherwise ignore the rest, whereas TSDoc tries to document literally everything which is undersirable).

Lastly, having to maintain the WET duplicated type definitions (one for JSDoc tools, one for TypeScript) is error prone, because if the types don't match, TypeScript does not give any error. It would also be great if at least TypeScript warned when comment types don't match source code types, so as to at least prevent errors editing both comments and source.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code - It may break code that has currently-ignored JSDoc comments within .ts files.
• 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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[MartinJohns]

Duplicate of #33189.

[trusktr]

Please don't close this issue until it has a resolved conversation.

Issue #33189 was closed as a duplicate of #20774 which was closed as a Question with the answer being "the JSDoc type didn't work in your .ts file because JSDoc works only in .js files and not in .ts files".

This issue is not a question, but a request for supporting the feature, and I believe it deserves some reasoning instead of being closed as duplicate of an issue that merely mentions why a JSDoc comment didn't work inside a .ts file.

I believe the example in #20774 is also not intuitive. The type of the parameter is defined, yet intellisense shows the type as any.

This doesn't help with incremental adoption of TypeScript, because if we convert a very large .js file to .ts, we have to port all the code, instead of just some.

[trusktr]

Here's a more practical example I didn't include in the OP. Coming from a JS code base, one might have this:

/** @type {number} */
const f = unknownAPI()

where unknownAPI is not typed yet, so the return type is any.

In the plain JS file, TS/intellisense correctly sees f as having the type number.

When we rename the file to end with .ts, TS/intellisense now sees the variable as type any.

Inside the .ts file, that previous snippet should behave as if the user had written the following TypeScript:

const f: number = unknownAPI()

[Jcparkyn]

This seems like a no-brainer to me, and it would be a pretty significant selling factor for any teams considering migrating a codebase from JS+JSDoc to TS. For a fully annotated JS codebase, this would mean being able to switch to TS (in strict mode or otherwise) without needing to make a single change.

I know it's been said that this is "by design", but like @trusktr I can't find any information about why this is the case.

[jamonholmgren]

There's one feature of JSDoc that isn't achievable in TypeScript, and that is to type-constrain only one property of an object literal while inferring the rest.

export type FoodType = "burger" | "steak" | "veggies";

const order = {
  customerName: "Bob",
  /** @type {FoodType} */
  food: "steak",
};

In this case, I want the order type to be:

{
  customerName: string; // inferred
  food: FoodType; // specified by JSDoc comment
}

This works in a .js file (assuming you import the FoodType type from a .d.ts file or something), but doesn't in a .ts file.

I know you can use as FoodType, but that doesn't constrain FoodType in the literal. It will cast, which I don't want here.

So this is another vote for allowing JSDoc in TS files, as it would allow me to do this.

[pauldvu]

100% would love this for patterns such as

 /** @type {typeof import("/.types").zodObject._type } */
 
 

I currently use this in my backend it's pretty convenient and allows us to get the type of a zod object
It saves us from having to export type z.infer on all of our ts zod constants

[MatthewPinheiro]

There's one feature of JSDoc that isn't achievable in TypeScript, and that is to type-constrain only one property of an object literal while inferring the rest.

@jamonholmgren just to mention it, though you probably know by now, you can accomplish this in TypeScript now with the satisfies keyword:

// food is still a string, but you will now get a compilation error
// if you assign food to something other than a valid FoodType
const order = {
  customerName: "Bob",
  food: "steak" satisfies FoodType
};

[jogibear9988]

I have a UI for a home automation system (iobroker), in wich users could edit scripts with monaco editor. As the users only edit javascript (not typescript, or I need to translate at runtime wich would have a perfomance implication) they still should get intellisense. This does not work, cause JSDoc is not interpreted in ts.
Why do I need JSDoc in TS if I said they edit javascript? I need to switch Monaco Editor to Typescript mode, or global variables, wich I defined with setExtraLibs are not used in Javascript mode.
So I could switch to Javascript, and the JSDoc coments work, or I could switch to Typescript and the global defines work.
(I dont not if the setExtraLibs error is also a typescript one? see: microsoft/monaco-editor#4323)

[jogibear9988]

Got the issue on my side solved, so I could switch back to javascript code, see: microsoft/monaco-editor#4323

But I still think types from JSDoc Comments should be used in TS code