Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Utility Types

TypeScript Awaited<T> utility type

Reference for Awaited<T> in TypeScript: the type you get after await, with recursive unwrapping, unions, thenables, Promise.all typing and ReturnType combos.

Awaited<T> models what the await operator does to a type. For Promise<string> it gives string; for a promise of a promise it keeps unwrapping until a non-thenable value is left; for a value that is not a promise at all it returns the type unchanged.

You rarely need it directly in application code, because await already produces the right type. It is useful when you hold a function's return type and want the settled value: Awaited<ReturnType<typeof load>>. The standard library also uses it to type Promise.all, Promise.race and friends. It was added in TypeScript 4.5.

TypeScript
type A = Awaited<Promise<string>>;               // string
type B = Awaited<Promise<Promise<number>>>;      // number
type C = Awaited<boolean | Promise<Date>>;       // boolean | Date

Try it

TypeScript Settled type of an async function

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.

TypeScript How it unwraps

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

TypeScript
type Awaited<T> = T extends null | undefined
  ? T
  : T extends object & { then(onfulfilled: infer F, ...args: infer _): any }
    ? F extends (value: infer V, ...args: infer _) => any
      ? Awaited<V>
      : never
    : T;
Name Description
T Any type. Promises, PromiseLike values and other thenables are unwrapped; everything else is returned as is.

Returns: the type that await would produce for a value of type T.

Edge cases:

  • null and undefined pass through unchanged.
  • A union is distributed: Awaited<A | B> is Awaited<A> | Awaited<B>.
  • A thenable whose then callback does not take a value argument gives never.
  • Awaited<any> is any, and Awaited<unknown> is unknown.

Usage notes

  • Prefer plain await in code. Reach for Awaited in generic type signatures and when deriving a type from ReturnType.
  • Promise<T>'s own type parameter is not unwrapped for you: Promise<Promise<number>> is a different type from Promise<number>, even though the runtime flattens them. Awaited is how you describe the flattened result.
  • It matches any object with a callable then, so custom thenables and PromiseLike count.
  • Before TypeScript 4.5 people wrote their own recursive Unwrap helper; Awaited replaces it.
  • The result of Promise.all([a, b]) is typed with Awaited on each element, so a non-promise like 42 stays number.
  • Inside an async function, the declared return type is Promise<X>, but return statements work with X | PromiseLike<X>.