TypeScript Reference ยท Primitive and Special Types
The TypeScript never type
Reference for never in TypeScript: functions that never return, exhaustive switch checks, empty unions, conditional types, intersections that collapse to never.
never is the empty type: no value has it. It appears as the return type of functions that cannot finish (they always throw or loop forever), as the leftover type after every case of a union has been handled, and as the result of impossible type operations such as string & number.
It is the bottom of the type system, assignable to every type, but no other type (except never) is assignable to it. That second property makes never the standard tool for exhaustiveness checking.
function fail(message: string): never { throw new Error(message); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
function f(): never { throw new Error(); } type Empty = never; let x: never; // can never be assigned a value
| Where it appears | Meaning |
|---|---|
Return type never |
The function never returns normally: it throws or loops forever. |
Narrowed to never |
The compiler has proved that no remaining possibility exists. |
A & B with disjoint primitives |
never. Object types with conflicting literal properties also collapse to never. |
T extends U ? X : Y with T = never |
Distributes over zero members and produces never (for naked type parameters). |
Usage notes
- Exhaustiveness. Passing a leftover value to a
neverparameter turns "I forgot a case" into a compile error (TS2345). - Functions that return
voidare different.voidreturnsundefined;nevernever returns at all. - Function expressions. A function expression or arrow that always throws is inferred
never, but a function declaration that always throws is inferredvoidunless you annotate it. - Unions drop
never.string | neverisstring, which is howExcludeandExtractfilter members. - Distribution surprise.
type X<T> = T extends string ? 1 : 2givesneverforX<never>; wrap in a tuple[T] extends [never]to test for it. - Type-level errors. Returning
neverfrom a conditional branch is a common way to make invalid usage fail. - Property filtering. In mapped types, mapping a key
as neverremoves it. - Empty arrays.
never[]is a legitimate type for an array literal[]in a strictconst.