When to use `never` and `unknown` in TypeScript

The never and unknown primitive types were introduced in TypeScript v2.0 and v3.0 respectively. These two types represent fundamental and complementary aspects of type theory. TypeScript is carefully designed according to principles of type theory, but it is also a practical language, and its features all have practical uses – including never and unknown. To understand those uses we will have to begin with the question, what exactly are types?

Types explained using set theory

When you get down to a fundamental definition a type is a set of possible values, and nothing more. For example, the type string in TypeScript is the set of all possible strings. The type Date is the set of all instances of the Date class (plus all structurally-compatible objects), and the type Iterable<T> is the set of all objects that implement the iterable interface for the given type of iterated values.

TypeScript is especially faithful to the set-theoretic basis for types; among other features, TypeScript has union and intersection types. A type like string | number is called a “union” type because it literally is the union of the set of all strings, and the set of all numbers.

Because string | number contains all string and all number values it is said to be a supertype of string and of number.

unknown is the set of all possible values. Any value can be assigned to a variable of type unknown. This means that unknown is a supertype of every other type. unknown is called the top type for that reason.

never is the empty set. There is no value that can be assigned to variable of type never. In fact, it is an error for the type of value to resolve to never because that would be a contradiction. The empty set can fit inside any other set, so never is a subtype of every other type. That is why never is called the bottom type.¹

The bottom and top types have the useful properties of being the identity element with respect to the union and intersection operations respectively. For any type T:

T | never ⇒ T
T & unknown ⇒ T

This is analogous to the idea that adding zero to a number does not change it, and the same goes for multiplying a number by one. Zero is the identity element for addition, and one is the identity element for multiplication.

A union with the empty set does not add anything, so never is the identity with respect to unions. An intersection selects the common elements between two sets, but unknown contains everything so unknown is the identity with respect to intersections.

never is the only type that will “factor out” in a type union which makes it indispensable for certain cases, as we will see in the next section.

`never` is for things that never happen

Let’s write some code that makes a network request, but that fails if the request takes too long. We can do that by using Promise.race to combine a promise for the network response with a promise that rejects after a given length of time. Here is a function to construct that second promise:

function timeout(ms: number): Promise<never> {
  return new Promise((_, reject) =>
    setTimeout(() => reject(new Error("Timeout elapsed")), ms)
  )
}

Note the return type: because timeout never calls resolve we could use any type for the promise type parameter, and there would be no contradiction. But the most specific type that will work is never. (By “most specific” I mean the type that represents the smallest set of possible values).

Now let’s see timeout in action:

async function fetchPriceWithTimeout(tickerSymbol: string): Promise<number> {
  const stock = await Promise.race([
    fetchStock(tickerSymbol), // returns `Promise<{ price: number }>`
    timeout(3000)
  ])
  return stock.price
}

This works nicely. But how does the compiler infer the correct return type from that Promise.race call? race returns a single promise with the result or failure from the first promise to settle. For purposes of this example the signature of Promise.race works like this:

// `Promise.race` specialized for two inputs.
// The real signature is more general than this.
function race<A, B>(inputs: [Promise<A>, Promise<B>]): Promise<A | B>

The type of the resolved value in the output promise is a union of the resolution types of the inputs. The example above combines fetchStock with timeout so the input promise resolution types are { price: number } and never, and the resolution type of the output (the type of the variable stock) should be { price: number } | never. Because never is the identity with respect to unions that type simplifies to { price: number }, which is what we want.

If we had used any type other than never as the parameter of the return type in timeout things would not have worked out so cleanly. If we had used any we would have lost benefits of type-checking because { price: number } | any is equivalent to any.

If we had used unknown then the type of stock would be { price: number } | unknown which simplifies to unknown. In that case, we would not be able to access the price property without further type narrowing because information about the existence of a price property would have been lost.

Use `never` to prune conditional types

You will often see never used in conditional types to prune unwanted cases. For example, these conditional types extract the argument and return types from a function type:

type Arguments<T> = T extends (...args: infer A) => any ? A : never
type Return<T> = T extends (...args: any[]) => infer R ? R : never

function time<F extends Function>(fn: F, ...args: Arguments<F>): Return<F> {
  console.time()
  const result = fn(...args)
  console.timeEnd()
  return result
}

If T is a function type then the compiler infers its argument types or return type. But if T is not a function type then there is no sensible result for Arguments<T> or Return<T>. We use never in the else branch of each condition to make that case an error:

// Error: Type '3' is not assignable to type 'never'.
const x: Return<"not a function type"> = 3

Conditional pruning is also useful for narrowing union types. TypeScript’s libraries include the NonNullable<T> type (source) which removes null and undefined from a union type. The definition looks like this:

type NonNullable<T> = T extends null | undefined ? never : T;

This works because conditional types distribute over type unions. Given any type of the form T extends U ? X : Y when a union type is substituted for T the type expands to distribute the condition to each branch of that union type:

// if T = A | B

T extends U ? X : T == (A extends U ? X : A) | (B extends U ? X : B)

In each union branch, every occurrence of T is replaced by one constituent from the substituted union type. This also applies if T appears in the true case instead of the false case, or occurs inside of a larger type expression:

// if T = A | B

T extends U ? SomeGeneric<T> : Y
  == (A extends U ? SomeGeneric<A> : Y) | (B extends U ? SomeGeneric<B> : Y)

So a type like NonNullable<string | null> resolves according to these steps:

NonNullable<string | null>
  // The conditional distributes over each branch in `string | null`.
  == (string extends null | undefined ? never : string) | (null extends null | undefined ? never : null)

  // The conditional in each union branch is resolved.
  == string | never

  // `never` factors out of the resulting union type.
  == string

The result is that given a union type NonNullable<T> produces a potentially narrowed type using never to prune unwanted union branches.

Use `unknown` for values that could be anything

Any value can be assigned to a variable of type unknown. So use unknown when a value might have any type, or when it is not convenient to use a more specific type. For example, a pretty-printing function should be able to accept any type of value:

function prettyPrint(x: unknown): string {
  if (Array.isArray(x)) {
    return "[" + x.map(prettyPrint).join(", ") + "]"
  }
  if (typeof x === "string") {
    return `"${x}"`
  }
  if (typeof x === "number") {
    return String(x)
  } 
  return "etc."
}

You cannot do much with an unknown value directly. But you can use type guards to narrow the type and get accurate type-checking for blocks of code operating on narrowed types.

Prior to TypeScript 3.0 the best way to write prettyPrint would have been to use any for the type of x. Type narrowing works with any mostly the same way that it does with unknown; so the compiler can check that we used map and join correctly in the case where x is narrowed to an array type regardless of whether we use any or unknown. But using unknown will save us if we make a mistake where we think that the type has been narrowed, but actually, it has not:

import isArray from "isarray"

function prettyPrint(x: any): string {
  if (isArray(x)) { // whoops - this `isArray` is not a type guard!
    return "[" + x.mop(prettyPrint).join(", ") + "]"
  }
  /* snip */
  return "etc."
}

The isarray package does not include type definitions to turn the isArray function into a type guard. But we might use isarray without realizing that detail. Because isArray is not a type guard, and we used any for the type of x, the type of x remains any in the if body. As a result, the compiler does not catch the typo in this version of prettyPrint. If the type of x were unknown we would have gotten this error instead:

Object is of type ‘unknown’.

In addition, using any lets you cheat by performing operations that are not necessarily safe. unknown keeps you honest.

How to choose between `never`, `unknown`, and `any`

The type of x in prettyPrint and the promise type parameter in the return type of timeout are both cases where a value could have any type. The difference is that in timeout the promise resolution value could trivially have any type because it will never exist.

• Use never in positions where there will not or should not be a value.
• Use unknown where there will be a value, but it might have any type.
• Avoid using any unless you really need an unsafe escape hatch.

In general use the most specific type that will work. never is the most specific type because there is no set smaller than the empty set. unknown is the least specific type because it contains all possible values. any is not a set, and it undermines type-checking; so try to pretend that it does not exist when you can.

[1]: ^ There is a crucial distinction between never and null: the type null is actually a unit type meaning that it contains exactly one value, the value null. Some languages treat null as though it is a subtype of every other type, in which case it is effectively a bottom type. (This includes TypeScript if it is not configured with strict checking options.) But that leads to contradictions because, for example, null is not actually present in the set of all strings. So please use the --strictNullChecks compiler option to get contradiction-free treatment of null!