Promise (Programming)

A promise is an object that represents the eventual outcome of an asynchronous operation. It starts as pending and ends as either fulfilled with a value or rejected with an error. Languages other than JavaScript use similar ideas under names such as future or task.

Why it matters

Promises make asynchronous code easier to compose than raw callbacks. Operations can be chained with then, errors flow to a single catch, and several operations can run in parallel and be awaited together. The async/await syntax is built on promises and lets asynchronous code read like synchronous code. The fetch API returns a promise, as do many Node.js libraries.

Example

fetch("https://example.com/api/status")
  .then(res => res.json())
  .then(data => console.log(data.ok))
  .catch(err => console.error("failed", err));

// equivalent
async function run() {
  const res = await fetch("https://example.com/api/status");
  console.log((await res.json()).ok);
}

Common mistakes

• Forgetting to return or await a promise, so errors go unhandled.
• Awaiting independent requests one by one instead of using Promise.all.
• Assuming fetch rejects on HTTP 404 or 500; it only rejects on network failure.

Related

• Callback
• Async programming
• Fetch API
• Event loop

This page is general information written by our editorial team and updated when documentation changes. Servers and providers differ, so test changes safely first. See our editorial policy and disclaimer.