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.
async function load(): Promise<number> { return 42; }
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
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
asyncfunction must declare its return type as aPromise<...>when annotated; writing: numberis an error (the return type must be the globalPromise<T>type). - Returning a promise from an
asyncfunction does not producePromise<Promise<T>>; promises flatten, soPromise<T>stays. Promise.allkeeps tuple types:Promise.all([p1, p2])givesPromise<[A, B]>.- Rejections cannot be typed. A function that "throws a
NotFound" has no trace of it inPromise<T>; model failures in the resolved value if you need typed errors (see result types).
Usage notes
- Top-level await. Works in ES modules (
moduleset toesnext/nodenextwithtargetES2017+), which is the setup used by these examples. - Do not forget
await. A missingawaitleaves you with aPromise<T>where you expectedT; enable theno-floating-promiseslint rule to catch unobserved promises. Promise<void>versusvoid. A callback typed() => voidmay 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, otherwiseresolveacceptsunknown.Awaited<T>(TypeScript 4.5) powers the types ofawait,Promise.alland friends.- Utility pairing.
ReturnType<typeof fn>of an async function isPromise<X>; wrap it inAwaitedto getX.