Never Type

The never type is unique. It represents a state that should be impossible to reach.

The mental model

If any means "it could be absolutely anything," never means "it can be absolutely nothing." A variable of type never can never be assigned a value. A function returning never will never finish executing normally (it will either loop forever or throw an error).

function throwError(message: string): never {
  throw new Error(message); // execution stops here
}

function infiniteLoop(): never {
  while (true) { }
}

The primary use case: Exhaustiveness checking

never shines brightest in switch statements or if-else chains. When you have a union type and you handle every possible case, what type is left? never.

You can assign that leftover value to a variable typed as never to let TypeScript ensure you haven't forgotten a case.

type Shape = "circle" | "square";

function getArea(shape: Shape) {
  switch (shape) {
    case "circle":
      return Math.PI;
    case "square":
      return 100;
    default:
      // If we add "triangle" to Shape but forget to add a case for it,
      // 'shape' will be "triangle" here, which cannot be assigned to 'never'.
      // TypeScript will throw a compile error.
      const _exhaustiveCheck: never = shape;
      return _exhaustiveCheck;
  }
}

never vs void

These are frequently confused, but they are very different:

• void means a function completes normally, but it doesn't return a value (or rather, it implicitly returns undefined).
• never means the function never completes normally at all.

Use the never type to enforce exhaustive switch statements. If the code reaches a never assignment, it means you have unhandled cases in your union types.