Detailed explanation of TypeScript 2.0 marked union types

Constructing payment methods using tagged union types

Suppose we model the following payment methods that users of our system can choose from

• Cash
• PayPal with a given email address
• Credit card with given card number and security code

For these payment methods, we can create a TypeScript interface

interface Cash {
  kind: "cash";
}

interface PayPal {
  kind: "paypal",
  email: string;
}

interface CreditCard {
  kind: "credit";
  cardNumber: string;
  securityCode: string;
}

Note that, in addition to the required information, each type has a kind attribute, the so-called discriminant attribute. Each case here is a string literal type.

Now define a PaymentMethod type, which is the union of the three types we just defined. In this way, each variable declared with PaymentMethod must have one of the three given component types:

type PaymentMethod = Cash | PayPal | CreditCard;

Now that our types are in place, let's write a function that accepts a payment method and returns a human-readable utterance:

function describePaymentMethod(method: PaymentMethod) {
  switch (method.kind) {
    case "cash":
      // Here, method has type Cash
      return "Cash";

    case "paypal":
      // Here, method has type PayPal
      return `PayPal (${method.email})`;

    case "credit":
      // Here, method has type CreditCard
      return `Credit card (${method.cardNumber})`;
  }
}

First, the function contains very few type annotations, only one for the method parameter. Other than that, the function is mostly pure ES2015 code.

In each case of the switch statement, the TypeScript compiler narrows the union type to one of its member types. For example, when matching "paypal", the type of the method parameter is narrowed from PaymentMethod to PayPal. Therefore, we can access the email property without having to add a type assertion.

Essentially, the compiler traces the program control flow to narrow down tagged union types. In addition to the switch statement, it also considers the condition and the effects of assignment and return.

function describePaymentMethod(method: PaymentMethod) {
  if (method.kind === "cash") {
    // Here, method has type Cash
    return "Cash";
  }

  // Here, method has type PayPal | CreditCard

  if (method.kind === "paypal") {
    // Here, method has type PayPal
    return `PayPal (${method.email})`;
  }

  // Here, method has type CreditCard
  return `Credit card (${method.cardNumber})`;
}

Control flow type analysis makes using tagged union types very smooth. With minimal TypeScript syntax overhead, we can write almost pure JavaScript and still benefit from type checking and code completion.

Building Redux actions with tagged union types

A use case where tagged union types really come into their own is when using Redux in a TypeScript application. Let’s create an example that includes a model, two actions, and a reducer for a Todo application.

The following is a simplified Todo type that represents a single todo. The readonly modifier is used here to prevent the property from being modified.

interface Todo {
  readonly text: string;
  readonly done: boolean;
}

Users can add new todos and toggle the completion status of existing todos. According to these requirements, we need two Redux operations, as follows:

interface AddTodo {
  type: "ADD_TODO";
  text: string;
}

interface ToggleTodo {
  type: "TOGGLE_TODO";
  index: number
}

As in the previous example, you can now construct a Redux action as a union of all the actions supported by your application:

type ReduxAction = AddTodo | ToggleTodo;

In this case, the type property acts as a discriminant attribute and follows a common naming pattern in Redux. Now add a Reducer that works with these two actions:

function todosReducer(
  state: ReadonlyArray<Todo> = [],
  action: ReduxAction
): ReadonlyArray<Todo> {
  switch (action.type) {
    case "ADD_TODO":
      // action has type AddTodo here
      return [...state, { text: action.text, done: false }];

    case "TOGGLE_TODO":
      // action has type ToggleTodo here
      return state.map((todo, index) => {
        if (index !== action.index) {
          return todo;
        }

        return {
          text: todo.text,
          done: !todo.done
        };
      });

    default:
      return state;
  }
}

Likewise, only function signatures contain type annotations. The rest of the code is pure ES2015 and not TypeScript specific.

We follow the same logic as in the previous example. Based on the type property of the Redux action, we calculate the new state without modifying the existing state. In the case of the switch statement, we can access the text and index properties specific to each operation type without any type assertions.

The never type

TypeScript 2.0 introduces a new primitive type, never. The never type indicates that the value of that type never appears. Specifically, never is the return type of a function that never returns, and it is also the type of a variable that is never true in a type guard.

These are the exact characteristics of the never type, as described below:

• Never is a subtype of all types and is assignable to all types.
• No type is a subtype of never or is assignable to never (except the never type itself).
• When a function expression or arrow function has no return type annotation, if the function has no return statement, or only a return statement of type never, and if the function is not executable to a endpoint (for example, as determined by control flow analysis), then the inferred return type of the function is never.
• In a function with an explicit never return type annotation, all return statements (if any) must have expressions of type never and the endpoint of the function must not be executable.

I am confused by what I heard. Next, I will use a few examples to talk about this big brother Never.

Functions that never return

Here is an example of a function that never returns:

// Type () => never
const sing = function() {
  while (true) {
    console.log("I just don't return a value, so what!");
    console.log("I just don't return a value, so what!");
    console.log("I just don't return a value, so what!");
    console.log("I just don't return a value, so what!");
    console.log("I just don't return a value, so what!");
    console.log("I just don't return a value, so what!");
  }
}

The function consists of an infinite loop that contains no break or return statements, so there is no way to jump out of the loop. Therefore, the inferred return type of the function is never.

Similarly, the return type of the following function is inferred to be never

// Type (message: string) => never
const failwith = (message: string) => {
  throw new Error(message);
};

TypeScript infers the never type because the function has neither a return type annotation nor a reachable endpoint (as determined by control flow analysis).

It is not possible to have a variable of this type

Alternatively, the never type is inferred to never be true. In the following example, we check if the value parameter is both a string and a number, which is impossible.

function impossibleTypeGuard(value: any) {
  if (
    typeof value === "string" &&
    typeof value === "number"
  ) {
    value; // Type never
  }
}

This example is obviously overly contrived, so let's look at a more practical use case. The following example shows TypeScript's control flow analysis narrowing the union type of the variable under the type guard. Intuitively, the type checker knows that once we check that value is a string, it cannot be a number, and vice versa.

function controlFlowAnalysisWithNever(
  value: string | number
) {
  if (typeof value === "string") {
    value; // Type string
  } else if (typeof value === "number") {
    value; // Type number
  } else {
    value; // Type never
  }
}

Note that in the last else branch, value cannot be a string or a number. In this case, TypeScript infers the never type because we have annotated the value parameter as type string | number, which means that the value parameter cannot have any other type except string or number.

Once control flow analysis eliminates string and number as candidates for the value type, the type checker infers the never type, which is the only remaining possibility. However, we can't do anything useful with value because its type is never, so our editor tool will not automatically display which methods or properties are available for the value.

The difference between never and void

You might ask why TypeScript needs a never type when it already has a void type. Although the two may seem similar, they are two different concepts:

Functions without an explicit return value will implicitly return undefined. Although we would normally say that such a function "returns nothing", it does return. In these cases, we usually ignore the return value. Such functions are inferred in TypeScript to have a void return type.

A function with a never return type never returns. It also doesn't return undefined. The function does not complete normally, which means it throws an error or does not finish running at all.

Type inference for function declarations

There is a small problem regarding return type inference for function declarations. If you look at the several never features we listed earlier, you will find the following sentence:

When a function expression or arrow function has no return type annotation, if the function has no return statement, or only a return statement of type never, and if the function is not executable to a endpoint (for example, as determined by control flow analysis), then the inferred return type of the function is never.

It mentions function expressions and arrow functions, but not function declarations. That is, the return type inferred for a function expression may be different from the return type inferred for a function declaration:

// Return type: void
function failwith1(message: string) {
  throw new Error(message);
}

// Return type: never
const failwith2 = function(message: string) {
  throw new Error(message);
};

The reason for this behavior is backward compatibility, as described below. If you want a function declaration to have a return type of never, you can annotate it explicitly:

function failwith1(message: string): never {
  throw new Error(message);
}

The above is a detailed explanation of TypeScript 2.0 tagged union types. For more information about TS 2.0 tagged union types, please pay attention to other related articles on 123WORDPRESS.COM!