TypeScript Reference ยท Keywords and Declarations
TypeScript async and await
Reference for TypeScript async and await: how async functions are typed as Promise<T>, how await unwraps values, error handling, async arrows and common mistakes.
async marks a function so that it always returns a promise, and await pauses that function until a promise settles. TypeScript adds types on top: the return type of an async function is always Promise<T>, and await unwraps a Promise<T> (or any thenable) into T.
You usually do not write the Promise yourself. If an async function returns a number, the compiler infers Promise<number>. When you do annotate the return type of an async function, it must be a Promise.
async function load(id: number): Promise<string> { return `item ${id}`; } const text: string = await load(1);
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
async function name(params): Promise<T> { /* await expr */ } const f = async (params): Promise<T> => { /* ... */ }; class C { async method(): Promise<T> { /* ... */ } } const value: T = await promiseOfT;
| Part | Description |
|---|---|
async |
Makes the function return a promise. A returned value is wrapped, a thrown error becomes a rejection. |
await expr |
Waits for expr. The type of the whole expression is Awaited<typeof expr>; a non-promise value is returned as is. |
| Return annotation | Must be Promise<T> (or a compatible type). Annotating string is error TS1064. |
Errors and edge cases
- A rejected promise makes
awaitthrow; the caught value isunknownwithstrict(seeuseUnknownInCatchVariables). - Top-level
awaitneeds an ES module and amodulesetting such ases2022,nodenextorpreserve, plus atargetofes2017or higher. awaiton a non-thenable is allowed. Theawait-thenablerule in typescript-eslint flags it as likely mistake.
Usage notes
- Return types are flattened. Returning
Promise<T>from an async function still givesPromise<T>, neverPromise<Promise<T>>. - Sequential vs concurrent. Two
awaitlines run one after the other. Start both promises first, thenawait Promise.all([...]), to run them together. - Forgotten
await. If you forget it, you get aPromise<T>where you expectedT. The compiler usually reports the mismatch when you use the value; typescript-eslint'sno-floating-promisescatches fire-and-forget calls. return await. Insidetry/catch,return await plets thecatchhandle rejections ofp; plainreturn pdoes not.- Async arrows use
async (x) => ...; with a type parameter in a.tsxfile writeasync <T,>(x: T) => x. - Targets older than ES2017 are downleveled to generator-based helpers; modern targets keep native
async. Awaited<T>is the utility type that models whatawaitdoes, including nested promises.