Typescript type annotations as comments

[nojvek]

Typescript’s goal is simply be Javascript + Types.

There are many use cases where one might want to use the excellent typechecker but not really have any emit stage.

Projects already written in javascript work with allowJS. Typescript already supports parsing types from jsdoc comments.

What would be really awesome is just comment annotating your javascript with types and the project gets the benefit of being type checked. This could be a boon for a lot of existing javascript projects. Getting intellisense, VSCode typechecking on the fly and a lot of language server awesomeness.

e.g.

/// <reference path="..." />

class Hello {
    /*:: private*/ hello(message /*: string*/) /*: Promise<{}>*/{
                const promise /*: Promise<void>*/ = null 
        return /*:: <Promise<{}>>*/ null;
    }
}

i.e

/: [type] */
/:: [tscode] */

[nojvek]

https://flowtype.org/blog/2015/02/20/Flow-Comments.html

Flow has a descent spec. It was a major feature request on their end too.

I think the big value add is typescript's language service. Being able to annotate an existing js code base and get on the fly error checking + code completion is pure awesomeness.

No source mapping needed, Browser/node reads the same code. Don't need to wait for a transpiling step. Node_modules written in this flavor don't need a separate typings install since source+types is same file.

[pardonmyenglish]

+1 I really love this aspect of flow and wish that TS supports something similar.

[eggers]

I haven't used it myself, but since 2.0, TypeScript supports jsdoc for typedef: JSDoc support in JavaScript

[pardonmyenglish]

In my view, the difference is that the JSDoc approach does not resemble the standard TS approach. Take the example in the tutorial: http://www.typescriptlang.org/docs/tutorial.html

function greeter(person) {
    return "Hello, " + person;
}

The recommended TS according to the docs:

function greeter(person: string) {
    return "Hello, " + person;
}

The comment-based approach that flow supports really resembles what you would write -- the type annotation is basically wrapped in a C-style comment:

function greeter(person/*: string*/) {
    return "Hello, " + person;
}

The JSDoc approach technically supports this case, but it is very different from the canonical TS approach:

/**
 * @param {string}  person  
 */
function greeter(person){
    return "Hello, " + person;
}

[nojvek]

You are correct. Jsdoc has a lot more verbosity than flow style comments.

…

On Wednesday, December 14, 2016, pardonmyenglish ***@***.***> wrote: In my view, the difference is that the JSDoc approach does not resemble the standard TS approach. Take the example in the tutorial: http://www.typescriptlang.org/docs/tutorial.html function greeter(person) { return "Hello, " + person; } The recommended TS according to the docs: function greeter(person: string) { return "Hello, " + person; } The comment-based approach that flow supports really resembles what you would write -- the type annotation is basically wrapped in a C-style comment: function greeter(person/*: string*/) { return "Hello, " + person; } The JSDoc approach technically supports this case, but it is very different from the canonical TS approach: /** * @param {string} person */function greeter(person){ return "Hello, " + person; } — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#9694 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA-JVH1GfPO_GWAXT_fmBeb4qedUwNqJks5rINRcgaJpZM4JLxhT> .

[akdor1154]

It seems there is often resistance to adding a build step in projects where previously was none - at my workplace I am using Flow to provide static analysis over Typescript precisely because of this, and the amount of community support this feature has in Flow suggests this scenario is reasonably common.
If Typescript supported annotations in comments I believe it would pick up a lot of this use, as it's generally considered on the whole to be more powerful than Flow. I know I'd rather use it.
This also shouldn't be specific to Salsa (I guess), my dream implementation of this feature would be that tsc or a ts language service in my IDE of choice would just load .js files with TS comments and treat them as if they were typescript.

[nojvek]

Totally agree with this. JS with typed comments definitely makes js more powerful.

…

On Mon, Jan 9, 2017 at 9:23 PM Jarrad Whitaker ***@***.***> wrote: It seems there is often resistance to adding a build step in projects where previously was none - at my workplace I am using Flow to provide static analysis over Typescript precisely because of this, and the amount of community support this feature has in Flow suggests this scenario is reasonably common. If Typescript supported annotations in comments I believe it would pick up a lot of this use, as it's generally considered on the whole to be more powerful than Flow. I know I'd rather use it. This also shouldn't be specific to Salsa (I guess), my dream implementation of this feature would be that tsc or a ts language service in my IDE of choice would just load .js files with TS comments and treat them as if they were typescript. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#9694 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA-JVH482DM1OpASNYEEGF-gmH_-XD2_ks5rQxXcgaJpZM4JLxhT> .

[akdor1154]

First shot at implementing this. It currently only looks at .ts files (pretty useless, we need it to work with .js). It may also benefit from some equivalent of //@flow, otherwise ts is likely to go parsing everything it can find in node_modules. However, the basic functionality is there and working.

[abenhamdine]

IMHO, I think this feature is not very necessary (and this is also for future readers who would were eagerly looking for this feature).

At the beginning, I was also shy to add a compilation step in our projects, and considered using Flow only for the benefit of comment syntax. But a few tries whith ts, I realized that :

• the compilation step in Typescript is quite fast, simple and reliable
• the js code generate is very readable. Actually, the code transpiled by Typescript is nearly the same that i would have written ! (minus some line breaks removed, etc...). It means that if you want, at any moment, you could stop using ts, and revert back to the js files.

Otherwise, you juste have to rename .js file to .ts file in order to have type checking.

FWIW, our project is a very complex application developped with node and extjs, and we migrate nearly 60% of server code to Typescript in 2 weeks.

[nojvek]

Thanks for your feedback Arnaud. This is a very polarizing discussion. I'll list some arguments I have experienced and got from friends at other companies. Argument 1: From the fundamentals Isn't Typescript just javascript + types? If so, then one would expect their javascript to remain as is and just add types in their js code. All major browsers and node support es6 in their latest version. Having plain js works. Transpilation is overkill. Node modules could benefit from it. JS libraries could benefit. It's only when you're stitching code that webpack is needed. With http2 push https://en.m.wikipedia.org/wiki/HTTP/2_Server_Push even stiching into one big js isn't needed. Argument 2: vscode js experience that uses the tsserver gives a very handicapped experience for js compared to ts. If js is the lingua franca of the Web then it makes sense to give javascript the nice experience. Jsdoc/closure comments/flow comments are all efforts to make js powerful. Argument 3: Dealing with sourcemaps is a PITA. Because of the reverse mapping step, the stars need to align for debuggers to get everything right. I've given up many times finding the exact setup and simply moved to just debug the generated js. Many tools do a half arsed Job with sourcemaps. See: microsoft/vscode#18363 ⋅⋅⋅ Found the issue. Well, found a fix. The issue is that no one understands sourcemaps. Neither do we nor anyone who develops libraries for sourcemaps. ⋅⋅⋅ Argument 4: Browser devtools have a great feature of live edit. A class of problems go away if source is what the engines run. Testing iterations with live edit is instantaneous. A transpile step breaks the dev loop. Can't copy a ts function into console to test something quick. Browsers barf at the type syntax. JS exceptions don't map to the source. We have to do that manually. In a way what we really need is browsers and node to run javascript with type hints. Python does that by ignoring the type hints https://www.python.org/dev/peps/pep-0484/. May be Ecma will someday approve of type syntax. JS engines will do the correct thing with types. Until then, a commented syntax would be handy. A great js editing experience would increase developer productivity.

…

On Thu, Jan 12, 2017 at 6:08 AM Arnaud Benhamdine ***@***.***> wrote: IMHO, I think this feature is not very necessary (and this is also for future readers who would were eagerly looking for this feature). At the beginning, I was also shy to add a compilation step in our projects, and considered using Flow only for the benefit of comment syntax. But a few tries whith ts, I realized that : - the compilation step in Typescript is quite fast, simple and reliable - the js code generate is very readable. Actually, the code transpiled by Typescript is nearly the same that i would have written ! (minus some line breaks removed, etc...). It means that if you want, at any moment, you could stop using ts, and revert back to the js files. You juste have to rename .js file to .ts file in order to have type checking. FWIW, our project is a very complex application developped with node and extjs, and we migrate nearly 60% of server code to Typescript in 2 weeks. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#9694 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA-JVIjPMSnz__hbsnZROGzIpcjJbrrMks5rRjPTgaJpZM4JLxhT> .

[abenhamdine]

Thx for you detailled answer !

I have to admit your arguments are quite valid, and probably my feedback too brief (mainly because I'm not a native english speaker).

My feedback is more "hey, you can jump into ts without syntax comment, you should not choose beetween TS and Flow just basing your decision upon the existence of this syntax in Flow".
Because it was exactly the situation where we were two months ago.

Concerning sourcemap, so far, we didn't have too much problems in VSCode. For instance, node debugging has always run perfectly (while again : it's a very complex project). And in case of error in prod, it's not so too difficult to map the .js line to the .ts line (even if it's indeed a waste of time).

However, we have only migrated server code to ts, we don't consider migrate browser code at the moment.

An other caveat is indeed the use of VS Code for editing .js files : we used to be on ST3 for js files, and we switched to VS Code after a poor experience with ST Typescript plugin. We found VS Code less fast and convenient than ST is.
However, VS Code is evolving quickly, and in the right direction IMO.

[aluanhaddad]

Then there will be two type syntaxes embedded in comments, actually three if you include Flow types. JSDoc already has multiple interpretations. Throw TypeScript types into comments and even more complexity is introduced.

[nojvek]

Want to clarify. I don't think commented types in Typescript bring much benefit. As you said it just introduces complexity. Commented types in javascript (.JS) are useful. In that scenario, there are only two types. Jsdoc and flow. Flow types are just Typescript types wrapped in comments. E.g /*:string*/ and /*::<any>*/(someValue) This means having a tsconfig with allowJs should give a very close experience to Typescript. Both type checker and vscode ide.

…

On Fri, Jan 13, 2017 at 12:17 AM Aluan Haddad ***@***.***> wrote: Then there will be two type syntaxes embedded in comments, actually three if you include Flow types. JSDoc already has multiple interpretations. Throw TypeScript types into comments and even more complexity is introduced. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#9694 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA-JVOwvwdI_N1Y2UeK7PcF1LuMp0PFdks5rRzMRgaJpZM4JLxhT> .

[aluanhaddad]

Want to clarify. I don't think commented types in Typescript bring much

Thanks I wasn't sure if this was intended to apply to JavaScript and TypeScript or just JavaScript.

Commented types in javascript (.JS) are useful. In that scenario, there
are only two types. Jsdoc and flow.

Perhaps but there are different interpretations of JSDoc, TypeScript is one interpretation, Closure is another, JSDoc v3 is yet another.

Flow types are just Typescript types wrapped in comments.

E.g /:string/ and /::/(someValue)

I so wish that were true. Unfortunately the syntax is subtly different. More significantly the meaning can be radically different.

This means having a tsconfig with allowJs should give a very close
experience to Typescript. Both type checker and vscode ide.

That would be a great indeed.

[zspitz]

@aluanhaddad Could you provide some examples of the differences between the three flavors of commented types?

[aluanhaddad]

Flow:

type T = { name: string }
Array<U: T>

TypeScript:

type T = { name: string }
Array<U extends T>

JSDoc:

@typedef T { name: string }
@template U implements T
Array<U>

The difference in interpretation is more what I'm concerned about.

[aluanhaddad]

That last example is not yet supported by closure and I'm not even sure if that's how you would write it it's hypothetical syntax

[pardonmyenglish]

@aluanhaddad I think you are confused about the proposal. The idea isn't to introduce the exact flow syntax into typescript, but rather to introduce a special comment form which JS engines ignore but tsc and typescript parsers interpret as valid TS code.

I gave an example in #9694 (comment) but it wasn't that clear so I will try another example from the tutorial.

Let's say you have an existing JS codebase:

function greeter(person) {
    return "Hello, " + person.firstName + " " + person.lastName;
}

var user = { firstName: "Jane", lastName: "User" };

document.body.innerHTML = greeter(user);

The TS form that defines the person interface looks like:

interface Person {
    firstName: string;
    lastName: string;
}

function greeter(person: Person) {
    return "Hello, " + person.firstName + " " + person.lastName;
}

var user = { firstName: "Jane", lastName: "User" };

document.body.innerHTML = greeter(user);

The comment form which we are discussing is a series of comments atop the JS form that aligns with the TS form:

/*::
interface Person { // <-- this is the same exact code you would write if you fully bought into TS
    firstName: string;
    lastName: string;
}
*/
function greeter(person/*: Person*/) { // <-- the type annotation is in a C-style comment that JS ignores but TS would parse
    return "Hello, " + person.firstName + " " + person.lastName;
}

var user = { firstName: "Jane", lastName: "User" };

document.body.innerHTML = greeter(user);

The ability to write snippets of typescript and embed them in comments would enable developers to slowly annotate their JS code without changing their minified JS output and without having to buy into TS from the onset. This is important for adoption. We ended up adopting flow for a 50kloc JS project because it was incredibly easy to demonstrate the power of flow and incremental type annotations without actually changing the existing workflows or existing live JS.

[aluanhaddad]

I am sorry, I am not trying to be stubborn. I do understand the use case and I agree it is both valid and valuable. I am talking about the way tools behave. If a tool uses a heuristic to find Flow types in comments, it could choke on this. The same is true for JSDoc, but this is probably easier to disambiguate.

[akdor1154]

@aluanhaddad a heuristic to pick up flow types would be unlikely to pick up these hypothetical typescript types by mistake - flow-annotated-js needs to contain a // @flow comment to trigger processing.

[nojvek]

Agree with @pardonmyenglish. Typescript doesn't need to understand every syntax out there. It just needs to enable a typechecking scenario for javascript files. With this Tsserver can support the magic of refactoring, code completion, etc for Javascript files

…

On Sat, Jan 14, 2017 at 5:25 PM Jarrad Whitaker ***@***.***> wrote: @aluanhaddad <https://github.com/aluanhaddad> a heuristic to pick up flow types would benefit unlikely to pick up these hypothetical typescript types by mistake - flow-annotated-js needs to contain a // @flow comment to trigger processing. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#9694 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA-JVGS43w9vnxsUXLvV0-ZGkgOToPkAks5rSXWJgaJpZM4JLxhT> .

[abenhamdine]

And in case of error in prod, it's not so too difficult to map the .js line to the .ts line (even if it's indeed a waste of time).

For the future reader : I correct myself, with https://github.com/evanw/node-source-map-support, we can have the line number in the .ts file, and it works perfectly for us.

[pitaj]

Any updates on this?

Is there a way to implement this as a plugin or something? I'm thinking of just pushing the source code through something like this:

return source
  .replace(/\/\*::([\s\S]*?)\*\//g, '$1')
  .replace(/\/\*:([\s\S]*?)\*\//g, ':$1');

and then passing that to TS, but I'm primarily focused on VS Code support

[nojvek]

I do like function syntax e.g

function hello(greeting /*: string */, notify /*: boolean */) {
}

Rather than jsdoc comments which are verbose and require duplication of param name.

Currently not supported but I feel that it should be pretty easy to add.

https://github.com/Microsoft/TypeScript/wiki/JSDoc-support-in-JavaScript

[nojvek]

Yeah the hardest part is really convincing Typescript team (cc @DanielRosenwasser) that this is a good idea. TS is essentially a superset of JS, so technically this should be quite straightforward to implement it such that the superset-ness of TS is literally just comments in a JS file.

[maranomynet]

The inability to gradually introduce proper TypeScript annotations into existing JavaScript modules without having to add a compile step for each and every one, is pretty much the only thing holding me and my team back from switching from Flow to TypeScript.

A comment-based annotation option (in .js files flagged with // @ts-check) also dramatically lowers the threshold for developers to do "drive-by-guerrilla-typing" on older projects and smaller modules.

[TomasHubelbauer]

The support for allowJs+checkJs with JSDoc has gotten me personally quite far with type checking in JavaScript files, which is why I personally am interested in this feature.

However, a big, big, drawback of using JSDoc is that it differs from TypeScript too much. There are a lot of patterns (especially dealing with generics, overloads, inference etc.) which I know how to type in TypeScript very well, but can't for the life of me figure out in JSDoc.

On top of that, the JSDoc documentation is very poor and overall it is just a different type system, so you don't really get TypeScript, just a super basic version of it.

This is why I'd like to see actual TypeScript type annotations supported in JavaScript files. I don't know if there is "philosophical" opposition to this from the TypeScript developers or it is just not seen as high-enough value, so the only thing I can do is to chime in and say I'd use it - a lot.

[kdmadej]

I just found myself in a similar situation as @TomasHubelbauer did.

I need to use more advanced concepts like mapped types or conditional types but I can't figure out a way to define the aforementioned concepts using JSDoc.

I'm currently working on a project that doesn't use TS but I'd love to get some type checking in VSCode based on type annotations in comments.
Adding support for type annotations in comments would be a life-saver for people who would like to get the benefits of TS but the decision about the techs used in the project is not made by them.

[DanielRosenwasser]

For situations where you need a more advanced type that isn't supported in JSDoc, you can declare the types in a .d.ts file and then reference the types back in the JSDoc.

[luciotato]

For anyone coming here looking to add TypeScript type-annotations within comments, I've made a fork with a hack to allow exactly that:
https://github.com/luciotato/plus-typescript/blob/master/README.md
https://github.com/luciotato/plus-typescript
@kdmadej @TomasHubelbauer @maranomynet @nojvek @joeytwiddle Maintainers are welcomed

[nojvek]

Holy moly. This is incredibly cool @luciotato . What I love about this is it supports full breadth of TS syntax. The current jsdoc annotations that typescript team recommends is really a hodge podge of quirks. I've invested 6 months of my life converting our existing js to jsdoc only to realize there are so many little things missing.

[martinheidegger]

@DanielRosenwasser

For situations where you need a more advanced type...

This is about 2 minutes into trying to define types. I basically have no code that does not use Generics... It becomes a really expensive problem once you realize that 50% of the code needs to be in the .d.ts file. Not only that, but trying to memorize two different syntax is not good for productivity.

[ixis-doug]

Like others who joined late to the party, let me start by saying how much I appreciate the effort that's gone into Typescript. It's an incredible tool, and to be commenting at all on an issue is a testament to that.

The nearly 6 years this issue has been open is a bit discouraging. The use cases and value have been established, @luciotato built a working prototype, and Flow has long supported this, so there are real users of this feature in the wild. Part of what "opt-in types" ought to mean is that you can start using types in a project that's not ready to be converted to Typescript, even if that conversion is rightly considered easy. The value of writing new libraries in TS is limited by the inability to fully exploit the value of those types in vanilla JS consuming code (and I say "fully exploit" to deliberately cover what one cannot accomplish by telling the editor to treat JS files like typescript and other ways of seeing the types of 3rd party libraries in a vacuum, without defining types in the vanilla JS calling code).

[joeytwiddle]

There appears to be some movement in the form of:

https://devblogs.microsoft.com/typescript/a-proposal-for-type-syntax-in-javascript/

... which proposes to redefine what is a comment in future ES.

[ixis-doug]

There appears to be some movement in the form of:

https://devblogs.microsoft.com/typescript/a-proposal-for-type-syntax-in-javascript/

... which proposes to redefine what is a comment in future ES.

This is indeed related and very exciting, but considering there are browsers that haven't hit EOL that don't even support ES2015 (looking at you IE 11), I think this is a potential solution for 2030 javascript/typescript developers, not 2022 javascript/typescript developers. The typescript language being able to find meaning within comments would be a much more powerful solution when backwards compatibility requirements are considered.

[maranomynet]

Also: "We decided to lobby for TypeScript officially becoming JavaScript, but still pretend that's not what we're doing"

🤪

[DanielRosenwasser]

but considering there are browsers that haven't hit EOL that don't even support ES2015 (looking at you IE 11) I think this is a potential solution for 2030

Types can always be stripped away/"downleveled" for older browsers. Considering the proposal will take years of work if it does proceed, 2030 might be when you actually get the feature!

[ixis-doug]

@DanielRosenwasser

Types can always be stripped away/"downleveled" for older browsers.

Stated differently, could we say "well you could still run your code through a typescript compiler to strip the types"? If so, this leaves us in the in the same position we're currently in, no?

[HolgerJeromin]

I think one of the use case is:
Develop with your fancy new browser and develop faster without compile.
But in production you still use the transpiled/stripped/minified output even for some ie8 if you like/must.

[DanielRosenwasser]

Well if you're targeting Node, Deno, or primarily evergreen browsers, you can run as-is (especially for the development-time scenarios that @HolgerJeromin just mentioned). If you really need to accommodate older runtimes, you can add this as a production-time build step.

[joeytwiddle]

By the way, I have tried using JSDoc in a project, and I learned something I didn't know before:

We don't have to stick to the JSDoc way of declaring types, which usually involves lots of @ tags, and splitting up of objects.

We can instead use TypeScript types inside the JSDocs, to keep things small and familiar!

Here is an example with a function that accepts two strings, and returns an object whose two properties are dictionaries.

This is how we might expect to annotate the function using JSDoc

/**
 * @typedef {Object} MemberGroupsResponse
 * @property {Object.<string, MemberGroup>} memberGroups
 * @property {Object.<string, Array.<string>>} memberGroupsByUser
 *
 * @function getMemberGroupsUncached
 * @async
 * @param {string} month
 * @param {string} memberGroupsSheet
 * @returns {Promise.<MemberGroupsResponse>}
 */
async function getMemberGroupsUncached(month, memberGroupsSheet) { /* ... */ }

But actually we can annotate the function more simply, using a single TypeScript type!

/**
 * @type {(month: string, memberGroupSheet: string) => Promise<{
 *   memberGroups: Record<string, MemberGroup>;
 *   memberGroupsByUser: Record<string, string[]>;
 * }>}
 */
async function getMemberGroupsUncached(month, memberGroupsSheet) { /* ... */ }

Advantage:

• This is much more concise!

We can also put comments like /** @type string | number */ above a variable

Disadvantages:

• This isn't really valid JSDoc, so this format isn't suitable for tools which only understand traditional JSDoc
• Basically these annotations are only really useful in TypeScript-based development environments
• Still not as short as actual TypeScript, or the inline comments people suggest in this thread
• I don't know how to lazily omit the return type, so TypeScript can derive it for me
• In VSCode, there is currently no syntax highlighting for these TS-types-inside-JSDoc
• In VSCode, autocomplete support works better inside JSDoc than it does for these TS-types-inside-JSDoc

So if you don't need traditional JSDoc but you would like some TS-checking in your JavaScript files, this hybrid approach might work for you.

(I am using TypeScript type checking in VSCode, with the option js/ts.implicitProjectConfig.checkJs but // @ts-check would also work.)

[ShadSterling]

I'm trying to use tsc to generate .d.ts files for my fork of a JavaScript project, making minimal changes to the original .js files. For almost everything tsc's inference is good enough, and for most of the rest adding comments as described by @joeytwiddle fills in the gaps. But here's one that fails:

The original code:

delete Number.prototype.then;

Types that work in TypeScript:

interface MaybeThenable { then?: Function }
delete (Number.prototype as Number & MaybeThenable).then;

The same types in JSDoc annotation in a .js file:

/** @typedef { { then?: Function } } MaybeThenable */
/** @type { Number & MaybeThenable } */
var klass = Number.prototype;
delete klass.then;

Is rejected by tsc:

Type 'Number' is not assignable to type '{ then?: Function; } & number'.
  Type 'Number' is not assignable to type 'number'.
    'number' is a primitive, but 'Number' is a wrapper object. Prefer using 'number' when possible.

73             var klass = Number.prototype;
                   ~~~~~

It seems that tsc doesn't respect wrapper types given in TSDoc annotations

[ShadSterling]

Turns out it works if I go to constructors, but it would be better if tsc handled types the same way in both TypeScript annotations and JSDoc annotations

/** @typedef { { prototype: Object & { then?: Function } } } MaybeThenableConstructor */
/** @type { NumberConstructor & MaybeThenableConstructor } */
var konstructor = Number
delete konstructor.prototype.then;