Creating Settled Promises
A settled promise is one that has already finished: it is either fulfilled with a value or rejected with a reason. JavaScript gives you two shortcuts for making one on the spot, Promise.resolve() and Promise.reject(). You reach for them when a function must return a promise but you already know the answer, for example a cached result, a default value, or an input that fails validation before any network call is made.
Promise.resolve() and Promise.reject() side by side
Promise.resolve(value) returns a promise that is already fulfilled with value. Promise.reject(reason) returns a promise that is already rejected with reason. Both are shorter versions of writing new Promise(...) and calling resolve or reject immediately.
// Long form
const a = new Promise((resolve) => resolve(42));
// Short form, same result
const b = Promise.resolve(42);
const c = Promise.reject(new Error('Invalid id'));
b.then((value) => console.log(value)); // 42
c.catch((err) => console.log(err.message)); // Invalid id
Even though these promises are settled from the start, their .then() and .catch() callbacks still run asynchronously. Code written after the .then() line runs first, and the callback runs once the current synchronous work is done. This keeps promise behaviour predictable: a callback never runs "sometimes now, sometimes later".
Keeping a function's return type consistent
The most practical use is making every path of a function return a promise. Imagine a function that loads a user profile. If the profile is already in memory, there is nothing to wait for, but callers still expect to write .then() or await.
const cache = new Map();
function getUser(id) {
if (!Number.isInteger(id)) {
return Promise.reject(new TypeError('id must be an integer'));
}
if (cache.has(id)) {
return Promise.resolve(cache.get(id));
}
return fetch(`/api/users/${id}`)
.then((res) => res.json())
.then((user) => {
cache.set(id, user);
return user;
});
}
Without the two shortcuts, the cached branch would return a plain object and the invalid branch might throw synchronously. Callers would then need both try/catch and .catch(). Returning settled promises means a single .catch() handles every failure.
What happens when you pass a promise in
Promise.resolve() has a special rule. If you give it a real promise, it hands that same promise back instead of wrapping it. If you give it a "thenable" (any object with a then method), it follows that object and settles the way it settles. This is why Promise.resolve() is a handy way to normalise "a value or a promise" into "definitely a promise".
Promise.reject() does not do this. Passing a promise to it simply uses that promise object as the rejection reason, which is almost never what you want.
Common mistake: rejecting with something that is not an Error
You can reject with any value, such as a string, but it makes debugging harder. A string has no stack trace, so the console cannot show where the problem started, and code that reads err.message gets undefined. Always reject with an Error object or a subclass like TypeError.
A second trap is creating a rejected promise and never attaching a handler. Browsers log an "Uncaught (in promise)" message, and Node can stop the process on unhandled rejections. If you create a rejected promise, make sure someone up the chain calls .catch() or wraps the await in try/catch.
Quick recap
- Use
Promise.resolve(value)for answers you already have, such as cached or default data. - Use
Promise.reject(new Error(...))for failures you detect before doing async work. - Callbacks on settled promises still run later, never immediately.
- Reject with
Errorobjects, and always handle the rejection somewhere.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.