never Keyword in Typescript

Do you want to know about the never keyword in Typescript? In this Typescript tutorial, I will explain how to use the never keyword in Typescript with complete code and examples.

The ‘never’ type in TypeScript is used for values that never occur, primarily in two scenarios: for functions that don’t return a value (like those throwing errors or having infinite loops), and to ensure exhaustive checks in union types, guaranteeing all possible cases are handled.

What is the ‘Never’ keyword in Typescript?

In TypeScript, the ‘never’ type represents the type of values that never occur. It’s a type that indicates that a variable will never have a value. In practical terms, ‘never’ is used in two main scenarios:

  • As the return type of functions that never return a value (because they always throw an error or have an infinite loop).
  • To represent a state that should never happen in a union type (a type-safe way to ensure exhaustive checks).

How to use the never keyword in Typescript

Let us see how to use the never keyword in Typescript.

Example 1: Functions that Never Return

A common use of ‘never’ is for functions that do not return a value because they either throw an error or never finish executing. Let’s look at a function that always throws an error:

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

try {
    throwError("Something went wrong");
} catch (e) {
    console.error(e);
}

In this example, the throwError function is annotated with a return type of never. This indicates that the function will never successfully return; it will always throw an error.

You can see the screenshot below for the output:

never keyword in typescript

Example 2: Exhaustive Type Checks

Another use of ‘never’ is to ensure exhaustive checks in union types. Consider an example with a union type and a switch statement:

type Shape = "circle" | "square" | "triangle";

function getArea(shape: Shape): number {
    switch (shape) {
        case "circle":
            return Math.PI * Math.pow(5, 2); // Area of a circle with radius 5
        case "square":
            return 25; // Area of a square with side 5
        default:
            const _exhaustiveCheck: never = shape;
            return _exhaustiveCheck;
    }
}

console.log(getArea("circle")); // Logs the area of a circle

In this example, the Shape type is a union of three string literals. The getArea function uses a switch statement to handle each type. The default case includes a variable of type never. If a new shape is added to the Shape type but not handled in the switch, TypeScript will throw an error, as the new shape type cannot be assigned to the never type. This ensures that all possible cases are handled.

Example 3: Using ‘Never’ with Unreachable Code

‘Never’ can also be used to indicate unreachable code. For instance:

function infiniteLoop(): never {
    while (true) {
        // Infinite loop
    }
}

In this function, the return type is never because the loop is infinite, and the function’s end is never reached.

Conclusion

In this tutorial, we learned how to use the never keyword in Typescript with three examples.

You may also like:

>