Static type checking with TypeScript

[adamstankiewicz]

The frontend code in Open edX repositories, including Paragon, have traditionally not used TypeScript, in favor of vanilla JavaScript. I think this may be because historically, edX has not had much internal domain expertise around TypeScript. Despite this, TypeScript has grown to be quite popular and commonplace for JavaScript developers, providing many great advantages at the short term cost of a small learning curve.

The main advantages we'd hope to get with TypeScript in Paragon are:

• Catch and prevent bugs earlier during development
• Type inference
• Defined structures (e.g., interface)
• Increased confidence in component code for consumers
• Self-documenting code, (e.g., without TypeScript, how do you know what the type of this argument should be: function renderItems(item) { ... }?)
• IDE support
  • Auto-completion
  • Easier code refactor
• In general, code with greater efficiency.

Some foreseeable disadvantages:

• Learning curve (this may vary anecdotally from engineer to engineer)
• Writing code could take longer

More discussion of the advantages/disadvantages of moving to TypeScript:

• https://medium.com/javascript-scene/the-typescript-tax-132ff4cb175b

Evidence of static type checking popularity

TypeScript is the 4th most popular file type on Github pull requests, whereas JavaScript is the 2nd. TypeScript's ranking has trended up over the past year.

source

TypeScript is the 2nd most "wanted" language developers hope to use, but aren't currently. Additionally, TypeScript is the 3rd "most loved" language.

source

From the 2021 State of JavaScript report, "Static Typing" ranked as the highest feature missing from native JavaScript.

source

From the 2020 State of JavaScript report, TypeScript received a 93% "would use it again" rating from JavaScript developers.

source

From the 2019 State of JavaScript report, ~60% of JavaScript developers have USED TypeScript and WOULD use it again, while ~22% WANT to try it (source).

Proposal

We'd love to collect feedback, thoughts, and concerns about moving Paragon to TypeScript. If you have strong feelings about static type checking via TypeScript for Paragon (other more broadly across Open edX), we'd appreciate your thoughts!

[arbrandes]

To get it out of the way first: among the type-checking JavaScript compilers, TypeScript would also be my choice. It's more popular and proven than the alternatives.

This is not to say that static typing itself is an easy choice. In my experience with TypeScript, it's three significant advantages are:

1. Catching runtime errors at build-time, saving developer time spent in debugging and/or writing certain types of unit tests;
2. It levels the codebase beyond what libraries/frameworks such as React can: because of more defined interfaces/structures, even a large team will end up writing more similar code;
3. Auto-complete, if you care to use an IDE that provides this.

Which is to say, if you don't auto-complete, as a developer there is only one advantage. Granted, it's a big one! But that's it: it theoretically saves an X amount of your time. TypeScript still compiles to Javascript, so you don't see the performance advantage you might in languages that compile to machine code. And no statically-typed language will save you from writing bad code.

As a project architect, one's likely to be big on 2. Nothing like a compiler to get folks to conform, because you can't eslint-comment-directive your way out of it. :P

Now, Typescript's two disadvantages are:

1. Writing code takes longer, even if you auto-complete. And you still need to unit test.
2. The learning curve is significant, in particular for devs accustomed to dynamically typed languages.

The big question for developers is how Advantage 1 compares to Disadvantage 1. In other words, how does the time you save on debugging compare to the additional time you'll spend writing the code to begin with? Defenders of TypeScript will say of course you save time. I don't think the distinction is self-evident, and will vary from team to team and from project to project. It is certainly worth discussing, though.

Auto-complete saves some additional time, doesn't it? It certainly can, and folks that like it are usually firmly in Typescript camp, because it makes it actually useful when writing JS code. And in practice, when it comes to developers, this is what the discussion is about. At this point in the discussion I usually snark at Java: it's such a bureaucratic, verbose language that it is basically impossible to be productive with without auto-complete. Where in the spectrum does Typescript stand?

The learning curve should also not be dismissed. It is harder to learn and write TypeScript than regular JS, and should be discussed appropriately. What are the costs associated with having the current development team learn it? Are TypeScript developers more expensive to hire?

And finally, thoughts on code standardization, quality, and dependability: all of these can be achieved with good engineering practices. I.e., good reviews and ample test coverage, all which you have to do anyway if you want dependable software. As mentioned above, static typing won't save you from buggy code. The question here is if static typing makes it cheaper.

[adamstankiewicz]

@arbrandes Great input/feedback! Yes, this thread is largely about static type checking in general, but most likely via TypeScript. As you mention, there are advantages, disadvantages, and tradeoffs to any technical decision. Also, to be clear, this discussion is largely just about static type checking in Paragon specifically, though I wouldn't be opposed to exploring it elsewhere, either.

Catching runtime errors at build-time, saving developer time spent in debugging and/or writing certain types of unit tests;

This is a big advantage why a few of us in Enterprise at edX/2U are interested in experimenting with TypeScript. We had a few recent bugs in our MFEs that snuck through code reviews that would have otherwise been caught by TypeScript at the time of implementation rather than costing us time later in the process, when trying to get a new feature released. Though, to your point, perhaps closer attention to tests would have helped here, especially during the code review process; on the other hand, there is some merit to having real-time build warnings about such errors during implementation rather than relying solely on test coverage and/or having no human error/oversight during the code review process:

It levels the codebase beyond what libraries/frameworks such as React can: because of more defined interfaces/structures, even a large team will end up writing more similar code;

In terms of Paragon specifically, which occasionally receives code contributions from teams throughout edX/2U, I would definitely find TypeScript beneficial for this reason to maintain a level of consistency between component conventions, etc. (e.g., defining a base interface/type that all Paragon components should be, to ensure that component authors are properly prop spreading to ensure flexibility in component design, as an example).

Auto-complete, if you care to use an IDE that provides this.

For sure. The biggest thing here for me personally is the self-documentation of defining things like what properties are in an object, especially as React Context becomes more common in our code bases (including Paragon), where it can be tricky to know exactly what values are inside the context (e.g., const contextValue = useContext(MyContext);), without needing to investigate and find the code to understand its contents, or use a console.log. Auto-complete solves this problem quite nicely 😄

Writing code takes longer, even if you auto-complete. And you still need to unit test.

I'd agree writing code may take longer but I also wonder how much time it saves in terms of engineers' time in the long run, with regard to not needing to track down as many bugs reported by users that could have otherwise been caught at build time, even if TypeScript "only" catches a theoretical maximum of ~15-20% of public bugs (imo that's still a significant number, especially in a project that is consumed by the majority of UI for Open edX).

Unit testing and other engineering best practices would indeed still need to be honored; that wouldn't change 😄 but as this article points out, TypeScript can be considered "JavaScript that scales", reducing the cognitive load for engineers during implementation despite probably needing to type more characters than they otherwise might have to. This benefit is appealing to me as someone who would love to see more contributions to Paragon from edX/2U & the community, but with a little automated help from TypeScript to maintain conventions/consistency with said contributions so as not to rely solely on my review for more trivial bugs, like typos in object properties that could otherwise go unnoticed.

The learning curve is significant, in particular for devs accustomed to dynamically typed languages.

Yes, although anecdotally, as someone who until recently hasn't used TypeScript before, I felt I got a pretty solid grasp of the high level concepts and was able to complete a slightly more complex "hello world" type project in TypeScript with relative ease in just a few hours one weekend; I'm also someone who doesn't have too much experience with statically typed languages, only using them during a couple classes and maybe an internship in college nearly 8 years ago, and still found TypeScript to be quite approachable once you get your hands dirty with it a bit 😉

It could even help make the code base more understandable/approachable, notably in more complex components like DataTable where there is a lot of prop drilling and there have been some mismatches between prop type definitions for certain attributes at different levels of the component tree; I would hypothesize that types could help alleviate some confusion for newcomers to the project.

Another interesting thing to note here might that TypeScript by nature is opt-in. It is something that can organically grow in a repository over time, assuming the owners of that repository are comfortable with not having complete standardization right away; for example, Material UI took this approach in migrating to TypeScript. They got more and more organic contributions using TypeScript and once it reached a certain level of adoption, they officially put it on their public roadmap and started to publicly track their official migration progress.

For most engineers working in Open edX, I would gather many will be active users of Paragon, but only a handful would be contributors to Paragon (in the form of contributing new/updated components, etc.). Any decision to move to TypeScript in Paragon specifically shouldn't really have any impact on its users, beyond having more robust/documented components, which I feel might be worth the learning curve/cost for not too many contributors to Paragon.