Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Primitive and Special Types

TypeScript Promise<T> type

Reference for Promise<T> in TypeScript: async function return types, Awaited<T>, Promise.all tuples, rejection typing, Promise<void> and common mistakes.

Promise<T> represents a value of type T that will be available later. TypeScript uses it to type the result of asynchronous work: fetch returns a Promise<Response>, and an async function that returns a number has the type Promise<number>.

The type parameter describes only the fulfilled value. Rejections are not part of the type, because JavaScript can reject with anything, so a catch clause gets unknown (or any, depending on settings). The await operator unwraps a promise: awaiting a Promise<string> gives a string.

TypeScript
async function load(): Promise<number> {
  return 42;
}

Try it

TypeScript async functions 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 Promise.all, Awaited and errors

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
Promise<T>
async function f(): Promise<T> { ... }
const p: Promise<T> = new Promise<T>((resolve, reject) => { ... });
type Unwrapped = Awaited<Promise<T>>;
Part Description
Promise<T> A promise that fulfills with T.
Promise<void> Completion with no value.
Awaited<T> The type you get after await, unwrapping nested promises and thenables recursively.
PromiseLike<T> Anything with a compatible then method; use it for parameters that accept thenables.

Edge cases:

  • An async function must declare its return type as a Promise<...> when annotated; writing : number is an error (the return type must be the global Promise<T> type).
  • Returning a promise from an async function does not produce Promise<Promise<T>>; promises flatten, so Promise<T> stays.
  • Promise.all keeps tuple types: Promise.all([p1, p2]) gives Promise<[A, B]>.
  • Rejections cannot be typed. A function that "throws a NotFound" has no trace of it in Promise<T>; model failures in the resolved value if you need typed errors (see result types).

Usage notes

  • Top-level await. Works in ES modules (module set to esnext/nodenext with target ES2017+), which is the setup used by these examples.
  • Do not forget await. A missing await leaves you with a Promise<T> where you expected T; enable the no-floating-promises lint rule to catch unobserved promises.
  • Promise<void> versus void. A callback typed () => void may return a promise that nobody awaits, which hides errors; type callbacks that should be awaited as () => Promise<void>.
  • new Promise<T>. Pass the type argument explicitly, otherwise resolve accepts unknown.
  • Awaited<T> (TypeScript 4.5) powers the types of await, Promise.all and friends.
  • Utility pairing. ReturnType<typeof fn> of an async function is Promise<X>; wrap it in Awaited to get X.