← Back to glossary

Promise.allSettled / Promise.any / Promise.race

javascript ES2020 Intermediate

Also Known As

Promise.allSettled Promise.any Promise.race Promise combinators

TL;DR

Three Promise combinators for handling multiple async operations — allSettled() waits for all to complete regardless of failure, any() resolves with the first success, race() resolves or rejects with the first to settle.

Explanation

Promise.all() is the most known combinator — it resolves when all promises resolve and rejects immediately on the first rejection (fail-fast). Three others cover different patterns: Promise.allSettled() (ES2020) waits for all promises to settle and returns an array of {status, value/reason} objects — none are skipped on failure. Promise.any() (ES2021) resolves with the first successful promise, only rejecting if all promises reject (with an AggregateError). Promise.race() resolves or rejects with whichever promise settles first — useful for timeouts. Combining these correctly depends entirely on whether you want fail-fast, fail-never, or first-success semantics.

Common Misconception

✗ Promise.race() cancels the slower promises when one wins. It does not — all promises continue running; race() just ignores the results of non-winners. The underlying work (API calls, timers) is not cancelled.

Why It Matters

Choosing the wrong Promise combinator causes subtle bugs: using Promise.all() when you want allSettled() means one failed API call silently aborts all the others. Using race() for a timeout without cancellation causes the losing promise to continue running in the background. Knowing which combinator fits which use case prevents these issues.

Common Mistakes

Using Promise.all() for independent operations where partial success is acceptable — one failure kills everything unnecessarily.
Not handling AggregateError from Promise.any() — when all promises reject, any() throws AggregateError containing all rejection reasons; catch and handle it.
Race condition with Promise.race() and side effects — the losing promises continue running and may modify shared state after the winner has already returned.
Forgetting that allSettled() never rejects — you must inspect each result's status field; the outer await will always succeed.

Code Examples

✗ Vulnerable

// ❌ Promise.all() fails-fast — one error aborts everything
const [user, orders, recommendations] = await Promise.all([
    fetchUser(id),          // If this fails...
    fetchOrders(id),        // ...these are abandoned
    fetchRecommendations(id), // ...and this too
]);
// User sees blank page instead of partial content

// ❌ Race timeout without cancellation — fetch continues in background
const result = await Promise.race([
    fetch('/api/data'),
    new Promise((_, reject) => setTimeout(() => reject('Timeout'), 3000)),
]);

✓ Fixed

// ✅ allSettled — partial failures show graceful degradation
const results = await Promise.allSettled([
    fetchUser(id),
    fetchOrders(id),
    fetchRecommendations(id),
]);

const [user, orders, recs] = results.map(r =>
    r.status === 'fulfilled' ? r.value : null
);
// Page renders with whatever data loaded successfully

// ✅ Race timeout with AbortController — actually cancels the request
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 3000);

try {
    const result = await fetch('/api/data', { signal: controller.signal });
    clearTimeout(timeout);
    return await result.json();
} catch (e) {
    if (e.name === 'AbortError') throw new Error('Request timed out');
    throw e;
}

// ✅ any() — first working CDN wins
const image = await Promise.any([
    fetch('https://cdn1.example.com/img.jpg'),
    fetch('https://cdn2.example.com/img.jpg'),
]);

References

↗ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled