The Awaited Type

Unwrapping Promises to their final resolved type.

TypeScript3 min readConcept 41 of 54

Unwrapping Promises

The Awaited<Type> utility is meant to model operations like await in async functions, or the .then() method on Promises.

It recursively unwraps Promises until it finds the base, non-promise value.

Extracting Async Results

If you are calling a function that returns a Promise<User>, you might want to extract the User type to use elsewhere in your app.

You can combine Awaited and ReturnType to grab the exact data type that the API call will eventually yield.

Syntax

typescript async function fetchUser() { return { id: 1, name: "Alice" }; } // 1. Get the return type (it's a Promise!) type AsyncResult = ReturnType<typeof fetchUser>; // Promise<{ id: number, name: string }> // 2. Unwrap the Promise using Awaited type UserData = Awaited<AsyncResult>; // { id: number, name: string }

Try it

Watch how the Awaited utility recursively peels back layers of Promises until it reaches the core primitive type.

// 1. A doubly-nested Promise
typeNestedAsync =Promise<Promise<string>>;

// 2. Recursive unwrapping
type FinalValue =Awaited<NestedAsync>;
Resolution Engine
Promise 1
Promise 2
string
Waiting for evaluation...

Check yourself

Pick an answer to lock it in, then read why. Getting one wrong is part of how it sticks.

  1. 1What is the result of `Awaited<Promise<Promise<number>>>`?

Remember this

  • Awaited<T> extracts the type that a Promise resolves to.
  • It is fully recursive, meaning it handles nested Promise<Promise<T>> automatically.
  • It models the behavior of the await keyword at the type level.
  • Often combined with ReturnType to extract the data type from an async API function.

Done with this concept?

Mark it complete to track your progress. No login needed.