Explain Promises to a 5-Year-Old — Then Use Them Like a Pro

// Creating a Promise
const pizzaOrder = new Promise((resolve, reject) => {
  const hasCheese = true;

  setTimeout(() => {
    if (hasCheese) {
      resolve({ type: "Margherita", size: "Large" });
    } else {
      reject(new Error("Out of cheese!"));
    }
  }, 2000);
});

// Consuming the Promise
pizzaOrder
  .then(pizza => console.log("Got pizza:", pizza))
  .catch(error => console.error("Order failed:", error))
  .finally(() => console.log("Transaction complete"));

fetch("/api/user/123")
  .then(response => {
    if (!response.ok) throw new Error("User not found");
    return response.json();  // Returns a new Promise
  })
  .then(user => {
    return fetch(`/api/posts?userId=${user.id}`);  // Chain another fetch
  })
  .then(response => response.json())
  .then(posts => {
    console.log("User posts:", posts);
  })
  .catch(error => {
    // Catches ANY error in the chain
    console.error("Something went wrong:", error);
  });

// Fetch multiple resources in parallel
const [users, posts, comments] = await Promise.all([
  fetch("/api/users").then(r => r.json()),
  fetch("/api/posts").then(r => r.json()),
  fetch("/api/comments").then(r => r.json()),
]);

// If ANY one fails, the whole thing rejects
// Use case: Dashboard that needs all data to render

const results = await Promise.allSettled([
  fetch("/api/critical"),
  fetch("/api/optional"),
  fetch("/api/nice-to-have"),
]);

results.forEach(result => {
  if (result.status === "fulfilled") {
    console.log("Success:", result.value);
  } else {
    console.log("Failed:", result.reason);
  }
});
// Use case: When some failures are acceptable

// Implement a timeout for fetch
const fetchWithTimeout = (url, timeout = 5000) => {
  return Promise.race([
    fetch(url),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error("Request timed out")), timeout)
    )
  ]);
};

// Use case: Race between fetch and timeout
const data = await fetchWithTimeout("/api/slow-endpoint", 3000);

async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      if (response.ok) return await response.json();
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      console.log(`Retry ${i + 1} in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Process items one at a time (not in parallel)
async function processSequentially(items) {
  const results = [];
  for (const item of items) {
    const result = await processItem(item); // Wait for each one
    results.push(result);
  }
  return results;
}

// Process with concurrency limit
async function processWithLimit(items, limit = 3) {
  const results = [];
  const executing = new Set();

  for (const item of items) {
    const promise = processItem(item).then(result => {
      executing.delete(promise);
      return result;
    });
    executing.add(promise);
    results.push(promise);

    if (executing.size >= limit) {
      await Promise.race(executing);
    }
  }
  return Promise.all(results);
}

// ❌ This silently fails in production
fetch("/api/data").then(r => r.json());

// ✅ Always handle errors
fetch("/api/data")
  .then(r => r.json())
  .catch(err => showErrorToUser(err));

// Node.js will crash on unhandled rejections (since Node 15)
process.on("unhandledRejection", (reason) => {
  console.error("Unhandled:", reason);
  process.exit(1);
});

// ❌ Mixing callbacks and promises
function getData(callback) {
  fetch("/api")
    .then(r => r.json())
    .then(data => callback(null, data))
    .catch(err => callback(err));
}

// ✅ Just return the promise
async function getData() {
  const response = await fetch("/api");
  return response.json();
}