Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
async function load(id: number): Promise<string> {
  return `item ${id}`;
}
const text: string = await load(1);

Try it

TypeScript Return types and await

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.

TypeScript Errors and a wrong annotation

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

TypeScript
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 await throw; the caught value is unknown with strict (see useUnknownInCatchVariables).
  • Top-level await needs an ES module and a module setting such as es2022, nodenext or preserve, plus a target of es2017 or higher.
  • await on a non-thenable is allowed. The await-thenable rule in typescript-eslint flags it as likely mistake.

Usage notes

  • Return types are flattened. Returning Promise<T> from an async function still gives Promise<T>, never Promise<Promise<T>>.
  • Sequential vs concurrent. Two await lines run one after the other. Start both promises first, then await Promise.all([...]), to run them together.
  • Forgotten await. If you forget it, you get a Promise<T> where you expected T. The compiler usually reports the mismatch when you use the value; typescript-eslint's no-floating-promises catches fire-and-forget calls.
  • return await. Inside try/catch, return await p lets the catch handle rejections of p; plain return p does not.
  • Async arrows use async (x) => ...; with a type parameter in a .tsx file write async <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 what await does, including nested promises.