Promise Combinators

## The shared shape `Promise.all` and `Promise.allSettled` are both static methods on the `Promise` constructor. Each takes an **iterable** — normally an array, but any iterable works — walks it, passes every entry through `Promise.resolve` so plain values and thenables are treated uniformly, and returns one new promise that aggregates the whole batch. Neither of them *starts* anything: by the time you build the array, the functions inside it have already been called and the underlying work is already in flight. The combinator is only a way to observe when the batch is done. They differ in exactly one decision: what counts as "done", and therefore what the aggregate promise settles with. ## Promise.all — all-or-nothing `Promise.all` fulfils only when **every** input has fulfilled. Its fulfilment value is an array of the individual values, in the **order of the input iterable**, regardless of which finished first. ```js const [user, orders] = await Promise.all([fetchUser(id), fetchOrders(id)]); ``` If any input rejects, the aggregate rejects **immediately** with that single rejection reason — not an array of reasons, not a partial result. This is called fail-fast. The `await` above throws exactly as if a single call had thrown, which is why `Promise.all` composes so naturally with `try/catch`: the failure of any part is the failure of the whole. Two consequences follow that candidates often miss. First, the values of the inputs that did succeed are gone — the aggregate promise settles once, and it settled as a rejection. Second, rejecting the aggregate does not stop the other inputs: a promise is a handle on work that is already running, not a job you can call off, so the remaining requests still complete and their side effects still land. ## Promise.allSettled — a report per entry `Promise.allSettled` (ES2020) fulfils once every input has **settled**, fulfilled or rejected. It essentially never rejects; you always get an array back, again positionally matched to the input. Each element is a descriptor object: ```js const results = await Promise.allSettled([a(), b(), c()]); // [{ status: 'fulfilled', value: 1 }, // { status: 'rejected', reason: Error }, // { status: 'fulfilled', value: 3 }] ``` A fulfilled descriptor has `status` and `value`; a rejected one has `status` and `reason`. The other property is simply absent, so reading `.value` on a rejected entry gives `undefined` rather than throwing. Because the aggregate always fulfils, **you** are responsible for inspecting statuses — nothing throws on your behalf: ```js const ok = results.filter(r => r.status === 'fulfilled').map(r => r.value); const failures = results.filter(r => r.status === 'rejected').map(r => r.reason); ``` ## Timing: which one settles sooner A common assumption is that `allSettled` is "the slow one". On the happy path both settle at the same moment — when the slowest input finishes. They diverge only when something rejects: `all` can settle much earlier (the instant of the first rejection), while `allSettled` still waits for every straggler. If you need every operation to be finished before you continue — cleanup, a summary log, a transaction boundary — `allSettled` is the one that actually guarantees it. ## Choosing between them Ask whether the caller's result is meaningful without one of the pieces. A page that needs the user record *and* their permissions is all-or-nothing: use `all` and let the rejection propagate. A dashboard with five independent widgets, or a batch importer processing 200 rows, is not: use `allSettled`, render what arrived, and report the rest. ## Edge cases worth knowing - Both fulfil immediately with `[]` for an empty iterable. - Non-promise entries pass straight through: `Promise.all([1, Promise.resolve(2)])` fulfils with `[1, 2]`. - `Promise.all` rejects with the *first* reason only; later rejections are dropped. They do not surface as unhandled rejections, because `all` attached handlers to every input up front — but the diagnostic detail in them is lost unless you capture it yourself. - Neither offers cancellation, and neither retries; those are separate concerns you layer on top.