The never type

TypeScript 2.0 introduces a new primitive type never.The never type represents the type of values that never occur.Specifically, never is the return type for functions that never return and never is the type of variables under type guards that are never true.

The never type has the following characteristics:

  • never is a subtype of and assignable to every type.
  • No type is a subtype of or assignable to never (except never itself).
  • In a function expression or arrow function with no return type annotation, if the function has no return statements, or only return statements with expressions of type never, and if the end point of the function is not reachable (as determined by control flow analysis), the inferred return type for 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 end point of the function must not be reachable.Because never is a subtype of every type, it is always omitted from union types and it is ignored in function return type inference as long as there are other types being returned.

Some examples of functions returning never:

  1. // Function returning never must have unreachable end point
  2. function error(message: string): never {
  3.     throw new Error(message);
  4. }
  6. // Inferred return type is never
  7. function fail() {
  8.     return error("Something failed");
  9. }
  11. // Function returning never must have unreachable end point
  12. function infiniteLoop(): never {
  13.     while (true) {
  14.     }
  15. }

Some examples of use of functions returning never:

  1. // Inferred return type is number
  2. function move1(direction: "up" | "down") {
  3.     switch (direction) {
  4.         case "up":
  5.             return 1;
  6.         case "down":
  7.             return -1;
  8.     }
  9.     return error("Should never get here");
  10. }
  12. // Inferred return type is number
  13. function move2(direction: "up" | "down") {
  14.     return direction === "up" ? 1 :
  15.         direction === "down" ? -1 :
  16.         error("Should never get here");
  17. }
  19. // Inferred return type is T
  20. function check<T>(x: T | undefined) {
  21.     return x || error("Undefined value");
  22. }

Because never is assignable to every type, a function returning never can be used when a callback returning a more specific type is required:

  1. function test(cb: () => string) {
  2.     let s = cb();
  3.     return s;
  4. }
  6. test(() => "hello");
  7. test(() => fail());
  8. test(() => { throw new Error(); })