Promises and Chaining

The Core Problem#

A phone login with an OTP has three steps: send the OTP, verify what the user typed, then create a session. Each step takes time and can fail. Written with callbacks, that is three nested levels with an error check at each one. You have seen where that leads.

A promise lets you write the same flow as a flat chain, with a single place to handle every failure. In this post you will learn what a promise is, its three states, and how chaining works, including the one missing keyword that breaks most chains.

By the end you will be able to:

• Create a function that returns a promise
• Explain pending, fulfilled and rejected
• Chain steps with .then, handle failures with .catch, and spot the missing return bug

Mental Model & Intuition#

Think of the token you get at a food counter. The token is not your food. It is a receipt that says "your order will be ready, or we will tell you why it cannot be."

A promise is that token. It is an object that stands for a result that has not arrived yet. It is always in one of three states:

Fulfilled and rejected are called settled. A settled promise never changes again.

You attach handlers to a promise:

• .then(fn) runs when the promise is fulfilled
• .catch(fn) runs when the promise is rejected
• .finally(fn) runs either way, which is useful for cleanup such as hiding a loader

The chaining rule is the heart of this topic: every .then returns a new promise. If your handler returns a plain value, the next .then receives it. If your handler returns a promise, the next .then waits for it to settle.

Step-by-Step Walkthrough#

Here is what happens in the login chain from the code section, step by step.

Code Implementation#

1. Creating promises#

Each function returns a new Promise. Inside, we call resolve on success and reject on failure.

function sendOtp(phone) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (phone.length !== 10) {
        return reject(new Error("Invalid phone number"));
      }
      resolve("4821");
    }, 500);
  });
}

function verifyOtp(expected, entered) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (expected !== entered) return reject(new Error("Wrong OTP"));
      resolve(true);
    }, 500);
  });
}

function createSession(phone) {
  return new Promise((resolve) => {
    setTimeout(() => resolve("token_" + phone.slice(-4)), 300);
  });
}

You can see the states directly:

const p = sendOtp("9876543210");
console.log(p);

p.then((otp) => console.log("OTP:", otp));
sendOtp("123").catch((err) => console.log("Failed:", err.message));

Output:

Promise { <pending> }
OTP: 4821
Failed: Invalid phone number

2. Chaining the login flow#

const phone = "9876543210";

sendOtp(phone)
  .then((otp) => {
    console.log("OTP sent");
    return verifyOtp(otp, otp);
  })
  .then(() => {
    console.log("OTP verified");
    return createSession(phone);
  })
  .then((token) => {
    console.log("Logged in:", token);
  })
  .catch((err) => {
    console.log("Failed:", err.message);
  })
  .finally(() => {
    console.log("Done");
  });

Output when the user types the correct OTP:

OTP sent
OTP verified
Logged in: token_3210
Done

Change verifyOtp(otp, otp) to verifyOtp(otp, "0000") to simulate a wrong OTP:

OTP sent
Failed: Wrong OTP
Done

Notice that "OTP verified" and "Logged in" never print. The failure skipped every .then and landed in .catch.

3. The same flow in two styles#

Here is a preview of what the next post covers. Both tabs do exactly the same thing.

Edge Cases & Gotchas#

sendOtp(phone)
  .then((otp) => {
    console.log("OTP sent");
    verifyOtp(otp, "0000"); // no return
  })
  .then((result) => {
    console.log("Next step got:", result);
    return createSession(phone);
  })
  .then((token) => console.log("Logged in:", token))
  .catch((err) => console.log("Failed:", err.message));

OTP sent
Next step got: undefined
Logged in: token_3210

sendOtp("123")
  .catch(() => "fallback value")
  .then((value) => console.log("Chain continues with:", value));

Chain continues with: fallback value

Pro Tip / Performance Insight#

Next Steps & Practice#

Try these on your own before moving on:

1. Write checkWallet(balance, price) that returns a promise. It should resolve with the remaining balance, or reject with an Error when the balance is too low.
2. Take the ticket booking pyramid from the previous post and rewrite it as a flat chain with a single .catch.
3. Remove one return from your chain on purpose. What do you see in the output? Put it back and confirm the fix.

Read next: async/await and Error Handling, where the same flow reads like ordinary top to bottom code.