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.
type A = Awaited<Promise<string>>; // string type B = Awaited<Promise<Promise<number>>>; // number type C = Awaited<boolean | Promise<Date>>; // boolean | Date
Try it
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.
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
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:
nullandundefinedpass through unchanged.- A union is distributed:
Awaited<A | B>isAwaited<A> | Awaited<B>. - A thenable whose
thencallback does not take a value argument givesnever. Awaited<any>isany, andAwaited<unknown>isunknown.
Usage notes
- Prefer plain
awaitin code. Reach forAwaitedin generic type signatures and when deriving a type fromReturnType. Promise<T>'s own type parameter is not unwrapped for you:Promise<Promise<number>>is a different type fromPromise<number>, even though the runtime flattens them.Awaitedis how you describe the flattened result.- It matches any object with a callable
then, so custom thenables andPromiseLikecount. - Before TypeScript 4.5 people wrote their own recursive
Unwraphelper;Awaitedreplaces it. - The result of
Promise.all([a, b])is typed withAwaitedon each element, so a non-promise like42staysnumber. - Inside an
asyncfunction, the declared return type isPromise<X>, butreturnstatements work withX | PromiseLike<X>.
Related
- PromiseLike
, ReturnType - Parameters
- Tutorial: Promises and async, Utility types