What is "TC39: Type Annotations" aka the Types as Comments proposal

All right. Hi, everybody. We're going to go through the TC59 Type Annotations proposal, a.k.a. Types with Comments. This is a proposal that adds the ability to run typed code in JavaScript.

Now, my name is Otto the Rocks. I used to work on the TypeScript team for about two and a half years. During that time I worked on website and documentation and a little bit of compiler features here and there. And one of my favorite things when I left was I had this great, like, YouTube video that describes the entire compiler process that's really, really useful if you're, you know, into understanding the tools that you use on an everyday basis.

So, to get this talk started, we want to at least have some shared vocabulary. We're going to talk a bit about TC39. There are a group of folks whose entire goal is to try and figure out how to evolve JavaScript slowly and safely. And the way in which they do this is sort of by making these proposals. These proposals, you know, they go through five stages. They're all sort of more and more specific over time. And we're talking about a TC39 proposal that is now at stage one.

So, the proposal itself is what we're going to go into first. We'll go over that briefly. We'll dig into why now makes some sense. Because it's not the first. We'll see how it affects TypeScript. That's kind of the majority. And we'll sort of go into where it's going next. So, this is the underlying concept. That there's a problem with this code. That it will not run in a JavaScript engine. Like the colon string is going to throw. And that means that that's not legitimate language. So, we want to be in a position where that does not happen. How to do that? That's the tricky question that people have asked a lot.

And this proposal argues that the way to do that is to say that, hey, JavaScript engines, you just ignore this code. You treat it as a comment. Now, comments are already pretty well defined in JavaScript. You've got a slash, slash. We'll do it to the end of the line. And you've got a slash, star. We'll do it to the end of a star, slash. This is us using the term a little bit ambiguously. It isn't a comment in the way in which we normally think of them. But it is telling both the person who is trying to understand this proposal, the idea is, you just ignore it. And we teach browsers how to ignore that type of code. And that is the idea.

If you want to really dig into the details, you can go to the TypeScript's, the TypeScript comments, I'm going to make that mistake a bunch. The Typescript comments proposal web page. And this is a higher-level version of the proposal. So it doesn't require you to be a language nerd, basically. And if you do want to really nerd out, you should watch Gil Tyre's talk on the lead up to his proposal, because he's one of the folks pushing it. How and why he got some consensus from a bunch of folks. And sort of why it makes sense in the long run in comparison to him using JSDoc support in JavaScript.

So why now? Right? Like, you know, there has been many attempts at trying to add a type system to JavaScript. And this is sort of the first time that one has sort of got to a level of, you know, people caring. TypeScript I think has really proven to folks that there's a need for typed JavaScript at a reasonable scale. TypeScript itself is now in a position where it's okay to sort of take on some of the constraints that would be necessary to make this work. And the idea's already been proven in prior languages that have similar constraints, like scripty type of languages, like Ruby and Python. The extent to which they fully agree with all of the tradeoffs is something that we can now use to figure out what that should look like in JavaScript in comparison to sort of Ruby and Python's implementation, too. So we're not the first, we're trying something new. We're trying something that's reasonably established.

Now, the thing that I think most people are in the context of TS Congress are interested in is how does this affect TypeScript, right? This is a proposal that adds some constraints to TypeScript that can sort of maybe bring TypeScript back into JavaScript. There's a lot of things going on here. And when I thought about how to frame this, I went through the notes from TC39's original discussion, and spotted that Rob Palmer had this beautiful sentence that sums it all up.

He sort of has four major points that we'll go through one by one. They want the ability to run TypeJavaScript anywhere, you want to unfork TypeScript from JavaScript, and you want to sort of make TC39 the place where syntax discussion is held. And you want there to be, like, a real separation between, like, what is a type system thing and what is a runtime thing, and this proposal helps all of those.

So, to sort of go through them one by one, I actually want to sort of switch these two around so I can work with a better story. Unforking TypeScript to JavaScript, I think, can best be explained by trying to figure out the popularity of TypeScript. And a good way to measure that is the amount of open source pull requests that happen on GitHub.

So, this is going to be a graph of the percentage of all pull requests that are a specific language. So, we're going to look first at JavaScript. So, from 2013, it was roughly 17%. And then that went up to about 25% before 2016. So, you have this of all pull requests, JavaScript went from being 17% of all pull requests to 25% of all pull requests, which means as the GitHub open source ecosystem was growing, the JavaScript ecosystem was growing faster. And then you start to see it sort of decline. And part of that, it's a growing ecosystem of everyone doing open source. So, you know, when more Python users come in, it's a bigger pie. But at the same time, there's almost a linear growth of TypeScript throughout this entire time period, too. So, it's hard to deny that TypeScript must be eating into JavaScript's sort of user base, in a way, on GitHub for open source pull requests.

But the interesting thing is that they're starting to converge, right? Like, they're getting very close to being about the same number, which is somewhere about 10% for each. I got this data from BigQuery, which is a Google project that allows you to parse all of these big open source datasets, including GitHub usage graph stuff. And this is, you can go on a website called GitHub 2.0, that will try to show you the exacts of how this sort of popularity metrics are measured. But it is pretty reasonable to say that roughly TypeScript is the fork of JavaScript, which is about as popular as JavaScript for modern code. It's about a 50-50 split between whether someone is going to be using JavaScript or TypeScript in a project or at least on a pull request in the open source.

And so, who knows what that looks like in private code. And, you know, it's hard to ever measure the exactness of things like this. But it isn't that hard to say that this could be how it is. And so, when you think about that, that's kind of worrying for JavaScript as a conceptual thing. Like JavaScript's, like, main schtick, if you will, is that it's a consensus-driven language that's very useful for all these web browser things. So, we have different sets of folks on TC39 that all have different sets of constraints. But together, they found a consensus that continues to make sure that a web page built 20 years ago still runs today, because JavaScript backswood compatibility is pretty solid. But the weird thing here is now, if there's a language that's ran by one set of one company, Microsoft, is it great space for us to be in where there's this one language that is the underlying bit that has a lot of people working together to try to figure out the right thing to do, but on the other side, there's one company that represents about 50% of all open source contributions to that language using those types of languages. It's a bit too much pressure for Microsoft.

It's a bit worrying for the TC39 folks, basically, to have someone maybe just pull the rug from under them. For TypeScript, when I was on the team, I actually read a talk on the constraints that TypeScript puts on top of itself in order to make sure that it has the least amount of negative impact on the ecosystem of JavaScript, and how that works, and why that that's at least worth reading up if you want to really dig deep into that. But I'm not going to go into that, generally speaking here.

TypeScript's unlikely to do that, and this helps those sets of constraints. So the way that I think about how code is used nowadays, you have most people are writing JavaScript, according to their BigQuery stats. But a very sizable chunk are doing TypeScript, and there's one or two JS people in between there that make it a bit ambiguous. But the way in which people interact with this code via tools and reading read-me's and things like that, is majority, is much more TypeScript based, because you have things like definitely typed, which provides inline comments in your editors, and that really eats into the interaction space in which you have people using JavaScript files generally.

And yet, of all of that, the actual code that can run in your JavaScript engine is just JavaScript. And so you find yourself in this position where you can't really explore with this code anymore, because it has to run through a transpiler to remove its type annotations. But it does feel weird once you start getting used to running in an ecosystem like Deno or Bund where TypeScript can be a native feature. It really starts to sort of mess your head with the idea that you're running a JavaScript file. You start thinking you're running a TypeScript file. And that's not generally good for TC39 because, again, they want you to be running a JavaScript file, the JavaScript engines. That's what it all is. And this proposal helps trying to bring folks back from TypeScript into JavaScript.

TypeScript gets a lot of freedom right now because it runs its own implementation of the language. And so when, you know, when features are added to TypeScript, they can be put wherever they want as long as it makes sense and can be used everywhere. But in the context of a types of comments world, it's not so true anymore. In this code, this sort of satisfies that feature's just not available. You can't add a post fix, like satisfies. You can't set a keyword arbitrarily. And satisfies might only be relevant for TypeScript. It might not be relevant for other type systems. And so, you know, the TypeScript team actually has to have some give here. And that's not all bad things, right? Like, this is a problem that the TypeScript team has already had to address at least once, because, you know, satisfies support is already in JSDock. And, you know, that works pretty elegantly. And so, you have this thing where, like, you know, there's all this TypeScript in the world. You know, anybody doing TypeScript today is basically doing a TypeScript project with .ts files, and there's a few JSDock people. But in the future, I think it's going to be much more like there's a vast majority of people that are doing JavaScript with TypeScript. And they sort of represent the majority of folks.

And, you know, the version of TypeScript that runs in the TypeChecker is going to constrain itself to fit within the scope of this proposal. And the folks that really want full syntactical freedom, they still have the capabilities to do that via the .ts files. But they're going to be like more of an edge case within the world of JavaScript, in my opinion.

The next one is that like they want to separate out type features versus runtime features in order to really specify that, you know, a type the type extensions can't really edit the code that's running. And, like, within the context of TypeScript, there are features that the TypeScript team sort of regret but still support forever. And it just happens to be that when you look at the Venn diagram of these two things, they actually are the exact same things. You know, the features that TypeScript doesn't want to support necessarily are all features that are expression level features.

So, this neat little meme that I made at some point, which is like a way of saying, like, at some point, you know, TypeScript decided that, like, enums and namespaces and these features that like affect the runtime, they're not really the types of things that TypeScript wants to be involved in and that's like a responsibility for 2.6.39. And this types of comments style system really helps enforce the, like, the line between those two responsibilities.

So, where are we now? We're a bit further down the line. You know, it was March 2022 when this proposal first came out. You know, the proposal said, hey, we're really trying to find a way to, like, do this types of comments conceptual thing. And they sort of got to a stage zero, which effectively means, hey, this might, this is a thing. No one's gonna rip it apart. It's actually gonna be implemented as this. But it got to a point where it was, when talking with the rest of the TC39 teams, people concluded there's a few good questions to look at to start thinking for stage one, and they came back a year later and started, you know, answering some of the, answering some of those problems.

The first one was trying to figure out, hey, if we build a type system like this, should it be able to interact with the runtime at all? Like, you know, TypeScript's general gist nowadays is you can go from a TypeScript file to a JavaScript file just by pressing delete. That's the goal. And that means that anything you do in types cannot have an effect of the runtime. Otherwise, you can't just press delete. That's not the same thing. And so, the proposal, you know, kind of codifies this. And, you know, after going back and talking to a bunch of folks, there's a lot of people that say, like, this is just not browsers would just absolutely block this if it required them to build a type checker in order to correctly know whether something should be the right type or not at different times. And so, if that's a blocker, then that's great. Because that frees up types as comments to be types as comments rather than types as performance hints, maybe.

This the next one is trying to avoid this problem of token soup. The rough gist is that, like, it's hard right now to be able to specify actually what can live in a type and what cannot. The rough heuristic right now is if it's an open brace, there needs to be a closed brace. And you can look from left to right and count your braces this way and count your closes this way. And once they're finished, then you could be finished with the type if you see say an equal sign.

And this is good for a paper heuristic, but in reality, there's a lot of complicated JavaScript code that needs to continue already existing. And so, there needs to be a lot of research done into figuring out what problems do we know about and what problems do we not know about in this space yet. But there was still enough for people to say, hey, this proposal, it has a chance. It is a chance that this could get in. And that's really what happened with stage one.

So, we're getting there. Right now, the folks that were working on the proposal are sort of working on trying to figure out how they can quantify the effects of changing to support this type of comment style. Ignoring can work. Browsers would be okay with very small performance hit in order to support the scope of this idea. But they might not be okay with trying to do that if it comes with too much performance trade-offs because the only way in which we can actually declare this is the type space is that it requires doing some parsing, going back and reparsing it again, now that we know they're in a different context, and things like that. It's kind of complicated compiler implementation stuff and if you really want to figure out those details, go watch my talk, How the Compiler Compiles, and you can see how a tokenizer generally works.

The next one is try and figure out community outreach, see what people are interested in this space. They want the opinions of many sets of people, so there'll be JavaScript folks that don't believe there should be types in there, and there'll be documentation folks that are like, hey, why don't we do our own thing in this space instead of just only using it for types. There's gonna be a lot of people doing really creative work in that types space, and I think that's the goal of the carve-out, but also you want to be careful about it. And then try to figure out, how do we figure out this token soup problem of trying to really define an area that could be reasonably ambiguous, but at the same time be not ambiguous, so that you can easily declare, hey, this is an area of code that just isn't gonna run. With comments, that's easy because there's easy end delineators, but this isn't so true with the thing that we're looking at.

So, how can you get involved? Well, first of all, maybe follow the GitHub repo. We get lots of, we get relatively few issues over time. A lot of that activity happened in the first six months, and now a lot of it is just sort of people that are trying to explore alternatives to this sort of comment style type system that they're kind of very interested in creative, so they're always worth a look, but it would be nice to have a few folks in there that are like, hey, yeah, like a bunch of these are solved answers, and there's a lot of very, a lot of people that have already got code that looks a lot like this that might be, might be good to have a few more folks saying that sort of thing in there, and the other one would be participate in community surveys. Like a lot of the times, you know, type sanitations is the number one most requested feature and that's, you know, good for this proposal, because it provides backing for saying, you know, people want this, and also, you know, there's going to be surveys from the folks that actually write these proposals about trying to figure out, like, what sort of trade ups are acceptable. If you ever see any of those, I think most of those folks are mastered on and ideally, so should everybody else, so check those out, too. And I think that's enough.