conditional

`Awaited<T>`

Models the type produced by awaiting T, recursively unwrapping nested Promises (and other thenables). Introduced in TS 4.5 and used internally by the `await` expression's type.

Definition

type Awaited<T> = T extends null | undefined ? T : T extends object & { then(onfulfilled: infer F, ...args: any): any } ? F extends (value: infer V, ...args: any) => any ? Awaited<V> : never : T

Usage patterns

Pattern	Purpose
Awaited<Promise<T>>	Get the resolved value of a Promise
Awaited<ReturnType<AsyncFn>>	Get the resolved return type of async functions
Awaited<Promise<Promise<T>>>	Recursively unwraps to T
Awaited<T \| Promise<U>>	Distributes over unions, unwrapping only the promise members

Examples

type A = Awaited<Promise<string>>;

Result: string

type B = Awaited<Promise<Promise<number>>>;

Result: number — recursively unwraps nested promises

async function fetchUser() { return { id: 1 }; }
type User = Awaited<ReturnType<typeof fetchUser>>;

Idiomatic way to type the awaited return of an async function

type C = Awaited<number>;

Result: number — passthrough for non-thenables

Gotcha

Unlike a simple `T extends Promise ? U : T`, Awaited recurses through nested thenables — matching the runtime behavior of `await`. Custom thenables must have a `then` method to be unwrapped.

Related utility types

ReturnType<T>

Infers the return type of a function type T using `infer R`. Widely used to derive types from existing functions without redeclaring them.

NonNullable<T>

Removes null and undefined from the type T. In TS 4.9+ it is implemented as `T & {}`, which drops nullish members without altering the rest.

Parameters<T>

Extracts the parameters of a function type T as a tuple. Enables reusing a function's argument list for wrappers, currying, or higher-order utilities.

infer R

A keyword usable only inside the extends clause of a conditional type that introduces a fresh type variable inferred from the matched shape. It is the primitive that powers ReturnType, Parameters, InstanceType, Awaited, and countless custom utilities.

InstanceType<T>

Given a constructor type T (typically obtained via `typeof ClassName`), returns the type of an instance produced by `new T()`. Useful for factory functions and generic wrappers over classes.

← All TS utility types · TypeScript vs JavaScript · any vs unknown vs never