Promise.race() in JavaScript: keeping the first promise to settle

A request that takes thirty seconds to answer is not a slow request, it is a lost one. But you still need a way to decide for yourself when to give up.

Promise.race exists for exactly that: put two outcomes against each other and keep whichever shows up first.

Definition

Promise.race(list) returns a promise that takes on the outcome of the first promise in the list to settle, fulfilled or rejected alike. The others keep running, and their result is ignored.

const later = (v, ms) => new Promise((r) => setTimeout(() => r(v), ms));

async function demo() {
  const winner = await Promise.race([
    later("slow", 300),
    later("fast", 50),
  ]);
  console.log(winner);   // fast
}

demo();

The word race is well chosen: there is only one winner, and a rejected promise that arrives before the others wins just as surely as a fulfilled one.

Setting a timeout

This is the main use. You run the real work against a promise that fails after a given time, and whichever comes first decides.

const failAfter = (ms) => new Promise((_, reject) => {
  setTimeout(() => reject(new Error("Timed out")), ms);
});

async function withTimeout(work, ms) {
  return Promise.race([work, failAfter(ms)]);
}

withTimeout(later("answer", 400), 100)
  .then((v) => console.log(v))
  .catch((err) => console.log(err.message));   // Timed out

The caller gets a clear error instead of an endless wait, and the catch treats the timeout exactly like any other failure.

race and any: two different races

Those three columns separate two needs. race answers the question of elapsed time, any answers the question of which server among several mirrors replies correctly first.

Frequently asked questions

No, and this is the costliest misunderstanding of the lot. The discarded promise carries its work through to the end: the request still leaves, the server still answers, the bill is the same. To really interrupt the call you need an AbortController.

It happens after the fact, with nobody listening, and the engine reports it as an unhandled rejection. An empty catch attached to the discarded promise is enough to neutralize it, or better still, a clean cancellation that stops it from happening at all.

By wrapping the call in a loop that starts over after a failure, with a growing pause between attempts. The race sets the limit of a single attempt, the loop decides how many attempts there are: the two mechanisms combine and should never be confused.