14. TypeScript II: unions, narrowing and generics

This or that

Some values honestly come in more than one kind. An id might be a number (42) or a string ('ada'). Labelling it number would be a lie, and so would string. TypeScript lets you say “either”:

function show(id: number | string) {
  return id.toUpperCase();
  // error: Property 'toUpperCase' does not
  // exist on type 'string | number'.
}

The checker is right to complain. If id is 42, there is no toUpperCase to call, and the program would crash.

Following the if

You already know the runtime check: typeof. Watch what the checker does with it:

function show(id: number | string) {
  if (typeof id === 'string') {
    return id.toUpperCase();
  }
  return id.toFixed(2);
}

function show(id: number | string) {
  if (typeof id === 'string') {
    return id.toUpperCase(); // id: string
  }
  return id.toFixed(2);      // id: number
}

(toFixed(2) turns a number into text with two decimal places.) Inside the if, only strings get through, so the checker treats id as a string there. After the if returns, only numbers are left.

Tagged variants

typeof can tell a number from a string, but not a circle from a rectangle: both are just 'object'. So we put a tag on every object.

type Shape =
  | { kind: 'circle'; r: number }
  | { kind: 'rect'; w: number; h: number };

function area(s: Shape): number {
  if (s.kind === 'circle') {
    return Math.PI * s.r * s.r;
  }
  return s.w * s.h;
}

type Shape = ... gives a name to a type, like interface does, but it can name a union too. In kind: 'circle', the type is the exact string 'circle' and nothing else. So checking s.kind tells the checker which variant s is: inside the if, s.r is allowed; after it, s.w is.

function area(s) {
  if (s.kind === 'circle') {
    return Math.PI * s.r * s.r;
  }
  return s.w * s.h;
}

const ss = [
  { kind: 'circle', r: 1 },
  { kind: 'rect', w: 2, h: 3 },
];
for (const s of ss) {
  console.log(s.kind, area(s));
}

// Try adding { kind: 'tri', b: 2 }.
// Why does area give NaN for it?

The shape of every syntax tree

Here’s why this chapter matters so much for the rest of the book. A program’s code, once a parser has read it, is a tree, and each node in the tree is one of a fixed set of kinds. That is exactly a discriminated union:

type Expr =
  | { kind: 'num'; value: number }
  | { kind: 'add'; left: Expr; right: Expr }
  | { kind: 'mul'; left: Expr; right: Expr }

Real JavaScript tools do exactly this. In ESTree, the tree format many JavaScript tools share, every node has a string type field that says which kind of node it is^[4]. You’ll walk a tree like this recursively in this chapter’s exercise, and that walk is your first interpreter.

Proving every case is handled

Suppose you add a third shape, { kind: 'tri'; b: number; h: number }, and forget to update area. You want the checker to notice. Here is the standard trick:

function unreachable(x: never): never {
  throw new Error('unhandled case');
}

function area(s: Shape): number {
  if (s.kind === 'circle') {
    return Math.PI * s.r * s.r;
  }
  if (s.kind === 'rect') {
    return s.w * s.h;
  }
  return unreachable(s);
}
// error: Argument of type '{ kind: "tri";
// b: number; h: number; }' is not
// assignable to parameter of type 'never'.

never is the type with no values at all. When every kind has been handled, narrowing leaves nothing for s to be by the last line, so s is never and the call is fine. Forget 'tri', and s could still be a triangle there, so the checker points straight at the gap.

Types with blanks: generics

What is the type of a function that returns the first item of any list? first(xs: number[]): number works only for numbers. Writing the same function again for strings would be silly.

function first<T>(xs: T[]): T | undefined {
  return xs[0];
}

const a = first([1, 2]);
// a: number | undefined
const b = first(['x']);
// b: string | undefined

<T> declares the blank. The checker fills it in from each call, so a is labelled a number (or undefined, for an empty list) and b a string. You’ve already met one generic: Array<number> is another way to write number[].

Your turn

type Expr =
  | { kind: 'num'; value: number }
  | { kind: 'neg'; arg: Expr }
  | { kind: 'add';
      left: Expr; right: Expr }
  | { kind: 'mul';
      left: Expr; right: Expr };

function evaluate(e: Expr): number {
  // your code here
}

// (1 + 2) * 4
const tree: Expr = {
  kind: 'mul',
  left: {
    kind: 'add',
    left: { kind: 'num', value: 1 },
    right: { kind: 'num', value: 2 },
  },
  right: { kind: 'num', value: 4 },
};
console.log(evaluate(tree));

function firstWhere<T>(
  xs: T[],
  ok: (x: T) => boolean,
): T | undefined {
  // your code here
}

const big = firstWhere([3, 8, 12],
  (n) => n > 5);
console.log(big);

What you learned

• A union type A | B holds either. Until you check, only things safe for both are allowed.
• Narrowing: the checker follows your typeof and kind checks, and your returns, to know the exact type in each region of code.
• A discriminated union tags each variant with a kind. It is the shape of every syntax tree and instruction in this book.
• Exhaustiveness: end with unreachable(x: never), and the checker proves every case is handled. Keep the runtime throw too.
• A generic like first<T> has a type parameter that each use fills in.

That’s all the TypeScript you need for now. Next: how to know your code really works.