Promise.race and Promise.any

## The one-sentence rule `Promise.race(iterable)` returns a new promise that settles the moment the **first** entry of the iterable settles, and it adopts that entry's outcome verbatim — fulfilled with its value, or rejected with its reason. "Race" is literal: it is first past the post, and finishing first is not the same as finishing well. ## Why the rejection case surprises people The name suggests "give me the first answer", and people read *answer* as *success*. The spec does not agree. Internally the combinator attaches the same pair of handlers to every entry — the resolve function and the reject function of the promise it hands back: ```javascript const first = Promise.race([ new Promise((resolve) => setTimeout(() => resolve('slow ok'), 50)), new Promise((_, reject) => setTimeout(() => reject(new Error('fast fail')), 10)), ]); first.catch((e) => console.log(e.message)); // fast fail ``` The fast rejection reaches the reject function first, so the race rejects. The slow fulfilment arrives 40 ms later and calls the resolve function, which is now a no-op: a promise settles once and cannot be re-settled. Practical consequence — **a fast failure hides a slow success**. If you race three mirrors of the same resource hoping for the quickest good answer, one mirror that fails instantly wins the race and your whole call fails. `Promise.any` exists precisely for that case: it waits for the first *fulfilment*. ## What "first" means for values already settled Every entry is passed through `Promise.resolve` (strictly, through the constructor's `resolve` method), so the iterable may hold plain values and thenables, not just promises: ```javascript Promise.race([fetch('/slow'), 'sentinel']).then(console.log); // sentinel ``` A plain value resolves in the next microtask turn, so nothing that involves real I/O can beat it. When two entries are *already* settled, the winner is the earlier one in iteration order, because reactions are queued in that order. This makes such snippets deterministic, which is exactly why interviewers use them. ## The empty iterable `Promise.race([])` returns a promise that is **pending forever**. There is no entry to settle it and no default outcome, so `await Promise.race([])` inside an async function simply never continues. If the array of candidates is built dynamically — filtered mirrors, filtered pending requests — guard against it being empty; a silently hung request is much harder to diagnose than a thrown error. ## The everyday use: timeouts The reason `race` is on every interviewer's list is that it is how you bolt a deadline onto a promise that has no deadline of its own: ```javascript const timeout = (ms) => new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), ms)); const result = await Promise.race([doWork(), timeout(2000)]); ``` The timeout branch is a promise that only ever rejects, so either the work wins and you get its value, or the clock wins and you get an error. This works precisely *because* race honours rejections. ## What race does not do It does not cancel. When the race settles, the losing promises are still running; their eventual values are dropped on the floor, but their side effects — the network request completing, the row being written, the timer still pending — are not undone. A promise is a handle on a result, not a handle on the work, so no combinator built out of promises can stop anything. Cancelling for real requires the underlying operation to expose its own abort mechanism. One related nuance worth knowing: because `race` attached a rejection handler to *every* entry, a loser that rejects after the race has settled is still considered **handled**. It will not fire an unhandled-rejection warning, even though nobody visibly caught it. ## Reading a race result The returned value tells you *what* won, never *which entry* won. If you need the winner's identity, tag each entry before racing: ```javascript const tagged = sources.map((p, i) => p.then((value) => ({ i, value }))); const { i, value } = await Promise.race(tagged); ``` That is a plain chaining trick, not a feature of the combinator — a good sign you understand that `race` returns a value, not a promise identity.