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.
At a glance
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.
See also
- Callback vs PromiseA callback is a function you hand to another function to run when it's done, while a promise stands for a future result you can chain and catch errors on.
- Promise vs Async/AwaitA promise is an object for a value that arrives later; async/await is syntax built on promises that lets you wait for them in step-by-step code.
- Async/AwaitProgramming Fundamentals, p. 5Async/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. 8A 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. 29JavaScript 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. 26A function is a named, reusable block of code that performs a specific task, optionally taking inputs called parameters and returning a result.
- MonadProgramming Fundamentals, p. 43A monad is a functional programming pattern for chaining steps that each return a wrapped value, such as an Optional, while the wrapper handles the plumbing.
Free ยท once a week
Software and AI, explained once a week
The week's software and AI news with every term explained, plus a term to learn and a quick quiz. A two-minute read.
See this week's issueAbout this page
Spotted a mistake or something missing on this page?Suggest an edit
How pages are made