The JavaScript Promise.any() method
The Promise.any() method resolves with the value of the first promise to fulfill, ignoring any that reject — unless they all reject, in which case it rejects with an AggregateError. Use it for "first success wins", like racing several mirrors and taking whichever responds first. It differs from Promise.race(), which settles on the first to settle (including a rejection).
Overview
Promise.any() takes a list of promises and resolves as soon as any one fulfills, giving you that value. Crucially, it ignores rejections — a failed promise doesn't end the race, it just doesn't win. You only get a rejection if every promise rejects.
That makes it the "first success" combinator. Fetching the same resource from several mirrors and using whichever responds first, trying multiple data sources, attempting a few fallbacks in parallel — Promise.any() returns the first that works and discards the failures. When all of them fail, it rejects with a special AggregateError whose .errors array holds every individual rejection.
It's easy to confuse with Promise.race(), but they differ on rejection: race() settles on the first promise to settle, so a fast rejection wins and rejects the race; any() waits for the first fulfillment and only cares about rejections if all fail. The full set is all() (all must succeed), allSettled() (every outcome), race() (first to settle), and any() (first to succeed).
Syntax
const first = await Promise.any([p1, p2, p3]);
try {
const data = await Promise.any([fetchA(), fetchB(), fetchC()]);
} catch (err) {
// err is an AggregateError; err.errors holds all rejections
}Parameters
The Promise.any() method accepts the following parameters.
| Parameter | Description |
|---|---|
iterable |
An iterable of promises. Resolves with the first fulfillment, or rejects with an AggregateError if all reject. |
Example
<pre id="out" style="font:15px ui-monospace,monospace"></pre>
<script>
const ok = (v, ms) => new Promise(r => setTimeout(() => r(v), ms));
const fail = (ms) => new Promise((_, rej) => setTimeout(() => rej('x'), ms));
// the fast failure is ignored; first success wins
Promise.any([fail(200), ok('B', 500), ok('C', 300)]).then(v => {
document.getElementById('out').textContent = 'first success: ' + v; // C
});
</script>Best practices
- Use
Promise.any()for "first success wins" — racing mirrors or fallbacks. - Catch the
AggregateError(its.errorsarray has every rejection) for the all-fail case. - Use Promise.race() instead when a fast rejection should win.
- For every outcome regardless of success, use Promise.allSettled().
Frequently asked questions
What does Promise.any() do?
AggregateError.What is the difference between Promise.any() and Promise.race()?
any() waits for the first fulfillment and ignores rejections; race() settles on the first to settle, so a fast rejection rejects the race.What happens if every promise rejects?
Promise.any() rejects with an AggregateError whose .errors array contains all the individual rejection reasons.