Algebraic data types in TypeScript

Question

Worded an other way:

How would you type the windowState DOM property in TypeScript?

SOLVED (in TypeScript 2):

declare var windowState: WindowState
const enum WindowState {
  STATE_MAXIMIZED = 1,
  STATE_MINIMIZED = 2,
  STATE_NORMAL = 3,
  STATE_FULLSCREEN = 4
}
...
var windowState = 5 // Type Error, as expected!

Original question:

How do I declare a type in TypeScript so that it describes an algebraic data type? The purpose of this is describing an existing API.

When I try the following, TypeScript obviously complains that a type is expected:

type Weather = 'sunny' | 'bad'

One idea I had is using a JavaScript 2015 Symbol, however TypeScript doesn't seem to know about these.

An other idea was using an enum, however TypeScript complains that a member initializer must be constant expression:

const enum Weather {
  sunny = 'sunny',
  bad = 'bad',
  windy = Symbol('windy')
}

I would have thought that a string constant is a constant expression.

Answer 1

TypeScript 2.0 has support for discriminated unions/algebraic data types. The documentation is here.

You can combine string literal types, union types, type guards, and type aliases to build an advanced pattern called discriminated unions, also known as tagged unions or algebraic data types. Discriminated unions are useful in functional programming. Some languages automatically discriminate unions for you; TypeScript instead builds on JavaScript patterns as they exist today. There are three ingredients:

1. Types that have a common literal (or enum) property — the discriminant.
2. A type alias that takes the union of those types — the union.
3. Type guards on the common property.

Let's start:

interface Square {
    kind: "square";
    size: number;
}
interface Rectangle {
    kind: "rectangle";
    width: number;
    height: number;
}
interface Circle {
    kind: "circle";
    radius: number;
}

First we declare the interfaces we will union. Each interface has a kind property with a different string literal type. The kind property is called the discriminant or tag. The other properties are specific to each interface. Notice that the interfaces are currently unrelated. Let's put them into a union:

type Shape = Square | Rectangle | Circle;

Now let's use the discriminated union:

function area(s: Shape) {
    switch (s.kind) {
        case "square": return s.size * s.size;
        case "rectangle": return s.height * s.width;
        case "circle": return Math.PI * s.radius ** 2;
    }
}

In each of those branches, TypeScript will narrow down the type. If you try to use a case clause with a value that isn't present as any kind property, then TypeScript will error.