Sequential vs parallel

Some work in JavaScript finishes later, not right away. Loading data from a server is one example. A timer is another. We call this async work. When you start async work, you get back a promise: an object that will hold the result once the work is done. When the work is done, we say the promise has settled. It either succeeded or failed.

You already know that await pauses a function until a promise settles. This lesson asks a new question: when you have several jobs, when should each one start? There are three choices:

• Sequential: one job at a time. The next job starts only after the one before it has settled.
• Parallel: start all the jobs first, then wait until every one is done.
• Limited: run only a few jobs at the same time, for example two. This is called a concurrency limit. "Concurrency" just means "how many things are running at the same time".

async function save(item) {
  console.log("saved " + item);
}

async function main() {
  for (const item of ["tea", "toast"]) {
    await save(item);
  }
  console.log("done");
}
main();

Line 6 loops over two items, "tea" and "toast". Line 7 calls save and waits for it. The loop does not move on to "toast" until the save for "tea" has settled. So the output is saved tea, then saved toast, then done. This is sequential: the second save starts only on the next turn of the loop.

const requests = [900, 500, 700, 300];

// Sequential: the next request starts after the one before it finishes.
for (const ms of requests) {
  await fakeRequest(ms);
}

// Parallel: start every request first, then wait for all of them.
await Promise.all(requests.map((ms) => fakeRequest(ms)));

// Limited: at most two workers take jobs from the list.
await mapWithLimit(requests, 2, fakeRequest);

When you put await inside a for...of loop, the loop runs one item at a time. That is on purpose. It is the right choice when:

• each step needs the result of the step before it,
• the order of the steps matters, or
• a server asks you not to send too many requests at once.

It is slow for no reason when the items don't depend on each other. Then they wait in line when they could all run at once.

Watch out for forEach. It calls your async function once for each item. Each call gives back a promise, but forEach throws those promises away. So the code after forEach doesn't wait for them. Switch the setting below and watch the order of the printed lines change.

async function save(item) {
  console.log("saved " + item);
}

async function main() {
  for (const item of ["tea", "toast"]) {
    await save(item);
  }
  console.log("done");
}
main();

The two items are saved in array order, and done prints last. That order matters when, for example, request 2 must not start until request 1 has finished.

1const items = ["A", "B", "C"];Run2items.forEach(async (item) => {3  await save(item);4  console.log("saved " + item);5});6console.log("done");

If you call array.map with an async function, you get back an array of promises, not an array of results. To get the results, you need something that waits for all of them. That is Promise.all. You give it an array of promises, and it gives you back one promise for the whole group.

So the usual pattern is await Promise.all(promises). First you start every job. Then you pause once, until the whole group is done.

1const promises = ids.map(async (id) => {2  return getProfile(id);3});4 5// promises is an array. This is the promise for the whole group.6const profiles = await Promise.all(promises);

Lines 1 to 3 call getProfile once for each id. Each call starts right away and gives back a promise. Line 6 waits for all of them and puts the results in profiles.

async function load(name) {
  return "loaded " + name;
}

async function main() {
  const results = await Promise.all([
    load("profile"),
    load("settings"),
  ]);
  console.log(results.join(" | "));
}
main();

Each load call gives back a promise. Promise.all waits for both and gives back the two strings in an array. The output is loaded profile | loaded settings. The results are always in the same order as the calls, even if the second job finishes first.

Promise.all fails fast. If one promise fails (we say it rejects), the whole group fails right away. You don't wait for the others. But Promise.all does not stop the other jobs. They keep running. The Cancellation with AbortController lesson, coming up next, shows how to stop them.

Sometimes you want every result, even the failed ones. Then use Promise.allSettled. It waits for every promise and gives you one small report object for each.

await getA(); await getB(); starts getB only after getA has finished. If the two jobs don't depend on each other, call both functions first, and wait afterwards. Remember this sentence: calling the function starts the job; await only decides when you stop and wait.

async function sequential() {
  const a = await getA();
  const b = await getB();
  return [a, b];
}

async function startEarly() {
  const aPromise = getA();
  const bPromise = getB();
  const a = await aPromise;
  const b = await bPromise;
  return [a, b];
}

async function safest() {
  return Promise.all([getA(), getB()]);
}

There is one catch with the middle version in the lab, where you call both functions and then await each one. Look at the code: const bPromise = getB(); await aPromise; await bPromise;. bPromise might fail while the function is still waiting on aPromise. At that moment, nothing is listening for that failure yet. Some browsers then show an "unhandled rejection" warning in the console. Promise.all listens to every promise in the group from the start, so it is usually the safer choice.

async function main() {
  const results = await Promise.allSettled([
    Promise.resolve("saved A"),
    Promise.reject("offline"),
  ]);

  console.log(results.map((result) => result.status).join(", "));
}
main();

The first promise succeeds and the second one fails. Promise.allSettled waits for both and gives one report object for each. Each object has a status: "fulfilled" for a success or "rejected" for a failure. So this prints fulfilled, rejected. Promise.all would have failed instead.

Starting every job at once is not always a good idea:

• Browsers open only a few connections to the same server at a time. With the older HTTP/1.1 protocol, it is often about six. Newer HTTP/2 can send many requests over one connection.
• A server may refuse your requests if you send too many too fast. This is called a rate limit.
• Your own page may run out of memory if it starts a thousand image jobs at once.

A pool solves this. The jobs still don't depend on each other, but only a few run at the same time. The code below makes a small number of workers. A worker is a function that repeats three steps:

1. Take the next position (index) from the list.
2. Wait for that item's job.
3. Store the result at the same position, so the results stay in the same order as the input.

1async function mapWithLimit(items, limit, fn) {2  const results = new Array(items.length);3  let nextIndex = 0;4 5  async function worker() {6    while (nextIndex < items.length) {7      const index = nextIndex++;8      results[index] = await fn(items[index], index);9    }10  }11 12  const workers = Array.from(13    { length: Math.min(limit, items.length) },14    () => worker()15  );16  await Promise.all(workers);17  return results;18}

async function main() {
  const results = await mapWithLimit(
    ["A", "B", "C"],
    2,
    async (item) => item.toLowerCase(),
  );

  console.log(results.join(","));
}
main();

With a limit of 2, the two workers can finish at different times. But each result goes into its own position. So this prints a,b,c, the same order as the input, not the order the workers finished in.

A waterfall is a chain of async steps where each step waits for the one before it. Some waterfalls are needed:

• You need the user before you can load their posts.
• You need a post before you can load its comments.

Other waterfalls happen by mistake. Imagine you phone Ann, wait for her answer, and only then phone Ben. Ben never needed Ann's answer, so the wait was wasted time.

1// A real waterfall: each request needs data from the one before.2const user = await getUser(userId);3const posts = await getPosts(user.id);4const comments = await getComments(posts[0].id);5 6// These requests don't need each other: start them together.7const [profile, settings, notifications] = await Promise.all([8  getProfile(userId),9  getSettings(userId),10  getNotifications(userId),11]);

Lines 2 to 4 are a real waterfall: getPosts needs user.id from line 2, and getComments needs a post's id from line 3. Lines 7 to 11 don't: all three requests only need userId, which you already have. So they start together.

async function main() {
  const user = { id: 7 };
  const posts = await getPosts(user.id);
  console.log("posts need " + posts[0].id);

  const profilePromise = getProfile(user.id);
  const settingsPromise = getSettings(user.id);
  const [profile, settings] = await Promise.all([
    profilePromise,
    settingsPromise,
  ]);
  console.log(profile.name + " / " + settings.theme);
}
main();

Line 3 waits for the posts, because line 4 needs them. The profile and the settings only need user.id, and neither needs the other. So lines 6 and 7 start both, and line 8 waits for the pair. This prints posts need 70, then Ada / dark.

Where you’ll use this

You will make this choice often. For example, when a page loads its data, when a dashboard fills its panels, when a tool uploads many files, or when a form is sent. Before you put one await under another, ask three questions:

1. Does the next job need the result of the one before it?
2. Would starting every job at once be too much for the server, the browser, or memory?
3. Do I need every job to succeed, or do I want a report on every job, even the failed ones?

The table below compares the four ways to wait. Read each row as: "this pattern is good for this, but watch out for that."

async function main() {
  const userId = 3;
  const [profile, settings] = await Promise.all([
    getProfile(userId),
    getSettings(userId),
  ]);

  console.log(profile.name + " / " + settings.theme);
}
main();

The profile and the settings both only need userId, so neither waits for the other. The dashboard waits once for both and prints Ada / dark.

Common misconceptions

• “await freezes all of JavaScript.” It only pauses the async function it is in. Other code, like click handlers, can still run.
• “Parallel means using several CPU cores.” Here it means the waits overlap. The browser or the network does the work while your JavaScript waits.
• “Promise.all stops the other jobs when one fails.” It fails right away, but the other jobs keep running. You need a separate way to cancel them.
• “map with an async function gives me the results.” It gives an array of promises. Wait for them with Promise.all to get the results.
• “One at a time is always bad.” It is correct when each step needs the one before, when order matters, or when a server limits your requests.
• “Starting everything at once is always fastest.” Too many jobs at once can overload the server or the browser and make things slower or fail.

Key takeaways

• await inside for...of runs one job at a time, on purpose.
• forEach doesn't wait for async functions.
• Start jobs that don't depend on each other first, then wait for them together, usually with Promise.all.
• Promise.all fails as soon as one job fails, but it doesn't stop the other jobs.
• Use Promise.allSettled when you need every result, even failures.
• Use a pool when starting every job at once would be too much.

Sequential waits in line. Parallel starts everything together. A pool starts a few at a time.

Up next: Cancellation with AbortController.