The two big announcements in 2025 were:

1. Microsoft is rewriting the TypeScript compiler and language service in Go.
2. Node.js began supporting TypeScript natively.

TypeScript rewrite in Go

I've followed the TypeScript release notes for years. Recent releases have had relatively few big new language features, and many of these have been contributed by external developers. This March, we found out why: The TypeScript team at Microsoft has been working on a massive project to port tsc and tsserver from TypeScript to Go.

My first reaction was: "is it April 1st already?" My next reaction was a whole lot of mixed feelings.

It's generally considered a good practice for compilers to be bootstrapped, i.e. written in their own language. While this sounds strange at first, it's quite common and has several positive consequences:

1. It's a demonstration that you can build a large, substantial program in the language.
2. It makes the development team aware of issues in the language, since they work in it day-to-day.
3. It makes the development team acutely sensitive to compiler and language service performance.

No one doubts that you can build large programs in TypeScript, but the "dogfooding" aspect of self-hosting has been good for the TypeScript ecosystem. Every TypeScript release comes with performance improvements, and one reason for this is that the TS team appreciates fast builds and responsive editors, too.

So bootstrapping is, in principle, good. That being said, a 10x speedup should make you question your principles.

When I was developing my inferred type predicates feature, I was struck that the TypeScript in tsc is written in a distinctive, low-level style. It often looks more like C than JavaScript. I started to think about how you could turn that into a faster tsc. A direct port to C wouldn't work since JavaScript has garbage collection and tsc relies on that. I wrote in a notebook: "what's the lowest-level language with garbage collection?" I figured it might be Java and left things there.

It seems the TS team, in particular Jake Bailey, went through the same thought process and came to a different conclusion: Go!

The new TypeScript is a line-by-line port of the existing one. There's a notorious 50,000+ line checker.ts file today, and in the future there will be a 50,000+ line checker.go. TypeScript 6.0 will be the last TypeScript-based version of TypeScript, and then future versions will be written in Go.

The upshot is that, sometime next year, you'll update your packages and everything will get 10x faster. Slow compiler and language service performance has always been one of the biggest complaints about TypeScript. I've experienced this myself on large projects and I'm looking forward to the speed boost.

My other hope is that, once the dust settles, we'll see a renewed focus on new language features.

Node.js Runs TypeScript Natively

This one flew under the radar for me when it happened earlier this year, and perhaps it's news to you, too: Node.js now natively supports TypeScript!

// test.ts
function add(x: number, y: number): number {
  return x + y;
}
console.log(add(1, 2));

> node test.ts
3

Impressive stuff! This should work with any version of Node.js after 22.18.0, which was released on July 31st, 2025. (This behavior has been available since Node 22.6.0 last year via --experimental-strip-types.)

This is a big deal. Ever since Node came out in 2009, people have been running preprocessors in front of it to improve JavaScript in various ways. CoffeeScript was one of the first, then we started using "transpilers" like Babel to get early access to ES2015 features, and now we use TypeScript to get types. In all these cases, we're adding a tool to the stack. It has to be configured, you have to know it exists, and something might go wrong with it. In short, it adds friction.

Node.js has supported ES2015 features for years now, so there's no need for a transpiler to use arrow functions, async, Map, etc. Now you don't need tsc to use TypeScript with node. It just works out of the box.

A few things to note here:

1. This is only about running your code. Node doesn't do type checking. It simply strips off the types. If you want type checking (and you do!) then you'll still need to run tsc separately.
2. Since this works by stripping types, you can't use TypeScript's niche runtime features: enums, parameter properties, triple-slash imports, experimental decorators, and member visibility modifiers (private). I've long advised against doing this (See Effective TypeScript Item 72: Prefer ECMAScript Features to TypeScript Features) and, as of TypeScript 5.8, there's an --erasableSyntaxOnly flag to keep you away from these.
3. Stripping types doesn't change line numbers, so you don't need source maps to debug.
4. While TypeScript supports any TC39 proposal at stage 3 or later, Node.js only supports features once they've landed in the spec. So for the few features in between those states, you'll need to hold off until they're official.

I want to reiterate that this doesn't do any type checking! Node will happily run programs with clear type errors:

// test-bad.ts
function add(x: number, y: string): Date {
  return x + y;
}
console.log(add(1, 2));

> node test-bad.ts
3

tsc can strip type annotations, of course, but there are several other tools that do the same thing, like Bloomberg's aptly-named ts-blank-space. Node uses @swc/wasm-typescript, which uses WASM for speed.

So does this mean that TypeScript has won? On some level, yes. It's so widely adopted now that Node.js felt the need to add built-in support. But this change also opens the door to more competition in the typed JavaScript landscape. It was designed with TypeScript in mind, but it doesn't have to be tsc checking your code. It could be some other type checker instead.

This puts JavaScript in a situation akin to Python. Python has a standardized syntax for type annotations but, for the most part, they have no effect on the runtime behavior of your program. There's a healthy ecosystem of type checkers for Python that all use the same syntax for type hints, but have different philosophies and provide different sorts of checking. Examples of Python type checkers include mypy, pyright (Microsoft), pyrefly (Facebook) and ty (Astral).

By standardizing a syntax for type annotations, Node is making it easier for new entrants to bring their own take on type checking to JavaScript. Competition is a good thing, and I hope this brings some of it to the typed JavaScript ecosystem.

What about browsers? There's a Microsoft-backed TC39 proposal to add type annotations to the language itself, but it's only at stage 1. I assume it would need to advance significantly before there's browser adoption. I hope Node's move gives this proposal some momentum. As it says, the motivation is to "unfork JavaScript," which would be good for everyone.

So long 2025! Here's hoping that 2026 brings faster build times, more responsive editors, exciting new language features, and a simpler JavaScript ecosystem.

Every December, I complete it in a new programming language. Every January, I intend to blog about the experience, but inevitably it slips, this year all the way back to November! (Sorry, I got completely consumed by a non-TypeScript side project.)

In 2024, I did the Advent of Code in Elixir, a functional programming language with immutable data types based on Erlang. This is analogous to how the JVM was built for Java, but also serves as a runtime for other languages like Kotlin and Scala.

I picked Elixir largely because a friend of mine worked in it. I'd also never written a substantial amount of code in a purely-functional language, and I was curious to see how it worked.

I suspect there's relatively little overlap between TypeScript and Elixir developers. They serve different roles and occupy different niches. But they do have a thing or two in common. In particular, Elixir is in the process of adding a gradual, optional typing system. Sound familiar?

1. A quick intro to Elixir
2. What can TypeScript learn from Elixir?
3. What can Elixir learn from TypeScript?
   1. Prioritize Language Services
   2. Adopting Types
4. General Impressions of Elixir
5. Thoughts on the 2024 Advent of Code
6. Conclusions

Here are the previous installments in this series:

• 2019: Python
• 2020: Rust
• 2021: Go
• 2022: TypeScript / Deno
• 2023: Zig

A quick intro to Elixir

Here's an Elixir function to read lines from a file (pretty helpful for Advent of Code problems!):

def read_lines(file) do
  File.read!(file) |> String.trim_trailing() |> String.split("\n")
end

Here you can see Elixir's pipeline operator (|>). This has been a hot topic in the JavaScript world for nearly a decade, so it was fun for me to get to play around with it. It wasn't as useful as I expected (more on this below).

Here's another pair of functions to "chunk" a list of strings into groups delineated by blanks (also very helpful in Advent of Code):

# Split a list of lines on the first blank line, returning a tuple.
def split_on_blank(lines) do
  # Enum.split_while: splits enumerable in two at the position of the element
  # for which fun returns a falsy value (false or nil) for the first time.
  {a, ["" | b]} = lines |> Enum.split_while(&(&1 != ""))
  {a, b}
end

def split_on_blanks(lines) do
  parts = lines |> Enum.split_while(&(&1 != ""))

  case parts do
    {last, []} -> [last]
    {a, ["" | rest]} -> [a | split_on_blanks(rest)]
  end
end

Here you can see more uses of the pipeline operator, a helper method from the ubiquitous Enum module, pattern matching on tuples, and an anonymous function (&(&1 != "")). In TypeScript, we might write this function in a more imperative style as:

function splitOnBlanks(lines: readonly string[]): string[][] {
  const chunks = [];
  let thisChunk = [];
  for (const line of lines) {
    if (!line) {
      if (thisChunk.length) {
        chunks.push(thisChunk);
        thisChunk = [];
      }
    } else {
      thisChunk.push(line);
    }
  }
  if (thisChunk.length) {
    chunks.push(thisChunk);
  }
  return chunks;
}

Here's one final Elixir snippet that reads a grid into an (x, y) -> char map and calculates its width and height. Again, this is very handy for Advent of Code problems!

def read_grid_from_lines(lines) do
  # Util.enumerate is my own code; it yields (index, value) like Array.entries()
  grid =
    for {y, line} <- lines |> Util.enumerate(),
        {x, char} <- line |> String.to_charlist() |> Util.enumerate(),
        into: %{},
        do: {{x, y}, char}

  w = for({x, _y} <- Map.keys(grid), do: x) |> Enum.max()
  h = for({_x, y} <- Map.keys(grid), do: y) |> Enum.max()

  {grid, {w, h}}
end

Here you can see Elixir's list comprehensions (for), which are a flexible way to build data structures. The into: %{} clause in the first comprehension says to put the results into a Map (%{} is an empty Map). These comprehensions all do pattern matching on the enumerable (what JavaScript would call an iterable). The last two use the pipeline operator to extract the max.

That gives you some of the flavor of Elixir. You can read much more about it on the official docs.

What can TypeScript learn from Elixir?

There are many long-stalled proposals to extend JavaScript, perhaps none more famous than the pipeline proposal, which has been around in some form since at least 2015.

At first blush, the pipeline proposal is simple and uncontroversial. Instead of writing nested function application as:

console.log(Object.keys(getUserPreferences(getCurrentUser())))

You'd be able to write it as:

getCurrentUser()
|> getUserPreferences
|> Object.keys
|> console.log

The beauty of this is that the order of the code reflects the order of execution (top-down here, rather than right-to-left) and there's much less nesting.

You can simulate a pipe in a few ways in JavaScript today. One approach is to repeatedly assign to a temporary variable:

let t;
t = getCurrentUser()
t = getUserPreferences(t)
t = Object.keys(t)
console.log(t)

This eliminates the nesting and inside-out order, but I can already see TypeScript users grimacing. While this works in JavaScript, it typically won't in TypeScript, where a symbol's type can only change in a very specific set of ways. Instead, you'd need to introduce a new variable for every assignment (static single assignment form).

Functional libraries typically offer pipelines via a wrapper object, notably jQuery and lodash:

console.log(_(obj).meth1().meth2().value)

These are limited to methods provided by the library, though. Lodash's chains can't help us with the getUserPreferences example. It would be much better if pipes were built into the language itself.

Why has the pipeline proposal has been stalled for so long? One reason is that there are different ideas about whether to offer special syntax for calling a function in a chain, and how that should work. This has always seemed like a secondary concern to me. Why not just add a basic pipe operator and worry about syntactic sugar later? Elixir has built-in pipes, so I was excited to see how they worked in practice.

The TL;DR is that pipes alone aren't all they're cracked up to be. I understand now why TC39 is so hung up on syntax extensions. It was incredibly rare that I used a function in a pipe without having to pass other arguments or adapt it in some way.

Elixir offers a few shorthands to facilitate working with pipes. For example:

f(x)      # regular function call
x |> f()  # equivalent pipe

This is stranger than it looks. When you write x |> f(), Elixir doesn't call f with zero arguments. Instead, it rewrites this expression to pass x as the first parameter to f (I assume using macros). This winds up feeling pretty natural when you use constructs like map:

[1, 2, 3, 4]
|> Enum.map(fn x -> x ** 2 end)  # [1, 4, 9, 16]
|> Enum.filter(&(&1 > 8))        # [9, 16]
|> IO.puts()

The Enum module contains many general functions for working with collections. These functions all take the collection as their first argument, which is conducive to piping. (I found this Enum cheatsheet extremely helpful.)

This example includes two ways of writing anonymous functions. &1 is the first argument to the function. This is convenient for writing very short functions. (You write the identity & &1.)

What would this look like with a plain vanilla JavaScript pipe? You'd have to create lots of wrapper functions:

[1, 2, 3, 4]
|> x => x.map(el => el ** 2)
|> x => x.filter(el => el > 8)
|> console.log

(this example looks silly since map and filter are already methods on Array)

This adds boilerplate and has been flagged as a performance concern by browser vendors. The proposal suggests introducing a new, concise syntax for creating anonymous functions using a placeholder symbol (perhaps %):

[1, 2, 3, 4]
|> %.map(el => el ** 2)
|> %.filter(el => el > 8)
|> console.log(%)

This at least makes the pipe more concise.

I enjoyed using Elixir pipes. (I would have enjoyed using them more with better typing!) But as I solved more AoC problems in Elixir, I found myself using them less and less. Instead, I starting using more and more comprehensions.

for(
  x <- [1, 2, 3, 4],  # input
  x**2 > 8,  # guard
  do: x**2   # map
) |> IO.puts()

Comprehensions let you combine multiple inputs, reduce your results and put them into any sort of collection you want. You can read more about them in this Comprehensive Guide. Perhaps it's because I'm comfortable with Python comprehensions or due to the Advent of Code problems themselves, but this was usually what I wanted. (One gotcha: a when clause in a comprehension is weirdly restricted. I understand this has something to do with Erlang and it's been explained to me a few times, but it never really clicked what I could and couldn't do.)

In conclusion: adding simple pipes to JavaScript probably wouldn't be that useful because you'd have to define so many small wrapper functions. If you want to fix that, too, you can understand why the proposal has gotten bogged down. At the end of the day, what I really want is comprehensions.

I'm not aware of any active proposals to add comprehensions to JavaScript. Interestingly, Firefox used to have its own non-standard comprehensions. There was discussion about adding this to what became ES2015, but it was deferred to a future standard in 2014 and seems to have died there.

What can Elixir learn from TypeScript?

Prioritize Language Services

When you install TypeScript, you get two binaries:

• tsc: the TypeScript compiler
• tsserver: the TypeScript language service

tsc is typically the only one you invoke directly, but you interact with tsserver more because it's what powers your editor. The TypeScript team treats the language service as a first-class citizen. It's just as important as the compiler or the language itself.

I didn't get the sense that Elixir Language Server got nearly so much attention. Three quick examples will illustrate the point.

First, Elixir has two modes, "scripting mode" (.exs file) and regular mode (.ex files). I started off in "scripting mode" for simplicity, but wasn't getting any editor support. Sure enough, this just isn't supported.

Second, syntax errors make the entire document flash red. I found this incredibly irritating. It often happens if you've just typed the "en" in end, say:

Third, there are basic features you expect from an IDE that simply don't work with Elixir. Rename support is high on the list.

Writing a great language service is no easy task. But the TypeScript experience is that it's critical to invest in it, because it determines how it feels to use the language.

Adopting Types

Side effects and mutation are notoriously difficult to model in a static type system. (Chapter Three of Effective TypeScript is all about this.) Elixir is purely functional (no side effects) and has exclusively immutable data structures. This makes writing code harder (at least for me!) but it should make static type analysis easier.

And yet, despite being fertile ground for static type analysis, Elixir has, historically, been untyped. So I was excited to learn that they're introducing an optional, gradual type system to the language. This should sound familiar to TypeScript users: TS pulled the same trick with JavaScript.

My first experiments with the new type system were deeply confusing. The new type system is, indeed, quite new. But if you search online for "elixir type system," you'll find lots of material about how to use it. This only cleared up for me when I realized that Elixir has two type systems: the old one (Dialyzer) and the new one (gradual set-theoretical types).

There's a paper (arXiv) describing the high-level goals and workings of the new type system, as well a video introducing it.

Set-theoretical type checking in Elixir seems very much a work-in-progress at this point. For example, you do get some errors in your editor:

def bad_add() do
  %{} + "12"
end

But you get more errors when you compile from the command line. I never got type errors in function chains, where it's sometimes hard to remember if you're working with a list or list of lists. And I was constantly making errors in how I read from maps with tuple keys:

def read_tuple_from_map() do
  grid = %{{1, 2} => true}
  Map.get(grid, 1, 2)  # bad!
  Map.get(grid, {1, 2})  # ok
end

The bad example does not produce a type error, at least not with Elixir 1.19.

It looks like the upcoming Elixir 1.20 release will add inference for whole functions:

def add_foo_and_bar(data) do
  data.foo + data.bar
end

Elixir now infers that the function expects a map as first argument, and the map must have the keys .foo and .bar whose values are either integer() or float(). The return type will be either integer() or float().

This is quite different than the sort of type inference that TypeScript does. TypeScript will infer a function's return type, but it never infers a parameter's type from the way that it's used in the function's body. (TypeScript will infer a parameter's type if it knows the function's type from context, for example if it's used as a callback.)

It's appealing to write fewer types, so why doesn't TypeScript do this sort of inference? The problem is that an implementation error in the function body can "leak" out into its signature, which will produce errors at call sites. Anders Hejlsberg, the creator of TypeScript, calls this "spooky action at a distance." For example, if you had a typo in add_foo_and_bar, say you accessed .baz:

def add_foo_and_bar(data) do
  data.foo + data.baz  # .baz!
end

then this would change the inferred type signature and you'd get errors at all your call sites. But the mistake is in the function body, not the call sites! The idea behind requiring type annotations for parameters is that you should know these types when you write your function. By writing explicit annotations, you make it clear to TypeScript whether the error is in the implementation or the caller.

We'll see how much of an issue this winds up being for Elixir. I suspect TypeScript's policy would be hard for Elixir to adopt in practice because its functional style encourages you to write lots of small, standalone helper functions that might be boilerplatey to type explicitly.

(See this comment from Ryan Cavanaugh for more on why TypeScript doesn't infer types for function parameters.)

General Impressions of Elixir

AoC isn’t a very good showcase for Elixir — it’s most well-known for concurrency, which is completely irrelevant for Advent of Code problems. Overall I didn’t dislike Elixir as much as I thought I might after the first week, but I never really came to like it that much, either.

• Elixir editor integration isn’t great, at least not in VS Code. There are big things (lack of types and quickinfo on variables) and small things (lack of F2 rename, bad autocompletes, screens of red).
• The lack of types makes Elixir dramatically less enjoyable to use.
• FP & immutability didn’t throw me off as much as I’d worried. After a few days, you get used to Enum.reduce. The pipeline operator is nice and comprehensions feel more like for loops that you’d write in other languages.
• There are some weird things: why the obsession with function arity? Why those weirdly-restricted filter clauses in for loops? Why aren’t functions first-class? Printing things is surprisingly fraught. The differences between && and and. The crazy range operator. No either/or matches. The weird Map.get_and_update method.
• My sense is that performance isn’t great… I assume that being compiled helps, but being functional and immutable hurts. My solutions generally seemed to be slower than the Python ones. Linked lists are a terrible data structure, but FP pushes you to use them for everything. There’s tons of potential for accidental O(N^2). ex: charlists

Thoughts on the 2024 Advent of Code

This was the first year where AI assistants like GitHub Copilot were relevant to the competition. I think Eric made some of the problem statements more elaborate than in the past to try and throw them off. I doubt it worked. Some of the winning times were suspiciously fast.

I didn't find GitHub Copilot particularly helpful for the 2024 Advent of Code problems. I did a few of the 2016 problems as a warm-up, and it was wildly helpful there. Sometimes you'd just start writing some boilerplate and Copilot autocomplete would fill in the entire solution! This makes sense if you think about it: the LLM's training data includes thousands of solutions to old Advent of Code problems in many languages, including Elixir.

The difficulty level in 2024 didn't feel too high. For me, 2019 remains the most difficult Advent of Code. As usual, building some tools for working with grids and doing BFS / A* search is helpful.

Standout puzzles for me included:

• Days 11–13: linear algebra in unfamiliar contexts
• Day 14: I loved hearing how everyone found their Christmas tree. I looked for states where an unusual number of robots had neighbors, but I think the best was to look for the lowest entropy state.
• Day 16: I liked the variations on BFS.
• Day 19: Eric teaches everyone how grep works.
• Day 21: Recursive keypads. This was probably my favorite puzzle this year, though it took some fiddling to get the right solution in the end.
• Day 24: I enjoyed the variety of solutions, particularly the people who visualized the circuit. I looked at the inputs to each output bit and used that to pare down to a manageable set of gates.

I didn't like day 20, the number we were computed felt very contrived and that threw me off. Days 22 and 23 were surprisingly easy. I had trouble with days 9 and 17 and wound up implementing solutions in Python.

Just like 2019, I was traveling for much of December and internet connectivity was sometimes an issue. Some of the lodges we stayed in had Starlink in the dining area, so I'd load the Advent of Code problem on my phone and Airdrop my input to my laptop back in our room. I queued up five or six problems to work on during my flight back and submitted all my answers on my phone when we landed.

Conclusions

Overall I enjoyed the 2024 Advent of Code. I wasn't a big fan of Elixir, though I understand that Advent of Code doesn't play to its strengths. Solving problems in a functional language wasn't as painful as I expected, so I might try it again next year. Speaking of which, the 2025 Advent of Code is going to be quite different!

You can find my code at danvk/aoc2024 (all days) and danvk/aoc2016 (days 1-11).

The item tries to be balanced in presenting the pros and cons of each approach. But in my own projects, I avoid Zod and use the third option instead (Generate Runtime Values from Your Types). I like TypeScript, and I'd like to define my types using its syntax!

At some point in the process of learning TypeScript, most developers have an epiphany when they realize that TypeScript types aren't "real": they're erased at runtime. This might be accompanied by a feeling of dread: if the types aren't real, how can you trust them?

The independence of types from runtime behavior is a key part of the relationship between TypeScript and JavaScript (Item 1). And most of the time this system works very well. But there are undeniably times when it would be extremely convenient to have access to TypeScript types at runtime. This item explores how this situation might arise and what your options are.

Imagine you're implementing a web server and you define an API endpoint for creating a comment on a blog post. You define a TypeScript type for the request body:

interface CreateComment {
  postId: string;
  title: string;
  body: string;
}

Your request handler should validate the request. Some of this validation will be at the application level (does postId reference a post that exists and that the user can comment on?), but some will be at the type level (does the request have all the properties we expect, are they of the right type, and are there any extra properties?).

Here's what that might look like:

app.post('/comment', (request, response) => {
  const {body} = request;
  // 🛑 Don't do validation this way!
  if (
    !body ||
    typeof body !== 'object' ||
    Object.keys(body).length !== 3 ||
    !('postId' in body) || typeof body.postId !== 'string' ||
    !('title' in body) || typeof body.title !== 'string' ||
    !('body' in body) || typeof body.body !== 'string'
  ) {
    return response.status(400).send('Invalid request');
  }
  const comment = body as CreateComment;
  // ... application validation and logic ...
  return response.status(200).send('ok');
});

This is already a lot of validation code, even with just three properties. Worse, there's nothing to ensure that the checks are accurate and in sync with our type. Nothing checks that we spelled the properties correctly. And if we add a new property, we'll need to remember to add a check, too.

This is code duplication at its worst. We have two things (a type and validation logic) that need to stay in sync. It would be better if there was a single source of truth. The interface seems like the natural source of truth, but it's erased at runtime so it's unclear how you'd use it in this way.

Let's look at a few possible solutions to this conundrum.

Generate the Types from Another Source

If your API is specified in some other form, perhaps using GraphQL or an OpenAPI schema, then you can use that as the source of truth and generate your TypeScript types from it.

This typically involves running an external tool to generate types and, possibly, validation code. An OpenAPI spec uses JSON Schema, for example, so you can use a tool like json-schema-to-typescript to generate the TypeScript types, and a JSON Schema validator such as Ajv to validate requests.

The downside of this approach is that it adds some complexity and a build step that must be run whenever your API schema changes. But if you're already specifying your API using OpenAPI or some other system, then this has the enormous advantage of not introducing any new sources of truth, and this is the approach that you should prefer.

If this is a good fit for your situation, then Item 42 of Effective TypeScript includes an example of generating TypeScript types from a schema.

Define Types with a Runtime Library

TypeScript's design makes it impossible to derive runtime values from static types. But going the other direction (from a runtime value to a static type) is straightforward using the type-level typeof operator:

const val = { postId: '123', title: 'First', body: 'That is all'};
type ValType = typeof val;
//   ^? type ValType = { postId: string; title: string; body: string; }

So one option is to define your types using runtime constructs and derive the static types from those. This is typically done using a library. There are many of these, but at the moment the most popular is Zod (React's PropTypes is another example).

Here's how the request validation logic would look with Zod:

import { z } from 'zod';

// runtime value for type validation
const createCommentSchema = z.object({
  postId: z.string(),
  title: z.string(),
  body: z.string(),
});

// static type
type CreateComment = z.infer<typeof createCommentSchema>;
//   ^? type CreateComment = { postId: string; title: string; body: string; }

app.post('/comment', (request, response) => {
  const {body} = request;
  try {
    const comment = createCommentSchema.parse(body);
    //    ^? const comment: { postId: string; title: string; body: string; }
    // ... application validation and logic ...
    return response.status(200).send('ok');
  } catch (e) {
    return response.status(400).send('Invalid request');
  }
});

Zod has completely eliminated the duplication: the value createCommentSchema is now the source of truth, and both the static type CreateComment and the schema validation (createCommentSchema.parse) are derived from that.

Zod and the other runtime type libraries are quite effective at solving this problem. So what are the downsides to using them?

• You now have two ways to define types: Zod's syntax (z.object) and TypeScript's (interface). While these systems have many similarities, they're not exactly the same. You're already using TypeScript, so presumably your team has committed to learning how to define types using it. Now everyone needs to learn to use Zod as well.
• Runtime type systems tend to be contagious: if createCommentSchema needs to reference another type, then that type will also need to be reworked into a runtime type. This may make it hard to interoperate with other sources of types, for example, if you wanted to reference a type from an external library or generate some types from your database using a tool like PgTyped or pg-to-ts.

Having a distinct runtime type validation system also comes with a few advantages:

• Libraries like Zod can express many constraints that are hard to capture with TypeScript types, for example, "a valid email address" or "an integer." If you don't use a tool like Zod, you'll have to write this sort of validation yourself.
• There's no additional build step. Everything is done through TypeScript. If you expect your schema to change frequently, then this will eliminate a failure mode and tighten your iteration cycle.

Generate Runtime Values from Your Types

If you're willing to introduce a new tool and build step, then there's another possibility: you can reverse the approach from the previous section and generate a runtime value from your TypeScript type. JSON Schema is a popular target.

To make this work we'll put our API types in an api.ts file:

// api.ts
export interface CreateComment {
  postId: string;
  title: string;
  body: string;
}

then we can run typescript-json-schema to generate JSON Schema for this type:

$ npx typescript-json-schema api.ts '*' > api.schema.json

Here's what that file looks like:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "CreateComment": {
      "type": "object",
      "properties": {
        "body": { "type": "string" },
        "postId": { "type": "string" },
        "title": { "type": "string" }
      }
    }
  }
}

Now we can load api.schema.json at runtime. If you enable TypeScript's resolveJsonModule option, this can be done with an ordinary import. You can perform validation using any JSON Schema validation library. Here we use the Ajv library:

import Ajv from 'ajv';

import apiSchema from './api.schema.json';
import {CreateComment} from './api';

const ajv = new Ajv();

app.post('/comment', (request, response) => {
  const {body} = request;
  if (!ajv.validate(apiSchema.definitions.CreateComment, body)) {
    return response.status(400).send('Invalid request');
  }
  const comment = body as CreateComment;
  // ... application validation and logic ...
  return response.status(200).send('ok');
});

The great strength of generating values from your TypeScript types is that you can continue to use all the TypeScript tools you know and love to define your types. You don't need to learn a second way to define types since the JSON Schema is an implementation detail. Your API types can reference types from @types or other sources since they're just TypeScript types.

The downside is that you've introduced a new tool and a new build step. Whenever you change api.ts, you'll need to regenerate api.schema.json. In practice, you'd want to enforce that these stay in sync using your continuous integration system.

While you don't typically need to access TypeScript types at runtime, there are occasionally situations like input validation where it's extremely useful. We've seen three approaches to this problem. So which one should you choose?

Unfortunately, there's no perfect answer. Each option is a trade-off. If your types are already expressed in some other form, like an OpenAPI schema, then use that as the source of truth for both your types and your validation logic. This will incur some tooling and process overhead, but it's worth it to have a single source of truth.

If not, then the decision is trickier. Would you rather introduce a build step or a second way to define types? If you need to reference types that are only defined using TypeScript types (perhaps they're coming from a library or are generated), then generating JSON Schema from your TypeScript types is the best option. Otherwise, you need to pick your poison!

Things to Remember

• TypeScript types are erased before your code is run. You can't access them at runtime without additional tooling.
• Know your options for runtime types: using a distinct runtime type system (such as Zod), generating TypeScript types from values (json-schema-to-typescript), and generating values from your TypeScript types (typescript-json-schema).
• If you have another specification for your types (e.g., a schema), use that as the source of truth.
• If you need to reference external TypeScript types, use typescript-json-schema or an equivalent.
• Otherwise, weigh whether you prefer another build step or another system for specifying types.

New Features

Disallowed Nullish and Truthy Checks

TypeScript will now alert you to certain conditionals that are always true or false:

const value = {} || 'unreachable';

Because {} is truthy, the right-hand side of the || is dead code. It should either be removed or investigated, since it might indicate a logic error.

If your project is large and has been around for a while, this check is likely to turn up some strange-looking code. For example, I got a "this expression is always truthy" error on code that looked like this:

const val = { ...obj, prop: value } || {};

What's that || {} doing there? Running git blame revealed the story. The code originally looked like this:

const val = obj || {};

Then a subsequent change added prop: value to the object and didn't remove the fallback. In this case, it's fine to remove the || {} since using object spread on a null/undefined value is OK.

This new check is the single best reason to update to TS 5.6. I haven't seen a single false positive, and I've found lots of strange-looking code. This matches the TypeScript team's findings.

Iterator Helper Methods

In addition to finding new errors in your code, new TypeScript releases continue the ongoing process of implementing all stage 3 ECMAScript features.

TypeScript 5.6 now supports Iterator Helper methods like map and take. If you've ever used Python's itertools package, this will be familiar. The appeal of iterators is that you can apply a series of operations to an array, for example, without constructing all the intermediate arrays. This reduces memory usage and should improve cache efficiency and performance.

Because these are JavaScript runtime methods, you'll need to use a runtime that supports them. At the moment that's Node.js 22 (which should enter long-term support in October) and around 67% of browsers. Unless you can guarantee support in your environment, you may want to wait on these for a bit.

Strict Builtin Iterator Checks (and --strictBuiltinIteratorReturn)

TypeScript's any type is dangerous: not only does it disable type checking, it can also silently spread through your program. Chapter 5 of Effective TypeScript is all about taming the any type.

Perhaps the scariest source of any types is type declaration files (.d.ts). If you call a function and it's declared to return any, then any is what you get, even if the word "any" never appears in your source code. JSON.parse is a famous example of this:

const obj = JSON.parse('{"a": 2}');  // whoops, any type!
const b = obj.b;  // no error!

(Matt Pocock's ts-reset fixes this and a few other well known issues.)

One subtle source of any came from direct use of an iterator's .next() method:

const letters = new Set(['a', 'b', 'c']);
const oneLetter = letters.values().next().value;
//    ^? const oneLetter: any (TS 5.5)
//                        string | undefined (TS 5.6)

The type in TS 5.6 makes a lot of sense! If the Set were empty, oneLetter would be undefined. Otherwise it would be a string. (You can also check the done property to narrow the type.) While directly working with an iterator is rare (you should typically use for-of loops or the new iterator helpers), this is a welcome improvement because it eliminates a surprising source of any types.

So the real question is… why was this an any type in older versions of TypeScript? To understand why, the TypeScript blog gives this example:

function* abc123() {
    yield "a";
    yield "b";
    yield "c";
    return 123;
}

const iter = abc123();

iter.next(); // { value: "a", done: false }
iter.next(); // { value: "b", done: false }
iter.next(); // { value: "c", done: false }
iter.next(); // { value: 123, done: true }

A generator function (which returns an iterator) can both yield and return values. When it returns a value, that goes into the value property of the iterator's value.

TypeScript models this with two type parameters: Iterator<T, TReturn>. Most iterators don't return a special value when they're done, so TReturn is typically void (the return type of a function without a return statement).

When TypeScript first added support for iterators in 2016, they didn't distinguish T and TReturn. When they did split these types in 2019, they had to default TReturn to any to maintain backwards compatibility. The kicked the can down the road for years until this release, when they added a new flag, strictBuiltinIteratorReturn, to fix it. This is enabled with --strict, so you should get it right away.

A few more quick notes on this:

• The types around iterators, generators and async iterators are all pretty confusing. I hope to write a blog post about them at some point in the future.
• If you don't have strictNullChecks enabled, you may see some strange errors around value having a type of string | void. The fix is to enable strictNullChecks!
• This was a surprising source of any types that could spread in your code. To limit the damage from these sorts of anys, consider using typescript-eslint's no-unsafe-assignment, York Yao's type-coverage tool, or my brand-new Any X-Ray Vision VS Code extension.

The --noUncheckedSideEffectImports Option

I first noticed this issue when I was working on the second edition of Effective TypeScript. I claimed that this would be an error:

import 'non-existent-file.css';

… but it wasn't! This is a pretty strange TypeScript behavior. For these "side-effect imports," where you don't import any symbols, TypeScript will try to resolve the path to the module. If it can, it will type check the file that you import. But if it can't, it will just ignore the import entirely.

Now you can change this behavior with noUncheckedSideEffectImports. If you use CSS imports, you're likely to get tons of errors when you first enable this, one for every import. The solution that the release notes suggest is to add this line to a .d.ts file:

declare module '*.css' {}

But this feels a bit too lenient. It will catch a typo if you get the extension wrong (.cs instead of .css). But it won't check that you're importing a file that exists. I experimented with listing all my CSS files in a .d.ts file:

declare module 'css/file1.css' {}
declare module 'css/file2.css' {}

But this didn't seem to work at all. Relative imports of these files still produced type errors. So I think this feature still needs some work to be useful.

Region-Prioritized Diagnostics in Editors

Like most compilers, TypeScript is self-hosting: tsc is written in TypeScript. This is a good idea because it's a form of dogfooding. The idea is that, since the TS team works in TypeScript every day, they'll be acutely aware of all the same issues that face other TypeScript developers.

Sometimes, though, this can have strange consequences. I suspect that most developers who contribute to TypeScript had a chuckle when they saw Region-Prioritized Diagnostics in Editors in the TS 5.6 release notes. The idea is that, for very large TypeScript files, the editor can focus on just the part that you're editing, rather than checking the whole file.

Sounds like a nice performance win. So why did I find this funny? It's because it's so clearly targeted at just one file, TypeScript's 50,000+ line checker.ts. It's incredible to me that the TS team implemented this feature rather than breaking up that file, but there you go!

New Errors

Whenever a new version of TypeScript comes out, I like to run it over all my projects and the code samples in Effective TypeScript using literate-ts to look for new errors. There were a few of them, including some surprises.

Several errors came from the new checks I discussed earlier in this post, "this expression is always truthy" and .next() calls having stricter types. These were all true positives: they flagged code that was suspicious.

There were also two types of errors that came as surprises.

One was a change in circularity detection for a code sample in Effective TypeScript, in Item 33: Push Null Values to the Perimeter of Your Types:

function extent(nums: Iterable<number>) {
  let minMax: [number, number] | null = null;
  for (const num of nums) {
    if (!minMax) {
      minMax = [num, num];
    } else {
      const [oldMin, oldMax] = minMax;
      //     ~~~~~~  ~~~~~~
      // 'oldMin' / 'oldMax' implicitly has type 'any' because it does not have a
      // type annotation and is referenced directly or indirectly in its own
      // initializer.
      // (Error before TS 5.4, OK in TS 5.4, 5.5, error again in TS 5.6)
      minMax = [Math.min(num, oldMin), Math.max(num, oldMax)];
    }
  }
  return minMax;
}

In the first edition of Effective TypeScript, the same snippet avoided destructuring assignment in the else clause due to the circularity error:

result = [Math.min(num, result[0]), Math.max(num, result[1])];

I filed an issue about this in 2019 and was excited to see that it was fixed with TS 5.4, just in time for the book release. Unfortunately, the fix got reverted and we're back to the circularity error. So I'll need to update the book.

I also ran into an issue where the inferred type parameters for a generic function call changed. It boiled down to something like this:

declare const f: <P>(
  fn: (props: P) => void,
  init?: P,
) => P;

interface Props {
  req: string;
  opt?: string;
}

const props = f(
  (p: Props) => '',
  { req: "" },
);

props.opt
// Error in TS 5.6, OK in earlier versions

I used every-ts to bisect this to #57909. This PR changed how type inference worked between covariant and contravariant parameters. If you see a surprising type change like this after updating to TS 5.6, this change might be the reason.

After reading some comments, this all seems pretty murky. There's often no clearly correct inference, just tradeoffs. Given that, I'm a bit surprised that TypeScript changed the existing behavior. Be on the lookout for this one!

Performance changes

New TypeScript releases have the potential to speed up or slow down compile times, but I was unable to measure any significant changes with this release.

Conclusions

While TS 5.6 isn't quite the blockbuster that TS 5.5 was, the new "this expression is always truthy" checks and the more precise iterator types make it a worthwhile upgrade.

It's sometimes said that software dependencies obey a "reverse triangle inequality:" it's easier to go from v1→v2→v3 than it is to go from v1→v3 directly. The idea is that you can fix a smaller set of issues at a time. There's not much reason to hold off on adopting TypeScript 5.6. Doing so now will make upgrading to 5.7 easier in a few months.

Speaking of which, keep an eye on that release! I'm hoping that it will include the proposed enforceReadonly flag.

keyof (A&B) = (keyof A) | (keyof B) keyof (A|B) = (keyof A) & (keyof B)

If you can build an intuition for why these equations hold, you'll have come a long way toward understanding TypeScript's type system!

I'll explain these equations in a moment. But before I do, head over to the TypeScript Playground and test them out with a few types. See if you can build that intuition for why they hold.

I first saw these equations in Anders Hejlsberg's keynote at TSConf 2018 ("Higher order type equivalences" at 26m15s):

Anders' explanation at the talk was helpful, but I still had to stare at them for a long time before they clicked. But when they did, I felt like I'd had a real insight about how TypeScript types work.

The feedback on these equations in the book is typically that I need to explain them more. Some readers have even claimed they're wrong. (They're not!) By presenting them a bit cryptically, I wanted to give readers a chance to think through them and have an insight of their own.

With that out of the way, let's dig into why these equations hold, and why they're interesting.

We can start by plugging in concrete types for A and B:

interface NamedPoint {
  name: string;
  x: number;
  y: number;
}
interface Point3D {
  x: number;
  y: number;
  z: number;
}

What's NamedPoint & Point3D, the intersection of these two types? It's easy to think that it's an interface with just the common fields:

// This is _not_ the same as NamedPoint & Point3D!
interface CommonFields {
  x: number;
  y: number;
}

That's not what it is, though. To understand the intersection of these types, we need to think a little more about what values are assignable to each type. A NamedPoint is an object with three properties, name, x, and y, with the expected types:

const nyc: NamedPoint = {
  name: 'New York',
  x: -73,
  y: 40,
};

But a NamedPoint could have other properties, too. In particular it could have a z property:

const namedXYZ = {
  name: 'New York',
  x: -73,
  y: 40,
  z: 0,
};
const nycN: NamedPoint = namedXYZ; // ok!

(We have to go through an intermediate object to avoid excess property checking errors here. If you have a copy of Effective TypeScript, check out Item 11: Distinguish Excess Property Checking from Type Checking.)

There's nothing special about z. It could have other properties, too, and still be assignable to NamedPoint. For this reason, we sometimes say that TypeScript types are "open."

Of course, Point3D is open, too. It could also have other fields, including a name field:

const nycZ: Point3D = namedXYZ; // ok!

So namedXYZ is assignable to both NamedPoint and Point3D. And that is the very definition of an intersection. Sure enough, namedXYZ is assignable to the intersection of these types, too:

const nycZ: Point3D & NamedPoint = namedXYZ; // ok!

This gives us a hint about what the intersection looks like:

interface NamedPoint3D {
  name: string;
  x: number;
  y: number;
  z: number;
}

This type is also "open:" a NamedPoint3D might have more than these four fields. But it has to have at least these four.

To intersect these two types, we unioned their properties. We can see this in code using keyof:

type KN = {} & keyof NamedPoint;
//   ^? type KN = "name" | "x" | "y"
type K3 = {} & keyof Point3D;
//   ^? type K3 = "x" | "y" | "z"

type KI = keyof (NamedPoint & Point3D);
//   ^? type KI = "name" | "x" | "y" | "z"
type KU = (keyof NamedPoint) | (keyof Point3D)
//   ^? type KU = "name" | "x" | "y" | "z"

So keyof (A&B) = (keyof A) | (keyof B)!

(The weird {} & forces TypeScript to print out the results of keyof. I wish this weren't necessary.)

What about the other relationship, keyof (A|B)? keyof T will only include a property if TypeScript can be sure that it will be present on values assignable to T (with a caveat, see below).

Again, let's make this more concrete with some examples:

const nyc: NamedPoint = {
  name: 'New York',
  x: -73,
  y: 40,
};
const pythagoras: Point3D = {
  x: 3,
  y: 4,
  z: 5,
};

To be assignable to A|B, a value must be assignable to either A or B (or both!). So these values are both assignable to NamedPoint | Point3D:

const u1: NamedPoint | Point3D = nyc; // ok
const u2: NamedPoint | Point3D = pythagoras; // ok

Thinking about keyof, which properties belong to both those objects? It's just "x" and "y". And that's keyof for the union type:

type KU = keyof (NamedPoint | Point3D)
//   ^? type KU = "x" | "y"
type IK = (keyof NamedPoint) & (keyof Point3D)
//   ^? type IK = "x" | "y"

So keyof (A|B) = (keyof A) & (keyof B) and the equation holds.

Hopefully working through these examples with some concrete types makes the equations clearer. I really like them because they're concise but still manage to say a lot about how types work in TypeScript.

I mentioned one caveat, and it has to do with optional fields:

interface PartialPoint {
  x: number;
  y?: number;
}
type KP = {} & keyof PartialPoint;
//   ^? type KP = "x" | "y"
const justX: PartialPoint = { x: 10 };

justX is assignable to PartialPoint, but it doesn't have a y property, which you'd expect given the keyof.

Optional fields are a little strange when you think about types in a set-theoretic way. On the one hand, it's surprising that keyof PartialPoint includes "y" because values needn't have that property. On the other hand, it would be incredibly annoying if it didn't because keyof is so often used with mapped types, and you'd really like to map over all the fields, not just the required ones.

At the end of the day, what's the difference between these two types?

interface JustX {
  x: number;
}
interface XMaybeY {
  x: number;
  y?: unknown;
}

I'll cryptically say "not much!" and leave it at that!

The Advent of Code is a fun annual programming competition with an Elf theme. It consists of 25 two-part problems of increasing difficulty, released every day in December leading up to Christmas.

Every December, I complete it in a new programming language. Every January, I intend to blog about the experience. Usually this slips to March or April, but this year it's fallen all the way back to July! As excuses, I'll offer writing a book, participating in Recurse Center and implementing a cool new feature in TypeScript 5.5.

Here are the previous installments in this series:

• 2019: Python
• 2020: Rust
• 2021: Go
• 2022: TypeScript / Deno

Solving concrete problems is fun, and so is learning new languages. But this is also a good way to break out of the mental bubble of your primary language to see what else is out there. As Alan Perlis once said, "A language that doesn't affect the way you think about programming is not worth knowing."

Like many people in the JavaScript world, I learned about Zig because Bun, the new JavaScript runtime, is implemented in it. I read a little bit about the language, thought it sounded interesting, and decided to do the 2023 Advent of Code in it.

I didn't know that much about Zig going in. My mental model was that it was a "modernized C" to complement Rust's "modernized C++." Having used Zig for a bit, I wouldn't say that any more. It can be a fine C++ replacement, too. But first things first. What's Zig?

1. A very quick intro to Zig
2. What can TypeScript learn from Zig?
   1. Detectable Illegal Behavior
   2. comptime
3. What can Zig learn from TypeScript?
   1. Language Server
   2. Error Message Ergonomics
   3. Documentation
   4. Caveats
4. General impressions of Zig
5. Thoughts on this year's Advent of Code
6. Zig gotchas for JavaScript developers
7. Tips for doing the Advent of Code in Zig
8. Conclusions

A very quick intro to Zig

Zig is a low-level programming language that was first announced in 2016. It fills a similar niche to C: manual memory management, access to the bits of your data structures, compatible with C APIs, no object orientation.

C is a very old language, and some of its design choices haven't aged well. While a whole source file might not have fit into memory in 1970, that seems like a safe assumption in the 21st century. And the internet has made the cost of bugs like buffer overflows dramatically higher, since they're now security holes. Zig has a reasonable module system and it doesn't allow null pointers.

Zig also takes the opportunity to clean up and modernize lots of C syntax. One small example: in C, dereferencing a pointer is a prefix operation (*p), unless you're accessing a property (p->prop). In Zig, dereferencing is a postfix operation (p.*) and you always access properties with a dot (p.prop).

Zig also embraces best practices that have emerged over the past few decades: option types instead of null pointers, slices instead of null-terminated strings, type inference, built-in testing tools, UTF-8 source code, and a canonical code formatter.

Here's what Hello World looks like in Zig:

const std = @import("std");

pub fn main() void {
    std.debug.print("Hello, {s}!\n", .{"World"});
}

Beyond modernizing C, Zig introduces a few novel constructs of its own. We'll take a look at two of these and think about what they'd look like in the context of TypeScript.

What can TypeScript learn from Zig?

Programming language designers sometimes talk about their novelty budget: if you want developers to learn your language, you can only deviate so much from languages they already know. So best to think carefully about what these novelties will be, and make sure that they're high impact.

Two of Zig's most novel features are Detectable Illegal Behavior and comptime. These are both fantastic ideas, and it's interesting think about what they'd look like in TypeScript.

Detectable Illegal Behavior

The earlier we can catch errors, the less damage they cause, and the better off we'll be. You can imagine a hierarchy of bad behavior:

• Worst: Incorrect runtime behavior, producing a wrong answer, or even data corruption.
• Bad: Throwing an exception or crashing at runtime.
• Better: Failing a test
• Best: Detecting the bug through static analysis (a compiler error)

(You could add more levels to this hierarchy, e.g. unit tests, integration tests and manual QA tests.) Detection through static analysis is best because we detect the bug without ever having to run the broken code, and it can't do any damage!

Languages like C are notorious for the high consequences of mistakes. Coding errors can often turn into memory corruption or security issues. Zig's "detectable illegal behavior" is an interesting take on how to improve this. To see how it works, consider an integer overflow bug:

pub fn main() void {
    const a: u8 = 255 + 1;
    std.debug.print("255 + 1 = {d}!\n", .{a});
}

A u8 is an 8-bit unsigned integer. It can only represent values from 0 to 255. When you compile this, you'll get an error:

src/main.zig:4:23: error: type 'u8' cannot represent integer value '256'
    const a: u8 = 255 + 1;
                  ~~~~^~~

This is the best case scenario. A u8 can't represent 256 and Zig has detected this error statically.

If you make the error a little more subtle, though, the Zig compiler can't see it:

pub fn main() void {
    var a: u8 = 255;
    a += 1;
    std.debug.print("255 + 1 = {d}!\n", .{a});
}

What happens now is that you get a crash when you run the program:

$ zig run src/main.zig
thread 12826611 panic: integer overflow
src/main.zig:5:7: 0x10031a413 in main (main)
    a += 1;
      ^

Zig knows that integer addition can cause an overflow, so it inserts a check for this at runtime. If you overflow, you get a panic. Looking at our hierarchy of bad behavior, this is bad but it's saving us from the worst case scenario: incorrect behavior and chaos at runtime. This comes at a cost, though: because the check happens at runtime, it slows your program down. If this addition is happening in a tight loop, this can be a problem.

Zig lets you take off the safety wheels by changing your release mode:

$ zig run -O ReleaseFast src/main.zig
255 + 1 = 0!

Now the safety checks are off and the integer overflow is allowed to happen. There are many more examples of this sort of detectable illegal behavior in Zig, for example bounds checking on arrays. (Zig doesn't guarantee that this code will output 0. This is also known as "undefined behavior," and this flexibility gives Zig more opportunities for optimization.)

The interesting thing here is that there's an intermediate between detecting problems statically and not detecting them at all. As a fallback, we can detect a class of problems at runtime in debug builds.

What would this look like in TypeScript? JavaScript's approach to numbers means that integer overflows are uncommon. But array out-of-bounds access can certainly happen:

const letters = ['A', 'B', 'C'];
el.textContent = letters[3];  // no error, displays "undefined" at runtime.

TypeScript does not modify this code when it compiles to JavaScript. But you could imagine tsc compiling this to a sort of "debug build" that added bounds-checking:

const letters = ['A', 'B', 'C'];
el.textContent = _checkedAccess(letters, 3);  // throws at runtime

There's no static error, but at least this moves us one notch up the hierarchy of bad behavior.

It's instructive to compare Zig's behavior to TypeScript's noUncheckedIndexedAccess setting. Zig's approach is "trust but verify:" during static analysis, it assumes your code is correct and only reports an error if it's confident that it's not. But then it inserts checks to verify its assumption at runtime.

By contrast, TypeScript with noUncheckedIndexedAccess assumes your code is invalid unless it can prove otherwise. There's a presumption of incorrectness, but no runtime checks are added:

const letters = ['A', 'B', 'C'];
const c = letters[2];  // this is a _valid_ access, so the error is spurious
el.textContent = c.toUpperCase();
//               ~ 'c' is possibly 'undefined'.

One of the ways to convince TypeScript that your array access is valid is to add a bounds check yourself:

const letters = ['A', 'B', 'C'];
const c = letters[2];
if (c !== undefined) {
  el.textContent = c.toUpperCase();  // ok for type checking and at runtime
}

Inserting runtime checks would allow TypeScript to flip over to an "innocent unless proven guilty" model like Zig's, which would result in fewer false positives and make noUncheckedIndexedAccess easier to adopt.

This is just one instance of the broader issue of unsoundness. This is when a variable's TypeScript type doesn't match its runtime type. There are many ways this can happen, but a common one is a type assertion ("as"):

interface FunFact {
  fact: string;
  funLevel: number;
}
const response = await fetch('/api/fun-fact');
const fact = await response.json() as FunFact;

Does this API endpoint actually return a FunFact? The type assertion assures TypeScript that it does, but there's no reason this has to be the case at runtime. When this snippet is converted to JavaScript, it looks like this:

const response = await fetch('/api/fun-fact');
const fact = await response.json();

There are no checks performed on the response. TypeScript is just trusting us. But perhaps the API has changed or we had a miscommunication with the backend team. If the response is actually some other type, then we may get a runtime crash or display unsightly "undefined"s on the page.

There are various standard ways to solve this problem in TypeScript. But what if TypeScript were a little more like Zig? What if it had some notion of a debug build that produced JavaScript that looked more like this:

const response = await fetch('/api/fun-fact');
const fact = debugCheckType(await response.json(), RuntimeVersionOfFunFact);

This could be pervasive. For example, a function like this:

function repeat(message: string, times: number) {
  return Array(times).fill(message).join('\n');
}

might get compiled to this:

function repeat(message: string, times: number) {
  if (typeof message !== 'string') throw new Error();
  if (typeof message !== 'number') throw new Error();
  return Array(times).fill(message).join('\n');
}

You can imagine how this would improve type safety, but also slow down your code at runtime.

The Dart language does something like this to achieve a sound type system. It's interesting to think about what something similar would look like for TypeScript. I'm sure it would find lots of surprising sources of unsound types!

comptime

In Zig, you can use the comptime keyword to force a block of code to execute at compile time, rather than runtime:

fn fibonacci(n: u16) u16 {
    if (n == 0 or n == 1) return n;
    return fibonacci(n - 1) + fibonacci(n - 2);
}

pub fn main() void {
    const comp = comptime fibonacci(40);
    std.debug.print("comptime: {d}\n", .{comp});
    const run = fibonacci(40);
    std.debug.print("runtime: {d}\n", .{run});
}

If you build this and then run it, you'll see the first line print instantly, then a noticeable pause before the second line prints the same number. When Zig compiles this code, it becomes something more like this:

const comp = 102334155;
const run = fibonacci(40);

In the first line, the compiler has run the Fibonacci function.

comptime is a particularly powerful, unifying concept in Zig because you can also manipulate types at comptime. This is how Zig implements generic types:

// Closed interval parameterized on integer type
pub fn Interval(comptime IntType: type) type {
    return struct {
        low: IntType,
        high: IntType,

        pub fn includes(self: @This(), val: IntType) bool {
            return val >= self.low and val <= self.high;
        }
    }
}

const Int32Range = Interval(i32);

Notice how this is just an ordinary Zig function, written with all the usual syntax and constructs. It's a function from from one type to another. This is how we think about types in TypeScript (Item 50 of Effective TypeScript is called "Think of Generics as Functions Between Types"). But in Zig they really are functions between types. Notice on the last line how "instantiating" a generic type just involves calling the function and assigning the result to a variable.

Compare this to what you'd write in TypeScript:

interface Interval<T> {
  low: T;
  high: T;
  includes(val: T): boolean;
}

type NumInterval = Interval<number>;

TypeScript has two Turing-complete languages: JavaScript for the runtime, and TypeScript's type system for type manipulation. The two are quite different, and TypeScript developers have to learn a new language to write complex, type-level code. Moreover, as I argue in Item 58 of Effective TypeScript, it's not a particularly good language, and you should try to avoid doing too much heavy lifting in it lest you fall into the infamous Turing Tarpit.

Zig, by contrast, only has one language: Zig. To manipulate types, you just write Zig code. The only difference is that it has to be comptime. Manipulating the properties of a type doesn't require any new concepts like mapped types or conditional types. You just use a for loop and an if statement.

In my 2020 post TypeScript Splits the Atom and Item 54 of Effective TypeScript, I walk through how you can construct a generic type that takes a snake_cased object ({foo_bar: string}) and produces the corresponding camelCased object ({fooBar: string}). This requires a bunch of concepts from TypeScript's type system: generic types, template literal types, conditional types, mapped types, and infer. It's not simple, and it doesn't look at all like JavaScript.

Here's what it might look like if TypeScript had something like Zig's comptime:

// e.g. "foo_bar" -> "fooBar"
function camelCase(term: string) {
  return term.replace(/_([a-z])/g, m => m[1].toUpperCase());
}

// Not real TypeScript, just imagining!
function ObjectToCamel(comptime type T extends object) type {
  interface Result {}
  for (const [k, v] of Object.entries(T)) {
    Result[camelCase(k)] = v;
  }
  return Result;
}

function objectToCamel<T extends object>(obj: T): ObjectToCamel(T) {
  const out: any = {};
  for (const [k, v] of Object.entries(obj)) {
    out[camelCase(k)] = v;
  }
  return out;
}

This is just a sketch, but it's satisfying to see how the code for manipulating the types and the code for manipulating the values are nearly identical. Even better, they both call the same camelCase function, so you know the type and value transformations will stay in sync and have identical edge case behaviors.

Type-level TypeScript is written in a different language and runs in the type checker. comptime Zig is still Zig, it just runs at a different time.

comptime is useful beyond type manipulation. I was afraid to look at the source code for std.fmt.format because I assumed it would involve some completely inscrutable metaprogramming. But it's actually pretty simple! The format string must be comptime known, and the formatting function just runs a for loop over it.

Using the same language for programming and metaprogramming seems like a great idea (see: Lisp macros). Are there any downsides? I can think of two: performance and inference.

• Performance: comptime isn't free. Your code still has to be run at some point. Zig doesn't have a very built-out language server (more on that shortly), but TypeScript does. It potentially has to run your type level code on every keystroke as you type in your text editor. To avoid bogging down or hanging, TypeScript sets some strict limits on how deeply recursive your type-level code can be. If your type-level code was written in JavaScript, it would much harder to enforce these limits in any systematic way. Timeouts aren't really an option in a compiler: you don't want the validity of code to depend on the developer's CPU speed.

• Inference: When it's inferring types, there are situations where TypeScript needs to run your type-level code in reverse. Type-level operations were built with inference in mind, but inverting an arbitrary snippet of JavaScript code isn't possible.

Here's a simple example of how this can happen:

type Box<T> = { value: T };
declare function unbox<T>(box: Box<T>): T;

const num = unbox({value: 12});
//    ^? const num: number

Here Box maps T → {value: T}, but on the last line TypeScript has to go from {value: number} → number to infer T. This even works with conditional types.

These are both serious issues. In practice I'd hope that caching could mitigate many of the performance concerns. And, to be honest, I'd be fine losing this form of type inference if it meant that we could manipulate types in plain old JavaScript!

To be clear, these would be radical changes to TypeScript and I don't expect anything like them to happen. But you could imagine building an alternative TypeScript to JavaScript emitter that inserted runtime type checks. (We could call it… DefinitelyTyped! 😜) And if an aspiring language designer wants to build the next great flavor of typed JavaScript, including a comptime construct would be a great way to differentiate from TypeScript.

What can Zig learn from TypeScript?

Flipping the question around, what are some good ideas from TypeScript that Zig might adopt?

My main suggestion would be to focus more on developer experience. To me, this means a few things:

1. Language server
2. Error message ergonomics
3. Documentation

Language Server

When you install TypeScript in a project, you get two binaries:

1. tsc, the TypeScript Compiler
2. tsserver, the TypeScript Language Server

It's pretty rare to run tsserver directly, but if you use VS Code or another editor that supports the language service protocol, you're interacting with it all the time. The TypeScript team treats these binaries as equally important. Every new language feature is supported by the language server on day one. And the release notes for TypeScript versions include things like new Quick Fixes, which you might not think of as being core to the language itself.

There is a language server available for Zig, zls. It's a third-party tool, though, and while an enormous amount of work has gone into it, it has a lot of issues. It provides syntax highlighting and some language service features like go-to-definition. It reports superficial errors like syntax errors and unused variables, but it quickly gets lost with anything much beyond that.

Some of the errors that it fails to report are surprising:

It should be print, not prin.

It's pretty disorienting to see no errors in your editor, only to have lots of them when you build from the command line. (See below for how to improve this.) The language server also hangs a lot. It was quite rare for me to solve an Advent of Code problem without having to restart zls.

Apparently gripes about zls are common in the Zig community, so this may not come as much of a surprise. Andrew Kelley talks about this a bit in the context of the 2024 Zig Roadmap. He thinks a first-party language server will happen eventually, but it's not a priority. He also mentions that he uses vim and does not use a language server, so a first-party language server would not benefit him personally.

I think this may be a cultural thing. I used to use vim 15 years go when I worked primarily in C++, and I also didn't use a language server. There wasn't much point. C++ is nearly impossible to parse, let alone analyze. It was only when I started working in TypeScript and switched to VS Code that I saw the light. Language servers are great, and it's hard to go back once you're used to them.

A language server changes your relationship with the language. A command-line compiler is all about looking over your code and telling you where you've made mistakes. A language server is like a partner that's right there in your editor with you, helping you to get things right. It's hard to underestimate how valuable a good language server is when you're coming up to speed on a new language. It lets you quickly experiment and develop an intuition for how types work and what errors result from your changes. A better zls would have greatly improved my experience with Zig.

Let's all hope Andrew works on a TypeScript side project someday and has a language server conversion experience. May I suggest the 2024 Advent of Code? 😀

Error Message Ergonomics

The user interface of a compiler consists mostly of the errors that it presents to you. So the way those error messages are presented has a huge impact on your experience of using the language. The TypeScript team takes this extremely seriously. There's an entire GitHub Issue Label for error messages, and many releases include improvements in error reporting.

Even more fundamental than messaging, though, is attribution. I ran into at least three cases during the Advent of Code where an error was correctly reported, but in the wrong place. This makes for an incredibly confusing experience, particularly when you're learning a new language and aren't very confident about how you're using it.

When I updated to Zig 0.13 for this post, I was happy to see that 2/3 of these misattributions had been fixed. The third issue was that calling std.debug.print with the wrong number of arguments doesn't include the relevant line number in the error message. I filed an issue about this in January. A fix was quickly posted, but it was rejected by Andrew Kelley, Zig's creator, as too hacky.

I have tremendous respect for Andrew's willingness to hold out for a better solution. Language designers need to do this to avoid bigger problems down the road. But I do hope this issue gets fixed, because missing locations on error messages is a truly terrible, disorienting user experience.

Here was another sort of error that tripped me up a few times:

const values = std.AutoHashMap(Point, u32);
defer values.deinit();
try values.put(Point{ .x = 0, .y = 0 }, 1);
//  ~~~~~~^~~~ error: expected 3 argument(s), found 2

The mistake here isn't on that line, and it doesn't have to do with the number of arguments. Rather, it's that I forgot to call .init() on the hash map:

var values = std.AutoHashMap(Point, u32).init(allocator);
defer values.deinit();
try values.put(Point{ .x = 0, .y = 0 }, 1);

I also found Zig pointer types to be pretty hard to read in error messages.

Documentation

Microsoft publishes an official TypeScript Handbook. When it launched in 2021, it was given as much attention and fanfare as the release of a new version of TypeScript itself.

I primarily used ziglearn.org to come up to speed, which is now zig.guide. There's a lot of content there, but I found it had quite a few gaps. For example, the documentation on build.zig is quite sparse, and it didn't give me much insight into how to set up a 25-day Advent of Code project (One binary? 25?). (Update: there's now an official docs page and a community forum post.)

I was surprised that Zig didn't have a toString() convention. Twenty days into the 2023 Advent of Code, I learned that it did (pub fn format) from reading the standard library source code. As it turns out, this does appear in one example in the docs on formatting, but I'd expect this to be given more front-and-center treatment since it's so useful any time you define a data structure.

Caveats

After sharing a draft of this post, I learned that's it's possible to get zls to display all compile-time errors using the buildOnSave feature. Here's a commit where I added it to my repo. I wish I'd known about this last December, it would have greatly improved my Zig experience!

And despite my grumblings about some aspects of developer experience, Zig may be making the correct tradeoffs. Why? It's still an early-stage language whose design is in flux. This is reflected not just in the version number (pre-1.0!) but also in its development: a recent release removed an existing async/await feature while they think about a better design. It's hard to imagine TypeScript doing something like that. If you expect the language to make major changes before 1.0, then building out a language server now will create more work down the road.

On the other hand, if the Zig team built out a language server now, they might gain valuable insights about which language features work well with it and which ones don't. This could inform the future design of the language. There's an assumption that a high-quality language service can be built after the language design is stabilized, but this might not be the case. It's a gamble!

Of course, another big difference between TypeScript and Zig is that Microsoft's annual revenue is nearly 500,000 times greater than the Zig Foundation's. This means that the Zig team needs to make harder choices about prioritization. Their top four goals are currently performance, language improvements, standard library improvements, and a formal language specification. It's hard to argue with the focus on build speed (Advent of Code solutions aren't big enough for this to be an issue), and that will definitely be a boon for developer experience. But I'd love to see other forms of DX move up that list. For what it's worth, TypeScript's experience with formal specification is that it's not worthwhile. A formal spec was released in 2014 and has been gathering dust ever since.

✨ Many thanks to the Zig Forum for feedback on this section.

General impressions of Zig

Those issues aside, I wound up really liking Zig! Given a choice, I'd strongly prefer it to C for a new project. I also found it easier to work in than Rust.

Zig advertises "No hidden control flow" and "No hidden memory allocations." I incorrectly read the latter to also mean "no hidden copying," and this led to a lot of confusion at first. For example:

const Box = struct {
    val: u32,
};

var a: Box = .{ .val = 1 };
var b = a;
b.val = 2;
std.debug.print("a: {} b: {}\n", .{ a, b });

In JavaScript, Python, or Java, var b = a would create a new reference to the same underlying object and this would print two 2s.

In Zig (as in C++ and Go), var b = a creates a copy of the struct and you get two different values:

a: main.Box{ .val = 1 } b: main.Box{ .val = 2 }

Zig implicitly copies data all the time. Sometimes this can be subtle. If you return a struct from a function, it may be copied. A slice is a struct with a len and a ptr, and these are copied when you assign to a slice (the pointer is copied, not the thing it points to). Understanding implicit copying and building a mental model for it was the key insight that made me feel comfortable programming in Zig. I had a similar insight about Go back in 2021.

As I mentioned above, I really liked comptime. It's a clever, unifying idea. I hope more languages adopt something like this in the future.

Just like C, Zig doesn't have classes or inheritance, but it does have structs. Unlike in C, a Zig struct can have methods defined on it and it can be generic. This feels a lot like C with Classes. Unless you're making heavy use of inheritance (and why would you be?), this means that Zig can also fill many of the same niches as C++. It's interesting that structs can have private functions but not private fields. I guess this makes some sense since you have to be able to copy the bytes of a struct to use it.

Most Advent of Code problems start with reading a text file (your puzzle input). The standard way to read a file line-by-line is a bit verbose:

var file = try std.fs.cwd().openFile("foo.txt", .{});
defer file.close();

var buf_reader = std.io.bufferedReader(file.reader());
var in_stream = buf_reader.reader();

var buf: [1024]u8 = undefined;
while (try in_stream.readUntilDelimiterOrEof(&buf, '\n')) |line| {
    // do something with line...
}

I thought it would be an interesting exercise to factor this out into a helper function. This wound up being dramatically harder than I expected. With some help from Stack Overflow and the Zig Forum, I was eventually able to come up with a solution. But the broader point from the forum was that maybe factoring this out isn't worth the hassle in Zig, because it's easier to see how all the pieces fit together with the explicit code, and to see what constants you're assuming (1024 and \n).

I eventually found another reason to avoid this pattern: if you read the entire input into a single buffer (rather than line by line), then you can assume this memory is available throughout execution and reference slices of it without having to think about ownership. This is particularly nice if you're putting them in a StringHashMap, which does not take responsibility for ownership of its keys.

Zig has a distinctive way of handling errors: it introduces special syntax (error!type) for something that can be either an error or a success value. Typically the error type can be inferred:

fn foo() !u32 {
  const a = try otherFunctionThatMightFail();
  return a + 1;
}

The try keyword checks if the other call returns an error and passes it on up the call chain. The possible error types that foo() returns will be the same as the other function. If foo() had returned u32 instead, then it would have needed to handle the error case itself.

I didn't wind up having very strong feelings about this feature. I almost always allowed error types to be inferred, so the only difference between this and JavaScript-style exceptions is that there were more trys. Remember, no hidden control flow. It wasn't obvious to me why some failure modes (out of memory) are handled with explicit errors, while others (integer overflow) are handled via detectable illegal behavior. (See this comment for an explanation.)

Whether a function can fail affects the way you call it, and this can be seen as an interesting nudge. Error-returning functions must be called with try, catch, or some other error-handling construct. Because you're constantly writing try, you're always aware of which type of function you're working with. This makes you prefer calling functions that can't fail. Since memory allocation can fail, this pushes you to write functions that don't allocate memory. Usually this means taking a buffer as an argument, or allocating one internally. And this is generally a more efficient design.

Another interesting choice is to not allow function closures. Instead, higher-level Zig functions like std.mem.sort take a context object that's passed to the comparison function. I believe this is equivalent in power to closures, it just requires the tedium of defining a context data type and populating it. This makes you aware of the context that you're capturing, and encourages you to capture as little as possible.

It's worth remembering that the Advent of Code tends to highlight specific aspects of a language, and these puzzles may not be the sorts of problems that the language is designed to solve. There were large parts of Zig that I never interacted with, for example its SIMD support or its C API. Zig is a great language for targeting WASM, but I never needed to do this.

A few other quick notes:

• An Arena allocator has some similarities to Rust-style lifetime annotations. Rather than tying the lifetimes of two values together, you connect them both to a moment in time during execution.
• Zig recently added destructuring assignment for tuples. This is great, but I wish it supported a similar syntax for structs, just like JavaScript, to encourage consistent naming. This would be particularly handy for imports. It's unlikely to happen, though.
• Payload capturing is ubiquitous and felt pretty intuitive. I just wish it worked better with the language server.
• Sentinel termination feels like a trivial generalization of null termination. Are there ever situations where you want to terminate a slice with anything other than a 0? (See discussion.)
• Zig does a pretty good job of inferring types where it can. The various integer types make this a harder problem than it is in TypeScript, though.
• I found the many, sight variations on pointer syntax quite hard to read and get comfortable with, particularly in error messages:
  • *T: pointer to a single item
  • [*]T: pointer to many (unknown number) of items
  • *[N]T: pointer to an array of N items
  • [*:x]T: pointer to a number of items determined by a sentinel
  • []T: slice, has a pointer of type [*]T and a len.

Thoughts on this year's Advent of Code

I completed the 2017 Advent of Code in Zig as a warmup, then did the 2023 Advent of Code as problems came out each day.

This made for quite a contrast. The 2017 Advent of Code was very, very easy (my notes are here). The 2023 Advent of Code was quite hard. Even day 1 had potential for trouble. Some of the problem setups were quite convoluted. There's been speculation that this was an attempt to thwart AI solvers. Whether or not it succeeded, it certainly led to some tedious code.

I learned about a few new things this year:

• Pick's Theorem relates the area of a polygon with integer vertices to the number of integer points inside the polygon.
• The Shoelace Formula is the standard way to find the area of a simple polygon.
• A Nonogram, aka Paint by Numbers, is a type of logic puzzle.
• sympy is a Python library for symbolic manipulation / computer algebra.

Notes on a few specific problems (spoiler alert!):

• Day 20: This one was super frustrating. I had the right idea for part 2, but I used an online LCM calculator and mistyped a number, leading to the wrong result. I wasted over an hour before realizing the mistake. Note to self: always copy/paste numbers, never type them!
• Day 21: I solved this by plugging numbers into a spreadsheet and looking for a pattern, even without fully understanding it. Judging by my finish number (#4624 at 11 AM Eastern), this was the hardest problem of the year.
• Day 24: I completed part 1 before going to a family Christmas. I had part 2 in the back of my head all day, and I was pretty sure I had the solution all figured out. I just needed to code it. When I got home, I realized that the sample input and my puzzle input were very different, and my idea wouldn't work at all. I wound up spending an enormous amount of time solving the equations, largely by hand. I was a bit disappointed that most people just plugged them into sympy to get a solution without any understanding. sympy does look cool, though!
• Day 25: My turn to use a Python library without understanding what I'm doing. I gave up on Zig and plugged in NetworkX. The k_edge_components method solves this problem. I did eventually wind up porting my solution to Zig.

Zig gotchas for JavaScript developers

Zig is a much lower-level language than JavaScript. If you haven't previously worked in a language with manual memory management, pointers, or a non-primitive string type, it's going to have a steep learning curve.

That being said, Zig has a few keywords that also exist in JavaScript, but mean completely different things. Watch out for these false friends:

• var and const: These are not analogous to var/let and const in JavaScript. In JavaScript, const is shallow. It just means that you can't reassign the variable. Some people don't like it. Zig's const is much stronger. If you declare a variable with const, you can't mutate it or call any methods that might mutate it. It's a deep const. Seeing var in JS should make you flinch because of its weird hoisting semantics. But Zig doesn't have that historical baggage. var is a great term for something that varies.
• try and catch: In JavaScript (and C++, Java, and many other languages), these are used to construct try {} catch (e) {} blocks. In Zig, they're more like operators on expressions. try f() calls f, checks if it returns an error, and returns that error if it does. catch is used to provide fallback values: f() catch val resolves to val if f returns an error.
• null and undefined: JavaScript finally has company: another language that has both null and undefined! These have pretty specific meanings in Zig, though. null is used exclusively with optional types. undefined is special: it's not a value; instead it means that you don't want to initialize the value. Generally you want to avoid this since you'll get garbage at runtime.
• for and while: Zig's for loop is quite limited. You can iterate over a slice or a range with it, and that's about it. For everything else, including iterators and C-style for(;;) loops, you use a while loop.
• || and or: In JavaScript (and C), || is logical or. Like Python, Zig spells that or instead. Fair enough. What's really confusing, though, is that Zig also has a || operator that does something totally different. It unions two error sets, more akin to TypeScript's type-level |. I never used ||.
• Zig has a switch statement but it works a bit differently than JavaScript's. It's more powerful, doesn't have fall-through, and must be exhaustive.
• Zig uses a different syntax for object literals: .{ .x=1, .y=2 } instead of { x: 1, y: 2 }. I screwed this up countless times, and so will you.
• Zig also has tagged unions but they're a little more constrained than TypeScript's.

Zig is still a relatively niche language and ChatGPT is going to have more trouble helping you write it than it would with JavaScript.

Tips for doing the Advent of Code in Zig

Various other blogs have mentioned struggling to do AoC in Zig. For the most part, I didn't find it to be too bad. If you decide to try it, good luck! Feel free to use my repo as a template and guide.

Here are a few specific tips:

• Zig doesn't have a scanf equivalent and regexes are inconvenient. So for parsing inputs, it's split, split, split. I wound up factoring out a few splitIntoBuf and extractIntsIntoBuf helpers that made short work of reading the input for most of the problems.
• Zig supports all sizes of ints, all the way up to u65536. If you're getting overflows, try using a bigger integer type. I used u128 and i128 on a few problems.
• std.meta.stringToEnum is a neat trick for parsing a restricted set of strings or characters.
• As mentioned above, you can define a format method on your structs to make them print however you like.
• Try to avoid copying strings to use as keys in a StringHashMap. This feels natural coming from JS, but it's awkward in Zig because you need to keep track of those strings to free them later. If you can put your keys into a struct or a tuple, that will work better because they have value semantics. If you need strings, you might be able to use slices of your puzzle input, as described above.
• Watch out for off-by-one bugs with numeric ranges. If you want to include max, it's min..(max+1), not min..max.
• Your code is going to have a lot of @intCast. It's OK.
• I found it odd that Zig has a built-in PriorityQueue but no built-in Queue. I wound up finding one online that I could paste into my repo. (Update: use std.SinglyLinkedList)
• A lot of the functions you use to work with strings are in std.mem, e.g. std.mem.eql and std.mem.startsWith.
• Use std.meta.eql to compare structs, not ==.
• There's a trick for slicing by offset and length: array[start..][0..length].
• It's often useful to memoize a function in Advent of Code. I have no idea if there's a general way to do this in Zig. (This led me to a unique solution that I was proud of on day 12.)
• Debug build are considerably slower than optimized builds, sometimes 10x. If you're within a factor of 10 of getting an answer in a reasonable amount of time, try a different release mode.
• Don't mutate an ArrayList as you iterate through it. You might change what .items refers to, which will lead to chaos.
• You may need to factor out a variable to clarify lifetimes in some situations where JavaScript would let you inline an expression. See this issue.

Here are a few other blog posts I found helpful in learning Zig for Advent of Code:

• Zig Quirks
• Zig's Curious Multi-Sequence For Loops
• Zig Cookbook

Conclusions

I thoroughly enjoyed doing the Advent of Code and I enjoyed learning Zig in the process. Zig and TypeScript occupy different niches and have different goals, but there are still a few things they can learn from each other.

There's less than five months until the 2024 Advent of Code starts! Which language will I use this year? After learning a bunch about programming languages at Recurse Center this winter, I'm thinking that I should just bite the bullet and use Haskell. We'll see how I feel about that in December!

TypeScript's motto is "JavaScript with syntax for types." New versions of TypeScript don't add new runtime features (that's JavaScript's responsibility). Rather, they make changes within the type system. These tend to take a few forms:

1. New ways of expressing and relating types (e.g., template literal types in TypeScript 4.1)
2. Increased precision in type checking and inference
3. Improvements to language services (e.g., a new quick fix)
4. Support for new ECMAScript standards
5. Performance improvements.

TypeScript 5.5 doesn't introduce any new type syntax, but it does include all the other kinds of changes. The official release notes have complete explanations and examples. What follows is my quick take on each of the major changes. After that we'll look at new errors and test some of the performance wins.

New Features

Inferred Type Predicates

This was my contribution to TypeScript, and I'm very happy that it's made it into an official release! I've written about it extensively on this blog before, so I won't go into too much more detail here:

• The Making of a TypeScript Feature: Inferring Type Predicates
• Flow Nodes: How Type Inference Is Implemented
• The Hidden Side of Type Predicates

Dimitri from Michigan TypeScript even recorded a video of me explaining the story of the feature to him and Josh Goldberg.

TypeScript will infer type predicates for any function where it's appropriate, but I think this will be most useful for arrow functions, the original motivator for this change:

const nums = [1, 2, 3, null];
//    ^? const nums: (number | null)[]
const onlyNums = nums.filter(n => n !== null);
//    ^? const onlyNums: number[]
//    Was (number | null)[] before TS 5.5!

I have two follow-on PRs to expand this feature to functions with multiple return statements and to infer assertion predicates (e.g., (x: string): asserts x is string). I think these would both be nice wins, but it's unclear whether they have a future since the pain points they address are much less common.

Control Flow Narrowing for Constant Indexed Accesses

This is a nice example of improved precision in type checking. Here's the motivating example:

function f1(obj: Record<string, unknown>, key: string) {
  if (typeof obj[key] === "string") {
    // Now okay, previously was error
    obj[key].toUpperCase();
  }
}

Previously this would only work for constant property accesses like obj.prop. It's undeniable that this is a win in terms of precision in type checking, but I think I'll keep using the standard workaround: factoring out a variable.

function f1(obj: Record<string, unknown>, key: string) {
  const val = obj[key];
  if (typeof val === "string") {
    val.toUpperCase();  // this has always worked!
  }
}

This reduces duplication in the code and avoids a double lookup at runtime. It also gives you an opportunity to give the variable a meaningful name, which will make your code easier to read.

Where I can see myself appreciating this is in single expression arrow functions, where you can't introduce a variable:

keys.map(k => typeof obj[k] === 'string' ? Number(obj[k]) : obj[k])

Regular Expression Syntax Checking

Regular Expressions may be the most common domain-specific language in computing. Previous versions of TypeScript ignored everything inside a /regex/ literal, but now they'll be checked for a few types of errors:

• syntax errors
• invalid backreferences to invalid named and numbered captures
• Using features that aren't available in your target ECMAScript version.

Regexes are notoriously cryptic and hard to debug (this online playground is handy), so anything TypeScript can do to improve the experience of writing them is appreciated.

Since the regular expressions in existing code bases have presumably been tested, you're most likely to run into the third error when you upgrade to TS 5.5. ES2018 added a bunch of new regex features like the /s modifier. If you're using them, but don't have your target set to ES2018 or later, you'll get an error. The fix is most likely to increase your target. The /s (dotAll) flag, in particular, is widely supported in browsers and has been available since Node.js since version 8 (2018). The general rule here is to create an accurate model of your environment, as described in Item 76 of Effective TypeScript.

Regex type checking is a welcome new frontier for TypeScript. I'm intrigued by the possibility that is a small step towards accurately typing the callback form of String.prototype.replace, JavaScript's most notoriously un-type friendly function:

"str".replace(/foo(bar)baz/, (match, capture) => capture);
//                                   ^?  (parameter) capture: any

Support for New ECMAScript Set Methods

When you have two sets, it's pretty natural to want to find the intersection, union and difference between them. It's always been surprising to me that JavaScript Sets didn't have this ability built in. Now they do!

While these new methods are stage 4, they haven't been included in any official ECMAScript release yet. (They'll probably be in ES2025.) That means that, to use them in TypeScript, you'll either need to set your target or lib to ESNext. Support for these methods is at around 80% in browsers at the moment, and requires Node.js 22 on the server, so use with caution or include a polyfill.

Isolated Declarations

The isolatedDeclarations setting opens a new front in the should you annotate your return types? debate. The primary motivator here is build speed for very large TypeScript projects. Adopting this feature won't give you a faster build, at least not yet. But it's a foundation for more things to come. If you'd like to understand this feature, I'd highly recommend watching Titian's TS Congress 2023 talk: Faster TypeScript builds with --isolatedDeclarations.

Should you enable this feature? Probably not, at least not yet. An exception might be if you use the explicit-function-return-type rule from typescript-eslint. In that case, switching to isolatedDeclarations will require explicit return type annotations only for your public API, where it's a clearer win.

I expect there will be lots more development around this feature in subsequent versions of TypeScript. I'll also just note that isolatedDeclarations had a funny merge conflict with inferred type predicates. All these new feature are developed independently, which makes it hard to anticipate the ways they'll interact together.

Performance and Size Optimizations

I sometimes like to ask: would you rather have a new feature or a performance win? In this case we get both!

Inferring type predicates does incur a performance hit. In some extreme cases it can be a significant one, but it's typically a 1-2% slowdown. The TypeScript team decided that this was a price they were willing to pay for the feature.

TypeScript 5.5 also includes a whole host of other performance improvements, though, so the net effect is a positive one. You get your feature and your performance, too.

Monomorphization has been an ongoing saga in TypeScript. This is a "death by a thousand cuts" sort of performance problem, which is hard to diagnose because it doesn't show up clearly in profiles. Monomorphization makes all property accesses on objects faster. Because there are so many of these, the net effect can be large.

One of the things we like about objects in JavaScript and TypeScript is that they don't have to fit into neat hierarchies like in Java or C#. But monomorphization is a push towards exactly these sorts of strict hierarchies. It's interesting to see this motivated by performance, rather than design considerations. If anyone tries to translate tsc to the JVM, say, this will help.

I was particularly happy with control flow graph simplifications, since the PR included a screenshot of the TS AST Viewer graph that I built!

These optimizations affect build times, the language service, and TypeScript API consumers. The TS team uses a set of benchmarks based on real projects, including TypeScript itself, to measure performance. I compared TypeScript 5.4 and 5.5 on a few of my own projects in a less scientifically rigorous way:

• Verifying the 934 code samples in the second edition of Effective TypeScript using literate-ts, which uses the TypeScript API, went from 347→352s. So minimal change, or maybe a slight degradation.
• Type checking times (tsc --noEmit) were unaffected across all the projects I checked.
• The time to run webpack on a project that uses ts-loader went from ~43→42s, which is a ~2% speedup.

So no dramatic changes for my projects, but your mileage may vary. If you're seeing big improvements (or regressions), let me know! (If you're seeing regressions, you should probably file a bug against TypeScript.)

Miscellaneous

• Editor and Watch-Mode Reliability Improvements: These are grungy quality of life improvements, and we should be grateful that the TypeScript team pays attention to them.
• Easier API Consumption from ECMAScript Modules: I'd always wondered why you couldn't import "typescript" like other modules. Now you can!
• Simplified Reference Directive Declaration Emit: A weird, dusty corner that no longer exists. Yay!

New Errors

Most of my TypeScript projects had no new errors after I updated to TS 5.5. The only exception was needing to update my target to ES2018 to get the /s regular expression flag, as described above.

Both Bloomberg and Google have posted GitHub issues describing the new errors they ran into while upgrading to TS 5.5. Neither of them ran into major issues.

Conclusions

Every new release of TypeScript is exciting, but the combination of new forms of type inference, isolatedDeclarations, and potential performance wins make this a particularly good one.

It's sometimes said that software dependencies obey a "reverse triangle inequality:" it's easier to go from v1→v2→v3 than it is to go from v1→v3 directly. The idea is that you can fix a smaller set of issues at a time. There's not much reason to hold off on adopting TypeScript 5.5. Doing so now will make upgrading to 5.6 easier in a few months.

JavaScript's string split method is a handy way to break a string around a delimiter:

> 'abcde'.split('c')[ 'ab', 'de' ] 

Let's write something like split, but for arrays. Here's an attempt:

function splitAround<T>(vals: readonly T[], val: T): [T[], T[]] {
  const index = vals.indexOf(val);
  return [vals.slice(0, index), vals.slice(index+1)];
}

This works as you'd expect:

> splitAround([1, 2, 3, 4, 5], 3)[ [ 1, 2 ], [ 4, 5 ] ]

If you try to splitAround an element that's not in the list, however, it does something quite unexpected:

> splitAround([1, 2, 3, 4, 5], 6)[ [ 1, 2, 3, 4 ], [ 1, 2, 3, 4, 5 ] ]

While it's not entirely clear what the function should do in this case, it's definitely not that! How did such simple code result in such strange behavior?

The root issue is that indexOf returns -1 if it can't find the element in the array. This is a special value: it indicates a failure rather than success. But -1 is just an ordinary number. You can pass it to the Array slice method and you can do arithmetic on it. When you pass a negative number to slice, it interprets it as counting back from the end of the array. And when you add 1 to -1, you get 0. So this evaluates as:

[vals.slice(0, -1), vals.slice(0)]

The first slice returns all but the last element of the array, and the second slice returns a complete copy of the array.

This behavior is a bug. Moreover, it's unfortunate that TypeScript wasn't able to help us find this problem. The root issue was that indexOf returned -1 when it couldn't find the element, rather than, say null. Why is that?

Without hopping in a time machine and visiting the Netscape offices in 1995, it's hard to know the answer for sure. But we can speculate! JavaScript was heavily influenced by Java, and its indexOf has this same behavior. In Java (and C), a function can't return a primitive or null. Only objects (or pointers) are nullable. So this behavior may derive from a technical limitation in Java that JavaScript does not share.

In JavaScript (and TypeScript), there's no problem having a function return a number or null. So we can wrap indexOf:

function safeIndexOf<T>(vals: readonly T[], val: T): number | null {
  const index = vals.indexOf(val);
  return index === -1 ? null : index;
}

If we plug that into our original definition of splitAround, we immediately get two type errors:

function splitAround<T>(vals: readonly T[], val: T): [T[], T[]] {
  const index = safeIndexOf(vals, val);
  return [vals.slice(0, index), vals.slice(index+1)];
  //                    ~~~~~              ~~~~~ 'index' is possibly 'null'
}

This is exactly what we want! There are always two cases to consider with indexOf. With the built-in version, TypeScript can't distinguish them, but with the wrapped version, it can. And it sees here that we've only considered the case where the array contained the value.

The solution is to handle the other case explicitly:

function splitAround<T>(vals: readonly T[], val: T): [T[], T[]] {
  const index = safeIndexOf(vals, val);
  if (index === null) {
    return [[...vals], []];
  }
  return [vals.slice(0, index), vals.slice(index+1)];  // ok
}

Whether this is the right behavior is debatable, but at least TypeScript has forced us to have that debate!

The root problem with the first implementation was that indexOf had two distinct cases, but the return value in the special case (-1) had the same type as the return value in the regular case (number). This meant that from TypeScript's perspective there was just a single case, and it wasn't able to detect that we didn't check for -1.

This situation comes up frequently when you're designing types. Perhaps you have a type for describing merchandise:

interface Product {
  title: string;
  priceDollars: number;
}

Then you realize that some products have an unknown price. Making this field optional or changing it to number|null might require a migration and lots of code changes, so instead you introduce a special value:

interface Product {
  title: string;
  /** Price of the product in dollars, or -1 if price is unknown */
  priceDollars: number;
}

You ship it to production. A week later your boss is irate and wants to know why you've been crediting money to customer cards. Your team works to roll back the change and you're tasked with writing the postmortem. In retrospect, it would have been much easier to deal with those type errors!

Choosing in-domain special values like -1, 0, or "" is similar in spirit to turning off strictNullChecks. When strictNullChecks is off, you can assign null or undefined to any type:

// @strictNullChecks: false
const truck: Product = {
  title: 'Tesla Cybertruck',
  priceDollars: null,  // ok
};

This lets a huge class of bugs slip through the type checker because TypeScript doesn't distinguish between number and number|null. null is a valid value in all types. When you enable strictNullChecks, TypeScript does distinguish between these types and it's able to detect a whole host of new problems. When you choose an in-domain special value like -1, you're effectively carving out a non-strict niche in your types. Expedient, yes, but ultimately not the best choice.

null and undefined may not always be the right way to represent special cases since their exact meaning may be context dependent. If you're modeling the state of a network request, for example, it would be a bad idea to use null to mean an error state and undefined to mean a pending state. Better to use a tagged union to represent these special states more explicitly.

Things to Remember

• Avoid special values that are assignable to regular values in a type. They will reduce TypeScript's ability to find bugs in your code.
• Prefer null or undefined as a special value instead of 0, -1, or "".
• Consider using a tagged union rather than null or undefined if the meaning of those values isn't clear.

You can buy a copy at all the usual places:

• Amazon
• Amazon eBook (Kindle)
• DRM-free eBook (ebooks.com)
• Read online (O'Reilly)

If you'd like to read it online, you can get a free month of access to the O'Reilly online platform using promo code ETYPESCRIPT24 (valid until the end of 2024).

The book has been thoroughly revised and expanded to reflect how TypeScript is used in 2024. You can find full release notes on the book's GitHub page, but here are the highlights:

• Two new chapters: one on Generics and Type-Level Programming and one on TypeScript Recipes
• 24 new items (one item from the first edition was dropped)
• Coverage of new TypeScript features like template literal types and recursive type aliases.

TypeScript has changed and grown since 2019 and so has Effective TypeScript: it's 50% thicker!

If you enjoyed the first edition or use it as a reference, you'll be happy to update to the second. If you haven't read it yet, now's the perfect time to pick up a copy.

If you'd like me to come give a talk at your company, please get in touch. For a preview, check out the talk I gave at Etsy in 2020.

This is not a short read, but it will give you a good sense of what it's like to become a TypeScript contributor and develop a new feature.

If you're new to the Effective TypeScript blog, consider subscribing or buying a copy of the book. You can find a list of all the posts on this blog here.

If you prefer videos, Dimitri from Michigan TypeScript recorded an interview where we talk through the making of this feature. It's about 70 minutes, and it's a fun watch if I say so myself!

What is Type Predicate Inference?

Before we dive into the backstory, let's take a quick look at the feature I added. If you write code like this:

function isNumber(data: unknown) {
  return typeof data === 'number';
}

TypeScript will now infer that the function is a type predicate:

Previously, TypeScript would have inferred a boolean return type. This also works for arrow functions, which means code that filters arrays becomes much more ergonomic:

const nums = [1, 2, null, 3, 4].filter(x => x !== null);
//    ^? const nums: number[]
console.log(nums[0].toFixed()); // ok

Previously, this type would have been (number | null)[] and the last line would have been a type error.

Why contribute to TypeScript?

I've been using TypeScript since 2016. I've been writing about it almost as long. But I'd never contributed code to it. This felt like a gap in my understanding of TypeScript and its ecosystem. Like most TS users, I have a long list of features I'd like to see added to the language, and I thought learning about compiler internals would help me understand which of those features were feasible and which weren't.

At the start of this year, I signed up for a 12-week batch at Recurse Center, a "writer's retreat for programmers." You apply with a project in mind, and mine was to contribute to TypeScript. RC provided an encouraging structure and the space for me to make this leap.

Hopes and Fears

I hoped that I'd build a stronger intuition for how TypeScript works internally and maybe have some insights along the way. If I was lucky, maybe I'd be able to say I was a TypeScript contributor and make some improvements to the language.

My biggest fear was that I'd put a lot of work into a PR only to see it stall. There are some notorious examples of this, most famously the cake-driven development incident. I knew the real goal was to learn more about TypeScript. But I did hope to get a change accepted.

Finding a first issue

Mid- to Late-January 2024

Before trying to implement something substantial, I thought I'd start by fixing a trivial bug. This would help me get familiar with the compiler and the development process. This is exactly how the TypeScript docs suggest you get started as a contributor.

Finding a "good first issue" proved harder than I'd expected. Most of the small, newly-filed issues get fixed quickly by one or two experienced community members. From a community perspective, this is great: if you file a bug and it's accepted, it's likely to get fixed. But for a new contributor this isn't good: I was unlikely to win any races to fix an issue.

There's a good first issue label, but this proved to be a bit of a joke. My favorite issue in this category was discussed by three of the top contributors to TypeScript, who decided it was impossible or not worth doing. But it's still got that "good first issue" label!

Eventually I found #53182, which involved numeric separators (1_234) not getting preserved in JS emit. This seemed low stakes and, as an added bonus, I'm a fan of the developer who filed it.

The fix was a one-liner, just like you'd expect, but I learned a lot about how TypeScript works along the way. TypeScript's code structure defies many best practices. All the code for type checking is in a single file, checker.ts, that's over 50,000 lines of code. And these are meaty lines since there's no set line width and relatively few comments. It also makes extensive use of numeric enums, a feature I discourage in Effective TypeScript.

That being said, there are some impressive parts of the tooling. Visual debugging (F5) works great in VS Code and is an excellent way to learn what the compiler is doing. There are relatively few unit tests, but there's an enormous collection of "baselines," a sort of end-to-end test that snapshots the types and errors for a code sample. There are over 18,000 of these, but TypeScript is able to run all of them on my laptop in just a few minutes.

After a few weeks, my PR was merged and released as part of TypeScript 5.4. I was officially a TypeScript contributor!

A meatier second issue

January 26, 2024

Fixing a small bug was a good start, but my bigger goal was to implement a new feature. Of all the issues I'd filed on TypeScript, #16069 stood out with over 500 👍s. This issue requested that TypeScript infer type predicates for functions like x => x !== null. Clearly I wasn't the only one who wanted this!

I also had reason to think that this issue might be solvable. In TypeScript 4.4 (2021), Anders added support for aliased conditions and discriminants. This let you write code like this:

function foo(x: string | null) {
  const ok = x !== null;
  if (ok) {
    x  // type is string
  }
  return ok;
}

Surely the ok symbol had to have information stored on it saying that its value was tied to a refinement on x. If I looked at Anders' PR, I'd find where this was stored. This felt at least adjacent to my issue. And it was a good story: the feature only became feasible after another seemingly-unrelated feature was added. There were even some comments suggesting as much.

As it turned out, this was totally wrong! Nothing was stored on the ok symbol and I totally misunderstood how type inference worked. This was a big insight for me, and I wrote about it in my last blog post, Flow Nodes: How Type Inference Is Implemented. Head over there to learn all about this epiphany.

As part of my efforts to understand how control-flow analysis worked, I wrote some code to visualize TypeScript's control flow graph. I contributed this as a new feature to the TS AST Viewer. This was a nice, concrete win: even if my work on type predicate inference went nowhere, at least I'd contributed something of value to the ecosystem.

"OK, maybe this isn’t hopeless…"

Week of February 2, 2024

Having built a stronger understanding of how type inference worked, I came back to the original problem. Did this make implementing my feature easier or harder?

Whenever I explained this feature, I'd demo how you could put the return expression in an if statement to see the narrowed type of the parameter:

function isNonNull(x: number | null) {
  return x !== null;
}

// ->

function isNonNullRewrite(x: number | null) {
  if (x !== null) {
    x  // type is number
  }
}

The key insight was to realize that I could do the exact same thing with the control flow graph. I'd just have to synthesize a FlowCondition node, plug it into wherever the return statement was, and check the type of the parameter in that branch if the condition was true. If it was different than the declared type, then I had a type predicate!

I could check the type of a parameter at a location using the getFlowTypeOfReference function. But where to put this check? This was also a challenge, but eventually I found a place in getTypePredicateOfSignature to slot it in. I added a new function, getTypePredicateFromBody, that this would call for boolean-returning functions.

This was all a bit of a struggle since it was my first time really working with the type checker. Even simple things felt quite hard. What's the difference between a Declaration, a Symbol and an Identifier? How should I go from one to the other? Often I found a very roundabout way that let me keep making progress before I later found a more canonical path. For example, if param is a ParameterDeclaration, then you can use param.name to get a BindingName, and isIdentifier(param.name) to make sure it's an Identifier.

Running the tests was easy, but it took me a bit longer to realize how to test them in an interactive setting. So far as I can tell, building your own version of the TypeScript Playground isn't possible. But if you run hereby local, it will build tsc.js, and you can point any VS Code workspace at that version of TypeScript. You can even do this for the TypeScript repo itself.

While learning my way around the codebase, I found it incredibly helpful to take notes. Which function did what? What questions did I have? What was I struggling with? What did I have left to do? This helped to keep me oriented and also gave me a sense of progress. In particular, it was satisfying to read questions I'd had weeks earlier that I now knew the answer to. Clearly I was learning! By the time my PR was merged, my Notion doc ran to 70+ pages of notes.

Eventually I was able to fit all the pieces together, though, and this let me infer type predicates for the first time, which was hugely encouraging!

43 failures

Week of February 9, 2024

This let me run the 18,000+ TypeScript "baselines." This was an exciting moment: the first time I'd see how my inference algorithm behaved on unfamiliar code! My initial implementation produced 43 test failures. I went through and categorized these:

• 32 were "Maximum call stack size exceeded" errors
• 5 were the identify function on booleans
• 1 involved my mishandling a function with multiple returns
• The other 5 were wins!

This change was pretty funny:

// function identity(b: boolean): b is true
function identity(b: boolean) {
  return b;
}

The identity function on booleans is a type predicate! But that didn't seem very useful. I added a special case to skip boolean parameters.

The maximum call stack errors turned out to be an infinite loop. I added some code to block this. Then I changed my code to only run on functions with a single return statement. This left me with just the wins.

One of these wins got me particularly excited:

declare function guard1(x: string|number): x is string;
function guard2(x: string | number) {
  return guard1(x);
}

I was inferring that guard2 was a type guard because guard1 was. This meant that type predicates could flow! There was another long-standing issue requesting just this behavior. Anders has said that you never want to fix just a single issue, you always want to fix a whole category of problems. This was an encouraging sign that I was doing just that. I hadn't set out to make type predicates flow, it just followed naturally from my change and TypeScript's control flow analysis.

More Predicates in More Places

Week of February 16, 2024

To keep things simple, I'd only been considering function statements, not function expressions or arrow functions. Now that I'd validated the basic approach, I wanted to support these, too.

Standalone function expressions and arrow functions weren't difficult to add, but I had a lot of trouble with functions whose parameter types are determined by context. For example:

const xs = [1, 2, 3, null];
const nums = xs.filter(x => x !== null);

The type of x is number | null, but TypeScript only determines this from a complex sequence of type inferences. I kept getting any types.

This problem didn't turn out to be deep. It just required finding the right function to call. getTypeForVariableLikeDeclaration did not work, but eventually I discovered getNarrowedTypeOfSymbol, which did. For the final PR I switched over to getSymbolLinks.

This was another really exciting moment! My commit message nicely captures my feelings:

Nearly seven years after I'd filed the original issue, I was able to make it pass the type checker:

Success would be fleeting for this code sample, though, as I was about to find out.

Pathological Cases and an Insight

As I was developing the feature, I started collecting a set of "pathological" functions, ones that I thought might trip up my algorithm. The goal here is to think of everything that could possibly go wrong. That's impossible, of course, but the more bugs you work out on your own, the better.

This one turned out to be particularly interesting:

function flakyIsString(x: string | null) {
  return typeof x === 'string' && Math.random() > 0.5;
}

Should this be a type predicate? If it returns true, then you know that x is a string. But what if it returns false? In that case, x could be either string or null.

TypeScript infers correct types on both sides if we rewrite this as an if statement:

function flakyIsStringRewrite(x: string | null) {
  if (typeof x === 'string' && Math.random() > 0.5) {
    x; // type is string
  } else {
    x; // type is string | null
  }
}

But if you make this a type predicate, that nuance is lost:

function flakyIsString(x: string | null): x is string {
  return typeof x === 'string' && Math.random() > 0.5;
}
declare let sOrN: string | null;
if (flakyIsString(sOrN)) {
  sOrN  // type is string
} else {
  sOrN  // type is null 😱
}

In other words, flakyIsString should not be a type predicate. This forced me to reformulate my criterion for inferring type predicates to consider the false case. If you rewrite a function that returns expr like this:

function foo(x: InitType) {
  if (expr) {
    x  // TrueType
  } else {
    x  // FalseType
  }
}

Then I required that FalseType = Exclude<InitType, TrueType>. This was the criterion I used when I first posted the PR, but it turned out to be subtly incorrect.

I hadn't realized that type predicates had these "if and only if" semantics before working on this PR. This was a genuine insight, and I wrote about in another post on this blog: The Hidden Side of Type Predicates.

Plot Twist: Truthiness and Nullishness

Here's the example code from the original feature request in 2017:

const evenSquares: number[] =
    [1, 2, 3, 4]
        .map(x => x % 2 === 0 ? x * x : null)
        .filter(x => !!x);  // errors, but should not

With my new criterion came a real plot twist: I stopped inferring a type guard in this case! The reason is that "truthiness" doesn't cleanly separate number|null:

declare let x: number | null;
if (!!x) {
  x;  // number
} else {
  x;  // number | null
}

number is possible in the else case because 0 is falsy. (A type of 0|null would be more precise).

I saw this as a mixed bag. While it meant that I didn't truly "fix" the original issue, I also think it's a good behavior. Checking for "truthiness" is usually a bad idea with primitive types. You typically want to exclude just null or undefined, not 0 or "". Filtering out 0 when you mean to filter out null is a common source of bugs.

To infer a type predicate for x => !!x, TypeScript would either need negated types (so that you could represent "numbers other than 0") or one-sided type predicates. Both are beyond the scope of my PR.

My change will infer a type predicate from x => !!x for object types, where there's no ambiguity.

Putting up the PR

February 20–21, 2024

I showed my PR to Josh Goldberg around this time. I was a bit nervous to post the PR—I'd put a lot of work into it at this point!—but he was excited and gave me the pep talk that I needed. So I wrote up a detailed PR description and posted my code the next day.

There was a lot of excitement! It was fun and encouraging to see all the positive feedback on Twitter. In particular Brad Zacher introduced me to %checks, which was a similar feature in Flow. His experience using this proved helpful later in keeping the scope of my PR large.

I'd run all the TypeScript unit tests on my laptop, so I knew that those passed. But there was a new test that failed in a really interesting way…

A Scary Self-Check Error

February 21, 2024

TypeScript is written in… TypeScript! This is a bit of a headscratcher at first, but it's actually a common practice in programming languages known as bootstrapping. As such, it's important that TypeScript be able to compile itself with every change.

My PR was unable to compile TypeScript, and for a very interesting reason. It boiled down to whether this function should be a type predicate:

function flakyIsStringUnknown(x: unknown) {
  return typeof x === 'string' && Math.random() > 0.5;
}

This is the same as flakyIsString, but with a broader parameter type. We can convert this to an if statement as usual:

function flakyIsStringUnknown(x: unknown) {
  if (typeof x === 'string' && Math.random() > 0.5) {
    x  // TrueType: string
  } else {
    x  // FalseType: unknown
  }
}

Since Exclude<unknown, string> = unknown, my PR inferred a type predicate for this function. And that is valid if you call it with a symbol whose type is unknown. But there's no reason you have to do that! As with any function in TypeScript, you can call it with a subtype of the declared type. And if we infer a type predicate, that's trouble:

function flakyIsStringUnknown(x: unknown): x is string {
  return typeof x === 'string' && Math.random() > 0.5;
}
declare const sOrN: string | number;
if (flakyIsStringUnknown(sOrN)) {
  sOrN  // type is string
} else {
  sOrN  // type is number 😱
}

The type in the else case is wrong. It could still be a string. So something was wrong with my criterion. I feared that this might be a fundamental problem with my approach.

I decided to step away from the problem and go for a walk.

Saving the PR: A New Criterion

Recall that this was the criterion I was using:

FalseType = Exclude<InitType, TrueType>

InitType is the declared parameter type. Really I needed that relationship to hold not just for InitType but for all subtypes of InitType. But how on earth to test that?

Intuitively, it seemed to me like there was just one subtype of InitType that was worth testing: TrueType. If I set InitType=TrueType, I could run the same inference algorithm again to get TrueSubType and FalseSubType. Then I could check a secondary criterion:

FalseSubType = Exclude<TrueType, TrueSubtype>

Here's what this would look like for flakyIsStringUnknown:

function flakyIsStringUnknown(x: unknown) {  // InitType: unknown
  if (typeof x === 'string' && Math.random() > 0.5) {
    x  // TrueType: string
  } else {
    x  // FalseType: unknown
  }
}
// ✅ unknown = Exclude<unknown, string>
function flakyIsStringUnknownSub(x: string) {  // TrueType: string
  if (typeof x === 'string' && Math.random() > 0.5) {
    x  // TrueSubType: string
  } else {
    x  // FalseSubType: string
  }
}
// ❌ string != Exclude<string, string>

This seemed to work, at the expense of making four calls to getFlowTypeOfReference rather than two. But correctness first, performance second. The PR was working again!

A Surprising Circularity Error

February 23, 2024

With the tests passing, I got my first glimpse of the performance impact of my changes, as well as the new errors on TypeScript's broader test suite of popular repos.

The performance wasn't great: +5% on one of their standard benchmarks.

There were six failures. Four were sensible consequences of my change. This one from VS Code was particularly interesting:

const responseItems = items.filter(i => isResponseVM(i));

isResponseVM is a type guard. The author of this code wrapped it in an arrow function to avoid applying it as a refinement to the items array. But with my PR TypeScript wasn't so easily fooled! The type guard flowed through and the type of responseItems changed.

The only really problematic failure came from Prisma. This was a new "circular reference" error. I spent quite a while setting up a minimal reproduction of this before I realized what was going on: my code was running on constructor functions!

But not just any constructor function. Only constructor functions with exactly one return statement. Did you know that a constructor function in JS could have a return statement? I didn't. It's allowed, but exceedingly rare. Regardless, constructors can't be type predicates, so I excluded them and this fixed the test.

One insight here is that lots of valid TypeScript code is teetering on the edge of triggering a circularity error. Just by checking a type in a different sequence in checker.ts, you might cause enough of a change to tip some over.

Performance and the Final Criterion

February 25, 2024

With the changes in the test suite well-characterized, I started to think about performance. Were those four calls to getFlowTypeOfReference all necessary? The TrueSubtype was irrelevant. It should just be the same as TrueType. Maybe I could also ditch FalseType and go directly to the FalseSubtype test.

Moreover, if TrueType == TrueSubtype, and

FalseSubType = Exclude<TrueType, TrueSubtype>

then really what I need to test is FalseSubtype == never. This was a nice win because it got me back to two calls to getFlowTypeOfReference and let me drop potentially-expensive Exclude calculations.

This wound up being the final version of the criterion. Let's walk through how it works for this function:

function isStringFromUnknown(x: unknown) {
  return typeof x === 'string';
}

First we rewrite this to an if statement to get the TrueType:

function isStringFromUnknown(x: unknown) {
  if (typeof x === 'string') {
    x  // TrueType = string
  }
}

Next we pass this through as the parameter type and look at the else case:

function isStringFromUnknown(x: string) {
  if (typeof x === 'string') {
  } else {
    x  // type is never
  }
}

If this type is never then we have a bulletproof type predicate. Otherwise we don't. This makes good intuitive sense: if the function returns true for every value in a type, then there should be nothing left in the else case, where it returns false.

With fewer calls to getFlowTypeOfReference and a simple never check, the performance hit dropped from 5% down to 1-2%.

More performance

February 27–March 6, 2024

At this point my PR started to get discussed at the weekly design meetings. They were generally supportive but wanted to track down that performance hit.

This set off a flurry of optimizations. Ryan experimented with narrowing the scope of the PR. Anders reordered some of the checks. I profiled my change and thought I found a big win that didn't hold up.

An insight from profiling was that getTypePredicateFromBody was usually quite fast, but there were a few pathological cases where it could be very slow. This was the worst of the worst:

function hasBindableName(node: Declaration) {
    return !hasDynamicName(node) || hasLateBindableName(node);
}

Both hasDynamicName and hasLateBindableName are explicit type predicates. So should this be a type predicate? Here's how the types come out:

InitType = Declaration
TrueType = NumericLiteral | StringLiteral | NoSubstitutionTemplateLiteral | Identifier | TypeParameterDeclaration | ... 106 more ... | LateBoundBinaryExpressionDeclaration
FalseSubtype = (PropertySignature & DynamicNamedDeclarationBase) | (PropertyDeclaration & DynamicNamedDeclarationBase) | ... 17 more ... | DynamicNamedBinaryExpression

That's a big union! Calculating these types, particularly the FalseSubtype, winds up being very expensive. This one call took 300ms on my laptop and accounted for 80% of the slowdown on one benchmark.

I tried adding a few more optimizations but unfortunately they didn't change the perf numbers much. So a 1-2% slowdown is where it was going to be.

A highlight here was getting a very positive code review from Anders. This is definitely going on my resume!

A productive prod

March 12, 2024

At this point the PR stalled for around a week. I wanted to keep things moving along, but I also didn't want to be that person posting "any updates?" comments. I've been on both sides of this. Those comments are rarely helpful. Presumably everyone wants the PR to make progress, there are just other priorities.

But in this case, there was an opportunity for a more constructive nudge. I had a draft of the second edition of Effective TypeScript due on March 15th. One of the new items was "Know how to filter null values from lists." If my PR went in, that item would be completely unsalvageable, and the best course of action would be to delete it completely.

Ryan Cavanaugh was a reviewer for the book, so I asked him what he thought the odds of my PR being merged were. If they were greater than 50/50, I should just delete the item.

Ryan said that Anders was "super stoked" on the PR and he thought it would go in for 5.5. Wow! Even better, he took the hint and reassigned the PR to Anders, who immediately approved it. Amazing! Ryan said he'd ping the team for a last round of reviews.

The final review

March 13–15, 2024

During that final round of reviews, Wes Wigham found two more issues:

1. I needed to avoid inferring type predicates for rest parameters (a pathological case I'd missed!)
2. I needed to make sure that inferred type predicates showed up in emitted declaration files (.d.ts), just like inferred return types do.

Adding .d.ts emit would have been a daunting change at the start of this process, but by now I was comfortable enough navigating the TypeScript codebase that it didn't prove too difficult.

The most confusing part here was that the tests all started failing on TypeScript's CI. I couldn't reproduce the failures on my laptop. This was quite frustrating until I figured out what was going on: the TypeScript CI does a git merge main before running your tests. There are differing opinions on whether this is a good idea, and I usually don't set up my repos to do it. But once I realized what was going on, the fix was easy: I just needed to merge the upstream changes myself.

There was one funny bug that came up here. My generated .d.ts files initially contained code that looked like this:

export declare function syntaxRequiresTrailingSemicolonOrASI(
  kind: SyntaxKind
): kind is SyntaxKind.PropertyDeclaration |
   SyntaxKind.VariableStatement |
   SyntaxKind.ExpressionStatement |
   SyntaxKind.DoStatement |
   SyntaxKind.ContinueStatement |
   SyntaxKind.BreakStatement |
   SyntaxKind.ReturnStatement |
   ... 7 more ... |
   SyntaxKind.ExportDeclaration;

That "... 7 more ..." isn't valid TypeScript syntax! It turns out I needed to set an emit flag to prevent truncation.

Wes requested that I do some minor refactoring and then approved the PR.

After a last round of tests, Ryan merged my PR. This was happening!

Aftermath

Once my PR went in, there was even more excitement on TypeScript Twitter. Andarist and Matt Pocock both tweeted about it, and Matt even wrote a blog post. Jake Bailey put up a very satisfying PR that removed newly-superfluous type assertions from the TypeScript code base. There was one bug filed about inferring type predicates for tagged unions, which Andarist quickly fixed.

I explored a two followup changes:

1. Lots of the Twitter reaction asked whether filter(Boolean) would work now. The answer is no, but I explored how we could make this work (for object types) and found it harder than expected.
2. I also looked into supporting type predicate inference for functions with multiple return statements. This isn't a major change to the existing logic and it has minimal performance impact. But there aren't many functions like this in the wild, so it may not be worth the effort.

Conclusions

Stepping back, creating this PR was a great experience that worked out far better than I had any right to expect. My goal was to get a better sense for how TypeScript worked internally, and I certainly did that! But fixing a seven year-old bug and seeing the wildly positive response was even better.

I filed this issue in 2017 when TypeScript 2.3 was the latest and greatest. I'd initially been drawn to work on it because I thought that an unrelated change in TypeScript 4.4 (2021) might have made it more tractable. That change turned out to be irrelevant. All of the machinery I wound up using to infer type predicates was already in place way back in 2017. It's just that no one had thought to put the pieces together in quite this way.

This is a great example of how bringing fresh eyes into an ecosystem can be beneficial. I don't think there are any other places where the type checker synthesizes a flow node. But I didn't know that, so I just did it. And it worked great!

TypeScript 5.5 should come out for beta testing in the next few weeks, and a final version should be out in the next few months. It's exciting to think that my experimental code from January will soon be running on every TypeScript function in the world!

In most programming languages a variable has a type and that type does not change. But one of the most interesting aspects of TypeScript's type system is that a symbol has a type at a location. Various control flow constructs can change this type:

function refine(x: string | number) {
  // type of x is string | number here
  if (typeof x === 'number') {
    // type of x is number here.
  } else {
    // type of x is string here.
  }
}

Dall-E's interpretation of TypeScript's control flow graph and type inference algorithm.

This is known as "refinement" or "narrowing." When I look at TypeScript code, I read it from top to bottom and I think about how the type of x changes as execution moves through each conditional. This works well but, as I learned from my recent work adding a new form of type inference in the TypeScript compiler, it's not at all how type inference is actually implemented!

For users of TypeScript, reading code from top to bottom works just fine. But if you're working in the TypeScript compiler itself, you'll need to know how type inference works "under the hood." The key to this is "Flow Nodes," which are the nodes in the Control Flow Graph. I had a remarkably hard time finding documentation about FlowNodes online. The official Compiler-Notes repo just has a "TODO" to document them. Basarat's TypeScript guide makes no mention of them in the section on the TypeScript Compiler.

I learned a lot about FlowNodes from implementing #57465 and this post is my attempt to write the "missing manual" on them that I wish I'd had a few months back.

Confusion

My first clue that type inference didn't work the way I expected came from reading a PR that Anders Hejlsberg wrote in 2021 to add "aliased conditions" to type inference. This let you write something like:

function refine(x: string | number) {
  const isNum = typeof x === 'number';
  if (isNum) {
    // type of x is number here.
  } else {
    // type of x is string here.
  }
}

In my top-to-bottom way of thinking about type inference, it seemed like there must be some kind of "tag" associated with the isNum variable indicating that it refined the parameter x. But looking at Anders' PR, this wasn't at all how it worked. He wasn't storing any information whatsoever! Instead, all I saw was a bunch of references to flow nodes. So clearly these were important.

When TypeScript parses your code, it forms an Abstract Syntax Tree (AST). Any node in the TypeScript AST can have an associated "flow node." The best way to view the TypeScript AST is David Sherret's TS AST Viewer. When you click on a node, it shows you its FlowNode. This consisted of some flags, a node, and one or more "antecedents." Curiously node.flowNode.node was never the same as node. It was always some other node in the AST.

A Flow Node and its antecedent in the TS AST Viewer. I didn't find this view very illuminating.

Graph Visualization and an Insight

The antecedents were other FlowNodes. These seemed to form some sort of graph structure, so I thought that visualizing them might help. I'd used GraphViz and the dot language to create graph visualizations on a previous project, and this seemed like a natural addition to the TS AST Viewer. I learned later that there was already a TypeScript playground plugin that did something similar.

Seeing this graph made it much clearer what was going on. This was the control flow graph in reverse! An if statement came out as a diamond shape:

Full control flow graph showing a diamond shape for branching code.

I showed this to a batchmate at Recurse Center who had the key insight: a Node's Flow Node is the previous statement that executed. With branching constructs, there will be more than one possible previous statement.

With loops, the graph can even have a cyclic:

Control flow graph showing a cycle for looping code.

I eventually added this visualization to the TS AST Viewer. You can play around with it yourself to get a sense for how Flow Nodes work.

Turning Type Inference Upside-Down

With some intuition about Flow Nodes in place, the code I was seeing in the type checker started to make a lot more sense.

TypeScript greedily constructs the control flow graph in the binder (binder.ts), then lazily evaluates it as it needs to get types in the checker (checker.ts) or for display (tsserver.ts). This is backwards from how we think about narrowing in our heads: rather than narrowing types as you read down your code, TypeScript narrows types by traversing back up the control flow graph from the point where symbols are referenced.

Why does TypeScript do type inference this way? There are two reasons I can think of. The first is performance. In the context of the compiler, a symbol's type in a location is called its "flow type." Determining a symbol's flow type can be an expensive operation. It requires traversing the control flow graph all the way back to the root (usually the start of a function) and potentially computing some relationships between types along the way.

But often the flow type isn't needed. If you have an if statement like this:

function logNum(x: unknown) {
  if (typeof x === 'number') {
    console.log('x is a number');
  }
}

Then the type of x inside the if statement is number. But that's not relevant to the type safety of this code in any way. There's no reason for TypeScript to determine the flow type of x. And indeed, it doesn't. At least not until you write x in the if block.

This leads us to a profound realization: until it becomes relevant, TypeScript has no idea what the type of x is!

If the type of x becomes relevant for type checking, then TypeScript will determine its flow type:

function logNum(x: unknown) {
  if (typeof x === 'number') {
    // x is referenced, so TypeScript needs to know its type.
    console.log("it's a number:", x);
  }
}

There may be many local variables in scope in your function. By only determining the flow types of the ones that are relevant for type checking, TypeScript potentially saves an enormous amount of work. This results in a more responsive editor and faster compile times. It also reduces TypeScript's memory usage: only the control flow graph needs to be stored permanently. Flow types can potentially be thrown away after they're checked.

The other reason that TypeScript does control flow analysis this way is to separate concerns in their code base. The control flow analysis graph is a standalone structure that's computed once in the binder. (This is the part of the compiler that determines which symbol x refers to in any location.) This graph can be constructed without any knowledge of what sort of analysis you'd like to do on it.

That analysis happens in the checker, checker.ts. One part of the compiler constructs the graph greedily, the other runs algorithms on it lazily.

This is what I was seeing in Anders's PR. He already had all the information he needed in the control flow graph. His PR just made the algorithm that ran over it a little more elaborate. Very few PRs need to change how the control flow is constructed. It's much more common to change the algorithms that run over it.

getFlowTypeOfReference

Speaking of algorithms, let's take a look at getFlowTypeOfReference, the workhorse of type inference. This is the function that determines the type of a symbol at a location. It's a real beast, clocking in at over 1200 lines of code. I'd link to it in checker.ts, but GitHub won't even display files this large!

getFlowTypeOfReference is so large because it follows the usual TypeScript compiler style of defining helper functions as local functions inside a large, top-level function. It quickly calls getTypeAtFlowNode, which is where the flow node graph traversal happens.

This function consists of a while loop that looks at the current Flow Node and tries to match it against all the different patterns that can trigger a refinement. If it doesn't find one, it moves up to the node's antecedent:

The code for traversing up the antecedent graph in getTypeAtFlowNode

All the different patterns of refinement that TypeScript supports are represented by helper functions. Here's a sample:

• narrowTypeByTruthiness
• narrowTypeByBinaryExpression
• narrowTypeByTypeof
• narrowTypeByTypeName
• narrowTypeBySwitchOnDiscriminant
• narrowTypeByInstanceof
• narrowTypeByTypePredicate
• narrowTypeByEquality
• narrowTypeByOptionalChainContainment

It's interesting to think about what sort of code would trigger each of these. narrowTypeByEquality, for example, is a special case of narrowTypeByBinaryExpression. It would trigger on code like this:

function foo(x: string | null) {
  if (x !== null) {
    // x is string in here
  }
}

(There's an assumeTrue flag that toggles behavior based on === vs. !==.)

narrowTypeByEquality is more subtle than you might expect! Take a look at this code:

function foo(x: string | number, y: number | Date) {
  if (x === y) {
    // x is number
    // y is number
  }
}

If two values are equal to one another, then their type must be the intersection of their declared types. Very clever, TypeScript!

What about branching constructs? TypeScript traverses up through both branches and unions the result. This should give you a sense for why determining flow types can be expensive! (The code for this is in getTypeAtFlowBranchLabel.)

Conclusion

Hopefully this post has clarified what flow nodes are and how type narrowing is implemented in the TypeScript compiler. While this isn't important to understand for TypeScript users, I'm still amazed that, after having used TypeScript for eight years, it turned out to work completely backwards from how I thought!

The result is PR #57465, which adds a feature I've always wanted in TypeScript: inference of type predicates. I'll have more to say about that PR in a future post. But for now I'd like to share some of what I've learned about type predicates while implementing it.

What are type predicates?

What is a type predicate? Whenever a function in TypeScript returns a boolean, you can change it to return a "type predicate" instead:

function isNumber(x: unknown): x is number {
  return typeof x === 'number';
}

Here x is number is the type predicate. Any function that returns a type predicate is a "user-defined type guard."

Here's how you use a type guard:

let strOrNum = Math.random() < 0.5 ? 123 : 'abc';
//  ^? let strOrNum: number | string
if (isNumber(strOrNum)) {
  strOrNum;
  // ^? let strOrNum: number
}

In this case there's little advantage over doing the typeof check directly in the if statement. But type guards really shine in two specific circumstances:

1. When TypeScript can't infer the type you want on its own.
2. When you pass the type guard as a callback.

The former often comes up with input validation:

function isProductReview(input: unknown): input is ProductReview {
  // ... validate input using JSONSchema, etc.
}

But in this post we're more interested in the latter. Here's the motivating scenario:

const strsAndNums = [123, 'abc', 456, 'def'];
//    ^? const strsAndNums: (number | string)[]
const nums = strsAndNums.filter(x => typeof x === 'number');
//    ^? const nums: (number | string)[]
for (const num of nums) {
  console.log(num.toFixed());
  //              ~~~~~~~
  //    Property 'toFixed' does not exist on type 'string | number'.
}

We've filtered the array of strings and numbers down to just the numbers, but TypeScript hasn't been able to follow along. The result is a spurious type error.

Changing from an arrow function to the type guard fixes the problem:

const strsAndNums = [123, 'abc', 456, 'def'];
//    ^? const strsAndNums: (number | string)[]
const nums = strsAndNums.filter(isNumber);
//    ^? const nums: number[]
for (const num of nums) {
  console.log(num.toFixed());  // ok
}

This works because the declaration of Array.prototype.filter has been overloaded to work with type predicates. Several built-in Array methods work this way, including find and every:

const num = strsAndNums.find(isNumber);
//    ^? const num: number | undefined
if (strsAndNums.every(isNumber)) {
  strsAndNums
  // ^? const strsAndNums: number[]
}

What if you return false?

If a function returns x is T, then it's clear what it means when it returns true: x is a T! But what does it mean if it returns false?

TypeScript's expectation is that type guards return true if and only if the predicate is true. To spell it out:

• If the type guard returns true then x is T.
• If the type guard returns false then x is not T.

This often works so intuitively that you don't even think about it. Using our isNumber type guard, for example:

let strOrNum = Math.random() < 0.5 ? 123 : 'abc';
//  ^? let strOrNum: number | string
if (isNumber(strOrNum)) {
  strOrNum;
  // ^? let strOrNum: number
} else {
  strOrNum;
  // ^? let strOrNum: string
}

But it can definitely go wrong! What about this type guard?

function isSmallNumber(x: string | number): x is number {
  return typeof x === 'number' && Math.abs(x) < 10;
}

If this returns true then x is definitely a number. But if it returns false, then x could be either a string or a large number. This is not an "if and only if" relationship. This sort of incorrect type predicate can lead to unsoundness:

if (isSmallNumber(strOrNum)) {
  console.log(strOrNum.toFixed());
  //          ^? let strOrNum: number
} else {
  console.log(strOrNum.toUpperCase());
  //          ^? let strOrNum: string
}

This passes the type checker but blows up at runtime:

  console.log(strOrNum.toUpperCase());
                       ^

Cannot read property toUpperCase of 123.

This highlights two important facts about type guards:

1. TypeScript does very little to check that they're valid.
2. There are expectations around the false case, and getting it right matters!

Generally functions that combine checks with && should not be type guards because the type will come out incorrectly for the false case.

Many functions only care about the true case. If you're just passing your type guard to filter or find, then you won't get into trouble. But if you pass it to a function like lodash's _.partition then you will:

import _ from 'lodash';
const [smallNums, others] = _.partition(strsOrNums, isSmallNumber);
//                ^? const others: string[]

This is an unsound type and it will lead to trouble. It's interesting to compare this with inlining the check into an if statement:

if (typeof strOrNum === 'number' && Math.abs(strOrNum) < 10) {
  strOrNum
  // ^? let strOrNum: number
} else {
  strOrNum
  // ^? let strOrNum: number | string
}

Left to its own devices, TypeScript gets this right. The only reason it went wrong before was because we fed it bad information: isSmallNumber should not have been a type predicate!

Because of the strict rules around what false means, a type guard cannot, in general, replace an if statement. There's a proposal to fix this by adding "one-sided" or "fine-grained" type guards. If it were adopted, you'd be able to declare something like this:

function isSmallNumber(x: string | number): x is number else (string|number);

A test for valid type predicates

In the last example, we could tell that the type predicate was invalid because inlining it into an if statement produced different types in the else block than calling the type guard did.

This feels like a good test for type guards! Does it work?

As it turns out, no! There's a subtlety around subtyping that hadn't occurred to me until the tests failed on my PR branch. The details and solution are a little too in the weeds for this post. But when I write a post about the making of this PR, we'll cover it in depth. There is a test. Check out the PR if you're curious.

In the meantime, though, we can talk about a few heuristics. If a condition fails the "inlining" test, then it's definitely not a valid type predicate.

Non-Nullishness, not Truthiness

JavaScript and TypeScript make a distinction between "truthiness" and "non-nullishness":

const isTruthy<T>(x: T) => !!x;
const isNonNullish<T>(x: T) => x !== null && x !== undefined;

This is important for types like number and string. Here's why:

declare let numOrNull: number | null;
if (numOrNull) {
  numOrNull;
  // ^? const numOrNull: number
} else {
  numOrNull;
  // ^? const numOrNull: number | null
}

The interesting part is the number in the else block. The number 0 is falsy, so numOrNull can be a number in the false case. (In theory TypeScript could narrow it to 0 | null, but the TS team has decided this is not worth it.)

This means that if you make isTruthy return a type predicate, functions like partition will produce unsound types:

const numsAndNulls = [1, 2, null, 4, null, 5];
//    ^? const numsAndNulls: (number | null)[]

const isTruthy = (x: number | null): x is number => !!x;  // don't do this!
const [nums, nulls] = _.partition(numsAndNulls, isTruthy);
//           ^? const nulls: null[]

TypeScript thinks that nulls is an array of null values, but it could actually contain numbers (specifically zeroes). This is an unsound type. It's also likely to be a logic error: do you really mean to filter out the zeroes? If you're calculating an average, this will give you an incorrect result.

Better to use isNonNullish or the equivalent. This is safe:

const [nums, nulls] = _.partition(numsAndNulls, (x): x is number => x !== null);
//           ^? const nulls: null[]

You can make the generic isNonNullish into a type predicate, too:

function isNonNullish<T>(x: T): x is T & {} {
  return x !== null && x !== undefined;
}

This relies on the {} type, which is TypeScript for "all values except null and undefined." This is one of the few good uses of this very broad type!

Composing predicates

In general you can compose type predicates with "or":

function isFooOrBar(x: unknown): x is Foo | Bar {
  return isFoo(x) || isBar(x);
}

Similarly, you can compose predicates with "and" if their types intersect:

function isFooAndBar(x: unknown): x is Foo & Bar {
  return isFoo(x) && isBar(x);
}

This could happen if you have a big discriminated union and you have helpers that match different subsets of it.

Be careful about composing conditions that can't be fully represented in the type system, however. You can't define a TypeScript type for "numbers less than 10" or "strings less than ten characters long" or "numbers other than zero." So conditions like these generally don't belong in a type guard:

// This should not return a type predicate!
function isShortString(x: unknown) {
  return typeof x === 'string' && x.length < 10;
}

Conclusions

When you write a user-defined type guard, it's easy to only think about the true case: if you write x is string and you know that x must be a string when the function returns true, then surely you're good to go, right?

As this post has explained, that's only half the battle. In order for a type guard to be completely safe, it's also important to know what the type of the parameter is when it returns false. This is the hidden side of type predicates. It's easy to get wrong, and this can lead to unsound types.

Because it might be used in an if / else statement or with functions like _.partition, you want your type guard to be bulletproof! Make sure you provide the "if and only if" semantics that TypeScript expects.

Here are the slides. Topics covered in this talk include:

• What is an "Effective" book?
• What's the relationship between TypeScript and JavaScript (playground)
• Why you shouldn't repeat type information in documentation (Item 30; playground)
• Why you should think about types as sets of values (Item 7, playground)
• Designing types that only represent valid states (Item 28, playground)
• How to avoid fighting with the type checker (playground)

The content of the talk represents my views, it wasn't by or on behalf of Etsy. If you're interested in hosting an Effective TypeScript talk at your company or meetup, please get in touch!

class Point2D {
  private x: number;
  private y: number;

  getX() {
    return this.x;
  }
  setX(x: number) {
    this.x = x;
  }
  getY() {
    return this.y;
  }
  setY(y: number) {
    this.y = y;
  }
}

This feels productive. You're writing code, after all! If you're feeling especially diligent, you might even write JSDoc comments for each of these methods. Your editor might even include shortcuts to write all these getters and setters for you.

Here's some code that uses that class:

const pt = new Point2D();
pt.setX(3);
pt.setY(4);
console.log(pt.getX(), pt.getY());  // logs 3, 4

The downside is that this is a lot of boilerplate code that doesn't do very much. Why write the getters and setters rather than this?

class DirectPoint2D {
  x: number;
  y: number;
}

const pt = new DirectPoint2D();
pt.x = 3;
pt.y = 4;
console.log(pt.x, pt.y);  // logs 3, 4

At least in Java, the answer is that getters and setters encapsulate the implementation of the class and give it much greater flexibility to evolve in the future.

For example, what if you realize that for some reason it's much better to use polar coordinates internally? With the getters and setters, it's no trouble to reimplement the old API using the new internal representation:

class Point2D {
  private r: number;
  private theta: number;

  getX() {
    return this.r * Math.cos(this.theta);
  }
  getY() {
    return this.r * Math.sin(this.theta);
  }
  setX(x: number) {
    const y = this.getY();
    this.r = Math.sqrt(x**2 + y**2);
    this.theta = Math.atan2(y, x);
  }
  setY(y: number) {
    // ... similar
  }
}

Users of the Point2D class will be completely oblivious to this internal change. The code above works without change. Contrast this with DirectPoint2D. You can't make an analogous change to this version because the internals are exposed. You can't get rid of the x and y properties without making a breaking change to the API. You're stuck.

That's the story in Java, anyway, and it was also the story for JavaScript in the 1990s and early 2000s. If you use very old JS libraries (or libraries written by recent transplants from Javaland), you may still run across these sorts of getter and setter methods. After publishing my post about Google's Closure Compiler I learned that one of its goals was to inline simple methods like these.

But getter and setter methods like these are not a good idea in modern JavaScript or TypeScript. The reason is that back in 2009, ES5 introduced a new syntax for get and set methods that entirely eliminates this problem with direct property access.

Here's how you'd migrate DirectPoint2D to a polar coordinates representation using getter and setter methods:

class DirectPoint2D {
  r = 0;
  theta = 0;

  get x() {
    return this.r * Math.cos(this.theta);
  }
  set x(x: number) {
    const y = this.y;
    this.r = Math.sqrt(x**2 + y**2);
    this.theta = Math.atan2(y, x);
  }

  get y() {
    return this.r * Math.sin(this.theta);
  }

  set y(y: number) {
    // ... similar to set x
  }
}

Usage looks exactly as it did before:

const pt = new DirectPoint2D();
pt.x = 3;
pt.y = 4;
console.log(pt.x, pt.y);  // logs 3, 4

What were direct property accesses before have become method calls. But the syntax is character-for-character identical, so the caller need not be aware that anything has changed. The public properties are no longer a constraint on your class design.

The takeaway here is that it's OK to use a public property on a class in JavaScript and TypeScript. You may read warnings in books and online about how this is a bad practice, but this advice has more to do with specific limitations of Java and old-school JS than it does with modern JavaScript and TypeScript. When you write getter and setter methods in JavaScript, you're working around a problem that no longer exists.

Simple getter and setter methods are a code smell in JavaScript and TypeScript. Don't write them! If you see them in a code review, suggest replacing them with a public property and send your coworker here for an explanation of why.

One cautionary note: don't go too crazy with get and set. When you read code like pt.x = 3, you expect that this will do something like setting the x property of pt to 3. Of course, with a set method, it could do anything. It could set y instead, or it could even issue a network request. But to avoid confusion and surprise, it's best if paired get and set methods get and set the same thing, at least conceptually.

Here's a complete playground link for the last example if you want to give it a try.

In a previous post I suggested using intersections as a sort of type-level "as any". I'd personally found this technique useful on a few projects as a way of silencing type errors without losing type safety. Because you often needed to apply this trick two or three times for deeply nested types, it also led me to explore ways of reducing repetition in type-level code.

But when I started reworking that advice into an Item for the upcoming second edition of Effective TypeScript, I learned something interesting: there's usually a better way! TypeScript's infer keyword can infer quite a lot, and it offers a more direct way to achieve the same goals I talked about in those two posts without the repetition.

Those previous posts were motivated by my crosswalk library, which helps you build and use type-safe REST APIs. Using infer works in that context, too, but the difference is even more dramatic when we look at an OpenAPI Schema.

Say your API lets you create a user. (It also lets you GET a user, but I'll only show the POST here since this is already verbose.) The OpenAPI Schema might look like this:

{
  "openapi": "3.0.3",
  "info": { "title": "Users API", "version": "0.1" },
  "paths": {
    "/users": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Newly-created User",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateUserRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "age": { "type": "number" }
        },
        "required": [ "name", "age" ]
      },
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "age": { "type": "number" }
        },
        "required": [ "id", "name", "age" ]
      }
    }
  }
}

You can run this through openapi-typescript to generate TypeScript types:

/** This file was auto-generated by openapi-typescript. */

export interface paths {
  "/users": {
    post: {
      requestBody: {
        content: {
          "application/json": components["schemas"]["CreateUserRequest"];
        };
      };
      responses: {
        /** @description Newly-created User */
        200: {
          content: {
            "application/json": components["schemas"]["User"];
          };
        };
      };
    };
    // also get, etc.
  };
}

export interface components {
  schemas: {
    CreateUserRequest: {
      name: string;
      age: number;
    };
    User: {
      id: string;
      name: string;
      age: number;
    };
  };
}

Accessing these types via the path structure involves a whole bunch of indexing:

type UserResponse = paths["/users"]["post"]["responses"][200]["content"]["application/json"];

If you want to make a generic POST method, you'll quickly run into some errors:

declare function post<Path extends keyof paths>(
  endpoint: Path
): Promise<paths[Path]["post"]["responses"][200]["content"]["application/json"]>;
//         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Type '"application/json"' cannot be used to index type 'paths[Path]["post"]["responses"][200]["content"]'. (2536)

This error makes sense: TypeScript has no reason to believe that this deep sequence of index operations will work on an arbitrary type.

You can use infer to extract just what you want out of this structure:

type HttpVerb = 'get' | 'post' | 'patch' | 'delete' | 'update';
type ResponseForMethod<Path extends keyof paths, Verb extends HttpVerb> =
  paths[Path] extends Record<Verb, {
    responses: {
      200: {
        content: {
          'application/json': infer ResponseType,  // <-- the "infer"
        }
      }
    }
  }> ? ResponseType : never;

declare function post<Path extends keyof paths>(
  endpoint: Path
): Promise<ResponseForMethod<Path, 'post'>>;

const response = post('/users');
//    ^? const response: Promise<{ id: string; name: string; age: number; }>

What surprised (and impressed me) was that infer can see right through the Record helper, which is a wrapper around a mapped type.

If the endpoint doesn't support POST requests, you'll get a never type back. A type error would be better, but hopefully the never will be enough to alert the caller that something is amiss.

My previous posts would have suggested this chain of helpers instead:

type LooseKey<T, K> = T[K & keyof T];
type LooseKey2<T, K1, K2> = LooseKey<LooseKey<T, K1>, K2>;
type LooseKey3<T, K1, K2, K3> = LooseKey<LooseKey2<T, K1, K2>, K3>;
type LooseKey4<T, K1, K2, K3, K4> = LooseKey<LooseKey3<T, K1, K2, K3>, K4>;
type LooseKey5<T, K1, K2, K3, K4, K5> = LooseKey<LooseKey4<T, K1, K2, K3, K4>, K5>;

type ResponseForMethod<Path extends keyof paths, Verb extends HttpVerb> =
  LooseKey5<paths[Path], Verb, 'responses', 200, 'content', 'application/json'>;

Yikes! Compared to this intersection form, the infer approach is more direct, easier to read and more closely matches the layout of the data. And if you need to extract multiple pieces of information from a type, it's clear how to do it. This is a nice win.

So is "intersect what you have with whatever TypeScript wants" still a useful technique? You sometimes need to write & string when passing a type parameter to another generic type that expects a string:

// see previous post
type ExtractRouteParams<Path extends string> = ...;
// e.g. ExtractRouteParams<'/users/:userId'> = {userId: string}

class ApiWrapper<API> {
  apiGet<Path extends keyof API>(
    path: Path,
    queryParams: ExtractRouteParams<Path>,
    //                              ~~~~
    // Type 'Path' does not satisfy the constraint 'string'.
    //   Type 'keyof API' is not assignable to type 'string'.
    //     Type 'string | number | symbol' is not assignable to type 'string'.
    //       Type 'number' is not assignable to type 'string'. (2344)
  ): Promise<GetResponseForMethod<API, Path>>;
}

Check out TypeScript Splits the Atom for a definition of ExtractRouteParams. The problem is that we expect keyof API to be a subtype of string, but strictly speaking all TypeScript knows is that it's a subtype of PropertyKey, aka string | number | symbol. There's nothing preventing API from being string[], for example, in which case keyof API = number. Since ExtractRouteParams expects a string, this won't fly.

The best solution would be to tell TypeScript that API should only have string keys. But I'm not aware of any way to do that: writing ApiWrapper<API extends Record<string, any>> results in the same error.

In this case, using an intersection to silence the error still makes sense:

class ApiWrapper<API> {
  apiGet<Path extends keyof API>(
    path: Path,
    queryParams: ExtractRouteParams<Path & string>,  // ok
  ): Promise<GetResponseForMethod<API, Path>>;
}

When you're working with nested object types, remember that you can use infer to extract a particular type from deep inside them.

Image credit: Wikimedia Commons

As you write type declarations for generic classes, you may find that you want to make some methods available only for particular values of the generic parameter. This often comes up with wrapper objects. In the lodash utility library, for example, you can rewrite a series of function calls:

_.sum(
  _.map(
    _.filter(
      _.split('' + Math.PI, ''),
      digit => digit !== '.'),
    Number));  // result is 80

into a chain:

_.chain('' + Math.PI)
  .split('')
  .filter(digit => digit !== '.')
  .map(Number)
  .sum()
  .value();  // result is 80

The call to _.chain(val) creates a wrapper object which is eventually unwrapped by a call to .value(). This reads more naturally since the execution order matches the code order: top to bottom, left to right.

Modeling this in TypeScript presents some challenges:

• The split method should only be available on wrapped strings.
• The filter and map methods should only be available on arrays. (In the real lodash library they work on objects, too, but have different type signatures.)
• The sum method should only be available on wrapped arrays of strings or numbers.

For example, calling map on a wrapped number should be an error:

_(Math.PI)
  .map(val => val);
// ~~~ map method not available

You can start by defining the wrapper interface:

interface Wrapper<T> {
  value(): T;
}
declare function _<T>(value: T): Wrapper<T>;

(Since we're writing declarations here, we assume there's already an implementation defined elsewhere which may use different classes at runtime.)

You can verify that this wraps and unwraps values by writing a simple chain and inspecting the intermediate types in your editor:

_(Math.PI).value();
       //  ----- (method) Wrapper<number>.value(): number

As expected, this forms a Wrapper<number> and then unwraps it.

So what if you want to add a map method that's only available on arrays? If you add it directly to the Wrapped interface, it will be available on all wrapped objects, not just arrays. Perhaps a better approach is to create a specialized ArrayWrapper interface:

interface Wrapper<T> {
  value(): T;
}
interface ArrayWrapper<T> extends Wrapper<T[]> {
  map<V>(mapFn: (v: T) => V): ArrayWrapper<V>;
}
declare function _<T>(value: T[]): ArrayWrapper<T>;
declare function _<T>(value: T): Wrapper<T>;

You can verify that this gives the desired completions and errors in your editor:

_(Math.PI)  // typing "." offers "value" as the only completion
_(Math.PI)
  .map(val => val);
// ~~~ Property 'map' does not exist on type 'Wrapper<number>'.

_([1, 2, 3])  // typing "." offers "map" and "value" completions
_([1, 2, 3]).map(v => '' + v).value();  // ok, type is string[]

So far so good. Now let's add support for the sum method. You can add this to the ArrayWrapper interface:

interface ArrayWrapper<T> extends Wrapper<T[]> {
  sum(): T;
}

and this will work, but it will also let you sum an array of Date objects to get a single Date, or an array of regular expressions to get a single regular expression. These should be errors.

You could try to model this out explicitly by creating more specialized interfaces:

interface Wrapper<T> {
  value(): T;
}
interface ArrayWrapper<T> extends Wrapper<T[]> {
  map<V>(mapFn: (v: T) => V): ArrayWrapper<V>;
}
interface ArrayOfNumbersWrapper extends ArrayWrapper<number> {
  sum(): Wrapper<number>;
}
interface ArrayOfStringsWrapper extends ArrayWrapper<string> {
  sum(): Wrapper<string>;
}
declare function _(value: string[]): ArrayOfStringsWrapper;
declare function _(value: number[]): ArrayOfNumbersWrapper;
declare function _<T>(value: T[]): ArrayWrapper<T>;
declare function _<T>(value: T): Wrapper<T>;

_([1, 2, 3, 4]).sum().value();  // ok, type is number
_([1, 2, 3]).map(v => v * v).sum();
//                           ~~~
//     Property 'sum' does not exist on type 'ArrayWrapper<number>'

What went wrong? When you use map on an ArrayOfNumbersWrapper, the result reverts back to ArrayWrapper<number>, which doesn't have a sum method. You can patch this:

interface ArrayOfNumbersWrapper extends ArrayWrapper<number> {
  sum(): Wrapper<number>;
  map(mapFn: (v: number) => number): ArrayOfNumbersWrapper;
  map<V>(mapFn: (v: number) => V): ArrayWrapper<V>;
}

_([1, 2, 3]).map(v => v * v).sum().value();  // ok, type is number

But this is a losing battle. There's always going to be some combination of method calls that your series of interfaces misses. This will be a frustrating experience for your users, since a TypeScript error will be only loosely correlated with a runtime error.

Taking a step back, this tracking of types through function calls is exactly what the TypeScript compiler does and is good at. It would be better to let it figure out that the wrapped type is number[] and provide the sum method in that case, rather than having to think of every possible way you could get a wrapped number array.

The trick to doing this is to specialize methods on the type of this:

interface Wrapper<T> {
  // Methods available for all types:
  value(): T;

  // Methods available on arrays:
  map<U, V>(this: Wrapper<U[]>, mapFn: (v: U) => V): Wrapper<V[]>;

  // Methods available on specific types of arrays:
  sum(this: Wrapper<number[]>): Wrapper<number>;
  sum(this: Wrapper<string[]>): Wrapper<string>;
}

declare function _<T>(value: T): Wrapper<T>;

_(Math.PI).value();  // type is number
_([1, 2, 3]).map(v => '' + v * v).value();  // type is string[]

_([1, 2, 3]).sum().value();  // type is number
_([1, 2, 3]).map(v => v * v).sum().value();  // type is number
_([1, 2, 3]).map(v => '' + v + v).sum().value();  // type is string
_([1, 2, 3]).map(v => '' + v + v).map(Number).sum().value();  // type is number

Everything works! The type checker is indeed quite good at tracking types: even trickier cases we didn't cover before, like mapping from strings to numbers and back, work as expected. What's more, this code is significantly clearer than our previous attempts. There's only a single Wrapper interface. As you add more and more specialized methods, the returns on this simplicity compound.

The only downside is that the error you get from calling an unavailable method is a bit cryptic:

_(Math.PI).map(val => val);
// ~~~~~~~ The 'this' context of type 'Wrapper<number>' is not assignable
//         to method's 'this' of type 'Wrapper<{}[]>'.
//         Type 'number' is not assignable to type '{}[]'.

But at least there's an error. Hopefully there are enough details in it to make the user realize that the map method only applies to arrays.

If you ever find yourself building a complex series of interfaces to model behaviors in a type declarations file, ask whether you could model the same thing by specializing on a generic type parameter. Overloading on the type of this will let TypeScript do the hard work for you. It'll be more accurate and a whole lot simpler!

Things to Remember

• Specify a narrower type for this to specialize generic methods in interfaces.
• Avoid building elaborate series of wrapper types. TypeScript is better at this!

Why was this cut from the book?

This item was inspired by Daniel Rossenwasser's comment on my 2017 blog post A typed chain: exploring the limits of TypeScript. The technique is perfect for typing _.chain and other generic wrappers. So why did I cut it? It's a complex technique to motivate, and I struggled to think of any other situation where it would be useful. Complex and not that useful? Sounded like a good one to drop!

I don't think the technique of specializing on this is widely-known, so perhaps this blog post can inspire some creative new use cases! Have you every run across this trick? Do you have a use case? Let me know in the comments!

Behind this application was an exciting new tool that Google had built for creating large JavaScript applications: the Closure Tools (that's Closure with an 's', not Clojure with a 'j', which is a different thing). This included the Closure Compiler (CC), a JavaScript source-to-source compiler that did type checking. Sound familiar?

Unless you've worked on frontend at Google at some point in the past 20 years, it's unlikely that you've ever encountered the Closure Compiler. It occupied a similar niche to TypeScript, but TypeScript has absolutely, definitively won.

Still, it's interesting to revisit CC for a few reasons:

1. By looking at a system that made different high-level design decisions than TypeScript, we can gain a deeper appreciation of TypeScript's design.
2. It shows us missing features from TypeScript that it might not have even occurred to us to want.
3. It's an interesting case study in the history of JavaScript.

In other words, the saga of the Closure Compiler gives us some perspective. TypeScript has become so ubiquitous that it's sometimes hard to imagine any other way of adding a type checker to JavaScript. The Closure Compiler shows us that the design space was larger than it looks in retrospect.

I wrote Closure-style JavaScript at Google most heavily from 2012–14. This post reflects Closure as it existed at that point. I'm much less familiar with how it's evolved since then.

What is the Closure Compiler?

TypeScript's motto is "TypeScript is a superset of JavaScript". Closure code, on the other hand, is JavaScript. It doesn't add any new syntax to the language.

If you've ever used TypeScript with --checkJs, it's a similar idea. Rather than adding types to JavaScript through new syntax, you add them via JSDoc-style comments.

Compare this TypeScript:

function max(a: number, b: number): number {
  return a > b ? a : b;
}

to the equivalent Closurized JavaScript:

/**
 * @param {number} a
 * @param {number} b
 * @return {number}
 */
function max(a, b) {
  return a > b ? a : b;
}

An invalid invocation of max will result in an error:

> google-closure-compiler "--warning_level" "VERBOSE" "max.js"

max.js:12:16: WARNING - [JSC_TYPE_MISMATCH] actual parameter 1 of max does not match formal parameter
found   : string
required: number
  12| console.log(max('foo', 'bar'));
                      ^^^^^

max.js:12:23: WARNING - [JSC_TYPE_MISMATCH] actual parameter 2 of max does not match formal parameter
found   : string
required: number
  12| console.log(max('foo', 'bar'));
                             ^^^^^

0 error(s), 2 warning(s), 100.0% typed
function max(a,b){return a>b?a:b}console.log(max("foo","bar"));

This is similar to what tsc does in some ways but different in others. Just like tsc, it reports type errors in your code. And just like tsc, it outputs JavaScript (the last line). At a high level, type checking and JS emit are also the two things that TypeScript does.

There are some interesting differences, too. The Closure Compiler reports that our code is "100.0% typed". Using TypeScript terminology, this is a measure of how many any types you have. (Effective TypeScript discusses using the type-coverage tool to get this information in Item 44: Track Your Type Coverage to Prevent Regressions in Type Safety.)

The other interesting difference is that the output is minified. This gets us the fundamental design goal of the Closure Compiler: producing the smallest JavaScript possible.

Minification as Design Goal

When Gmail came out back in 2004, network speeds were much, much slower than they are today. The Gmail team found that runtime JavaScript performance was almost irrelevant compared to download times (Update: this isn't quite right, see below). If you wanted to make your page load faster, you needed to make your JavaScript bundle smaller. So this is the central goal of the Closure Compiler and its "advanced optimizations" mode.

To see how this works, let's look at some code to fetch and process data from the network.

Here's an "externs" file (the CC equivalent of a type declarations file) that defines a type and declares a function:

// api-externs.js
/**
 * @typedef {{
 *   foo: string,
 *   bar: number,
 * }}
 */
let APIResponse;

/** @return {APIResponse} */
function fetchData() {}

Some interesting things to note here:

• Types are introduced via @typedef in a JSDoc comment. The APIResponse symbol exists at runtime but is not particularly useful. Just because CC is JavaScript doesn't mean that the JavaScript always makes sense.
• The declaration of fetchData includes an empty implementation. TypeScript would use declare function here, but this is not JS syntax. So CC uses an empty function body.

Here's some more code that fetches data and processes it:

// api.js
/**
 * @typedef {{
 *   longPropertyName: string,
 *   anotherLongName: number
 * }}
 */
let ProcessedData;

/**
 * @param {APIResponse} data
 * @return {ProcessedData}
 */
function processData(data) {
  return {
    longPropertyName: data.foo,
    anotherLongName: data.bar,
  };
}

const apiData = fetchData();
const processedData = processData(apiData);
console.log(processedData.longPropertyName, processedData.anotherLongName);

Because it's just JavaScript, this code can be executed directly, presumably via a <script> tag (CC predates Node.js). No build step is required and your iteration cycle is very tight.

Let's look at what happens when you compile this:

> google-closure-compiler "--warning_level" "VERBOSE" "--externs" "api-externs.js" "api.js"

let ProcessedData;function processData(a){return{longPropertyName:a.foo,anotherLongName:a.bar}}const apiData=fetchData(),processedData=processData(apiData);console.log(processedData.longPropertyName,processedData.anotherLongName);

Here's what that looks like when we unminify it:

let ProcessedData;

function processData(a) {
    return {
        longPropertyName: a.foo,
        anotherLongName: a.bar
    };
}

const apiData = fetchData(), processedData = processData(apiData);

console.log(processedData.longPropertyName, processedData.anotherLongName);

Just like TypeScript, compilation here mostly consists of stripping out type information (in this case JSDoc comments).

Now look at what happens when we turn on "advanced optimizations":

> google-closure-compiler "--compilation_level" "ADVANCED" "--warning_level" "VERBOSE" "--externs" "api-externs.js" "api.js"

var a,b=fetchData();a={h:b.foo,g:b.bar};console.log(a.h,a.g);

The output is much shorter. Here's what it looks like unminified:

var a, b = fetchData();

a = {
    h: b.foo,
    g: b.bar
};

console.log(a.h, a.g);

This is a radical transformation of our original code. In addition to mangling our variable names (apiData became b, processedData became a), the Closure Compiler has mangled property names on ProcessedData (longPropertyName→h, anotherLongName→g) and inlined the call to processData, which let it remove that function entirely.

The results are dramatic. Whereas the minified code with simple optimizations was 231 bytes, the code with advanced optimizations is only 62 bytes!

Notice that CC has preserved some symbols: the fetchData function and the foo and bar property names. The rule is that symbols in an "externs" file are externally visible and cannot be changed, whereas the symbols elsewhere are internal and can be mangled or inlined as CC sees fit.

This is fundamentally unlike anything that TypeScript does. TypeScript does not rename symbols when it emits JavaScript nor does it attempt to minify your code. Even if you run your generated JavaScript through a minifier, it won't do anything nearly this radical. It's hard (or impossible) for a minifier to know which symbols or property names are part of an external API. So mangling property names is generally unsafe. You're unlikely to get anything smaller than the 231 byte "simple optimizations" output with TypeScript.

These results generally hold up well after gzip compression, and in larger projects as well. I ported a JavaScript library to Closure in 2013 and shrank my bundle by 40% vs. uglifyjs.

This is great stuff! So why didn't the Closure Compiler take off?

The Problems with Minification as a Design Goal

The externs file was critical to correct minification. Without it, CC would have mangled the fetchData function name and the foo and bar properties, too, which would have resulted in runtime errors. Omitting a symbol from an externs file would result in incorrect runtime behavior that could be extremely difficult to track down. In other words, this was a really bad developer experience (DX).

CC introduced some extralinguistic conventions to deal with this. For example, in JS (and TS) there's no distinction between using dot notation and square braces to access a property on an object:

const a = obj.property;
const b = obj['property'];
console.log(a, b);  // exact same

This is not true with the Closure Compiler. Its convention is that quoted property access is preserved whereas dotted can be mangled. Here's how that code comes through the minifier with advanced optimizations:

console.log(obj.g,obj.property);

Note how the property names have diverged. In other words, while Closurized JavaScript is just JavaScript, it also kind of isn't.

There's another big problem with advanced optimizations: in order to consistently mangle a property name, CC needs to have access to all the source code that might use it. For this to be maximally effective, all the code you import must also be written with the Closure Compiler in mind, as must all the code that that code imports, etc.

In the context of npm in 2023, this would be impossible. In most projects, at least 90+% of the lines of code are third-party. For this style of minification to be effective, all of that code would have to be written with the Closure Compiler in mind and compiled by it as a unit.

On the other hand at Google in 2004, or 2012, or perhaps even today, that is quite realistic. At huge companies, the first- to third-party code ratio tends to be flipped. Using third-party code is more painful because there are legal and security concerns that come with it, as well as a loss of control. TypeScript's zero runtime dependencies are a good example of this.

All of Google's JavaScript was written with the Closure Compiler in mind and the vast majority of it is first-party. So advanced optimizations works beautifully. But the rest of the JS world doesn't operate that way. As soon as you pull in any dependencies like React or Lodash that aren't written with Closure Compiler in mind, it starts to lose its value.

Contrast this with TypeScript. It only needs to know about the types of existing libraries. This is all that's needed for type checking. The DefinitelyTyped project has been a monumental undertaking but it does mean that, generally speaking, you can get TypeScript types for almost any JS library. (There's a similar, though much smaller, set of externs to get type checking for popular JS libraries for the Closure Compiler.)

Stating it more directly: advanced optimizations requires that the compiler understand a library's implementation, not just its types, and that's simply infeasible given the enormous diversity of the JavaScript ecosystem.

Timing Is Everything

Google developed Closure c. 2004 but it wasn't open sourced until late 2009. An O'Reilly book on it, Closure: The Definitive Guide, came out in 2010.

In retrospect this timing was terrible. In 2010, JavaScript was just entering its period of maximum churn. JavaScript: The Good Parts came out in 2008 and ES5 codified many of its recommendations in a new "strict" mode in 2009. Node.js was first released in 2009 and npm followed hot on its heels in 2010, creating the ecosystem of JavaScript packages we know today. npm grew significantly more powerful and useful when browserify made it applicable to client-side code starting in 2011.

And finally, CoffeeScript was released in 2010. It normalized the idea of compiling an "improved" JavaScript down to regular JavaScript, as well having a build step. All of these influenced the direction of JavaScript, with ES2015 bringing some of the best elements of CoffeeScript into the language itself.

The Closure Compiler was developed in the era when JavaScript was a "bad" language that was to be avoided. CC itself is implemented in Java, which made it harder to integrate into an all-JS toolchain. And it attempted to add missing parts to JavaScript. Since it couldn't add new syntax, it used special functions: goog.provide and goog.require provided a module system and goog.inherits smoothed out the process of creating class hierarchies. These were real JavaScript functions that did something at runtime. If memory serves, goog.require might inject a <script> tag!

There were a few problems with this. One was that all the goog functions reinforced the idea that this was a tool primarily built for Google. Putting company names in your packages is common in Java, so presumably it felt natural for the Closure developers. But it's not in JavaScript. We just import 'react', not "facebook/react".

Second, it made it awkward when JavaScript itself gained a module system and class keyword. TypeScript faced some of these problems in its early days, too. It used to have its own module system and class system, but in the interests of ecosystem coherence it deprecated them in favor of the native solutions. TypeScript now lets JavaScript be JavaScript and innovates only in the type system.

This transition happened early in TypeScript's history, but late in the Closure Compiler's. Presumably adaptation was harder.

Why TypeScript won

TypeScript came along at a better time and has been able to adapt to the changes in JavaScript and its ecosystem over the past decade. It's self-hosted (tsc is written in TypeScript) and distributed with npm.

TypeScript also won by focusing more on developer tooling. The Closure Compiler is an offline system: you run a command, it checks your program for errors, then you edit and repeat. I'm not aware of any standard Closure language service. There's no equivalent of inspecting a symbol in your editor to see what CC thinks its type is. TypeScript, on the other hand, places as much emphasis on tsserver as tsc. Especially with Visual Studio Code, which is written in TypeScript and came out in 2015, TypeScript is a joy to use. TypeScript uses types to make you more productive whereas Closure used them to point out your mistakes. No wonder developers preferred TypeScript!

(Google engineers are no exception to this. In the past decade they've adopted TypeScript and migrated to it en masse. You can read about one team's experience porting Chrome Devtools from Closure to TypeScript).

TypeScript did a better job of engaging the JavaScript community. TypeScript is developed and planned in the open on GitHub. They respond to bug reports from anyone and treat non-Microsoft users as important customers. The Closure Tools, on the other hand, were very much an open source release of an internal Google tool. Google was always the primary consumer and external users were mostly on their own. The goog namespacing reinforced this.

Closure's idea of "it's just JavaScript" was appealing because it let you avoid a build step. This remains appealing in 2023: some TypeScript users still prefer to use JSDoc-style type annotations and --checkJs. But using JSDoc for all types is awkward and noisy. Ergonomics do matter and TypeScript's are undeniably better.

Finally, TypeScript's central idea of "JavaScript + Types" has held up better than the Closure Tools' idea of "minification" and "it's just JavaScript". While shaving bytes off your bundle was all the rage in 2008, our connections are much faster now and, while bundle size still matters, it is not as critical as it was back then. Closure forced a uniform system on you and all your dependencies in order to achieve extreme minification. We've given up that goal in exchange for more flexibility.

There's a general principle here. I'm reminded of Michael Feathers's 2009 blog post 10 Papers Every Developer Should Read at Least Twice which discusses D.L. Parnas's classic 1972 paper "On the criteria to be used in decomposing systems into modules":

Another thing I really like in the paper is his comment on the KWIC system which he used as an example. He mentioned that it would take a good programmer a week or two to code. Today, it would take practically no time at all. Thumbs up for improved skills and better tools. We have made progress.

The KWIC system basically sorts a text file. So are we correct to laud our progress as software developers? This would be a one-liner today:

console.log(
  fs.readFileSync('input.txt')
  .split('\n')
  .toSorted((a, b) => a.localeCompare(b))
  .join('\n')
);

But think about what makes this possible:

• We're assuming that the entire file fits in memory, which almost certainly would not have been true in 1972.
• We're using a garbage collected language, which would have been a rarity back then.
• We have an enormous library at our fingertips via node built-ins and npm.
• We have great text editors and operating systems.
• We have the web and StackOverflow: no need to consult a reference manual!

All of these things are thanks to advances in hardware. The hardware people give us extra transistors and the software people take most of those for ourselves to get a nicer development process. So it is with faster network speeds and the Closure Compiler. We've taken back some of that bandwidth in exchange for a more flexible development process and ecosystem.

Conclusions

There were discussions of adding minification to TypeScript in the early days but now optimized output is an explicit non-goal for the language. If you've ever thought that type-driven minification would be a beautiful thing, the Closure Compiler is a fascinating data point. It can be tremendously effective, but it also comes at an enormous cost to the ecosystem.

The Closure Compiler as a standalone external tool seems mostly dead (the closure playground is badly broken and says "Copyright 2009"!). But it still lives on at Google. Since they've adopted TypeScript, they can use the Closure Compiler for just what it does best: minification. To make this work, Google has built a tool, tsickle, that makes TypeScript produce Closurized JavaScript. True to form, this tool is open source but pretty inscrutable to an outsider. It may be used by Angular but I couldn't tell.

Hopefully this was an interesting lesson in JavaScript history! The Closure Compiler represents an alternative path that the JavaScript ecosystem could have taken, with different principles and different tradeoffs.

There's a lively discussion of this article on Hacker News. In particular Paul Buchheit (the creator of Gmail!) points out that runtime performance was very much a goal of the Closure Compiler and inlining/dead code removal was a way to achieve this. It's hard to get back in the pre-JIT IE6 mindset where every getter comes with a cost! I don't think this changes the conclusions of the article. Also, the Closure Compiler is not the Google Web Toolkit (GWT).

Over many years of working with TypeScript and Postgres, one of the most popular open source databases, I've developed some opinions and hard-earned knowledge. This post lays out the decision tree you face as you work with TypeScript and a database and presents my preferred techniques.

If you'd like to watch in video form, I gave a 30 minute talk on this at last year's TS Congress. Watching it again 16 months later, I have to say that it's pretty good! It goes into more detail on each option than this post does. You can follow along with the slides and sample repo if you like.

The DB Schema looks something like this:

CREATE TABLE book(
  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  title varchar NOT NULL,
  publication_year integer NOT NULL,
);

Raw SQL + Hand-coded types

Say you write a query to fetch all the books in your database using node-postgres:

const books = await dbPool.query(`SELECT * FROM book`);
//    ^? const books: any[]
for (const book of books) {
  console.log(book.title, book.year);
}

This code has a bug: it should be book.publication_year, not book.year. But because the the query returns an any type, TypeScript hasn't been able to flag it. No problem, we'll just write out an interface:

interface Book {
  id: string;
  title: string;
  publication_year: number;
}
const books = await dbPool.query<Book>(`SELECT * FROM book`);
//    ^? const books: Book[]
for (const book of books) {
  console.log(book.title, book.year);
  //                           ~~~~ Property 'year' does not exist on type 'Book'
}

Voila! TypeScript flags the error and we can easily fix it by changing year to publication_year.

This is a big improvement over untyped code, and this tends to be the approach that developers fall into by default if they don't step back back and think about the problem of TypeScript and SQL.

But this approach also has a big problem: there's no single source of truth. If the database changes (say because of a migration) then our TypeScript types won't update. And nothing ensures that they types are accurate to begin with.

On the other hand, this approach has some strengths: it doesn't introduce any abstractions (you're just writing TypeScript and SQL) and it doesn't introduce any sort of build step into your project.

Pros and Cons of Raw SQL and Hand-Coded Types

• Pros
  • Zero abstraction
  • You do get some type safety
• Cons
  • Repetition between DB + TS
  • Types don't stay in sync:
  • No Single Source of Truth

ORMs (TypeORM, Sequelize, Waterline, Prisma, …)

So you want a single source of truth. The first big question you have to ask is "where is the source of truth?" Since we're dealing with TypeScript and SQL, the two obvious choices are… TypeScript and SQL. If you want to make TypeScript your source of truth, then you'll be using an ORM, aka an Object-Relational Mapper.

Here's how we might define a Book table using TypeORM:

import { Entity, PrimaryGeneratedColumn, Column } form 'typeorm';

@Entity()
export class Book {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column()
  title!: string;

  @Column('integer', {nullable: true})
  publication_year!: number | null;
}

TypeORM handles the messy business of converting this class to SQL for us. And now we can use the Book class in our code:

const books = await entityManager.find(Book);
//    ^? const books: Book[]
for (const book of books) {
  console.log(book.title, book.publication_year);
}

And we have types! There's a single source of truth. Another nice property of ORMs is that they can often generate migrations for you, so that you don't have to write the SQL out by hand.

On the downside, ORMs are the classic example of a "leaky abstraction". The theory with an ORM is that you can treat the database as an implementation detail and you can just work in TypeScript. But in practice, that doesn't really work. To use an ORM effectively, you need to know SQL, you need to know TypeScript, and you need to know how to use the ORM. If you want to fine tune the performance of a query, say, you'll wind up working with your ORM to try to produce a really specific SQL query, which is just adding overhead over writing the SQL query directly. And if you work in an environment where there are multiple users of your database, perhaps working with other languages, then they'll feel like second class citizens since the database certainly won't be an implementation detail for them.

Using an ORM won't make you popular on Hacker News, but they are undeniably popular. You probably already know how you feel about them. Personally I'm not a fan, but they are ubiquitous and you'll eventually find yourself working on a project that uses one.

Pros and Cons of ORMs

• Pros
  • Keep your types & DB in sync: single source of truth!
  • Generate migrations for you
  • Low boilerplate for simple queries
  • ORMs are undeniably popular
• Cons
  • The classic "leaky abstraction": You need to know SQL, TypeScript, and your ORM
  • Performance is confusing
  • They make other users of your DB second-class citizens
  • Lots more churn in ORMs than in databases

Schema Generator (e.g. pg-to-ts)

So what if you're not going to use an ORM? Then your database will be the source of truth. But it's undeniably useful to have a TypeScript version of your database schema. So you can generate TypeScript from your live database. A tool that does this is called a Schema Generator, and they're an essential part of any system that uses the database as the source of truth.

The granddaddy in this space is SchemaTS, which got a lot of GitHub stars but was abandoned in 2018. So lots of people forked it. One popular one was PyST/SchemaTS, but that was abandoned in 2020. I needed to add some Postgres-specific features so I forked that one, updated it and re-released it as pg-to-ts. Give it a star! 😊

The idea with pg-to-ts (or any other Schema Generator) is that you point it to your live database and it outputs a dbschema.ts file:

$ npx pg-to-ts generate -c 'postgres://dbhost/database' --output dbschema.ts

Here's what the dbschema.ts file looks like:

// Table book
export interface Book {
  id: string;
  title: string;
  publication_year: number | null;
}
export interface BookInput {
  id?: string;
  title: string;
  publication_year?: number | null;
}

For each table in your database you get two types: one for a complete row (i.e. the result of a SELECT statement) and one with just the properties you need to insert a new row (note the optional fields).

You can use this to adapt the "Raw SQL + Hand-coded types" example code:

import { Book } from './dbschema';
const books = await dbPool.query<Book>(`SELECT * FROM book`);
//    ^? const books: Book[]
for (const book of books) {
  console.log(book.title, book.publication_year);
}

This is exactly the same as the hand-coded version, except that we don't have to write the types by hand. Superficially this doesn't seem like a big change, but it's actually a huge win! In practice you'd generate dbschema.ts on your CI to make sure it stays in sync with the database.

This does add a build step. But schemas tend to change less frequently than code, so in practice most changes don't require this step.

Another issue is that we still had to manually add the Book annotation to our query to get the desired type out. For a more complex query, you may wind up writing duplicating logic with complicated Pick expressions or new interfaces based on your dbschema.

Schema Generators are a key building block for other tools (more on that below), so if you're not using an ORM then you should absolutely use a Schema Generator.

Pros and Cons of Schema Generators

• Pros
  • Keep your types & DB in sync
  • Key building block (more on this later!)
• Cons
  • Add a build step
  • Still have to manually add types to queries
  • Some DB types are hard to model in TS (e.g. integers)

Query Builder (e.g. knex.js)

The next question to ask is whether you want to write raw SQL or use a query builder. Probably the most popular query builder for TypeScript is knex.js. Here's what it looks like:

import { knex } from 'knex';
const knexDb = knex({ client: 'pg', connection: 'postgres://...' });

const books = await knexDb('book').select();
//    ^? const books: Book[]

A type! How does this work? Assuming you've run pg-to-ts to generate a schema, you can tell Knex about it using a type declaration:

import { knex } from 'knex';
import { Book } from './dbschema';
declare module 'knex/types/tables' {
  interface Tables {
    book: Book;
  }
}

This is the bridge between the Schema Generator and the Query Builder and it powers the type generation.

It's great that we get accurate types without having to write them out ourselves. You can generate much more complex queries using Knex.js and generally it will do a good job of inferring accurate types.

So what's the downside? Just as with ORMs, Query Builders are a classic example of a leaky abstraction. As your queries get more and more complicated, it becomes less clear that writing them with a query builder is any simpler than it would be to write them as raw SQL.

Pros and Cons of Query Builders

• Pros
  • With schema generation, they get you accurate types for your queries.
  • Less context-switching between languages.
  • No added build step (beyond schema generation)
• Cons
  • Another "leaky abstraction": You need to know TS, SQL, and your Query Builder

SQL → TS (e.g. PgTyped)

If you're not going to use a Query Builder, then you have another option: a tool reads your raw SQL queries, tests them against your live database and outputs types. This like a Schema Generator, but for your individual queries, not your database as a whole. The best example of this is PgTyped.

Here's what a query looks like with PgTyped:

import { sql } from '@pgtyped/query';

const getBooks = sql`SELECT * FROM book;`;

const books = await getBooks.run(/* query parameters */ undefined, dbPool);
//    ^? const books: any

What? any!? What's the point of that?

With PgTyped you have another step: you need to run the pgtyped command to get types for your query:

$ yarn run pgtyped -c config.json
Processing src/index.ts
Saved 1 query to src/index.types.ts

PgTyped read our tagged SQL query, inspected it against our live database (configured in config.json) and produced a types file:

/** Types generated for queries found in "src/index.ts" */

/** 'GetBooks' parameters type */
export type IGetBooksParams = void;

/** 'GetBooks' return type */
export interface IGetBooksResult {
  id: string;
  publication_year: string | null;
  title: string;
}

/** 'GetBooks' query type */
export interface IGetBooksQuery {
  params: IGetBooksParams;
  result: IGetBooksResult;
}

PgTyped has produced two interfaces: one for query parameters (we have none, so this is void) and one for the results of our query. The third interface bundles these up for us. We can plug these back into our original code to get types:

import { sql } from '@pgtyped/query';
import { IGetBooksQuery } from './index.types';

const getBooks = sql<IGetBooksQuery>`SELECT * FROM book;`;

const books = await getBooks.run(/* query parameters */ undefined, dbPool);
//    ^? const books: IGetBooksResult[]

Since it runs against your live database, PgTyped doesn't require a DB Schema. But with TypeScript's structural typing system, the IGetBooksResult interface is compatible with Book, so you can freely interchange them. You may wish to wrap your query to consistently use the DB Schema type.

PgTyped shines with more complex queries. You can use any features of PostgreSQL and PgTyped will follow along. There's no abstraction here, you're just writing SQL.

What are the downsides? As with other non-ORM tools, PgTyped does add a build step that you'll need to run as part of your development flow and on your CI (to make sure your types and queries stay in sync). Sometimes the types you get back aren't perfect, there are some issues around nullability. While the types are usually accurate, it can feel a little "duck typey" to have so many distinct but compatible types floating around. And finally, it's a lot of ceremony for simple queries like SELECT * FROM book.

Pros and Cons of PgTyped

• Pros
  • You get types for your queries, however complex they are
  • Zero abstraction: you're just writing SQL
• Cons
  • Not all types can be accurately derived this way (nullability issues)
  • Adds a build step
  • A little "ducky" w/o dbschema
  • Lots of fuss for simple queries

SQL→TS + a smidge of query building (zapatos, @databases, PgTyped + crudely-typed)

Finally, we get to my preferred approach! A Schema Generator produces the best-looking types and a Query Builder works with that schema. PgTyped excels at complex queries where you'd rather write raw SQL. So the idea here is to use a minimal, TypeScript-first query builder that won't tempt you into writing complex queries with it because it doesn't support them. You should be using PgTyped for those, anyway.

Enter: crudely-typed!

crudely-typed (which I built at my last job) is a query builder that generates only relatively simple queries with a focus on working with your dbschema to get perfect types. Here's what it looks like:

import {TypedSQL} from 'crudely-typed';
import {tables} from './dbschema';  // <-- output of pg-to-ts

const typedSql = new TypedSQL(tables);
const booksTable = typedSql.table('book');
const getBooks = booksTable.select();
//    ^? const getBooks: (db: Queryable) => Promise<Book[]>
const books = await getBooks(dbPool);
//    ^? const books: Book[]

You still have to regenerate dbschema.ts when your DB Schema changes, but there's no build step or overhead for the simple queries that crudely-typed supports. These include the basic CRUD (Create, Read, Update, Delete) queries as well as some very minimal support for 1-1 joins. Because it knows about your DB Schema, you'll get nice-looking type signatures on your functions:

const updateBook = bookTable.updateByPrimaryKey();
//    ^? const updateBook:
//          (db: Queryable, where: { id: string; }, update: Partial<Book>)
//          => Promise<Book | null>

In practice this covers 90+% of the SQL queries that you run in most applications. For the remaining 10% you can fall back to using PgTyped. The net effect is that you have a single source of truth (your database) and you get accurate TypeScript types with relatively minimal fuss.

While I've never personally used them, I believe zapatos and @databases follow a similar approach.

Pros and Cons of hybrid Schema Generator + Query Builder / PgTyped

• Pros
  • Zero abstraction/overhead for complex SQL queries (PgTyped)
  • Minimum fuss, dbschema types for simple queries (crudely-typed)
• Cons
  • Adds a build step
  • You might be tempted to put logic in JS instead of SQL, i.e. run 10 crudely-typed queries instead of one SQL query.

Conclusion

Here's the final decision tree from my slides:

There are no perfect choices here. Depending on how you feel about ORMs and Query Builders, you'll wind up in a different place. Regardless, the key thing is to make a conscious, informed decision about how you want to combine TypeScript and SQL. However you do it, try to have a single source of truth.

The final, hybrid option is where I've wound up after years of dealing with this problem. How do you like to work with databases in TypeScript? Let me know in the comments!

Three years ago I recommended using --noUnusedLocals and ts-prune to find dead code and dead types in your projects. ts-prune worked well enough, but it's now in maintenance mode and won't be receiving updates. This is a fine decision and it's the responsible thing to do when you no longer plan to maintain an open source project (I sometimes struggle with this!).

While ts-prune was effective at its core job, it always had a few shortcomings: it couldn't detect unused dependencies or mutually recursive dead code. It also made no attempts to understand whether your test code was alive or dead. So when I noticed that Josh's template-typescript-node-package was using a new tool called Knip, I was intrigued. Could this be the dead code removal tool of my dreams?

Basically, yes! knip uses the same sort of mark-and-sweep algorithm as ts-prune to find dead code (see my previous post for why this is what you want). But it's much more ambitious in the sorts of issues it tries to find:

• It will report unused dependencies and even devDependencies from your package.json. Removing these can be a huge win since it reduces your package size and eases the burden of keeping up to date with the latest versions.
• It will report files that are never imported by non-test code.
• It will report missing dependencies. This can happen if you depend on A which depends on B. You import something from B and it works, but you didn't list it in your dependencies. If you ever remove the dependency on A, this will be a problem. Best to depend on B directly if you use it directly.
• It will report duplicate exports.
• It will report unused class members and enum members.

Because of the enormous diversity of JS/TS libraries and tools, you'd expect that explaining your project setup to a tool like knip would involve writing a complicated configuration file. But that's usually not the case. knip's models this enormous diversity with an enormous collection of plugins. Chances are that your test runner and framework are already on the list.

Give knip a try! You might be surprised at the dead code you've accumulated. You can use this PR as a template for setting it up in a project. Once you get down to zero errors, add knip to your CI to ensure that you never have dead code again!

Performance Improvements

When you hear "new TypeScript version", the natural tendency is to think about new language features. But what would you be more excited about: an exciting new feature like template literal types or a 10% faster compiler? Sorry, you can't have both!

The TypeScript team takes compiler performance incredibly seriously and every single set of release notes includes a few performance optimizations. A recent theme has been improving build times for projects that use complex libraries like Material-UI. The 5.1 release includes several optimizations that add up to a big win.

As readers of this blog may recall, Effective TypeScript is itself type-checked using literate-ts. The idea is that when new versions of TypeScript come out, I can quickly check whether any of the hundreds of code samples in the book produce new and unexpected errors. This is a great confidence booster that my book still matches reality, but it also means that Effective TypeScript can serve as a good gauge of what's changed between releases.

First let's look at performance:

• Checking Effective TypeScript (TS 5.0.4): 180.6s average
• Checking Effective TypeScript (TS 5.1.3): 170.9s average

That's about a 5% speedup. Not bad!

Improved Error Messages

literate-ts is very sensitive to how error messages and types display. TypeScript 5.1 includes a nice change in how type errors on return statements are displayed that didn't make it into the release notes. In previous versions of TypeScript, if you returned an expression of the wrong type, you'd get the dreaded red squiggles under both the return keyword and the entire expression. For multiline expressions, this could be a lot of red!

With TypeScript 5.1, the red squiggles only appear under the return keyword:

This is less distracting and makes it easier for you to inspect your code to find the source of the error. Not a huge change, but a nice win nonetheless. Next time you're debugging a type error in a return statement, thank Mateusz Burzyński for the change!

New Errors

Upgrading TypeScript often uncovers existing mistakes in your code and TS 5.1 was no exception. There was one new error that came up in a few of my projects.

TypeScript has long flagged duplicate keys in object literals:

const obj = {
    foo: 12,
    bar: 34,
    foo: 56,
//  ~~~ An object literal cannot have multiple properties with the same name.
};

But if you used computed keys, this error would go away:

const FOO = 'foo';
const BAR = 'bar';

const obj = {
  [FOO]: 12,
  [BAR]: 34,
  [FOO]: 56,  // (not an error in TS 5.0)
};

With TS 5.1, this is an error:

const obj = {
  [FOO]: 12,
  [BAR]: 34,
  [FOO]: 56,
// ~~~~ An object literal cannot have multiple properties with the same name.
};

This check only occurs for single-valued literal types.

Notes on other changes

The "headline" features in the official release notes for TS 5.1 are mostly niche changes that won't affect many users immediately. Here's a quick rundown:

• Easier Implicit Returns for undefined-Returning Functions I've never personally run across a function that was declared to return undefined rather than void. But if you work with such functions, your life gets easier with TS 5.1.
• Unrelated Types for Getters and Setters This seems like a bad idea though as the CSS example in the release notes makes clear, this is an established pattern in the wild that TypeScript needs to model. I tend to avoid getters and setters (and classes in general). This relates to Effective TypeScript's Item 29: Be Liberal in What You Accept and Strict in What You Produce.
• Decoupled Type-Checking Between JSX Elements and JSX Tag Types This seems quite in the weeds, but the gist is that it's future-proofing for async React components, which may land sometime in the future. When these eventually land, we'll be happy that TypeScript supports them out of the box.

I was extremely excited about one other change in the TypeScript 5.1 RC that sadly got cut for the release: a "move to existing file" refactor. There's a nice video of this in action in the RC release notes. This has been a long-standing and much-upvoted feature request. You can move a symbol to a new file, but not to an existing file.

I have a workaround, but it's a bit gross. Say you want to move a symbol to an existing file src/utils/my-utils.ts. Instead, move it to a new file src/utils/new-file.ts. This will update all the imports for the symbol to point to the new file. Then cut/paste the definition of your symbol into my-utils.ts, delete new-file.ts and run a big Find/Replace to update all the imports:

git ls-files | xargs perl -i -pe 's,new-file.ts,my-utils.ts,`

Like I said, gross! Hopefully this feature lands more permanently in TypeScript 5.2.

Conclusions

TypeScript 5.1 is not a major release when it comes to new language features, but it does include some performance wins, it may catch some new errors in your project, and it lays the groundwork for more changes in the future. Keep your eyes out for the TypeScript 5.2 beta which should be landing any day now and looks to have some exciting new features.