Promise
In short
A promise is an object that represents the eventual result of an asynchronous operation, letting code react to success or failure once the work completes.
What is a promise?
A promise is a placeholder for a value that isn't available yet, such as the response to a network request. Instead of blocking the program while it waits, an asynchronous function returns a promise right away. Your code then attaches handlers that run when the result arrives or when something goes wrong.
A promise is always in one of three states: pending (still waiting), fulfilled (finished successfully with a value), or rejected (failed with an error). Once it is fulfilled or rejected, it is called settled, and its state can never change again. You react to the outcome with .then() for success, .catch() for errors, and .finally() for cleanup.
The buzzer a restaurant hands you when you order is a good analogy for a promise. It isn't your food, but it guarantees you'll hear back, either when your order is ready or when there's a problem. Promises are built into JavaScript and are returned by modern APIs like fetch; other languages have similar concepts called futures or tasks.
Promises replaced deeply nested callbacks as the standard way to write asynchronous JavaScript. The async/await syntax is built on top of promises: an async function always returns a promise, and await pauses that function until a promise settles.
Key takeaways
- A promise represents a value that will be available in the future.
- It starts pending, then becomes either fulfilled with a value or rejected with an error.
- Use
.then(),.catch(), and.finally()to handle the outcome. - Helpers like
Promise.allwait for several async operations running in parallel. - Async/await is a more readable syntax built on top of promises.
Example
// fetch returns a promise that resolves to a response
fetch("https://api.example.com/users/42")
.then((response) => response.json()) // runs on success
.then((user) => console.log(user.name))
.catch((error) => console.error("Request failed:", error))
.finally(() => console.log("Done"));
// Creating your own promise that resolves after a delay
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
wait(500).then(() => console.log("Half a second later"));Readers ask
What are the three states of a promise?
A promise is pending while the operation is in progress, fulfilled when it completes successfully with a value, and rejected when it fails with an error. Once fulfilled or rejected, it is settled and cannot change.
What is the difference between a promise and async/await?
They are not alternatives: async/await is syntax built on top of promises. It lets you write promise-based code that reads like normal step-by-step code, using try/catch for errors instead of .catch().
What is the difference between Promise.all and Promise.allSettled?
Promise.all waits for every promise to succeed and rejects as soon as any one of them fails. Promise.allSettled waits for all of them to finish and reports each result, whether it succeeded or failed.
Often compared
See also
- Async/AwaitProgramming Fundamentals, p. 4Async/await is a syntax for writing asynchronous code that reads like ordinary step-by-step code, pausing at each await until a promise or task finishes.
- CallbackProgramming Fundamentals, p. 7A callback is a function passed as an argument to another function, which then calls it later, for example when a task finishes or an event happens.
- JavaScriptWeb Development, p. 24JavaScript is the programming language that runs in web browsers to make pages interactive, and it also runs on servers through runtimes like Node.js.
- APIBackend & APIs, p. 2An API is a set of rules that lets one piece of software request data or actions from another in a predictable, documented way.
- FunctionProgramming Fundamentals, p. 21A function is a named, reusable block of code that performs a specific task, optionally taking inputs called parameters and returning a result.
Spotted a mistake or something missing on this page?Suggest an edit