Promise.race: Examples and Use Cases in JavaScript

Promise.race: Examples and Use Cases in JavaScript

Promise.race returns as soon as the first promise settles (fulfilled or rejected). Here are practical examples.

Timeout

function withTimeout(promise, ms) {
  const timeout = new Promise((_, reject) =>
    setTimeout(() => reject(new Error("timeout")), ms)
  );
  return Promise.race([promise, timeout]);
}
const result = await withTimeout(fetch("/api"), 5000);
``
If `fetch` takes more than 5 seconds, the timeout rejects first, and the race rejects.

### First Successful Source

```js
const fastest = await Promise.race([
  fetchFromCDN(),
  fetchFromOrigin(),
]);
``
Use whichever source responds first.

### Cancellation (Simplified)

```js
function cancellableFetch(url, signal) {
  return Promise.race([
    fetch(url),
    new Promise((_, reject) => signal.addEventListener("abort", () => reject(new Error("cancelled")))),
  ]);
}
``
If the signal aborts before the fetch completes, the race rejects.

### Empty Array

```js
const result = await Promise.race([]); // never settles (stays pending forever)
``
`Promise.race([])` never settles. Be careful not to pass an empty array.

### The First to Settle Can Be a Rejection

```js
const result = await Promise.race([
  Promise.resolve("success"),
  Promise.reject(new Error("fail")),
]);
// could be "success" or could throw, depending on which settles first
``
If the rejection settles first, the race rejects. This is different from `Promise.any`, which ignores rejections.

### The Takeaway

`Promise.race` returns the first promise to settle (fulfilled or rejected). Use cases: timeouts, first successful source, cancellation. If the first to settle is a rejection, the race rejects. `Promise.race([])` never settles.