TypeScript never Type

Introduction

In this chapter, we will explore the never type in TypeScript. The never type represents values that never occur. It is used to indicate that a function never returns, such as in the case of throwing an error or an infinite loop. Understanding how to use the never type is essential for handling scenarios where a function cannot successfully complete.

Table of Contents

• Definition
• Using the never Type
• Functions with never Return Type
• Exhaustiveness Checking with never
• Complete Example with Output
• Conclusion

Definition

The never type in TypeScript represents values that never occur. It is used to indicate that a function never returns a value. This can happen if the function throws an error, enters an infinite loop, or otherwise never reaches a point where it returns.

Using the never Type

The never type is primarily used for functions that never return a value. This includes functions that throw errors or run infinitely. The never type can also be used in union types to perform exhaustive type checking.

Functions with never Return Type

When a function never successfully completes, you should specify the return type as never. This makes it clear that the function does not produce a result under any circumstances.

Example

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

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

throwError("An unexpected error occurred!");
// The following line will never be reached
infiniteLoop();

Output

Error: An unexpected error occurred!
    at throwError (path/to/file.ts:2:9)
    ...

Exhaustiveness Checking with never

The never type can be used to ensure that all possible cases are handled in a union type. This is useful for exhaustiveness checking in switch statements.

Example

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; sideLength: number };

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.sideLength ** 2;
    default:
      // Exhaustiveness check
      const _exhaustiveCheck: never = shape;
      throw new Error(`Unhandled shape: ${_exhaustiveCheck}`);
  }
}

const circle = { kind: "circle", radius: 10 };
console.log(getArea(circle)); // Output: 314.159...

const square = { kind: "square", sideLength: 5 };
console.log(getArea(square)); // Output: 25

Output

314.159...
25

Complete Example with Output

In this section, we will combine all the examples into a single TypeScript file, compile it to JavaScript, and run it to see the output.

TypeScript Code

You can test the following code in the TypeScript Playground:

// Functions with `never` Return Type
function throwError(message: string): never {
  throw new Error(message);
}

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

try {
  throwError("An unexpected error occurred!");
} catch (e) {
  console.error(e);
}

// The following line will never be reached
// infiniteLoop();

// Exhaustiveness Checking with `never`
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; sideLength: number };

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.sideLength ** 2;
    default:
      // Exhaustiveness check
      const _exhaustiveCheck: never = shape;
      throw new Error(`Unhandled shape: ${_exhaustiveCheck}`);
  }
}

const circle = { kind: "circle", radius: 10 };
console.log(getArea(circle)); // Output: 314.159...

const square = { kind: "square", sideLength: 5 };
console.log(getArea(square)); // Output: 25

Conclusion

In this chapter, we covered the never type in TypeScript, including how to use it to indicate that a function never returns a value, and how to use it for exhaustiveness checking in union types. We provided a complete example with its output to illustrate how the never type works in TypeScript. Understanding the never type is essential for handling scenarios where a function cannot successfully complete.