In a JavaScript promise chain, what does .finally() pass on to the next link, and in which cases can its callback change the outcome?

## What it is for `Promise.prototype.finally(onFinally)`, standardised in ES2018, exists for the cleanup that has to happen whichever way the operation went: hide the loading indicator, release the connection, stop the timer. Because that work is not interested in the result, `.finally` is defined to be *transparent*. ## The pass-through contract Three rules cover almost every case: 1. **The callback receives no arguments.** It cannot see the fulfilment value or the rejection reason. If you need them, use `.then(v => ..., e => ...)` or a `.catch` instead. 2. **The callback's return value is discarded.** The derived promise fulfils with the *original* value. 3. **A rejection keeps travelling.** `.finally` does not handle it; the derived promise rejects with the same reason, so a `.catch` is still required somewhere downstream or you get an unhandled rejection. ```js Promise.resolve('value') .finally(() => 'ignored') .then(v => console.log(v)); // "value" Promise.reject(new Error('boom')) .finally(() => console.log('cleanup')) // runs, but does not handle .catch(e => console.log('caught', e.message)); ``` It helps to think of `.finally(fn)` as roughly equivalent to `.then(v => { fn(); return v; }, e => { fn(); throw e; })`, with one important refinement described below. ## The two ways it *can* change the outcome **Throwing.** If `onFinally` throws, the derived promise rejects with that error, replacing the original outcome — including replacing an original rejection, whose reason is then lost unless the cleanup code captures it. That is the same hazard as a `finally` block in `try`/`catch`/`finally` swallowing the in-flight exception, and it is a good reason to keep cleanup code defensive. **Returning a rejected promise.** The refinement to the naive equivalence above is that a thenable returned from `onFinally` *is* respected for settlement timing and for failure — just not for its value. Concretely: if `onFinally` returns a pending promise, the derived promise waits for it, and then still settles with the original value or reason; if that promise rejects, the derived promise rejects with its reason instead. ```js Promise.resolve('value') .finally(() => new Promise(r => setTimeout(r, 100))) .then(v => console.log(v)); // logs "value" after ~100 ms Promise.resolve('value') .finally(() => Promise.reject(new Error('cleanup failed'))) .catch(e => console.log(e.message)); // "cleanup failed" — value is gone ``` That delay behaviour is genuinely useful: an asynchronous cleanup such as closing a handle can be awaited without changing what the caller receives. ## Common misuses **Trying to read the value.** `.finally(v => console.log(v))` always logs `undefined` — there is no argument. People discover this after a debugging session. **Trying to substitute a fallback.** `.finally(() => defaultValue)` does nothing to the chain's value. Recovering from a failure is `.catch`'s job; substituting a value on success is `.then`'s. **Assuming it handles errors.** Because the word reads like the end of a `try` block, people put `.finally` last and believe the chain is safe. It is not: the derived promise still rejects, so a chain ending in `.finally` with no `.catch` produces an unhandled rejection. **Order matters with `.catch`.** `p.catch(h).finally(f)` runs the handler first, so `f` sees an already-recovered chain and the derived promise is fulfilled. `p.finally(f).catch(h)` runs cleanup first and lets `h` handle the original error — and also handles an error thrown by `f` itself. The second order is usually what you want when cleanup can fail. ## Where it returns a new promise, like everything else `.finally` follows the same structural rule as the rest of the chain: it returns a **new** promise rather than the receiver. The transparency is in the *value*, not the identity — so `p.finally(f) !== p`, and attaching further links continues from the derived promise. Keep that in mind when you store a promise in a variable and then call `.finally` on it without reassigning: the cleanup still runs, but any error it introduces lives on a promise nobody is holding, which is its own quiet failure mode.