Promises & async functions

A promise of a cart is not a cart

A shop page loads the visitor's cart from its server. That takes time, so loadCart gives back a promise: an object that stands for a value that arrives later (the Promises lesson covers them). Here loadCart is a small stand-in for the server, so nothing goes over the network. The code forgets one word:

1type Cart = { items: number; total: number };2 3async function loadCart(): Promise<Cart> {4  return { items: 3, total: 12 };5}6 7async function showTotal() {8  const cart = loadCart();9  //    ^?10  console.log(`Total: $${cart.total}`);11}12 13showTotal();

Line 1 describes a Cart. Lines 3 to 5 are the stand-in: an async function that gives back a cart with 3 items and a total of 12. Line 8 calls it, and the answer after the ^? on line 9 shows what cart is: Promise<Cart>, a promise that will hold a Cart. So line 10 gets an error, on purpose: Property 'total' does not exist on type 'Promise<Cart>'. In plain words: "you're reading total from the promise, and a promise has no total". When it runs, it prints Total: $undefined.

Add await, which waits for the promise and gives back what's inside (the async & await lesson covers it):

1type Cart = { items: number; total: number };2 3async function loadCart(): Promise<Cart> {4  return { items: 3, total: 12 };5}6 7async function showTotal() {8  const cart = await loadCart();9  //    ^?10  console.log(`Total: $${cart.total}`);11}12 13showTotal();

Only line 8 changed. The answer on line 9 now says const cart: Cart, line 10 has no error, and the code prints Total: $12. TypeScript keeps track of which values are promises and which are the values inside them, and stops you from mixing them up.

Promise<T> names what arrives later

Promise is a generic type: a type with a slot, written in angle brackets, for another type (the Generic types & interfaces lesson covers them). Promise<Cart> holds a cart, and Promise<number> holds a number. When you make a promise yourself with new Promise, TypeScript needs to be told what goes in the slot:

1type Cart = { items: number; total: number };2 3const unnamed = new Promise((resolve) => resolve({ items: 3, total: 12 }));4//    ^?5const named = new Promise<Cart>((resolve) => resolve({ items: 3, total: 12 }));6//    ^?7const broken = new Promise<Cart>((resolve) => resolve({ items: 3 }));

Line 3 makes a promise and calls resolve, the function that fills it, with a cart. The answer on line 4 shows Promise<unknown>: TypeScript doesn't guess the type from what you pass to resolve. Line 5 writes the type in the brackets, new Promise<Cart>, and the answer on line 6 shows Promise<Cart>. Now resolve only takes a Cart, so line 7 gets an error, on purpose: Argument of type '{ items: number; }' is not assignable to parameter of type 'Cart | PromiseLike<Cart>'. In plain words: the object has no total, so it isn't a Cart. (PromiseLike<Cart> means another promise of a cart, which resolve also accepts.)

A function's return type fills the slot too. Here the stand-in answers after 50 milliseconds, with setTimeout, as a real server would answer after a while:

1type Cart = { items: number; total: number };2 3function loadCart(): Promise<Cart> {4  return new Promise((resolve) => {5    setTimeout(() => resolve({ items: 3, total: 12 }), 50);6  });7}8 9const total = loadCart().then((cart) => cart.total);10//    ^?11total.then((value) => console.log(`Total: $${value}`));

Line 3 says loadCart gives back a Promise<Cart>, so the new Promise on line 4 knows it holds a cart without its own brackets. Line 9 calls then (the Promise chaining lesson covers it): its callback gets the Cart, and gives back cart.total, a number. The answer on line 10 shows Promise<number>: whatever a then callback gives back becomes the type of the next promise. Line 11 prints Total: $12.

When you forget await

Forgetting await is the most common mistake with promises. Try the three ways to write line 8 below, and watch what TypeScript says and what the code prints:

1type Cart = { items: number; total: number };2 3async function loadCart(): Promise<Cart> {4  return { items: 3, total: 12 };5}6 7async function showTotal() {8  const cart = await loadCart();9  console.log(`Total: $${cart.total}`);10}11 12showTotal();

With await, all is well. Without it, the error appears on line 9, where the promise is used. And if you write the type you expect on line 8, the error moves to line 8 itself, with Type 'Promise<Cart>' is missing the following properties from type 'Cart': items, total: "you said Cart, but this is a promise, which has neither of a cart's properties".

A forgotten await in a condition is worse, because the code still runs and takes the wrong branch:

1async function isLoggedIn(): Promise<boolean> {2  return false;3}4 5async function showMenu() {6  if (isLoggedIn()) {7    console.log("Welcome back");8  } else {9    console.log("Please log in");10  }11}12 13showMenu();

Line 1 says isLoggedIn gives back a Promise<boolean>, and line 2 makes it false. Line 6 forgets await, so the if tests the promise, an object, which always counts as true. TypeScript marks it, on purpose: This condition will always return true since this 'Promise<boolean>' is always defined. In plain words: "this is a promise, so the test can never be false; did you mean to await it?". When it runs, it prints Welcome back to a visitor who isn't logged in.

TypeScript catches a forgotten await when you use the promise as if it were the value: reading a property, testing it, or putting it where a Cart must go. It says nothing about a call on its own line, like saveCart();, because starting a promise without waiting for it is allowed. A linter rule such as typescript-eslint's no-floating-promises reports those.

What an async function gives back

An async function always gives back a promise, whatever it returns. TypeScript works out the type for you:

1type Cart = { items: number; total: number };2 3async function loadCart() {4//             ^?5  return { items: 3, total: 12 };6}7 8async function saveCart(cart: Cart) {9//             ^?10  console.log(`Saved ${cart.items} items`);11}12 13saveCart({ items: 3, total: 12 });

Line 5 returns a plain object, but the answer on line 4 shows that loadCart gives back a Promise of that object. Line 8's saveCart returns nothing, and the answer on line 9 shows Promise<void>: a promise that only says "done". Line 13 calls it, and it prints Saved 3 items.

When you write the return type yourself, write the promise, not the value inside it. Both mistakes below are on purpose:

1type Cart = { items: number; total: number };2 3async function countItems(): number {4  return 3;5}6 7async function loadCart(): Promise<Cart> {8  return { items: 3, total: "12" };9}

Line 3 says countItems gives back a number. TypeScript says The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? In plain words: "callers get a promise, so say Promise<number>". Line 7 gets it right, and now TypeScript checks every return against the type inside. Line 8 returns the total as the text "12", so it gets Type 'string' is not assignable to type 'number'.

The table below shows what TypeScript says for each way of writing an async function. Read each row from left to right:

The last row matters: returning a promise from an async function doesn't make a promise of a promise. Both await and the type Awaited<T> unwrap all the way down to the value (the ReturnType, Awaited & more lesson covers Awaited):

1type Cart = { items: number; total: number };2 3async function loadCart(): Promise<Cart> {4  return { items: 3, total: 12 };5}6 7async function loadCartAgain() {8  return loadCart();9}10 11type Again = ReturnType<typeof loadCartAgain>;12//   ^?13type Loaded = Awaited<Again>;14//   ^?

Line 8 returns the promise from loadCart. Line 11 asks for loadCartAgain's return type, and the answer on line 12 is Promise<Cart>, one promise. Line 13 unwraps it with Awaited, and the answer on line 14 is the cart's shape, { items: number; total: number; }. That's the Cart type: TypeScript writes out its properties instead of its name. Awaited is the type of what await would give you.

Promise.all keeps each result in its place

A checkout page needs the user and the cart. Waiting for one and then the other is slow, so the page starts both at once and waits for both with Promise.all (the Promise combinators lesson covers it):

1type User = { name: string };2type Cart = { items: number; total: number };3 4async function loadUser(): Promise<User> {5  return { name: "Asha" };6}7 8async function loadCart(): Promise<Cart> {9  return { items: 3, total: 12 };10}11 12async function showCheckout() {13  const [user, cart] = await Promise.all([loadUser(), loadCart()]);14  //     ^?15  //           ^?16  console.log(`${user.name} has ${cart.items} items`);17}18 19showCheckout();

Lines 4 to 10 are two stand-ins. Line 13 passes a list of two promises to Promise.all, awaits it, and takes the two results apart with destructuring. The answers on lines 14 and 15 show that user is a User and cart is a Cart. TypeScript types what Promise.all gives back as a tuple, a list with a type for each place (the Arrays & tuples lesson covers them): [User, Cart]. Line 16 prints Asha has 3 items.

That only works when TypeScript can see each place. Change how line 13 makes the list, and watch the types of user and cart:

1type User = { name: string };2type Cart = { items: number; total: number };3 4async function loadUser(): Promise<User> {5  return { name: "Asha" };6}7 8async function loadCart(): Promise<Cart> {9  return { items: 3, total: 12 };10}11 12async function showCheckout() {13  const requests = [loadUser(), loadCart()] as const;14  const [user, cart] = await Promise.all(requests);15  console.log(`${user.name} has ${cart.items} items`);16}17 18showCheckout();

A plain list saved in a variable is an array, not a tuple: every item is a Promise<User> | Promise<Cart>, so every result is a User | Cart. as const (the as const & satisfies lesson covers it) or a written tuple type keeps the places.

Promise.all fails as soon as one request fails. When a page can live without some of its data, like a list of offers, Promise.allSettled waits for every request and tells you how each one went:

1type Cart = { items: number; total: number };2 3async function loadCart(): Promise<Cart> {4  return { items: 3, total: 12 };5}6 7async function loadOffers(): Promise<string[]> {8  throw new Error("Offers server is down");9}10 11async function showPage() {12  const [cart, offers] = await Promise.allSettled([loadCart(), loadOffers()]);13  if (cart.status === "fulfilled") console.log(`Total: $${cart.value.total}`);14  if (offers.status === "rejected") {15    const reason = offers.reason;16    //    ^?17    console.log(`No offers: ${reason.message}`);18  }19}20 21showPage();

Line 8 makes the offers request fail. Line 12 waits for both. Each result has a status: "fulfilled" with a value, or "rejected" with a reason. Its type is a union of the two, and checking status narrows it (the Discriminated unions lesson covers this). So line 13 can read cart.value.total only after checking status; without the check, TypeScript says Property 'value' does not exist on type 'PromiseSettledResult<Cart>'. The answer on line 16 shows the reason is any: TypeScript doesn't know what a failed promise holds. The code prints Total: $12, then No offers: Offers server is down.

The table below compares the four ways to wait for several promises, for a user request and a cart request. Read each row from left to right:

Typing timeouts and retries

Pages wait for things: a pause before saving, a request that takes too long, a server that fails once and works the next time (the Async patterns lesson builds these in JavaScript). Typing them well starts with a small helper that waits:

1function wait(ms: number) {2//       ^?3  return new Promise((resolve) => setTimeout(resolve, ms));4}5 6function pause(ms: number): Promise<void> {7//       ^?8  return new Promise((resolve) => setTimeout(resolve, ms));9}10 11async function showSaved() {12  await pause(50);13  console.log("Saved");14}15 16showSaved();

Line 3 makes a promise that setTimeout fills after ms milliseconds. With no return type, the answer on line 2 shows wait gives back Promise<unknown>. Line 6 says what the pause really holds, Promise<void>: nothing to use, only "done". The answer on line 7 shows it. Line 12 waits 50 milliseconds, and line 13 prints Saved.

setTimeout itself gives back an id that clearTimeout uses to cancel the timer, as a page does when it saves a draft only after the typing stops:

1let timer = setTimeout(() => console.log("Saving draft"), 50);2//  ^?3clearTimeout(timer);4timer = setTimeout(() => console.log("Saved"), 50);

The answer on line 2 shows timer is a number, from TypeScript's browser types. Line 3 cancels the first timer, so only line 4's timer runs, and it prints Saved. In code for Node.js, its types say setTimeout gives back a NodeJS.Timeout object instead. ReturnType<typeof setTimeout> is the type of the id in both places.

Now a timeout: give a request 100 milliseconds, and give up after that. Promise.race settles like whichever promise settles first, so race the request against a promise that rejects after the time is up. The first try has a type error, on purpose:

1function timeout(ms: number) {2  return new Promise((_, reject) => {3    setTimeout(() => reject(new Error("Timed out")), ms);4  });5}6 7function withTimeout<T>(task: Promise<T>, ms: number): Promise<T> {8  return Promise.race([task, timeout(ms)]);9}

Lines 1 to 5 make a promise that rejects with an error after ms milliseconds. It has no return type, so it's a Promise<unknown>. Line 7 says withTimeout works for any promise: T is a type parameter, filled in by each call (the Generic functions lesson covers them). On line 8, the race gives a promise of T | unknown, which is just unknown, so TypeScript says Type 'Promise<unknown>' is not assignable to type 'Promise<T>': "you promised a T, but this could hold anything".

The fix is to say what the timeout really gives back: nothing, ever. It only rejects. That's the type never (the any, unknown & never lesson covers it):

1type Cart = { items: number; total: number };2 3function timeout(ms: number): Promise<never> {4  return new Promise((_, reject) => {5    setTimeout(() => reject(new Error("Timed out")), ms);6  });7}8 9function withTimeout<T>(task: Promise<T>, ms: number): Promise<T> {10  return Promise.race([task, timeout(ms)]);11}12 13function loadCart(delay: number): Promise<Cart> {14  return new Promise((resolve) => {15    setTimeout(() => resolve({ items: 3, total: 12 }), delay);16  });17}18 19withTimeout(loadCart(20), 100).then((cart) => console.log(`Total: $${cart.total}`));20withTimeout(loadCart(300), 100).catch((error) => console.log(error.message));

Line 3 is the only change to the helpers: Promise<never>. Now line 10 is fine, because T | never is just T. Lines 13 to 17 are a stand-in that answers after delay milliseconds. Line 19 asks for a cart that takes 20 milliseconds, well inside the limit, and prints Total: $12. Line 20 asks for one that takes 300, so the timeout rejects first, and it prints Timed out.

The last helper tries again when a request fails. It works for any request, so it's generic too:

1type Cart = { items: number; total: number };2 3async function retry<T>(task: () => Promise<T>, times: number): Promise<T> {4  for (let attempt = 1; ; attempt++) {5    try {6      return await task();7    } catch (error) {8      if (attempt >= times) throw error;9      console.log(`Attempt ${attempt} failed`);10    }11  }12}13 14let calls = 0;15async function loadCart(): Promise<Cart> {16  calls++;17  if (calls < 3) throw new Error("Server busy");18  return { items: 3, total: 12 };19}20 21retry(loadCart, 3).then((cart) => console.log(`Total: $${cart.total}`));22//                       ^?

Line 3 takes task, a function that gives back a Promise<T>, and gives back a Promise<T> too. Line 4 loops, counting attempts. Line 6 runs the task and waits for it. If it fails, line 8 throws the error once there are no attempts left, and line 9 prints a note before trying again. Lines 14 to 19 are a stand-in that fails twice, then works. Line 21 passes loadCart, so T is Cart, and the answer on line 22 shows the callback gets a Cart. It prints Attempt 1 failed, Attempt 2 failed, then Total: $12.

The await on line 6 matters. Without it, line 6 returns the promise before it fails, the catch on line 7 never sees the failure, and nothing is retried. TypeScript can't catch that: both versions have the right types. Exercise 6 lets you see it.

Loading a checkout page

A real checkout page puts these together: it loads the user and the cart at once, gives up after 100 milliseconds, and shows a message either way:

1type User = { name: string };2type Cart = { items: number; total: number };3 4function timeout(ms: number): Promise<never> {5  return new Promise((_, reject) => {6    setTimeout(() => reject(new Error("Timed out")), ms);7  });8}9 10function withTimeout<T>(task: Promise<T>, ms: number): Promise<T> {11  return Promise.race([task, timeout(ms)]);12}13 14async function loadUser(): Promise<User> {15  return { name: "Asha" };16}17 18async function loadCart(): Promise<Cart> {19  return { items: 3, total: 12 };20}21 22async function loadCheckout(): Promise<string> {23  const both = Promise.all([loadUser(), loadCart()]);24  const [user, cart] = await withTimeout(both, 100);25  //     ^?26  return `${user.name}, your ${cart.items} items cost $${cart.total}`;27}28 29loadCheckout()30  .then((message) => console.log(message))31  .catch(() => console.log("Checkout is slow. Try again."));

Lines 4 to 12 are the timeout helpers from before, and lines 14 to 20 are the stand-ins. Line 22 says loadCheckout gives back a promise of a message. Line 23 starts both requests, which makes a Promise<[User, Cart]>. Line 24 passes it to withTimeout, so T is the tuple [User, Cart], and the answer on line 25 shows user is still a User after the timeout. Line 26 builds the message, and line 30 prints Asha, your 3 items cost $12. If either request took too long, line 31 would print Checkout is slow. Try again.

Now sort some one-line snippets by what TypeScript says about them:

Common mix-ups

An async function gives back a promise even when it never waits for anything. This one returns 3 at once, and the mistake is on purpose:

1async function countItems() {2  return 3;3}4 5const count: number = countItems();

Line 2 returns 3 straight away. Still, line 5 gets Type 'Promise<number>' is not assignable to type 'number': the word async on line 1 is what makes the promise.

• "An async function gives back what it returns." No. It always gives back a promise of what it returns. Use await to get the value.
• "TypeScript always tells me when I forget await." No. It tells you when you use the promise as a value. A call on its own line needs a linter rule like no-floating-promises.
• "Promise.all always keeps each result's type." No. Only for a list written in the call, a list with as const, or a tuple type. A saved plain list mixes them.
• "Promise<Cart> also says what the error will be." No. It only types the value. What a rejected promise holds is any in .catch and in reason. The Typing errors lesson shows how to handle it.
• "Writing Promise<Cart> makes the server send a cart." No. Types are gone when the code runs. Check data from a server first, as in Typing fetch & JSON.
• "setTimeout gives back a number everywhere." No. In the browser it does. Node.js's types say NodeJS.Timeout. ReturnType<typeof setTimeout> fits both.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try a fix: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1type Order = { id: number; total: number };2 3async function loadOrder(): Promise<Order> {4  return { id: 7, total: 12 };5}6 7const order = loadOrder();

1type Order = { id: number; total: number };2 3async function loadOrder(): Promise<Order> {4  return { id: 7, total: 12 };5}6 7const order = loadOrder();8//    ^?

async function isInStock(): Promise<boolean> {
  return false;
}

async function showButton() {
  const inStock = isInStock();
  if (inStock) console.log("Add to cart");
  else console.log("Sold out");
}

showButton();

1async function isInStock(): Promise<boolean> {2  return false;3}4 5async function showButton() {6  const inStock = await isInStock();7  if (inStock) console.log("Add to cart");8  else console.log("Sold out");9}10 11showButton();

1type Cart = { items: number; total: number };2 3async function loadCart(): Promise<Cart> {4  return { items: 3, total: 12 };5}6 7async function showTax() {8  const cart = loadCart();9  const tax = cart.total * 0.25;10  console.log(`Tax: $${tax}`);11}12 13showTax();

1type Cart = { items: number; total: number };2 3async function loadCart(): Promise<Cart> {4  return { items: 3, total: 12 };5}6 7async function showTax() {8  const cart = await loadCart();9  const tax = cart.total * 0.25;10  console.log(`Tax: $${tax}`);11}12 13showTax();

1type User = { name: string };2type Cart = { items: number; total: number };3 4async function loadUser(): Promise<User> {5  return { name: "Asha" };6}7 8async function loadCart(): Promise<Cart> {9  return { items: 3, total: 12 };10}11 12async function greet() {13  const requests = [loadUser(), loadCart()];14  const [user, cart] = await Promise.all(requests);15  console.log(`Hi ${user.name}, you have ${cart.items} items`);16}17 18greet();

1type User = { name: string };2type Cart = { items: number; total: number };3 4async function loadUser(): Promise<User> {5  return { name: "Asha" };6}7 8async function loadCart(): Promise<Cart> {9  return { items: 3, total: 12 };10}11 12async function greet() {13  const requests = [loadUser(), loadCart()] as const;14  const [user, cart] = await Promise.all(requests);15  console.log(`Hi ${user.name}, you have ${cart.items} items`);16}17 18greet();

1type Cart = { items: number; total: number };2 3function timeout(ms: number) {4  return new Promise((_, reject) => {5    setTimeout(() => reject(new Error("Timed out")), ms);6  });7}8 9function withTimeout<T>(task: Promise<T>, ms: number): Promise<T> {10  return Promise.race([task, timeout(ms)]);11}12 13function loadCart(): Promise<Cart> {14  return new Promise((resolve) => {15    setTimeout(() => resolve({ items: 3, total: 12 }), 300);16  });17}18 19withTimeout(loadCart(), 100)20  .then((cart) => console.log(`Total: $${cart.total}`))21  .catch((error) => console.log(error.message));

1type Cart = { items: number; total: number };2 3function timeout(ms: number): Promise<never> {4  return new Promise((_, reject) => {5    setTimeout(() => reject(new Error("Timed out")), ms);6  });7}8 9function withTimeout<T>(task: Promise<T>, ms: number): Promise<T> {10  return Promise.race([task, timeout(ms)]);11}12 13function loadCart(): Promise<Cart> {14  return new Promise((resolve) => {15    setTimeout(() => resolve({ items: 3, total: 12 }), 300);16  });17}18 19withTimeout(loadCart(), 100)20  .then((cart) => console.log(`Total: $${cart.total}`))21  .catch((error) => console.log(error.message));

1type Cart = { items: number; total: number };2 3async function retry<T>(task: () => Promise<T>, times: number): Promise<T> {4  for (let attempt = 1; ; attempt++) {5    try {6      return task();7    } catch (error) {8      if (attempt >= times) throw error;9      console.log(`Attempt ${attempt} failed`);10    }11  }12}13 14let calls = 0;15async function loadCart(): Promise<Cart> {16  calls++;17  if (calls < 3) throw new Error("Server busy");18  return { items: 3, total: 12 };19}20 21retry(loadCart, 3)22  .then((cart) => console.log(`Total: $${cart.total}`))23  .catch((error) => console.log(`Failed: ${error.message}`));

1type Cart = { items: number; total: number };2 3async function retry<T>(task: () => Promise<T>, times: number): Promise<T> {4  for (let attempt = 1; ; attempt++) {5    try {6      return await task();7    } catch (error) {8      if (attempt >= times) throw error;9      console.log(`Attempt ${attempt} failed`);10    }11  }12}13 14let calls = 0;15async function loadCart(): Promise<Cart> {16  calls++;17  if (calls < 3) throw new Error("Server busy");18  return { items: 3, total: 12 };19}20 21retry(loadCart, 3)22  .then((cart) => console.log(`Total: $${cart.total}`))23  .catch((error) => console.log(`Failed: ${error.message}`));

Check your understanding

For each question, ask: is this the promise, or the value inside it? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Promise<Cart> is a promise that a cart will arrive. Only await or then gets the Cart out.
• An async function always gives back a promise. Write its return type as Promise<T>.
• TypeScript catches a forgotten await when you use the promise as a value, including in a condition.
• Promise.all gives a tuple, like [User, Cart], when it can see each place in the list.
• Type a timeout as Promise<never> and helpers like withTimeout and retry as generics, so the result keeps its type.

Coming next: Typing errors. It covers the other side of a promise: why a catch block gives you unknown while a .catch callback gets any, and how to type what goes wrong.