Promise

The Promise object represents the eventual completion or failure of an asynchronous operation. Introduced in ES6, it provides a cleaner alternative to callback-based asynchronous code. A Promise is in one of three states: pending (initial state), fulfilled (operation completed successfully), or rejected (operation failed).

Syntax

new Promise(executor)
Promise.resolve(value)
Promise.reject(reason)
Promise.all(promises)
Promise.allSettled(promises)
Promise.race(promises)
Promise.any(promises)

Parameters

Parameter	Type	Default	Description
executor	function	—	A function with resolve and reject parameters that initiates the async operation
resolve	function	—	Callback to resolve the promise with a value
reject	function	—	Callback to reject the promise with a reason (error)
promises	array	—	An iterable of Promises/values to wait for

Static Methods

Method	Return Type	Description
Promise.resolve(value)	Promise	Returns a resolved Promise
Promise.reject(reason)	Promise	Returns a rejected Promise
Promise.all(iterable)	Promise	Resolves when all input Promises resolve, rejects if any reject
Promise.allSettled(iterable)	Promise	Resolves when all input Promises settle (never rejects)
Promise.race(iterable)	Promise	Resolves/rejects as soon as the first input Promise settles
Promise.any(iterable)	Promise	Resolves when any input Promise resolves, rejects if all reject

Instance Methods

Method	Return Type	Description
promise.then(onFulfilled, onRejected)	Promise	Attaches callbacks for fulfillment and rejection
promise.catch(onRejected)	Promise	Attaches a callback for rejection
promise.finally(onFinally)	Promise	Attaches a callback regardless of outcome

Examples

Creating a Promise

const myPromise = new Promise((resolve, reject) => {
  const success = true;
  
  if (success) {
    resolve("Operation succeeded!");
  } else {
    reject(new Error("Operation failed"));
  }
});

myPromise.then(result => {
  console.log(result); // "Operation succeeded!"
}).catch(error => {
  console.error(error.message);
});

Chaining Promises

fetchUserData(userId)
  .then(user => fetchUserPosts(user.id))
  .then(posts => {
    console.log(`Found ${posts.length} posts`);
    return posts;
  })
  .catch(error => {
    console.error("Failed to fetch user data:", error);
  });

Using Promise.all()

const urls = [
  "https://api.example.com/users",
  "https://api.example.com/posts",
  "https://api.example.com/comments"
];

const requests = urls.map(url => fetch(url).then(r => r.json()));

Promise.all(requests)
  .then(([users, posts, comments]) => {
    console.log("All data loaded:", { users, posts, comments });
  })
  .catch(error => {
    console.error("One or more requests failed:", error);
  });

Using Promise.allSettled()

const results = await Promise.allSettled([
  fetch("/api/users"),
  fetch("/api/posts"),
  fetch("/api/unknown")
]);

results.forEach((result, index) => {
  if (result.status === "fulfilled") {
    console.log(`Request ${index} succeeded:`, result.value);
  } else {
    console.log(`Request ${index} failed:`, result.reason);
  }
});

Using Promise.race()

function timeout(ms) {
  return new Promise((_, reject) => 
    setTimeout(() => reject(new Error("Timeout")), ms)
  );
}

Promise.race([
  fetch("https://slow-api.example.com/data"),
  timeout(5000)
])
  .then(data => console.log("Data received:", data))
  .catch(error => console.error("Race finished:", error.message));

Common Patterns

Converting Callback to Promise

function promisify(callbackBasedFn) {
  return (...args) => new Promise((resolve, reject) => {
    callbackBasedFn(...args, (error, result) => {
      if (error) reject(error);
      else resolve(result);
    });
  });
}

// Usage
const readFileAsync = promisify(fs.readFile);
const data = await readFileAsync("./package.json", "utf-8");

Promise.withResolvers()

// Modern pattern (ES2024+)
const { promise, resolve, reject } = Promise.withResolvers();

setTimeout(() => resolve("Done!"), 1000);
const result = await promise;

Avoiding Promise Anti-Patterns

// BAD: Creating promises unnecessarily
const bad = new Promise((resolve, reject) => {
  resolve(await fetchData()); // Don't await inside executor!
});

// GOOD: await the promise directly
const good = await fetchData();

See Also

• fetch() — Make HTTP requests that return Promises
• Promise.resolve() — Create a resolved Promise