Promises in JavaScript

Hello readers 👋, welcome to the 17th blog in this JavaScript series!

In the last post, we talked about synchronous vs asynchronous code and how JavaScript uses the event loop to stay responsive. Today we are going to dive deeper into one of the most powerful tools for handling async operations cleanly: Promises.

If you have ever written nested callbacks that became hard to read, or if you have struggled to understand how to work with data that arrives later, this post will give you a solid foundation. We will start with the problem Promises solve, understand their lifecycle, and see how they make asynchronous code much more readable and maintainable.

Let’s get into it.

The problem: callback chaos

Before Promises, the standard way to handle something like fetching data from a server was through callbacks. We passed a function that would be called when the data arrived. That works, but it quickly leads to deeply nested code, often called "callback hell" or "the pyramid of doom".

Imagine you need to fetch a user, then fetch their posts, then fetch comments for the first post. With callbacks, it might look like this:

getUser(userId, function(user) {
  getPosts(user.id, function(posts) {
    getComments(posts[0].id, function(comments) {
      console.log(comments);
      // maybe another nested step...
    });
  });
});

Every new step adds another level of indentation. Error handling becomes repetitive and messy, and the whole flow is hard to follow. Promises were introduced to solve exactly this problem by representing a value that will be available in the future, in a flat, chainable way.

What exactly is a Promise?

Think of a promise as a special object that acts as a placeholder for the result of an asynchronous operation. When you start an async task (like a network request), you immediately get back a promise. That promise does not contain the data yet, but it promises to hold the data once the operation completes.

Over time, the promise will either be fulfilled with a value, or rejected with a reason (an error). This is incredibly helpful because you can attach handlers to the promise right away, and they will be called automatically when the result arrives.

A promise is like ordering a coffee at a busy cafe. You place your order and get a buzzer (the promise). You don't have your coffee yet, but you have a guarantee that the buzzer will beep when your coffee is ready, and you can go pick it up. While waiting, you can do other things. That's exactly how promises work in JavaScript.

The three states of a promise

Every promise goes through a lifecycle with three possible states:

1. Pending: The initial state. The async operation is still in progress, and the outcome is not yet known. This is like the waiting time after you place the order.
2. Fulfilled: The operation completed successfully, and the promise now holds a value. In our cafe analogy, the coffee is ready, and you get your cup.
3. Rejected: The operation failed, and the promise holds a reason for the failure (an error). In the cafe, maybe they ran out of ingredients and cannot make your drink.

Once a promise is fulfilled or rejected, it is considered settled. A settled promise never changes state again. It will stay fulfilled with its value, or rejected with its error, forever. This means you can attach handlers even after the promise has settled, and they will still run with the correct result.

Creating a basic promise

You create a promise using the new Promise constructor, passing it a function called the executor. The executor receives two functions as arguments: resolve and reject. You call resolve(value) when the async work succeeds, and reject(error) when it fails.

Here is a simple example that wraps setTimeout to simulate an async task:

const myPromise = new Promise(function(resolve, reject) {
  setTimeout(function() {
    const success = true; // try setting to false to see rejection
    if (success) {
      resolve("Data loaded successfully");
    } else {
      reject("Failed to load data");
    }
  }, 2000);
});

console.log(myPromise); // Promise { <pending> }

Right after creation, myPromise is pending. After two seconds, it becomes fulfilled with the string "Data loaded successfully" (or rejected if success was false). The promise object itself doesn't do anything with the result until we attach handlers.

Handling success and failure

To access the eventual value, we use the .then() method. It takes up to two callback arguments: the first for fulfillment, the second for rejection (though the second is optional, because we have a better way for errors).

myPromise.then(
  function(value) {
    console.log("Success:", value);
  },
  function(error) {
    console.log("Error:", error);
  }
);

A cleaner pattern for handling errors alone is .catch(). We can chain it after .then():

myPromise
  .then(function(value) {
    console.log("Success:", value);
  })
  .catch(function(error) {
    console.log("Error:", error);
  });

Both approaches work, but using .catch() at the end of a chain is more elegant and catches any errors that happen in the preceding .then() handlers as well.

The promise lifecycle visually

If we try to picture the lifecycle, it looks like this:

The arrows show the possible transitions. The promise starts pending, and depending on the outcome, it moves to fulfilled or rejected. The handlers we attach with .then() or .catch() will be queued to execute once the state changes.

Promise chaining: the real magic

The biggest advantage of promises over raw callbacks is chaining. Every call to .then() returns a new promise, which allows us to flatten the code and avoid deep nesting.

Let’s rewrite the earlier nested callback example using promises. Suppose we have promise-based functions:

function getUser(userId) {
  return fetch(`/api/users/${userId}`).then(res => res.json());
}

function getPosts(userId) {
  return fetch(`/api/posts?userId=${userId}`).then(res => res.json());
}

function getComments(postId) {
  return fetch(`/api/comments?postId=${postId}`).then(res => res.json());
}

Now we can chain them cleanly:

getUser(1)
  .then(function(user) {
    return getPosts(user.id);
  })
  .then(function(posts) {
    return getComments(posts[0].id);
  })
  .then(function(comments) {
    console.log("Comments:", comments);
  })
  .catch(function(error) {
    console.log("Something went wrong:", error);
  });

Notice how each step is at the same indentation level. The code reads top to bottom, almost like a story. Each .then() gets the result of the previous handler, and if any step fails, the error skips to the .catch() at the end. That is far easier to reason about than deeply nested callbacks.

A more real-world example with fetch

We already used fetch above, which itself returns a promise. That’s why we can directly call .then() on it. Let’s see a full example of fetching data from a public API and handling both success and failure:

console.log("Start fetching...");

fetch("https://jsonplaceholder.typicode.com/users/1")
  .then(function(response) {
    if (!response.ok) {
      throw new Error("Network response was not OK");
    }
    return response.json();
  })
  .then(function(data) {
    console.log("User name:", data.name);
  })
  .catch(function(error) {
    console.log("Fetch failed:", error.message);
  });

console.log("This runs before the data arrives");

Here we check response.ok and throw an error if the HTTP status is not in the 200 range. That thrown error is caught by the .catch() block. The whole flow is linear and predictable.

Callbacks vs promises: a side-by-side comparison

Let’s put the readability improvement in perspective. Suppose we want to execute three async tasks in sequence.

Using callbacks (deep nesting)

task1(function(result1) {
  task2(result1, function(result2) {
    task3(result2, function(result3) {
      console.log("Done:", result3);
    }, handleError);
  }, handleError);
}, handleError);

Using promises (chaining)

task1()
  .then(result1 => task2(result1))
  .then(result2 => task3(result2))
  .then(result3 => console.log("Done:", result3))
  .catch(handleError);

The promise version is not only shorter, but also separates the success path from the error path clearly. Adding another step is as simple as adding another .then(), without increasing indentation. This flat structure is why promises became the backbone of modern async JavaScript.

Important details to remember

• A promise executor runs synchronously when the promise is created. The async part is inside the callbacks passed to resolve/reject, which happen later. So new Promise(fn) runs fn immediately, but the resolution is async.
• .then() and .catch() always return a new promise, enabling chaining. Whatever you return from a .then() becomes the resolved value of the next promise in the chain. If you return a promise, the chain waits for that promise to settle.
• Error handling with .catch() catches any rejection that hasn’t been handled earlier in the chain. It’s a good practice to place a single .catch() at the end of a chain.
• Promises are microtasks. In the event loop, promise callbacks are executed before setTimeout callbacks. This is an advanced nuance but good to know.
• You can also create an immediately resolved or rejected promise using Promise.resolve(value) and Promise.reject(error), which are useful shortcuts.

Conclusion

Promises transform the way we think about asynchronous code. Instead of passing callbacks around and ending up with nested chaos, we work with objects that represent future values, and we chain transformations in a clean, readable way.

To quickly recap:

• Promises solve the problem of callback hell by providing a flat chain for async operations.
• A promise can be in one of three states: pending, fulfilled, or rejected.
• Once settled, it never changes state, and handlers always receive the final result.
• We use .then() to handle fulfillment and .catch() to handle errors.
• Chaining .then() calls returns new promises, allowing sequential async flows without nesting.
• Promises make error handling centralized and code far more maintainable.

Once you are comfortable with promises, you are ready for the next step: the async/await syntax, which builds directly on top of promises to make async code look even more like synchronous code. We will cover that in a future blog.

For now, I hope this explanation has made promises feel less like magic and more like a practical tool you can start using confidently.

---

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.