JSDoc typing <-> inline type annotation conversion

[zoller27osu]

⭐ Suggestion

.ts files transpiled to .js should have an option to move the typing to JSDoc-style comments, like https://www.npmjs.com/package/ts-to-jsdoc . Intelligently built, this could also allow the reverse - diligently JSDoc'd .js files to be "upgraded" to .ts with the typical in-line type annotations instead of the JSDoc, which could help a lot with TypeScript adoption.

🔍 Search Terms

jsdoc transpiling transpiler transpilation typing type_annotations

✅ 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
  • depends on whether you count comments as "different JS"?
• 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.

📃 Motivating Example

Admittedly the possible JSDoc'd .js -> inline-annotated .ts that could be informed by this change would be much more productive for most purposes, but I strongly believe that a deep enough understanding of the JSDoc vs. .ts typing connection would be useful for both.

💻 Use Cases

What do you want to use this for?

The Bitburner community extensively uses TypeScript via a VS Code extension and template to write scripts for the game in much more tightly typed TypeScript. However, the game itself only supports Javascript (technically, a very close sibling called Netscript 2), so the TypeScript written this way has to be transpiled to .js before being sent to the game, thus losing all type readability in-game. If the transpilation added JSDoc, though, it would continue to be very readable in-game due to the JSDoc support the game has.

What shortcomings exist with current approaches?

Obviously, you could just use removeComments = false and put the JSDoc typing into the .ts before transpiling, but that would result in double-typing and be ugly and unwieldy. The converse (JSDoc .js to inline-annotated .ts) doesn't even seem to be automatically possible atm, which is a shame because for the most part the supported type names are exactly the same.

What workarounds are you using in the meantime?

As mentioned, there's https://www.npmjs.com/package/ts-to-jsdoc, but it only seems to support single files at a time, which, as the TypeScript docs mention, can miss out on typing information from other files. Also, I am using a gulp pipeline to do the transpile for https://www.npmjs.com/package/gulp-preserve-typescript-whitespace, and I don't understand how/if I could integrate https://www.npmjs.com/package/ts-to-jsdoc with https://www.npmjs.com/package/gulp-typescript.

If anybody has additional workarounds, I'm very interested in hearing about them!

[fatcerberus]

Basically the same as #19285.

[MartinJohns]

@fatcerberus That's JS-to-TS. The other point is TS-to-JS (with JSDocs), which is a duplicate of #42547. I've misread the issue I linked.

[Josh-Cena]

If I understand this, what the OP primarily wants is...

export function foo(a: number, b: number): number {
  return a + b;
}

...to be compiled to...

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
export function foo(a, b) {
  return a + b;
}

I don't think that's a duplicate of either. Basically, people want the JS output to be both (a) runnable on its own and (b) contains all the necessary type information.

[fatcerberus]

I’m pretty sure there’s an existing issue about converting TS types to JSDoc when compiling, but I couldn’t find it.

[RyanCavanaugh]

See #10

[zoller27osu]

See #10

I swear I did a comprehensive search but didn't see that one, thanks!
It only seems to cover the .ts -> .js w/ JSDoc part though, not the reverse which I believe it would enable quite handily

[typescript-bot]

This issue has been marked as a 'Duplicate' and has seen no recent activity. It has been automatically closed for house-keeping purposes.