Promises: then, catch, finally and chaining
A promise is a value that stands for a result which is not here yet. It is in one of three states: pending while the work runs, fulfilled with a value, or rejected with a reason. Once it settles it never changes again, and every callback that was attached to it runs with that one result.
The four programs of this lesson build one by hand, show what a rejected promise does to a chain, follow a chain of steps with a failure in the middle, and end with finally, the method that runs on both paths. The next lesson runs several promises at once, and the one after that writes the same chains with await.
Creating a promise
new Promise(executor) calls the executor at once, before the constructor returns, and hands it two functions: resolve for the value and reject for the reason. The program below resolves immediately and still sees the value arrive after the next line, because a callback of then is a microtask.
The file create.mjs:
const promise = new Promise((resolve) => {
resolve(41);
});
console.log('the state before then is pending');
promise.then((value) => {
console.log('the value arrives later:', value + 1);
});
console.log('the synchronous line runs first');
node create.mjs
the state before then is pending
the synchronous line runs first
the value arrives later: 42
The promise was already fulfilled by the time then was called, and the callback still waited for the microtask queue. That is the one rule that explains every order in this part of the course: a settled promise does not run its callbacks where it was settled.
What a rejected promise does
A rejection skips every then that has no rejection handler and stops at the first catch. What the catch returns becomes the value of the next step, so a chain can recover and carry on rather than end. The program below has one chain that recovers and one that never rejects.
The file value.mjs:
Promise.reject(new Error('the load failed'))
.then(() => {
console.log('this line does not run');
})
.catch((error) => {
console.log('the catch runs:', error.message);
return 'a value again';
})
.then((value) => {
console.log('the chain continues:', value);
});
Promise.resolve('ok')
.then((value) => {
console.log('the fulfilled promise:', value);
})
.catch(() => {
console.log('this catch does not run');
});
node value.mjs
the fulfilled promise: ok
the catch runs: the load failed
the chain continues: a value again
The fulfilled chain printed before the catch of the rejected one, because the rejection passed through one then that had no handler before the catch saw it, and each step is one microtask. The then after the catch ran with the returned string, which is the recovery: the rejection is gone and the chain is fulfilled again.
Chaining
then returns a new promise, and what its callback returns decides the value of that promise. Returning a promise makes the next step wait for it, and throwing inside a callback rejects the new promise instead of ending the program. A chain is therefore a sequence of steps with one error path.
The file chain.mjs:
function step(value) {
return new Promise((resolve) => {
resolve(value * 2);
});
}
step(1)
.then((value) => {
console.log('the first then:', value);
return step(value);
})
.then((value) => {
console.log('the second then:', value);
throw new Error('the third step failed');
})
.catch((error) => {
console.log('catch:', error.message);
return 'recovered';
})
.then((value) => {
console.log('after the catch:', value);
});
node chain.mjs
the first then: 2
the second then: 4
catch: the third step failed
after the catch: recovered
The second step doubled the value it received, which proves that the promise returned by the first step was waited for. The throw ended that step and the catch took over, and one line after it the chain was a normal sequence again. A catch in the middle is a recovery point, not the end of the chain.
finally
finally takes a callback with no arguments and runs it on both paths, then passes the value or the rejection on unchanged. It is the place for the cleanup that has to happen whether the work succeeded or failed, and its return value is ignored unless it throws.
The file finally.mjs:
function load(ok) {
return new Promise((resolve, reject) => {
if (ok) {
resolve('the contents');
} else {
reject(new Error('the load failed'));
}
});
}
load(true)
.finally(() => {
console.log('finally after a success');
})
.then((value) => {
console.log('the value:', value);
});
load(false)
.finally(() => {
console.log('finally after a failure');
})
.catch((error) => {
console.log('the error:', error.message);
});
node finally.mjs
finally after a success
finally after a failure
the value: the contents
the error: the load failed
Both cleanups ran before the handlers that used the result, and the rejection still reached its catch. That is the last of the single-chain methods; the next lesson runs several promises together and asks in which order their results come back.
Exercises
- Make the first program reject instead of resolve and add a catch. Which line prints first now?
- Return a rejected promise from the first then of the chain program. Does the catch see the same message?
- Put a finally between the second then and the catch of the chain program. Which order do the lines print in?
- Remove the catch from the chain program and run it. What does Node.js print, and what is the exit code?
- Write a function that returns a promise resolving after a short timer, and chain two of them. Which value reaches the last then?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
When is the executor of
new Promise(executor)called?Answer
At once, before the constructor returns
The executor runs synchronously, and only the callbacks attached to the promise are microtasks.
-
What does then return?
Answer
A new promise for the value its callback returns
Each then makes a new promise, which is what makes a chain possible.
-
What happens to a rejected promise that nobody handles?
Answer
Node.js reports an unhandled rejection and exits with 1
An unhandled rejection ends the process with an error and a nonzero code.
-
What does a catch do to the chain?
Answer
It handles the rejection and the chain continues with its result
The value returned by the catch fulfils the next promise, so the chain can recover.
-
What does this program print?
const promise = new Promise((resolve) => resolve("a")); promise.then((value) => console.log(value)); console.log("b");Answer
b / a
The then callback is a microtask, so the synchronous line prints first.
-
What does this program print?
Promise.reject(new Error("no")) .catch((error) => error.message.toUpperCase()) .then((value) => console.log(value));Answer
NO
The catch returns the upper case text, which fulfils the next promise.
-
What does this program print?
Promise.resolve(1) .then((value) => value + 1) .then(() => { throw new Error("stop"); }) .then(() => console.log("not here")) .catch((error) => console.log(error.message));Answer
stop
The throw rejects the step, the following then is skipped and the catch prints the message.
-
What does finally pass to the next step?
Answer
The value or the rejection, unchanged
The callback of finally runs for its side effect, and its return value is ignored.
-
What does this program print?
Promise.resolve("x") .finally(() => console.log("f")) .then((value) => console.log(value));Answer
f / x
The finally callback runs first and the value passes through to the then.
-
What is the state of a promise before resolve is called?
Answer
pending
A promise starts pending and settles once, into a value or a reason.
The code on this page was run with Node.js 24.22.1 and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev