Promise Fundamentals

## The rule in one line Inside a promise chain, `throw` is a rejection. Whatever a `.then` callback throws becomes the rejection reason of the promise that `.then()` returned. ## Why it works that way Every call to `.then(onFulfilled, onRejected)` creates and returns a **new** promise — call it the *derived* promise. When the upstream promise settles, the runtime calls the matching handler and inspects how it finished: - the handler **returns a plain value** → the derived promise fulfills with that value; - the handler **returns a promise or thenable** → the derived promise adopts its eventual outcome; - the handler **throws** → the derived promise rejects with the thrown value. The third case is the whole answer. The runtime does not let the exception escape into the surrounding code, because there *is* no meaningful surrounding code: handlers run later, from the job queue, on an empty stack. There is no `try` block from the original synchronous turn still on the stack to catch anything. Converting the throw into a rejection is the only way the failure can reach code that cares about it. ```js Promise.resolve('start') .then(() => { throw new Error('boom'); }) .then(() => console.log('never runs')) .catch((err) => console.log('caught:', err.message)); // caught: boom ``` ## How a rejection travels forward A rejection moves *down* the chain, never back up it. The propagation rule is simple: if a `.then` was given no rejection handler (or a second argument that is not a function), the rejection is passed straight through to the promise it returned. That is why the middle `.then(() => console.log('never runs'))` above is skipped rather than run with `undefined`. Nothing is "cancelled" — each derived promise in between really does reject, one after another, carrying the same reason, until something is willing to handle it. `.catch(fn)` is not a separate mechanism. It is specified as `this.then(undefined, fn)` — a `.then` whose fulfillment handler is missing, which means fulfilled values pass straight through it and only rejections stop there. The *nearest* rejection handler downstream wins; handlers further along the chain never see the original rejection because the first one already consumed it. ## What counts as a throw Everything that raises inside the handler body: an explicit `throw`, a `TypeError` from reading a property of `undefined`, a `SyntaxError` from `JSON.parse` on bad input, a failed assertion. All of them land in the same place. ```js fetchProfile() .then((res) => JSON.parse(res.body)) // may throw SyntaxError .then((profile) => profile.name.trim()) // may throw TypeError .catch((err) => console.error('pipeline failed:', err)); ``` One `.catch` at the end covers both, which is exactly the ergonomic win promises were designed for: a single failure path for a multi-step pipeline. ## The important limit Only throws **inside a handler** are converted. Code that runs synchronously *around* the chain is ordinary code: ```js function load(id) { if (!id) throw new Error('id required'); // synchronous throw, not a rejection return fetchUser(id).then((u) => u.name); } ``` A caller writing `load().catch(handle)` gets a synchronous exception at the call itself and never reaches `.catch`, because `.catch` can only be attached to a promise that was actually returned. Functions that sometimes throw synchronously and sometimes reject force callers to write two error paths, so a promise-returning API should report argument errors as rejections too — for example by doing the validation inside a `.then`, or by declaring the function `async`, which converts any synchronous throw in its body into a rejection of its returned promise. ## What to say in an interview "A handler that throws rejects the promise that `.then` returned. The rejection then skips forward past every fulfillment-only handler to the nearest rejection handler. Throwing and calling `reject` are the same signal — which is why one `.catch` at the end of a chain covers every step in it."