Suggest an edit

Improve this article

Refine the answer for “What does Promise.race() do?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## What `Promise.race()` does

`Promise.race(iterable)` takes an array (or any iterable) of promises
and **returns a new promise** that:

- **is fulfilled** or **is rejected**,
**as soon as the first of the passed promises settles**,
regardless of whether it succeeded or failed.

> In other words, it's a "race" of promises: whichever finishes first determines the result.

---

## Syntax

```javascript
Promise.race(iterable)
```

### Returns:

a new **Promise** that:

- settles with the value of the first promise that resolved (`resolve`),
- or fails with an error, if the first one to settle was a `reject`.

---

## Example 1 - whoever is faster wins

```javascript
const fast = new Promise(resolve => setTimeout(() => resolve('Fast'), 1000));
const slow = new Promise(resolve => setTimeout(() => resolve('Slow'), 3000));

Promise.race([fast, slow]).then(console.log);
```

**Result after 1 second:**

```javascript
Fast
```

The second promise (`slow`) keeps running in the background,
but the result is already decided - `fast` won the "race".

---

## Example 2 - if the first promise fails

```javascript
const ok = new Promise(resolve => setTimeout(() => resolve('All good'), 2000));
const fail = new Promise((_, reject) => setTimeout(() => reject('Error!'), 1000));

Promise.race([ok, fail])
  .then(console.log)
  .catch(console.error);
```

**Result after 1 second:**

```javascript
Error!
```

Even though `ok` will later resolve successfully,
the outcome of the whole race is already decided by the error.

---

## How this works under the hood

1. All promises start running *practically* at the same time.
2. As soon as **one of them settles** (`resolve` or `reject`):
  - that promise's result becomes **the result of the whole race**;
  - `Promise.race()` **moves to the** `fulfilled` **or** `rejected` **state**;
  - the remaining promises **are ignored** (but not canceled).
3. The rest keep running in the background, but their result doesn't affect anything.

---

## Example 3 - with a "timeout"

A common practice: using `Promise.race()` to set a **time limit**

```javascript
function timeout(ms) {
  return new Promise((_, reject) =>
    setTimeout(() => reject(`Timed out (${ms}ms)`), ms)
  );
}

const fetchData = new Promise(resolve =>
  setTimeout(() => resolve('Response received'), 3000)
);

Promise.race([fetchData, timeout(2000)])
  .then(console.log)
  .catch(console.error);
```

**Output after 2 seconds:**

```javascript
Timed out (2000ms)
```

This is one of the most common scenarios for `Promise.race()`,
limiting "hanging" operations (for example, requests).

---

## Example 4 - all promises are instant

```javascript
Promise.race([
  Promise.resolve('First'),
  Promise.resolve('Second'),
  Promise.resolve('Third')
]).then(console.log);
```

Output:

```javascript
First
```

Even if all of them resolve instantly,
the **first in iteration order** wins.

---

## If you pass non-promises

`Promise.race()` automatically "wraps" plain values in `Promise.resolve()`:

```javascript
Promise.race([42, Promise.resolve('OK')]).then(console.log); // 42
```

---

## Difference from other methods

| Method | What it does | Settles when | On error |
|---|---|---|---|
| `Promise.all()` | Waits for all promises | All settle successfully | Fails on the first `reject` |
| `Promise.allSettled()` | Waits for all, regardless of outcome | All settle | Never fails |
| `Promise.race()` | Takes the first to settle | The first `resolve` or `reject` | Depends on the first promise |
| `Promise.any()` | Takes the first success (`resolve`) | The first `fulfilled` | Fails if **all** are `rejected` |

---

## A simple analogy

> Imagine a race.
>
> You have several couriers - whoever delivers the package first, that's the result you accept.
> The rest are still on the way, but you no longer care, you already got what you needed.

---

## SUMMARY

| Feature | `Promise.race()` |
|---|---|
| Accepts | An array (or other iterable) of promises |
| Settles when | The first promise resolves or rejects |
| Returns | The result (or error) of the first promise to settle |
| The remaining promises | Are ignored (but not canceled) |
| Common use | Time limits (`timeout`), competing requests |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts626 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.