Really Advanced Typescript Types (2023)

In my last article, I introduced the idea that Typescript is ever evolving to accommodate different personas. Today, I dive into a great deal of detail of how Tableau developers embrace their inner mathematician and fully leverage Typescript’s type system. We’re going to explore a number of advanced building blocks including custom compilation errors, surprising ways to use generics, and constructing type sets and type maps using a builder based on partial evaluation rather than a mutable class. These types allow us to enforce complex compile-time invariants, but I’ll cover how we create these invariants in more detail in a future article.

Much of Typescript’s value proposition is adding rigidity and order to the loosey-goosey world of JavaScript. From a product perspective, the compiler is the first line of defense against defects. Static typing enforces contracts, which prevent certain classes of defects. Usually these contracts are fairly mundane:

• Don’t give a string to Math.sin.
• That injected dependency is guaranteed to at least implement a set of methods.
• Don’t mutate this readonly field.
• No, don’t give that possibly null thing to that method.

These contracts obviate certain boilerplate checks and serve as a free set of tests you would otherwise have to write in a dynamically typed language. If you enable strict null checks, you don’t need to check for your function receiving a null or undefined value (unless you allow it), much less unit test it. Usually. I don’t know how many hours I’ve wasted in life reading Java code that throws when constructor parameters are null, never mind the hours I’ve spent debugging when they don’t fail fast. But Typescript’s type system doesn’t stop at null checks; you can enforce more complex rules in your application.

Our first stop: branding and custom compiler errors.

While first authoring ts-checked-fsm, a state machine library that gives you compile-time correctness guarantees, I found the need to intentionally cause compilation failures if the consumer violated some invariants. For example, when the user declares a transition in their state machine between states that don’t exist, this should result in a compilation failure. Another simple but contrived example: suppose I want to write a function that refuses to accept an object without the key “ponies.” You can do this with a simple generic constraint:

const yayPonies = <T extends {ponies: 'yay'}>(ponylike: T) => {}// Argument of type 'string' is not assignable to parameter of type 
// '{ ponies: "yay"; }'.(2345)
yayPonies('no ponies :(')

The error message in this simple example is fairly clear, we didn’t put a pony on it. But in more complex cases, the errors can become inscrutable and nothing stands out as to what you did wrong. Additionally, I don’t think type constraints are general enough to do the opposite: block objects that do have a pony.

A simple conditional type and illegal assignment help us keep the ponies out of our function:

const booPonies = <T>(p: keyof T extends 'pony' ? never : T) => {}
booPonies('no ponies') // Good// Type 'string' is not assignable to type 'never'.(2322)
booPonies({pony: 'neigh'})

Why does this work? never is a special type usually used to indicate the type of a value in an impossible situation: a default case in an exhaustive switch or the return type of a function that never returns (e.g. it always throws or has an infinite loop). However, it also has other uses (as we’ll see later). never is a bottom type with two properties:

• No type except never itself extends never, hence no type assigns to never (other than never itself).
• never extends all types, hence you can assign it to anything.

The first property is the reason compilation fails in the above example; you’re trying to assign an input type T to never because the conditional has found that T has a pony key. Note this example also keeps all the ponies out regardless of their type whereas using a generic constraint can only keep string ponies in. While this never coercion trick does usually succeed in causing a compilation error, an important exception is if T is actually never. If it is, the assignment will succeed due to the second property. This can come up when we start using type sets later on. Additionally, the errors are confusing to those not initiated in our type-loving-pony-hating ways (note: I don’t actually hate ponies).

To help out the poor devs that have to use your APIs know why they’re doing something wrong, we’d like to give an error message better than Something can't be never. To improve on this, we’ll use a technique called branding:

type ErrorBrand<Err extends string> = Readonly<{
 [key in Err]: void;
}>;const booPonies = <T>(
 ponies: keyof T extends 'pony' 
 ? ErrorBrand<'No ponies allowed!'> 
 : T
) => {}booPonies('no ponies') // Good
booPonies({pony: 'neigh'}) // ヽ(ಠ_ಠ)ノ

By slapping a void member on a type, we’ve ensured nothing you can actually instantiate will assign to it. Thus, assignment will fail unless consumers do some adversarial casting. Since the key of the void member appears in the type, it effectively serves as the true meaning as to what you did wrong when you ignore a bunch of yada yada:

Argument of type '{ pony: string; }' is not assignable to parameter of type 'Readonly<{ "No ponies allowed!": void; }>'.
 Object literal may only specify known properties, and 'pony' does not exist in type 'Readonly<{ "No ponies allowed!": void; }>'.(2345)

If you ignore everything in the message other than ‘No ponies allowed!’ part, the error indicates what needs fixing. A throw types proposal would obviate this trick and deliver cleaner messages.

Other implementations of this trick simply attempt to assign to a string literal, which usually does work. The error message is a little cleaner, but has a corner case that comes up in some of our later tricks. Namely:

type AssertIsAnimal<T> = T extends 'dog' | 'pony' ? T : 'Not a pony';
const barn = <T>(animal: AssertIsAnimal<T>) => { }barn('Not a pony') // Compiles because T assigns to the
 // "failure" branch.

In the above snippet, 'Not a pony' does not extend 'dog', so rather than becoming a 'T', type binds to 'Not a pony'. However, since the type 'Not a pony' is assignable to type 'Not a pony', you don’t get a compilation failure.

While it might be unlikely a developer would do this, I find reserved values distasteful.

Those familiar with Typescript (or Java, or C#…) know that generic type arguments serve as a way of abstracting behavior across a variety of types. For example:

const identity = <T>(val: T): T => { return val; }
const y = identity(7);

This trivial function returns the same value as its single input parameter. The return type is also the same as its input type; typeof y resolves to 7. This happens because the type literal 7 is the narrowest type that describes val and identity returns the same type.

While maybe not immediately obvious, generics in Typescript are extremely flexible.To merely state things you can do with generics understates their power, so I’ll instead list misconceptions about limitations that generics in Typescript do not have:

1. The number of type arguments to a function is not necessarily equal to the number of parameters:

type MyThing<T, U> = T & U;
type foo = <T,U,V,W,X,Y,Z>(x: MyThing<T, U> extends V ? W: X) => Y|Z; // Legal

The number of type arguments in the above example illustrates that one can use generics for things far less mundane than the 1:1 type substitution. This misconception is not unique to Typescript either: Java and Rust (among others) allow for at least composing generics into composite types. E.g. Java’s MapEntry<K, V>. However because Typescript allows unions, intersections, conditionals, infer, and lots of other type features, using lots of type parameters can be very powerful.

2. Functions returned by other functions need not be non-generic. In other words, functions may return generic functions:

const f = <X extends number>() => {
 return <Y extends number>(x: X, y: Y) => {
 return x + y;
 }
}const foo = f<8>();// typeof foo is (x: 8, y: 7) => number
foo(8, 7);

In the above contrived example, we’re currying the generic parameters rather than the function parameters. When invoking foo, the type of X is 8 and the type of Y is 7 (X and Y are type literals). This observation is essential for some of the things presented later.

3. When declaring function signature types, type arguments are not limited to the left hand side of the =:

type Foo<T> = <U extends number>(x: T, y: U) => number;
const foo: Foo<5> = (x, y) => x + y;
foo(5, 7); // Fine
foo(5, 8); // Fine
foo(6, 8); // Illegal, type 6 does not extend type T=5

In this example, the type of the foo as we’re invoking it the first time is (x: 5, y: 7) => number. When declaring an argument on the left hand side of the =, the type parameter resolves to a concrete type when we assign a value to the type’s variable. When declaring a type argument on the right hand side (RHS) of the = for a function type, we defer resolving to a concrete type until we invoke the function. Furthermore, RHS type assignments persist only for a single invocation; during the second invocation foo’s U type parameter resolves to 8. The third invocation fails to compile because we’ve already bound T to 5 when we assigned foo on line 2.

This feature is effectively a corollary to expressing the second observation (i.e. that functions can return generic functions) with types.

We’ll exploit all three of these observations quite heavily later on.

A set is simply a collection of items. Some sets have infinite items. Some do not. Some are interesting. Some are not. Historically, type theory and set theory have an intertwined lineage and shared purpose: to be the fundamental mathematical atom upon which you can derive every provable statement. A type describes the set of all values assignable to the type, which is why type intersections and unions are confusing. This confusion arises because types in Typescript are also sets of other types. The string type is the countably infinite set of all strings, while number is the finite set of all IEEE-754 doubles (except NaN and Infinity [kinda]). In addition to these built-in type sets, we can build custom finite sets in Typescript using the | type operator.

Generally speaking, for sets to be useful to us, we need a few operations. Firstly, we need to be able to describe ∅, the empty set. The empty set is analogous to the number zero for set theory. Empty set is defined by the following property:

∀ 𝐀: 𝐀 ⋃ ∅ = 𝐀

That is, if you try to combine the empty set with any other set, you don’t change anything.

In Typescript, there is such a type that behaves like ∅: never. In the below example, we demonstrate (but don’t prove) some of these properties on arbitrary types:

// Demonstrate ∀ 𝐀: 𝐀 ⋃ ∅ = 𝐀
type A<T> = [T | never] extends [T] ? true : false;
type B<T> = [T] extends [never | T] ? true : false;
type Aa = A<'a' | 'b'> & B<'a' | 'b'>; // true// Demonstrate ∀ 𝐀: 𝐀 ⋂ ∅ = ∅
type C<T> = [T & never]
type Ca = C<'a' | 7>; // [never]// Demonstrate ∀ 𝐀: ∅ ⊆ 𝐀
type D<T> = [never] extends [T] ? true : false;
type E = [never] extends [never] ? true : false;
type Da = D<'a' | symbol | 7> & E // true

Aside: we wrap T in a tuple to stop type distribution.

The second thing we need for sets to be useful for us in Typescript is to be able to check that something is a subset of another set. We do this using the extends keyword in a conditional type (generic constraints are more limited, as previously discussed).

The final thing we need to express to be able to usefully construct sets in Typescript is a way to construct them by adding members. The | operator does exactly this, by design.

Now we’re free to use Typescript types as sets:

type Thing = 'foo' | 7 | true;// This type is impossible to construct and assignments from all 
// types should fail modulo horrible casting to intentionally defeat // the brand.
type ErrorBrand<Err extends string> = Readonly<{
 [key in Err]: void;
}>;function a<T>(
 x: T extends Thing ? T : ErrorBrand<'Parameter is not a Thing'>
) {
}a(7); // OK, {7} ⊆ Thingconst x = Math.random() < .5 ? 7 : true;
a(x); // OK, {7, true} ⊆ Thing// Fails to compile because 6∉Thing: Argument of type 'number' is 
// not assignable to parameter of type 
// 'Readonly<"Parameter is not a Thing": void; }>'.
a(6);

I’m going to call types used for overtly describing sets “type sets.” These types behave in the same way as Set values in many languages except that rather than holding a collection of values, they hold a collection of types.

Sometimes you need more than to merely store a cookie in a jar. Type maps allow you to associate keys (strings, numbers, and symbols) with a type. Typescript allows us to do this by being clever with the index type:

type Thing<T extends string | number | symbol, U> = { tag: T } & U;type TagMapEntry<T extends string | number | symbol, U> = { 
 [key in T]: Thing<T, U> 
};type TagMap = 
 TagMapEntry<'cow', {moo: 'milk'}> & 
 TagMapEntry<'cat', {meow: 'notmilk'}>;type Cow = TagMap['cow']; // Cow = Thing<'cow', {moo: 'milk'}>
type Cat = TagMap['cat']; // Cat = Thing<'cat', {meow: 'notmilk'}>
type CowOrCat = TagMap['cat' | 'cow']; // CowOrCat = Cat | Cow
type Dog = TagMap['dog']; // Fails to compile, no dog in the map

A few key observations here:

• Unlike with sets where we used | to add elements, here we use the & (intersection) type operator to add entries to our map (TagMap).
• Unlike most value maps (i.e. instances of Dictionary or Map you commonly see in languages) where you can query only a single thing at a time, Typescript type maps allow you to query several values at once as seen with CowOrCat. When you do this, you get back a type set.
• In the extreme case, you can query TagMap[keyof TagMap] and get back the entire type set of all the mapped types.

One can also associate multiple types to a given key. To do this in a general and extensible way is a bit tricky if you don’t know all the types in one place:

type AddKeyToMap<M, K extends string | number | symbol, V> =
 Omit<M, K> & { [key in K]: M[Extract<K, keyof M>] | V }type Map1 = AddKeyToMap<{}, 'cat', 'meow'>;
type Map2 = AddKeyToMap<Map1, 'cat', 'purr'>;
type Cat = Map2['cat']; // 'meow' | 'purr'

Assigning multiple types to a key in this way requires nesting conditional types (the AddKeyToMap Omit usages amount to conditionals), which can cause errors if they recurse too deeply. There may exist other constructions that don’t cause recursive conditionals.

Both type sets and type maps are quite powerful in their own right, but pretty annoying to construct. Furthermore, they aren’t very dynamic; you get whatever you statically declare. But what if we need something more variable?

Anyone who has programmed in any of the classes-and-interfaces types of languages (Java, C#) may have seen the builder pattern. Builders are glorified constructors that allow for more flexible semantics than a single function. In these languages, builders tend to be a class that mutates itself as you call the member functions and when you call build, it acts as a factory and produces an object according to your specification. However, there is another way to implement this pattern without classes or mutability.

We can instead use partial function evaluation to express the builder pattern:

The key to the partial evaluation builder pattern is creating functions that return functions that close over definition. This allows us to define a builder with a few advantages over the class-based version:

• The operations you can perform can vary depending where you are in the builder. In our example, you can’t call done until you’ve added at least one number.
• An interesting corollary to this is that the type of the builder changes as you perform different operations. Doing this with class builders requires multiple classes and a ton of boilerplate.
• The builder never mutates anything; we copy the underlying definition with a new value using the spread operator. This allows us to assert correctness at each stage of the builder knowing they act in isolation.
• Another less-useful-in-practice advantage this has over the class version is that you can fork the builder halfway through to make 2 builders without them interfering with one another.

The builder on lines 41–44 declare that myBuilder should only accept the values 7 and 5. Indeed, executing this code gives you a runtime exception on line 48:

[ERR]: Value 8 not allowed

However, you don’t know you did something wrong until you run it, which means you need to write tests and may ship bugs to customers. What if there was a way to assert this at compile time?

At Tableau, we’re discovering new ways to uncover problems earlier in our software’s development cycle. We have security reviews, author PM and developer specifications, use languages with static typing, and write tests to try to prevent bugs from getting out to customers. Shifting left is to take something that would have been caught at a later stage in software development and somehow preventing it at an earlier stage. In our above example, we validated that you don’t pass any number other than 5 or 7 to our validation function. If you violated the rules, you (and hopefully not a customer) got an exception. But we can do better:

This builder example builds (pun intended) on some of the techniques previously described to turn a runtime exception into a compilation error. We use all three of our interesting observations on generics:

• Our generic builder functions return generic functions (line 26).
• Our types declare generic arguments on the left and right-hand side of = (line 15).
• We declare more type parameters than parameters. On line 36, the right-hand side of the type assignment doesn’t take any value parameters.

Our previous builder varied its type to let you call different functions based on where you were in the builder. This version does the same, but also varies its type to build up a type set of numbers. Note, this is a type set of numbers, not a value set of numbers! We do this by initializing a set of numbers to never (i.e. empty set) in the addNumber partial call inside makeAThing’s definition (line 11). Each time you call addNumber in the builder, we return a new builder whose Nums set contains the new T you declared by passing x. The return value on line 18 takes care of this and the corresponding implementation on line 26 must match lest we get a compile error.

When calling our type builder, we use the Nums type set to validate 2 things:

• You can’t pass a value other than those in Nums to the builder’s returned validation function. Doing so gives you the compile error on line 52.
• You can’t add the same number more than once. Doing so gives you the compile error on line 59.

To perform validation and report the issue in a somewhat clear way, we combine our previously outlined forced compiler error and custom compilation error tricks.

Type builders allow end-users to express very complex types built using a fairly simple pattern. These complex types allow you to guarantee intricate invariants at compilation time.

As an example, I wrote and open-sourced ts-checked-fsm for expressing finite state machines in Typescript. Using all the techniques described in this article (and a clever use of void not discussed here), ts-checked-fsm allows users to declare a finite state machine and guarantee at compile time that it’s internally consistent. Some example validations include:

• You can’t declare the same state more than once.
• Declared transitions may only name declared states.
• Action handlers must return only states that are consistent with declared transitions.
• You must declare at least one action handler for every non-final state.

Violating any of these invariants results in code that doesn’t compile and red squiggles in your IDE. Furthermore, action handlers are properly typed and the state and action labels dictate the types in your handler callback.

We use this library to dramatically reduce the possibility of bugs in our finite state machines without having to write a plethora of unit tests. The type system has already validated their internal consistency, leaving few crevices for bugs to hide. That it compiles at all means it’s probably correct. This allows us to instead focus our energies on integration testing components that use the state machine to prevent defects at a higher level.

Another less obvious benefit to all of this is that by performing checks at compile time, you can omit them at runtime. This results in smaller, faster code. Indeed, ts-checked-fsm adds only 565 bytes to your app when minified and gzipped.

In addition to compile-time checked state machines, I also created a richly typed library for expressing observers using redux-sagas. We used this library to exterminate some nasty concurrency bug farms in Tableau Prep’s asynchronous code.

Both of these libraries improve developer productivity and prevent bugs much earlier in development than even unit tests. In the areas of Tableau Prep where we’ve used them, we’ve significantly improved both correctness and readability.

This post was a bit on the longer side, but we dived very deep into some tricky things you can do with Typescript’s type system. We explored how to cause compilation errors when users do illegal things, how to create sets and maps of types, and how to construct types using a special builder pattern. We very briefly touched on how to use these tricks to require users to pass correct values to a function at compile-time.

The final example was a toy problem that highlights these techniques while still maintaining some semblance of clarity. The real examples linked are significantly denser but now that we have the techniques under our belt we’re in a position to take a closer look. Stay tuned for future posts where I’ll cover each of these libraries in more detail.