JavaScript Promises Explained for Beginners

You order a coffee. The barista doesn't hand it to you immediately. They give you a receipt and say "we'll call your name when it's ready." That receipt is your promise. It doesn't have the coffee yet. But it represents a future value. You can sit down, check your phone, do whatever. When the coffee is ready, you get called. If they run out of oat milk, they still call you, just with bad news.

That's exactly what a JavaScript Promise is.

The Problem Promises Were Designed to Solve

Before promises, JavaScript developers handled asynchronous operations using callbacks. A callback is just a function you pass into another function so it can be called later when the work is done. Sounds fine in theory.

Here's what it looks like in practice:

javascript
Copy
Loading syntax highlighter...

This is what people call "callback hell." Each async operation nests inside the previous one. Error handling repeats at every level. The indentation alone tells you something is wrong. The deeper you go, the harder it is to follow the logic, debug issues, or add new steps.

Promises were introduced in ES6 to fix exactly this. They let you write async code that reads more like a straight line, handles errors in one place, and is much easier to reason about.

What a Promise Actually Is

A Promise is an object that represents the eventual result of an async operation. It's a placeholder. Right now, the value isn't there yet. But JavaScript gives you this object to work with immediately, and you attach handlers that run when the value arrives.

┌─────────────────────────────────────────────────────┐
│                    PROMISE OBJECT                   │
│                                                     │
│   Represents a value that doesn't exist yet,        │
│   but will (or won't) at some point in the future   │
└─────────────────────────────────────────────────────┘

Every Promise exists in one of three states at any given moment.

Promise States: The Three Modes of Existence

┌──────────────────────────────────────────────────────────────┐
│                     PROMISE LIFECYCLE                        │
│                                                              │
│                       ┌───────────┐                          │
│                       │  PENDING  │  <-- Initial state       │
│                       └─────┬─────┘                          │
│                             │                                │
│              ┌──────────────┴───────────────┐                │
│              │                              │                │
│              ▼                              ▼                │
│       ┌────────────┐                ┌──────────────┐         │
│       │ FULFILLED  │                │   REJECTED   │         │
│       │ (resolved) │                │   (failed)   │         │
│       └────────────┘                └──────────────┘         │
│                                                              │
│   Once settled (fulfilled or rejected),                      │
│   a promise CANNOT change state again.                       │
└──────────────────────────────────────────────────────────────┘

Pending is the starting state. The operation is still in progress.

Fulfilled means the operation completed successfully. The promise now has a value.

Rejected means something went wrong. The promise now has a reason (usually an error).

Here's the key detail that trips people up: once a promise settles into either fulfilled or rejected, it's done. It will never change state again. This is different from an event emitter, which can fire multiple times.

Creating a Promise

You create a promise using the new Promise() constructor. It takes a function with two parameters: resolve and reject. You call resolve when the work succeeds and reject when it fails.

javascript
Copy
const myPromise = new Promise((resolve, reject) => {
  const success = true; // imagine this is the result of some async work

  if (success) {
    resolve("Here's your data!");
  } else {
    reject(new Error("Something went wrong"));
  }
});

In real code you'd rarely create promises this way directly. Most of the time you're working with promises returned by existing APIs like fetch, database clients, or timers. But knowing how they're built helps you understand what you're consuming.

Handling the Result: .then(), .catch(), and .finally()

Once you have a promise, you attach handlers to it. These three methods are how you do that.

.then() runs when the promise fulfills. .catch() runs when it rejects. .finally() runs in both cases, once the promise settles.

javascript
Copy
fetch("https://api.example.com/user/1")
  .then((response) => response.json())
  .then((user) => {
    console.log("Got user:", user.name);
  })
  .catch((error) => {
    console.error("Request failed:", error.message);
  })
  .finally(() => {
    console.log("Request finished, regardless of outcome");
  });

The .catch() at the end isn't just for the last .then(). It catches errors from any step in the chain. That's one of the core advantages over callbacks where you had to handle errors separately at each level.

Callback Hell vs Promise Chain: Side by Side

CALLBACK APPROACH                    PROMISE APPROACH
─────────────────                    ────────────────

getUser(id, (err, user) => {         getUser(id)
  if (err) handle(err)                 .then(user => getPosts(user.id))
  getPosts(user.id, (err, posts) => {  .then(posts => getComments(posts[0].id))
    if (err) handle(err)               .then(comments => console.log(comments))
    getComments(posts[0].id,           .catch(err => handle(err))
      (err, comments) => {
        if (err) handle(err)
        console.log(comments)
      }
    )
  })
})

Indentation grows rightward.         Reads top to bottom.
Error handling everywhere.           One error handler covers all.
Hard to modify.                      Easy to add/remove steps.

Both do the same thing. But the promise chain version is far easier to read, maintain, and debug. That gap only gets wider as the number of operations increases.

Promise Chaining: How It Actually Works

Here's the thing most beginners miss: .then() returns a new promise. Not the same one. A brand new promise that resolves with whatever you return from the .then() callback.

javascript
Copy
Loading syntax highlighter...

Each .then() in the chain receives the resolved value of the previous one. If you return a plain value, it gets wrapped in a fulfilled promise automatically. If you return a promise, the chain waits for that promise to settle before moving to the next .then().

This is the mechanism behind chaining. Each step passes its result to the next one, and errors bubble down to the nearest .catch().

┌──────────────────────────────────────────────────────────────┐
│                    PROMISE CHAIN FLOW                        │
│                                                              │
│   fetch(url)                                                 │
│       │ returns Promise<Response>                            │
│       ▼                                                      │
│   .then(res => res.json())                                   │
│       │ returns Promise<Data>                                │
│       ▼                                                      │
│   .then(data => process(data))                               │
│       │ returns Promise<Result>                              │
│       ▼                                                      │
│   .then(result => console.log(result))                       │
│       │                                                      │
│       ▼                                                      │
│   .catch(err => console.error(err))  <-- catches from ALL    │
│                                          steps above         │
└──────────────────────────────────────────────────────────────┘

One important thing to get right: always return the inner promise when chaining. Forgetting the return is a classic bug where your chain doesn't wait for the async step.

javascript
Copy
// WRONG: forgot to return, chain doesn't wait
.then((user) => {
  fetch("/api/posts/" + user.id); // this promise is ignored
})

// RIGHT: return it so the chain waits
.then((user) => {
  return fetch("/api/posts/" + user.id);
})

A Note for Intermediate and Advanced Devs

If you're already comfortable with promises, a few things worth knowing:

Unhandled promise rejections are a real problem. In modern Node.js, an unhandled rejection will terminate the process. Always attach a .catch() or use a try/catch with async/await (which is syntactic sugar over promises).

Promises are eager. The executor function (the one you pass to new Promise()) runs immediately when the promise is created, not when you call .then(). If you want lazy evaluation, you need a function that returns a promise, not just a promise.

.then(onFulfilled, onRejected) can actually take two arguments. The second is an error handler. But using .catch() is almost always cleaner and easier to understand.

Promise.all(), Promise.race(), Promise.allSettled(), and Promise.any() are built-in utilities for working with multiple promises at once. Each has a different strategy: all waits for all and fails fast on rejection, allSettled waits for all regardless, race takes the first to settle, any takes the first to fulfill.

A Real Example Putting It Together

javascript
Copy
Loading syntax highlighter...

This fetches a user, then fetches their posts, and returns both as one combined object. One .catch() handles any failure at any point.

Key Takeaways

Promises solve the callback hell problem by giving async operations a consistent structure and a single place to handle errors.

Every promise is either pending, fulfilled, or rejected. It can only ever be one of those at a time, and once it settles it stays that way.

.then() returns a new promise, which is what makes chaining possible. Each step gets the previous step's result.

.catch() anywhere in the chain will catch errors from any step above it. You don't need error handling at every level.

You'll rarely create promises manually in real-world code. But knowing how they work internally makes you much better at using the APIs that return them, including fetch, database drivers, file system APIs, and more.

Once this clicks, async/await starts to make a lot more sense since it's just a cleaner way to write promise-based code.