Promise Basics

🎁 The Promise: Your JavaScript Gift Box

Imagine you order a gift box online. The delivery person says:

“I promise I’ll bring your gift. It might take a while, but I’ll either deliver it… or tell you if something went wrong.”

That’s exactly what a Promise is in JavaScript! It’s a special box that says: “I’m working on something. Just wait, and I’ll let you know when it’s done!”

🤔 What Are Promises?

A Promise is JavaScript’s way of handling things that take time.

Think about ordering pizza:

• You call the pizza shop 📞
• They say “Your pizza will be ready!”
• You don’t stand at the door waiting
• You do other things
• When pizza arrives, you eat! 🍕

// This is a Promise!
const pizzaOrder = new Promise((resolve, reject) => {
  // Pizza is being made...
});

Without Promises, JavaScript would freeze and wait. Nothing else could happen. That’s bad!

With Promises, JavaScript says: “Okay, I started that task. I’ll keep doing other things while we wait!”

🚦 Promise States: The Three Moods

Every Promise has exactly three possible moods (we call them “states”):

graph TD
    A["🟡 PENDING"] --> B["🟢 FULFILLED"]
    A --> C["🔴 REJECTED"]

1. 🟡 Pending - “I’m still working on it!”

The Promise is busy. Not done yet. Like your pizza still being made in the oven.

const myPromise = new Promise((resolve, reject) => {
  // Still cooking...
});
console.log(myPromise); // Promise { <pending> }

2. 🟢 Fulfilled - “Done! Here’s your result!”

Success! The Promise finished and has a value for you. Pizza delivered! 🎉

const myPromise = new Promise((resolve, reject) => {
  resolve("Pizza is here!"); // ✅ Fulfilled!
});

3. 🔴 Rejected - “Sorry, something went wrong…”

Oops. The Promise tried but failed. Pizza shop burned down. 😢

const myPromise = new Promise((resolve, reject) => {
  reject("Sorry, we're closed!"); // ❌ Rejected!
});

📝 Key Point: Once a Promise is fulfilled or rejected, it’s settled. It can never change again!

🏗️ Creating Promises

Let’s build our own Promise! It’s like setting up a gift delivery.

The Magic Formula

const myPromise = new Promise((resolve, reject) => {
  // Do something that takes time...

  if (everythingWorked) {
    resolve("Here's your result! 🎁");
  } else {
    reject("Oops, something broke! 💥");
  }
});

Two special powers:

• resolve(value) → “Mission complete! Here’s the answer!”
• reject(error) → “Mission failed! Here’s what went wrong!”

Real Example: Coin Flip Game

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

  setTimeout(() => {
    if (result) {
      resolve("🎉 You won! Heads!");
    } else {
      reject("😢 You lost! Tails!");
    }
  }, 1000); // Wait 1 second
});

Using Your Promise

coinFlip
  .then((message) => {
    console.log(message); // Runs if resolve()
  })
  .catch((error) => {
    console.log(error);   // Runs if reject()
  });

⚡ Promise.resolve and Promise.reject

Sometimes you don’t need to wait. You already know the answer!

Promise.resolve() - Instant Success! 🎁

Creates a Promise that is immediately fulfilled.

// Instead of this long way:
const longWay = new Promise((resolve) => {
  resolve("Hello!");
});

// Use this shortcut:
const quickWay = Promise.resolve("Hello!");

When to use it?

• When you need a Promise but already have the value
• To wrap regular values in Promise form

Promise.resolve(42)
  .then(num => console.log(num)); // 42

Promise.resolve({ name: "Alex" })
  .then(user => console.log(user.name)); // Alex

Promise.reject() - Instant Failure! 💔

Creates a Promise that is immediately rejected.

const error = Promise.reject("Something broke!");

error.catch((msg) => {
  console.log(msg); // "Something broke!"
});

When to use it?

• Testing error handling
• Early exit when you know it will fail

function checkAge(age) {
  if (age < 0) {
    return Promise.reject("Age can't be negative!");
  }
  return Promise.resolve(`You are ${age} years old`);
}

checkAge(-5).catch(console.log);
// "Age can't be negative!"

🔧 Promise.withResolvers()

This is the newest tool in the Promise toolbox! (Added in 2024)

Normally, resolve and reject are trapped inside the Promise:

// Old way - resolve is stuck inside
const promise = new Promise((resolve, reject) => {
  // Only here can I call resolve!
});

But what if you need to control the Promise from outside?

The New Way: withResolvers()

const { promise, resolve, reject } =
  Promise.withResolvers();

// Now resolve and reject are FREE!
// You can call them from anywhere!

Real Example: Button Click

const { promise, resolve } = Promise.withResolvers();

// Somewhere in your code...
button.onclick = () => {
  resolve("Button was clicked!");
};

// Somewhere else...
promise.then((msg) => {
  console.log(msg); // "Button was clicked!"
});

Why Is This Useful?

// Before: Awkward workaround
let outsideResolve;
const promise = new Promise((resolve) => {
  outsideResolve = resolve; // Escape!
});
outsideResolve("Done!"); // Works, but ugly

// After: Clean and official
const { promise, resolve } = Promise.withResolvers();
resolve("Done!"); // Beautiful! ✨

🎯 Quick Summary

🧠 The Big Picture

graph TD
    A["Create Promise"] --> B{What happens?}
    B -->|Success| C["resolve - value"]
    B -->|Failure| D["reject - error"]
    C --> E[".then - handles value"]
    D --> F[".catch - handles error"]
    E --> G["🎉 Use your data!"]
    F --> H["🛠️ Fix the problem!"]

💡 Remember This!

1. Promises are gift boxes - They hold future values
2. Three states only - Pending, Fulfilled, Rejected
3. Once settled, forever settled - No take-backs!
4. resolve = success, reject = failure
5. Promise.resolve/reject = Instant Promises
6. withResolvers() = Control from outside

You now understand Promises! 🎊 They’re just fancy boxes that say: “I’m working on it, trust me!”