JavaScript Promises Explained — Async Patterns, Chaining & Real-World Pitfalls

// Simulating a real scenario: fetching a user profile from an API
function fetchUserProfile(userId) {
  // The Promise constructor takes an executor function
  // that runs immediately and synchronously
  return new Promise((resolve, reject) => {
    console.log('Promise is now: PENDING');

    // Simulating a network request with setTimeout
    setTimeout(() => {
      if (userId > 0) {
        // Calling resolve() transitions state to FULFILLED
        // and locks in this value permanently
        resolve({ id: userId, name: 'Alice Johnson', role: 'admin' });
      } else {
        // Calling reject() transitions state to REJECTED
        // Any subsequent resolve() call is completely ignored
        reject(new Error(`Invalid userId: ${userId}. Must be a positive integer.`));
      }
    }, 1000);
  });
}

const profilePromise = fetchUserProfile(42);

// Attaching handlers AFTER creation — still works perfectly
// because the Promise holds onto its settled state
profilePromise.then((userProfile) => {
  console.log('Promise is now: FULFILLED');
  console.log('User loaded:', userProfile.name, '| Role:', userProfile.role);
});

// Demonstrating that the same Promise can be consumed
// by multiple independent .then() calls
profilePromise.then((userProfile) => {
  console.log('Second handler also received:', userProfile.id);
});

// Testing the rejection path
fetchUserProfile(-1)
  .then((data) => console.log('This will never run'))
  .catch((error) => {
    console.log('Promise is now: REJECTED');
    console.log('Error caught:', error.message);
  });

// Real-world pipeline: authenticate → fetch dashboard data → format for UI

// Step 1: Simulate authenticating a user with credentials
function authenticateUser(email, password) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (email === 'alice@example.com' && password === 'secure123') {
        resolve({ token: 'jwt_abc123xyz', userId: 42 });
      } else {
        reject(new Error('Authentication failed: invalid credentials'));
      }
    }, 500);
  });
}

// Step 2: Use the auth token to fetch the user's dashboard stats
function fetchDashboardStats(authToken, userId) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (!authToken) {
        reject(new Error('No auth token provided'));
        return; // Important: return after reject to stop executor
      }
      resolve({
        userId,
        totalOrders: 128,
        pendingOrders: 3,
        revenue: 14750.50
      });
    }, 700);
  });
}

// Step 3: Format the raw stats into a display-ready object
function formatStatsForDisplay(rawStats) {
  // This is a plain synchronous function
  // Returning a plain value here works — .then() wraps it automatically
  return {
    headline: `${rawStats.totalOrders} total orders`,
    alert: rawStats.pendingOrders > 0
      ? `⚠ ${rawStats.pendingOrders} orders need attention`
      : '✓ All orders processed',
    revenueDisplay: `$${rawStats.revenue.toLocaleString('en-US')}`
  };
}

// The chain: flat, readable, each step clearly building on the last
authenticateUser('alice@example.com', 'secure123')
  .then((authResult) => {
    console.log('Step 1 complete — token received:', authResult.token);
    // Returning a Promise here causes the chain to WAIT for it
    return fetchDashboardStats(authResult.token, authResult.userId);
  })
  .then((rawStats) => {
    console.log('Step 2 complete — raw stats received for user:', rawStats.userId);
    // Returning a plain value here — chain continues immediately
    return formatStatsForDisplay(rawStats);
  })
  .then((displayData) => {
    console.log('Step 3 complete — ready to render:');
    console.log('  Headline:', displayData.headline);
    console.log('  Alert:   ', displayData.alert);
    console.log('  Revenue: ', displayData.revenueDisplay);
  })
  .catch((error) => {
    // This single catch handles failures from ALL three steps above
    console.error('Pipeline failed at some step:', error.message);
  });

// Testing the error path — wrong password breaks at step 1
authenticateUser('alice@example.com', 'wrongpassword')
  .then((authResult) => fetchDashboardStats(authResult.token, authResult.userId))
  .then((rawStats) => formatStatsForDisplay(rawStats))
  .then((displayData) => console.log('This line never runs'))
  .catch((error) => {
    console.error('Caught in chain:', error.message);
  });

// Simulating three independent API calls for a user dashboard
function loadUserProfile(userId) {
  return new Promise((resolve) =>
    setTimeout(() => resolve({ name: 'Alice Johnson', plan: 'Pro' }), 300)
  );
}

function loadOrderHistory(userId) {
  return new Promise((resolve) =>
    setTimeout(() => resolve([{ id: 'ORD-001', total: 49.99 }, { id: 'ORD-002', total: 120.00 }]), 600)
  );
}

function loadNotifications(userId) {
  // Simulating a flaky notifications service that fails sometimes
  return new Promise((resolve, reject) =>
    setTimeout(() => reject(new Error('Notifications service temporarily unavailable')), 400)
  );
}

const userId = 42;
const startTime = Date.now();

// --- Strategy 1: Promise.all — fails fast if ANY request fails ---
console.log('--- Testing Promise.all ---');
Promise.all([
  loadUserProfile(userId),
  loadOrderHistory(userId),
  loadNotifications(userId) // This will reject!
])
  .then(([profile, orders, notifications]) => {
    // Destructuring preserves the original array order
    console.log('All loaded:', profile, orders, notifications);
  })
  .catch((error) => {
    // Fires as soon as the fastest rejection arrives (~400ms)
    // We lose the profile and order data even though they succeeded
    console.log(`Promise.all rejected after ${Date.now() - startTime}ms`);
    console.log('Error:', error.message);
    console.log('Profile and orders data is lost — even though they succeeded!');
  });

// --- Strategy 2: Promise.allSettled — always gives you everything ---
const start2 = Date.now();
console.log('\n--- Testing Promise.allSettled ---');
Promise.allSettled([
  loadUserProfile(userId),
  loadOrderHistory(userId),
  loadNotifications(userId) // Still rejects, but the others survive
])
  .then((results) => {
    // results is always an array, one entry per input Promise
    results.forEach((result, index) => {
      const label = ['Profile', 'Orders', 'Notifications'][index];
      if (result.status === 'fulfilled') {
        console.log(`✓ ${label} loaded:`, result.value);
      } else {
        // Failed widget logs its own error — page still renders
        console.warn(`✗ ${label} failed:`, result.reason.message);
      }
    });
    console.log(`allSettled resolved after ${Date.now() - start2}ms (waited for all)`);
  });

// Real-world pattern: API call with loading state, fallback data, and cleanup

let isLoadingData = false; // Simulating a UI loading state

function fetchProductCatalog(categoryId) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (categoryId === 'electronics') {
        resolve([
          { id: 1, name: 'Wireless Headphones', price: 89.99 },
          { id: 2, name: 'USB-C Hub', price: 45.00 }
        ]);
      } else {
        reject(new Error(`Category '${categoryId}' not found in catalog`));
      }
    }, 500);
  });
}

// Pattern 1: Catch and recover with fallback data
function loadCatalogWithFallback(categoryId) {
  isLoadingData = true;
  console.log('Loading spinner: ON');

  return fetchProductCatalog(categoryId)
    .then((products) => {
      console.log(`Loaded ${products.length} products from API`);
      return products; // Pass real data down the chain
    })
    .catch((error) => {
      // Returning a value from .catch() RECOVERS the chain — 
      // the next .then() will run with this fallback value
      console.warn('API failed, using fallback data. Reason:', error.message);
      return [{ id: 0, name: 'No products available', price: 0 }]; // Fallback
    })
    .then((productsToDisplay) => {
      // This runs whether we got real data OR fallback data
      console.log('Rendering', productsToDisplay.length, 'product(s) to UI');
      return productsToDisplay;
    })
    .finally(() => {
      // Always runs — real data, fallback, or unrecoverable error
      // Does NOT receive the resolved value — just cleans up
      isLoadingData = false;
      console.log('Loading spinner: OFF — cleanup complete');
    });
}

// Test with a valid category
console.log('=== Valid category ===');
loadCatalogWithFallback('electronics').then((items) => {
  console.log('Final items received by caller:', items.map(i => i.name));
});

// Small delay so outputs don't interleave in this demo
setTimeout(() => {
  console.log('\n=== Invalid category (triggers fallback) ===');
  loadCatalogWithFallback('furniture').then((items) => {
    console.log('Final items received by caller:', items.map(i => i.name));
  });
}, 1000);

// Pattern 2: Unhandled rejection — demonstrating what NOT to do
// This Promise rejects with no .catch() — will trigger UnhandledPromiseRejection
// fetchProductCatalog('invalid'); // <-- DON'T do this in production

// The correct way: always handle rejection
fetchProductCatalog('invalid-category')
  .catch((error) => {
    console.error('\nAlways attach .catch() to every Promise chain:', error.message);
  });