What Are JavaScript Promises and How They Work

Explore what JavaScript promises are, how they work under the hood, and practical patterns for creating, chaining, and error handling with promises, async/await, and real world API calls.

JavaScripting Team

February 16, 2026·5 min read

JavaScript Tutorials Learn JavaScript Promises Async Await

JavaScript Promise

JavaScript Promise is an object that represents the eventual outcome of an asynchronous operation, delivering a value when fulfilled or an error when rejected.

What is a JavaScript Promise

What are javascript promises? According to JavaScripting, promises are a foundational pattern for managing asynchronous work in JavaScript. A JavaScript Promise is an object that represents the eventual outcome of an operation that runs asynchronously. It begins in a pending state and later settles as fulfilled with a value or rejected with an error. This simple model lets you separate the timing of asynchronous work from the logic that uses its result, improving readability and maintainability in real applications.

In practical terms, a promise is like a placeholder for a result you do not yet have. You attach handlers to respond when the result becomes available, and you can chain several steps in sequence or in parallel. The core idea is that asynchronous code should not block the main thread; instead, it returns a promise so the rest of your code can continue running and react when the operation completes. This pattern has become the standard way to handle asynchronous work in modern JavaScript.

According to JavaScripting, embracing promises helps you write cleaner, more maintainable code and makes future refactoring easier as your codebase grows.

How Promises Work Under the Hood

Promises have three states: pending, fulfilled, and rejected. When created, a promise starts in pending. If the asynchronous work finishes successfully, it becomes fulfilled and yields a value. If something goes wrong, it becomes rejected and carries an error. The transitions are unidirectional, and a promise can only be settled once.

The .then, .catch, and .finally methods register handlers that will run after the promise settles. These handlers are invoked asynchronously, via the microtask queue, which means their execution is scheduled after the current turn of the event loop but before the next task. This guarantees a predictable order of operations even when multiple asynchronous tasks run concurrently. Modern engines optimize this flow so that promise callbacks often execute quickly, even under heavy UI workloads.

From a design perspective, promises decouple what you want to do from when you want to do it. This separation makes complex flows easier to reason about and test, especially when used with async/await for sequential logic and clearer error handling.

Creating and Resolving Promises

You create a promise with the Promise constructor. The executor function receives two callbacks: resolve and reject. Call resolve(value) when the operation succeeds or reject(error) when it fails.

JavaScript

function simulateWork(delay, succeed) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (succeed) {
        resolve('result after ' + delay + 'ms');
      } else {
        reject(new Error('failure after ' + delay + 'ms'));
      }
    }, delay);
  });
}

const p1 = simulateWork(500, true);
p1.then(console.log).catch(console.error);

This example demonstrates a tiny asynchronous task that resolves or rejects after a delay. The important point is that the Promise constructor returns immediately, while the work runs in the background and signals completion by calling resolve or reject. You can create many promises in parallel, then combine their results later.

Consuming Promises with then and catch

Promises expose then and catch for handling outcomes. You can chain multiple then calls to perform a sequence of steps, each receiving the previous result. If a step throws an error, control passes to the next catch in the chain.

JavaScript

simulateWork(400, true)
  .then(result => {
    console.log('Step 1', result);
    return result.toUpperCase();
  })
  .then(upper => console.log('Step 2', upper))
  .catch(err => console.error('Failed', err.message));

Note that a returned value from a then handler becomes the input for the next handler. If a then handler returns a Promise, it will wait for that Promise to settle before continuing. This chaining is the core reason promises are favored over nested callbacks.

Promise.all, Promise.allSettled, and Promise.race

When you need to coordinate multiple promises, these helpers come in handy. Promise.all waits for all promises to fulfill and then returns an array of results; if any promise rejects, the whole promise rejects immediately. Promise.allSettled waits for all promises to settle and returns an array describing each outcome. Promise.race returns as soon as any promise settles, whether fulfilled or rejected, with that result.

JavaScript

Promise.all([p1, p2]).then(([r1, r2]) => {
  // both fulfilled
}).catch(err => { /* any rejected */ });

Understanding these helpers is essential when multiple asynchronous tasks run concurrently, such as parallel API calls or batch processing. They enable efficient composition without sacrificing clarity.

Async/Await: Writing Promises with Syntactic Sugar

Async/await provides a more linear, readable syntax for working with promises. An async function returns a Promise implicitly. Inside, you can pause execution with await to wait for a Promise to resolve, while try/catch blocks handle errors in a familiar way.

JavaScript

async function loadData(url) {
  try {
    const res = await fetch(url);
    if (!res.ok) throw new Error('Network response was not ok');
    const data = await res.json();
    return data;
  } catch (e) {
    console.error('Fetch failed', e);
    throw e;
  }
}

Async/await makes asynchronous code look synchronous, which reduces complexity and improves error handling. However, it does not replace promises; it simply provides a different, often cleaner, syntax for working with them.

Common Pitfalls and Best Practices

Promising code can become hard to read if misused. Common issues include unhandled rejections, returning non promises from then handlers, or creating nested promises. Best practices include always returning promises, attaching a final catch, and using async/await for sequential logic when it improves readability. Prefer Promise.all for parallelism, but handle rejections thoughtfully with allSettled if you need the results of every task. Keep side effects predictable, and document edge cases where a promise may reject unexpectedly.

Real World Patterns: API Calls, Retries, and Timeouts

In real applications, promises power API calls, data fetching, and user interactions. A practical pattern is to wrap fetch calls in a helper that handles common errors, retries with backoff, and timeouts. For example, you can create a fetchWithTimeout helper that rejects after a given time, or implement a retry loop using a small utility that delays and reattempts failed requests. When composing multiple API calls, Promise.all or Promise.allSettled can help gather results in a single place, while careful error handling prevents a single failure from cascading through the UI.

JavaScript

function fetchWithTimeout(resource, options = {}, t = 5000) {
  return Promise.race([
    fetch(resource, options),
    new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), t))
  ]);
}

async function getUsers() {
  const [u1, u2] = await Promise.all([
    fetchWithTimeout('/api/users/1'),
    fetchWithTimeout('/api/users/2')
  ]);
  return Promise.all([u1.json(), u2.json()]);
}

When to Use Promises and When to Avoid Them

Promises are ideal for any asynchronous work that produces a value or an error you need to handle later and that you want to compose with other asynchronous tasks. They fit well with API calls, file operations, and UI event flows. In situations with deeply nested callbacks or extremely time-sensitive tasks where you need micro-optimizations, a critical eye is required to decide whether promises are the right tool or if a simpler callback approach or event-driven pattern is more appropriate.

Questions & Answers

What is a JavaScript Promise?

A Promise is an object representing the eventual outcome of an asynchronous operation. It can resolve with a value or reject with an error. It enables clean, predictable handling of async work without blocking the main thread.

How do I create a Promise?

You create a Promise with the Promise constructor, passing an executor function that receives resolve and reject. Call resolve when the work succeeds and reject when it fails. The constructor runs immediately, while the asynchronous work happens in the background.

What is the difference between a Promise and a callback?

A Promise represents the future result and allows chaining, error handling, and parallel composition. A callback is a function passed to another function to be invoked later. Promises reduce callback pyramids and improve readability compared to nested callbacks.

What is the difference between Promise.all and Promise.allSettled?

Promise.all waits for all promises to fulfill and rejects if any reject. Promise.allSettled waits for all to settle, returning each outcome as fulfilled or rejected. Use all when you need all results to proceed; use allSettled when you want a full report of results regardless of failures.

How does async/await relate to Promises?

Async/await is syntactic sugar over promises. Await pauses execution until a promise settles, while async marks a function that returns a promise. They make asynchronous code look synchronous while preserving the underlying promise-based behavior.

What are common error-handling patterns with Promises?

Always attach a catch to handle rejections, or use try/catch within async functions. Use finally for cleanup and consider centralized error handling for consistent user feedback. Be explicit about the error you propagate to callers.