Suggest an edit

Improve this article

Refine the answer for “What does Promise.any() 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.any()` does

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

- **fulfills**, as soon as **the first promise resolves successfully**;
- **rejects**, if **all the promises are rejected**.

> In other words: "give me the first successful result - ignore the errors".

---

## Syntax

```javascript
Promise.any(iterable)
```

### Returns:

a new **Promise** that:

- fulfills with the value of the **first** `fulfilled` **promise**;
- rejects with a special `AggregateError` if all the promises fail.

---

## Example 1 - the first success "wins"

```javascript
const p1 = Promise.reject('Error 1');
const p2 = new Promise(resolve => setTimeout(() => resolve('Success 2'), 1000));
const p3 = new Promise(resolve => setTimeout(() => resolve('Success 3'), 2000));

Promise.any([p1, p2, p3])
  .then(result => console.log('Result:', result))
  .catch(err => console.error('Error:', err));
```

**Output after 1 second:**

```javascript
Result: Success 2
```

The first success (`p2`) "wins",
even if the others are still running or fail later.

---

## Example 2 - if all promises reject

```javascript
const p1 = Promise.reject('Error A');
const p2 = Promise.reject('Error B');

Promise.any([p1, p2])
  .then(console.log)
  .catch(err => console.error(err));
```

**Output:**

```javascript
AggregateError: All promises were rejected
```

The error contains **a list of all reasons**:

```javascript
err.errors // ['Error A', 'Error B']
```

---

## How it works under the hood

1. All promises run **in parallel**.
2. If at least one of them **fulfills successfully (**`resolve`**)** →
`Promise.any()` **immediately resolves with that result**.
3. If **all** of them turn out `rejected` →
it returns an **error of type** `AggregateError` with an array of all reasons.

---

## Example 3 - a mix of successes and errors

```javascript
const slow = new Promise(resolve => setTimeout(() => resolve('Slow success'), 2000));
const fail = Promise.reject('Error!');
const fast = new Promise(resolve => setTimeout(() => resolve('Fast success'), 500));

Promise.any([slow, fail, fast])
  .then(console.log)
  .catch(console.error);
```

**Result after 0.5 sec:**

```javascript
Fast success
```

Even though `fail` fails earlier, `Promise.any()` waits for the first **successful** promise.

---

## Difference from other methods

| Method | What it returns | Resolves when | Error when |
|---|---|---|---|
| `Promise.all()` | An array of all successful results | All promises are `fulfilled` | The first `reject` |
| `Promise.allSettled()` | An array of statuses (`fulfilled` / `rejected`) | All promises have settled | Never |
| `Promise.race()` | The first promise to settle (success or error) | Any `resolve` or `reject` | Resolves on the first `reject` |
| `Promise.any()` | The first successful result | The first `fulfilled` | When **all** are `rejected` |

In other words:

- `Promise.race()` reacts to **the first promise to settle** (including errors),
- `Promise.any()` reacts only to **the first success**.

---

## Example 4 - "backup" (fallback)

Imagine you have three servers:
you want to get data **from the first one that responds successfully**,
even if the other two are unavailable.

```javascript
const fetchFromA = fetch('/api/a'); // can fail
const fetchFromB = fetch('/api/b');
const fetchFromC = fetch('/api/c');

Promise.any([fetchFromA, fetchFromB, fetchFromC])
  .then(res => console.log('Response received'))
  .catch(() => console.error('All servers unavailable'));
```

This is how you implement a "fallback" strategy -
**success from any source is considered enough**.

---

## Example 5 - `AggregateError` behavior

```javascript
Promise.any([
  Promise.reject('Error 1'),
  Promise.reject('Error 2')
]).catch(err => {
  console.error(err.name);   // AggregateError
  console.error(err.errors); // ['Error 1', 'Error 2']
});
```

---

## A simple analogy

> Imagine you send three couriers: a bike, a car, and a rocket.
>
> - `Promise.any()` says: "whoever **delivers successfully first**, I take their result;
> the errors of the rest - don't matter".
> - Only if **all** of them get lost - only then do you learn about the error.

---

## SUMMARY

| Property | Value |
|---|---|
| **What it does** | Returns the first **successfully fulfilled** promise |
| **If all are rejected** | Returns `AggregateError` with the reasons |
| **Return type** | `Promise` |
| **Similar to** | `Promise.race()`, but ignores `reject` |
| **Typical scenarios** | fallback requests, backup data sources, redundant API requests |

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.