How to use async/await in a loop in JavaScript

1A sleep() helper built from setTimeout

JavaScript has no built-in sleep(), because a function that blocked the thread would freeze everything else the program is doing. What you can do is make a promise that resolves after a delay and await it. setTimeout(resolve, ms) calls resolve once the time is up, which fulfils the promise and lets the awaiting code continue. Every other example on this page uses this one-line helper.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

console.log('start');
await sleep(500); // pauses here for half a second
console.log('half a second later');

// sleep() pauses only the async function that awaits it
async function countdown(label) {
  for (const n of [3, 2, 1]) {
    console.log(label, n);
    await sleep(100);
  }
  console.log(label, 'liftoff');
}

const running = countdown('rocket'); // started, not awaited yet
console.log('the rest of the program keeps going');
await running;
console.log('end');

Prints start and half a second later, then rocket 3 followed by the rest of the program keeps going, then rocket 2, rocket 1, rocket liftoff and end. The second half is the point. countdown ran until its first await and handed control back, so the next line printed before rocket 2. Nothing was blocked. The top-level await works because this code runs as an ES module. In an older CommonJS script, put the code inside an async function and call it.

2Why forEach does not wait

Here is the bug from the Stack Overflow question. An async callback returns a promise as soon as it reaches its first await. forEach calls the callback for each item, throws that promise away and moves on. It returns undefined, so there is nothing to await either: await items.forEach(...) waits for nothing. The three jobs below take 300, 100 and 200 ms.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const jobs = [
  { name: 'a', ms: 300 },
  { name: 'b', ms: 100 },
  { name: 'c', ms: 200 },
];
const done = [];

const returned = jobs.forEach(async (job) => {
  await sleep(job.ms);
  console.log('finished', job.name);
  done.push(job.name);
});

console.log('forEach returned', returned);
console.log('after forEach:', done); // nothing has finished yet

await sleep(500);
console.log('500 ms later:', done); // finish order, not input order

Prints forEach returned undefined and after forEach: [] first: the loop was over before any job finished. Then come finished b, finished c, finished a, and finally 500 ms later: [ 'b', 'c', 'a' ], in the order the timers fired rather than the order of the array. Two more problems hide here. The jobs all ran at once, which is not what most people who write await in a loop expect. And if a callback throws, nobody is listening: the rejection is unhandled, which crashes a Node process. The await sleep(500) guess only makes this demo work. Never use it as a fix. The same applies to map, filter, some and reduce with an async callback; none of them await it.

3One at a time: for...of with awaitRecommended

The direct fix is a real loop. In a for...of body, await pauses the enclosing function, so iteration two does not start until iteration one has finished. Use it when order matters, when each step depends on the one before, or when the other side can only handle one request at a time. A classic for (let i = 0; ...) loop and while work the same way; only the callback-based array methods don't.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Stand-in for a network call: waits, then returns a value
async function loadUser(id) {
  await sleep(id * 50);
  return { id, name: `user${id}` };
}

const ids = [3, 1, 2];
const users = [];

for (const id of ids) {
  const user = await loadUser(id); // the loop waits here each time
  console.log('loaded', user.name);
  users.push(user);
}

console.log('all done:', users.map((u) => u.name));

// Need the index too? entries() works the same way
for (const [i, id] of ids.entries()) {
  const user = await loadUser(id);
  console.log(i, user.name);
}

Prints loaded user3, loaded user1, loaded user2, then all done: [ 'user3', 'user1', 'user2' ], then 0 user3, 1 user1, 2 user2. User 3 is the slowest (150 ms) yet it still comes first, because nothing else starts until it is done. The cost is time: the loop takes the sum of all the delays. break, continue and return all work here, which they never do inside forEach, and a try/catch around the await catches a failure in that iteration.

4All at once: Promise.all with map

When the jobs are independent, start them all and wait once. items.map(work) calls the async function for every item straight away and returns an array of promises. Promise.all turns that array into one promise that fulfils with every result, in input order, once all of them are done. The total time is roughly the slowest job, not the sum.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function work(job) {
  await sleep(job.ms);
  console.log('finished', job.name);
  return job.name.toUpperCase();
}

const jobs = [
  { name: 'a', ms: 300 },
  { name: 'b', ms: 100 },
  { name: 'c', ms: 200 },
];
const start = Date.now();

// map() starts every call at once and gives you an array of promises
const promises = jobs.map(work);
console.log(promises);

// Promise.all waits for all of them; results come back in input order
const results = await Promise.all(promises);
console.log(results);
console.log('took under 400 ms:', Date.now() - start < 400);

The first line is [ Promise { <pending> }, Promise { <pending> }, Promise { <pending> } ]. That is what map with an async callback gives you on its own, and why it always needs Promise.all. The jobs finish as finished b, finished c, finished a, but the result is still [ 'A', 'B', 'C' ], lined up with jobs. Then took under 400 ms: true: about 300 ms in total, where the for...of version would take 600. One catch: Promise.all rejects as soon as any promise rejects, which the next section deals with. It also starts everything at once, so for thousands of items, process them in batches (see the FAQ).

5When some fail: Promise.allSettled

With Promise.all, one failure throws away every result, including the ones that succeeded. Promise.allSettled never rejects. It waits for every promise and gives back one object per input, in input order: { status: 'fulfilled', value } or { status: 'rejected', reason }. Use it when a partial result is still useful, such as health checks, batch uploads or notifications.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function check(service) {
  await sleep(service.ms);
  if (service.name === 'db') throw new Error('db timed out');
  return `${service.name} ok`;
}

const services = [
  { name: 'cache', ms: 100 },
  { name: 'db', ms: 50 },
  { name: 'queue', ms: 150 },
];

// Promise.all rejects as soon as any one promise rejects
try {
  await Promise.all(services.map(check));
} catch (err) {
  console.log('Promise.all threw:', err.message);
}

// Promise.allSettled waits for every promise and reports each outcome
const outcomes = await Promise.allSettled(services.map(check));
console.log(outcomes[0]);

for (const [i, outcome] of outcomes.entries()) {
  const name = services[i].name;
  if (outcome.status === 'fulfilled') {
    console.log(name, '->', outcome.value);
  } else {
    console.log(name, '-> failed:', outcome.reason.message);
  }
}

Prints Promise.all threw: db timed out, and the cache and queue results are lost. The allSettled version prints the first outcome as { status: 'fulfilled', value: 'cache ok' }, then cache -> cache ok, db -> failed: db timed out and queue -> queue ok. Note that a rejected Promise.all does not cancel the other jobs; they keep running and their results are simply ignored. JavaScript promises can't be cancelled. If you want the first success instead of all of them, use Promise.any; for the first to finish either way, Promise.race.

6Values that arrive over time: for await...of

for await...of loops over an async iterable: a source that produces its next value later, such as pages from an API or chunks of a stream. The easiest way to write one is an async function* generator, which can await and yield. The loop asks for one value, waits for it, runs the body, then asks for the next.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// An async generator produces values over time, one page at a time
async function* pages() {
  for (let page = 1; page <= 3; page++) {
    await sleep(50); // pretend to fetch the next page
    yield [`item${page * 2 - 1}`, `item${page * 2}`];
  }
}

for await (const items of pages()) {
  console.log('got page:', items);
}

// It also accepts an array of promises and awaits them in array order
const timers = [300, 100, 200].map((ms) => sleep(ms).then(() => ms));
for await (const ms of timers) {
  console.log('timer', ms);
}

Prints got page: [ 'item1', 'item2' ], then [ 'item3', 'item4' ] and [ 'item5', 'item6' ] pages, then timer 300, timer 100, timer 200: array order, not the order they finished. Looping over an array of promises this way works, but prefer Promise.all for it. If a later promise rejects while the loop is still waiting on an earlier one, that rejection has no handler yet and can crash the process. for await is meant for sources that really produce values one by one, and it only works inside an async function or at the top level of a module.

7Which should you use?