Wednesday, October 13, 2021

Learning Typescript, and why I'm not a fan

A work project I'm helping out with uses Typescript, I tried to use it for my extension, and now I just use JavaScript. It's all because TypeScript documentation is bad, the module system is silly, their conversion times are slow, and their target user is 100% not me.

I'm a little bit of a computer language enthusiast, and have been for years. My first intern project was to make a YACC grammar for a Fortran "wirelist" program for Teradyne (hi, Chuck!); I designed and built a technically-oriented terminal-based hypertext system for electric engineering; I created an incredibly simple search language for a game company (technical requirement: must be functional in less than one day, because otherwise we'd have to use my boss's approach, and he was wrong). 

I was enthused by having a reason to jump into Typescript for this project. I 100% love the concept of typescript: it's like JavaScript, but adds in types, so you make fewer mistakes. Who wouldn't like that? I'm not a fan of being all loosey-goosey with naming, and appreciate the little boost that Typescript add. The generated JavaScript code matches well with the original, making debugging easier.

And then in all went wrong. After a successful start, within a day I stopped working on the Typescript source and instead just edited the JavaScript file. 

The compile speeds take me out of the flow. My file is just a few hundred lines long; in JavaScript I can just reload. With TypeScript, you have an awkward pause. The pause is for no technical reason; my files are small, a reasonable program would be able to read it, parse it, and convert it in under a second. (my own current language project is a language converter; my own goal is <1second for a 1K line file)

The module documentation is much to terse. Specifically, if you already know how modules work, and know what you want, then you can understand the module documentation. Otherwise, it fails to provide basic information about what the settings do, and when to use them.

Modules simply emit errors. The goal of Typescript is that it generates working JavaScript. There are two settings for modules: ones that generate non-working JavaScript (the browser sees an import statement and complains that it doesn't know what requires means), and ones that spit out long lists of compiler errors about not finding some package that I'm not asking for (some configuration language).

If your customers are highly motived people then you can get away with badly documented features that generate errors. I'm not that highly motivated, and have an alternative.

Why do I even need modules? Typescript requires modules for two reasons: 

The -watch command that's needed to make compile times acceptable only work with the -build switch and that in turn only works with modules. It would have been nice if I would have just typed tsc file.ts --watch and be done with it. 

As soon as you have two files, you have to have modules. Otherwise, nothing works.

The language documentation is a barrier to understanding. The documentation for Typescript hardly presents an easy onboarding experience. There's pretty much nothing that I found that presents a high-level work flow, or explains their design choices. 

Mathematicians are the bane of computer documentation. I firmly believe that there's a mathematicians brain that some people have, such that they read in equations and very short, very succinct descriptions, and from that generate an entire field. It's actually an awesome ability, and it makes them write completely useless documentation for the rest of us. (Note: I have a degree in mathematics).

Typescript is full of the mathematicians approach: provide a tiny number of words, with no worked-out example, and starting from first principles (which no beginner know) instead of from what starting people need to read.

I wanted typescript to be a powerful new tool in my toolbox for designing programs. Instead, after multiple fruitless hours of trying to make Typescript work within my work-flow, I simply gave up and embraced JavaScript. And it makes me sad