JavaScript Promises Explained for Beginners

The cure for callback hell — and a cleaner way to handle things that take time.

---

In the last article, we talked about callbacks and saw how they can spiral into deeply nested, hard-to-read code — the infamous "Pyramid of Doom." If you've ever looked at five levels of indented callbacks and thought "there has to be a better way," you're right. There is.

Promises are that better way. They take the same asynchronous operations — fetching data, reading files, waiting for timers — and give you a flat, readable chain instead of a nested pyramid. Same results, dramatically better code.

When I first encountered Promises in the ChaiCode Web Dev Cohort 2026, I'll be honest — the concept felt abstract. "A future value?" "Pending, fulfilled, rejected?" But once I wrote a few .then() chains and compared them to the callback versions, the improvement was so obvious I never wanted to go back.

Let me show you.

---

What Problem Do Promises Solve?

Let's start with the pain. Here's a callback-based approach to a common pattern: fetch a user, then their orders, then shipping details.

// Callback version — the Pyramid of Doom
getUser(1, (err, user) => {
  if (err) return console.log(err);

  getOrders(user.id, (err, orders) => {
    if (err) return console.log(err);

    getShipping(orders[0].id, (err, shipping) => {
      if (err) return console.log(err);

      console.log(`Shipping to: ${shipping.address}`);
    });
  });
});

Problems: deep nesting, repeated error handling, hard to read, hard to maintain.

Now here's the same thing with Promises:

// Promise version — flat and readable
getUser(1)
  .then((user) => getOrders(user.id))
  .then((orders) => getShipping(orders[0].id))
  .then((shipping) => console.log(`Shipping to: ${shipping.address}`))
  .catch((err) => console.log(err));

Same steps. Same logic. But flat, linear, and with one catch handling all errors. That's the problem Promises solve.

---

What Is a Promise?

A Promise is an object that represents a value that might not be available yet but will be at some point in the future — or it might fail.

Think of it like ordering food online:

1. You place the order → you get a receipt (the promise). The food isn't here yet, but you have a guarantee that it will arrive or you'll be notified of a problem.
2. Your order is being prepared → the promise is pending.
3. Food arrives → the promise is fulfilled (success!).
4. Something goes wrong (restaurant closed, wrong address) → the promise is rejected (failure).

Online Order Analogy:

  Place order  →  Pending...  →  Fulfilled (food arrives! 🍕)
                                 OR
                              →  Rejected (order failed ❌)

In code, a Promise works the same way: it starts in a pending state, and eventually settles as either fulfilled (with a value) or rejected (with an error).

---

Promise States

Every Promise has exactly three possible states:

State	Meaning	Settled?
Pending	Operation hasn't completed yet	❌ No
Fulfilled	Operation succeeded — result is available	✅ Yes
Rejected	Operation failed — error is available	✅ Yes

A Promise moves from pending to either fulfilled or rejected — never both, and never back to pending.

Promise Lifecycle Diagram

┌──────────────────────────────────────────────────┐
│                                                  │
│   new Promise((resolve, reject) => { ... })      │
│                                                  │
│                    ┌─────────┐                   │
│                    │ PENDING │                   │
│                    └────┬────┘                   │
│                         │                        │
│              ┌──────────┴──────────┐             │
│              ↓                     ↓             │
│       ┌────────────┐        ┌───────────┐        │
│       │ FULFILLED  │        │ REJECTED  │        │
│       │            │        │           │        │
│       │ resolve()  │        │ reject()  │        │
│       │ called     │        │ called    │        │
│       └──────┬─────┘        └─────┬─────┘        │
│              ↓                    ↓              │
│          .then()              .catch()           │
│       handles the          handles the           │
│       success value        error reason          │
│                                                  │
└──────────────────────────────────────────────────┘

Once settled (fulfilled or rejected), a promise NEVER changes state again.

---

Creating a Basic Promise

Here's the syntax for creating a Promise from scratch:

const myPromise = new Promise((resolve, reject) => {
  // Do some async work here...

  // If successful:
  resolve("Success! Here's your data.");

  // If something goes wrong:
  // reject("Something failed.");
});

• resolve(value) — call this when the operation succeeds. The promise becomes fulfilled with this value.
• reject(reason) — call this when the operation fails. The promise becomes rejected with this reason.

Example: Simulating an API Call

const fetchUser = (userId) => {
  return new Promise((resolve, reject) => {
    console.log(`Fetching user ${userId}...`);

    setTimeout(() => {
      if (userId > 0) {
        resolve({ id: userId, name: "Pratham", role: "developer" });
      } else {
        reject("Invalid user ID!");
      }
    }, 2000);
  });
};

This function returns a Promise. After 2 seconds:

• If userId is valid → resolved with user data
• If userId is invalid → rejected with an error message

---

Handling Success and Failure

.then() — Handle Fulfilled Promises

fetchUser(1).then((user) => {
  console.log(`Got user: ${user.name}`);
});
// (after 2 seconds) "Got user: Pratham"

.then() receives the value that resolve() was called with.

.catch() — Handle Rejected Promises

fetchUser(-1).catch((error) => {
  console.log(`Error: ${error}`);
});
// (after 2 seconds) "Error: Invalid user ID!"

.catch() receives the reason that reject() was called with.

Using Both Together

fetchUser(1)
  .then((user) => {
    console.log(`✅ User: ${user.name} (${user.role})`);
  })
  .catch((error) => {
    console.log(`❌ Failed: ${error}`);
  });

If the promise is fulfilled, .then() runs. If it's rejected, .catch() runs. Only one will execute — never both.

.finally() — Run No Matter What

fetchUser(1)
  .then((user) => console.log(`User: ${user.name}`))
  .catch((error) => console.log(`Error: ${error}`))
  .finally(() => console.log("Request complete — cleanup done."));

.finally() runs whether the promise succeeded or failed. Perfect for cleanup tasks like hiding loading spinners.

---

The Promise Lifecycle in Action

Let me trace through the complete lifecycle with a real example:

console.log("1. Starting...");

const order = new Promise((resolve, reject) => {
  console.log("2. Promise created — cooking pizza... 🍕");

  setTimeout(() => {
    const success = true;

    if (success) {
      resolve("Margherita Pizza");
    } else {
      reject("Kitchen is closed!");
    }
  }, 3000);
});

console.log("3. Doing other things while waiting...");

order
  .then((pizza) => {
    console.log(`4. Order fulfilled: ${pizza} delivered! 🎉`);
  })
  .catch((reason) => {
    console.log(`4. Order rejected: ${reason} 😞`);
  });

console.log("5. More synchronous code...");

Output:

1. Starting...
2. Promise created — cooking pizza... 🍕
3. Doing other things while waiting...
5. More synchronous code...
4. Order fulfilled: Margherita Pizza delivered! 🎉   ← 3 seconds later

Trace

Time 0ms:
  "1. Starting..." — synchronous, runs immediately
  Promise constructor runs — "2. Promise created..." — synchronous!
  setTimeout registered (3-second timer starts)
  "3. Doing other things..." — synchronous
  .then() registered — "I'll call this function when the promise resolves"
  "5. More synchronous code..." — synchronous

Time 3000ms:
  Timer fires → resolve("Margherita Pizza") → promise is FULFILLED
  .then() callback executes → "4. Order fulfilled: ..."

Key insight: The Promise constructor runs synchronously. Only the .then() and .catch() callbacks are deferred until the promise settles.

---

Promise Chaining

This is where Promises truly shine. Each .then() returns a new Promise, which means you can chain them — one after another, flat and readable.

How Chaining Works

const getUser = (id) =>
  new Promise((resolve) => {
    setTimeout(() => resolve({ id, name: "Pratham" }), 500);
  });

const getOrders = (userId) =>
  new Promise((resolve) => {
    setTimeout(() => resolve([{ id: 101, item: "Laptop" }]), 500);
  });

const getShipping = (orderId) =>
  new Promise((resolve) => {
    setTimeout(() => resolve({ address: "Delhi, India" }), 500);
  });

// Chained — each .then() passes its result to the next
getUser(1)
  .then((user) => {
    console.log(`User: ${user.name}`);
    return getOrders(user.id);
  })
  .then((orders) => {
    console.log(`Order: ${orders[0].item}`);
    return getShipping(orders[0].id);
  })
  .then((shipping) => {
    console.log(`Ship to: ${shipping.address}`);
  })
  .catch((error) => {
    console.log(`Error at any step: ${error}`);
  });

// User: Pratham
// Order: Laptop
// Ship to: Delhi, India

Chaining Flow Visual

getUser(1)
    │
    ↓ resolves with user
.then(user => getOrders(user.id))
    │
    ↓ resolves with orders
.then(orders => getShipping(orders[0].id))
    │
    ↓ resolves with shipping
.then(shipping => console.log(shipping.address))

    If ANY step fails:
    ↓
.catch(error => handle it)

FLAT. LINEAR. ONE ERROR HANDLER.

Compare this to the nested callback version — same three steps, but without the pyramid:

Callbacks:                          Promises:

getUser(1, (err, user) => {         getUser(1)
  getOrders(user.id, (err, o) => {    .then(user => getOrders(user.id))
    getShipping(o[0].id, (err, s) =>  .then(orders => getShipping(...))
      console.log(s.address)          .then(ship => console.log(...))
    });                               .catch(err => console.log(err));
  });
});

Nested, messy, error-prone         Flat, clean, one catch

---

Callback vs Promise — The Comparison

Feature	Callbacks	Promises
Readability	Nested → hard to follow	Flat chain → easy to read
Error handling	Every level needs if (err)	One .catch() for the entire chain
Composability	Difficult to combine	.then() chains naturally
Return values	Can't return — must pass forward	Each .then() returns a new Promise
State tracking	No built-in state	Pending → Fulfilled / Rejected
Debugging	Hard to trace through nesting	Clear, linear flow

Promises don't add new capabilities — everything you can do with Promises, you could technically do with callbacks. But Promises make the code dramatically cleaner, more maintainable, and less error-prone.

---

Common Mistakes

1. Forgetting to Return in .then()

// ❌ Wrong — missing return
getUser(1)
  .then((user) => {
    getOrders(user.id); // Not returned! Chain breaks here.
  })
  .then((orders) => {
    console.log(orders); // undefined!
  });

// ✅ Correct — return the Promise
getUser(1)
  .then((user) => {
    return getOrders(user.id);
  })
  .then((orders) => {
    console.log(orders); // Works!
  });

2. Nesting Promises (Defeating the Purpose)

// ❌ Don't do this — you're back to callback hell
getUser(1).then((user) => {
  getOrders(user.id).then((orders) => {
    getShipping(orders[0].id).then((shipping) => {
      console.log(shipping.address);
    });
  });
});

// ✅ Do this — flat chain
getUser(1)
  .then((user) => getOrders(user.id))
  .then((orders) => getShipping(orders[0].id))
  .then((shipping) => console.log(shipping.address))
  .catch((err) => console.log(err));

3. Not Adding .catch()

// ❌ Unhandled rejection — will cause warnings/errors
getUser(-1).then((user) => console.log(user));

// ✅ Always handle errors
getUser(-1)
  .then((user) => console.log(user))
  .catch((err) => console.log("Handled:", err));

---

Let's Practice: Hands-On Assignment

Part 1: Create a Basic Promise

const coinFlip = new Promise((resolve, reject) => {
  const result = Math.random() > 0.5;

  setTimeout(() => {
    if (result) {
      resolve("Heads! You win! 🎉");
    } else {
      reject("Tails! You lose. 😅");
    }
  }, 1000);
});

coinFlip
  .then((message) => console.log(message))
  .catch((message) => console.log(message))
  .finally(() => console.log("Game over."));

Part 2: Chain Promises

const step1 = () =>
  new Promise((resolve) => {
    setTimeout(() => {
      console.log("Step 1: Data fetched");
      resolve("raw data");
    }, 1000);
  });

const step2 = (data) =>
  new Promise((resolve) => {
    setTimeout(() => {
      console.log(`Step 2: Processing ${data}`);
      resolve("processed data");
    }, 1000);
  });

const step3 = (data) =>
  new Promise((resolve) => {
    setTimeout(() => {
      console.log(`Step 3: Saving ${data}`);
      resolve("saved successfully");
    }, 1000);
  });

step1()
  .then((result) => step2(result))
  .then((result) => step3(result))
  .then((result) => console.log(`Done: ${result}`))
  .catch((err) => console.log(`Error: ${err}`));

Part 3: Handle Errors in a Chain

const riskyOperation = (name) =>
  new Promise((resolve, reject) => {
    setTimeout(() => {
      if (name.length > 0) {
        resolve(`${name} processed successfully!`);
      } else {
        reject("Empty name — operation failed!");
      }
    }, 500);
  });

// Successful
riskyOperation("Pratham")
  .then((msg) => console.log(`✅ ${msg}`))
  .catch((err) => console.log(`❌ ${err}`));

// Failed
riskyOperation("")
  .then((msg) => console.log(`✅ ${msg}`))
  .catch((err) => console.log(`❌ ${err}`));

---

Key Takeaways

1. Promises solve callback hell by replacing nested callbacks with flat, chainable .then() calls and centralized error handling with .catch().
2. A Promise has three states: pending (waiting), fulfilled (success via resolve()), and rejected (failure via reject()). Once settled, it never changes.
3. .then() handles success. .catch() handles failure. .finally() runs regardless. Together they cover every outcome.
4. Promise chaining works because each .then() returns a new Promise. Always return inside .then() to keep the chain going.
5. Promises don't add new capabilities over callbacks — they add structure, readability, and maintainability to async code.

---

Wrapping Up

Promises were the moment async JavaScript stopped being painful and started being elegant. The same operations, the same logic, but expressed in a way that reads top-to-bottom instead of nesting inward. And once you're comfortable with Promises, the next step — async/await — makes the syntax even cleaner by letting you write async code that looks synchronous.

I'm learning all of this through the ChaiCode Web Dev Cohort 2026 under Hitesh Chaudhary and Piyush Garg. Promises were one of those topics where I went from "this is confusing" to "this is beautiful" in the span of a single lesson. If callbacks made sense to you, Promises will feel like a natural upgrade.

Connect with me on LinkedIn or visit PrathamDEV.in. More articles on the way.

Happy coding! 🚀

---

Written by Pratham Bhardwaj | Web Dev Cohort 2026, ChaiCode