$ cat choices/typescript.md
the call
I reach for TypeScript anywhere code lives in the JS/Node/web world and has to survive past the demo. The types are the cheapest guardrail there is: a class of bugs becomes a compile error instead of a 2am page. I skip it only for genuinely throwaway scripts.
JavaScript’s reach is unmatched and its footguns are legendary. TypeScript keeps the reach and removes a whole category of the footguns: undefined-is-not-a-function, the shape that drifted, the refactor that missed a caller. The compiler reads the whole codebase on every keystroke, a reviewer that never gets tired and never assumes. For anything that has to be maintained, that’s a guardrail you take by default, not an upgrade you earn later.
A genuinely throwaway script, a five-line glue file, a one-off: the ceremony of types isn’t worth it there. And TypeScript is not a correctness proof. It checks shapes, not logic, and any is always one keystroke from undoing the guarantee. Reaching for ever-more-baroque type gymnastics to model something the type system resists is its own rabbit hole. The goal is fewer bugs, not a cleverer types file.
The Bushido tooling runs on it. han is TypeScript and Rust: TypeScript for the surface area where ecosystem and iteration speed matter, Rust for the parts where performance and correctness are non-negotiable. Two typed languages, each placed where its strengths land. That pairing is the whole point: types where they’re cheap, a borrow checker where they’re worth more.— see: open-source / han · choices / rust
Take the guardrail when it’s cheap. TypeScript’s cost is near-zero in the JS world and its payoff compounds with every line and every refactor. It’s the same instinct as Crystal, Rust, and a typed discipline in general: let the compiler carry the load a human reviewer otherwise has to, and push the cost of a mistake back to authoring time, where it’s cheapest to fix.
the gaps — what it costs even when it’s right
It checks shapes, not truth. Green types and a wrong answer coexist happily. Types reduce a class of bugs; they don’t replace tests or judgment, and treating a clean compile as “correct” is a trap.
any and casts are escape hatches that quietly undo the guarantee. Discipline and lint rules required, or the safety is theater. A typed codebase full of any is just a slower untyped one.
The build step and type-gymnastics tax. A layer of tooling, and the occasional hour lost modeling something the type system fights. Worth it for code that lasts; overhead for code that won’t.