Model async results
Derive the resolved value type returned by an async API, including APIs with nested promises.
TypeScript · Type Alias
Awaited
Awaited<Type> models the result of await and Promise.then by recursively unwrapping promises. It also distributes over unions, preserving non-promise members.
- Since
- 4.5
How it works
Awaited<Type> models the value produced by await and Promise.then. It recursively removes promise layers, distributes across unions, and preserves non-promise members, making asynchronous API result types match their resolved values.
Syntax
type Awaited<Type> = ...Parameters
| Name | Type | Description |
|---|---|---|
Type | type | The type to transform by recursively modeling await or Promise.then unwrapping. |
Returns
The recursively unwrapped type of Type; union members are handled individually.
Key points
- Use Awaited to describe the type of a value after an async function's await operation.
- Promise nesting is unwrapped recursively rather than only removing one Promise layer.
- Awaited<Promise<string>> resolves to string.
- Nested promises resolve all the way to their underlying value type.
- Awaited distributes over unions, retaining non-promise members alongside resolved promise values.
- Awaited was introduced in TypeScript 4.5.
Example: Recursively unwrap a promise
type User = { name: string };
type UserResult = Awaited<Promise<Promise<User>>>;
async function loadUser(): Promise<Promise<User>> {
return Promise.resolve({ name: "Ada" });
}
async function main(): Promise<void> {
const user: UserResult = await loadUser();
console.log(user.name);
}
void main();The nested promise is recursively unwrapped, so UserResult is User and the awaited value can be used as a User.
When to use it
Type promise utilities
Describe the resolved element types of promise-oriented collection APIs.
Resolve mixed unions
Keep synchronous and asynchronous alternatives represented in one union type.
Related
Promiseasyncawait