async and await in JavaScript — How, Why, and When to Use Them

// ─── Demonstrating that async functions always return a Promise ───

async function getWelcomeMessage() {
  // We return a plain string, but the async keyword
  // automatically wraps this in Promise.resolve('Hello!')
  return 'Hello from an async function!';
}

// Proof: call it and check what we get back
const result = getWelcomeMessage();
console.log(result instanceof Promise); // true — it's always a Promise

// Use .then() on it — totally valid because it IS a Promise
result.then((message) => console.log(message));

// ─── Demonstrating what await actually does ───

function simulateNetworkDelay(ms) {
  // Returns a Promise that resolves after `ms` milliseconds
  // This mimics a real API call or database query
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function fetchUserProfile() {
  console.log('1. fetchUserProfile started');

  // await pauses THIS function but NOT the whole program.
  // The event loop is free to run other code during this wait.
  await simulateNetworkDelay(1000);

  console.log('3. fetchUserProfile resumed after 1 second');
  return { id: 42, name: 'Sarah Connor', role: 'engineer' };
}

console.log('0. Before calling fetchUserProfile');
fetchUserProfile().then((user) => console.log('4. Got user:', user.name));
console.log('2. After calling fetchUserProfile — proof the thread is NOT blocked');

// ─── Pattern 1: try/catch — most readable for most situations ───

async function loadUserDashboard(userId) {
  try {
    // Both of these can throw — one try/catch covers both
    const userResponse = await fetch(`https://api.example.com/users/${userId}`);

    if (!userResponse.ok) {
      // Manually throw so we catch HTTP errors, not just network errors
      throw new Error(`HTTP ${userResponse.status}: Failed to load user ${userId}`);
    }

    const user = await userResponse.json(); // This can also throw if JSON is malformed
    console.log(`Dashboard loaded for: ${user.name}`);
    return user;

  } catch (error) {
    // One place to handle every failure in this async flow
    console.error('Dashboard failed to load:', error.message);
    return null; // Return a safe fallback so callers don't blow up
  }
}

// ─── Pattern 2: The 'safeAwait' helper — great for granular error handling ───
// Instead of nested try/catches, wrap each await to get [error, result] tuples
// Inspired by Go's error handling style

async function safeAwait(promise) {
  try {
    const data = await promise;
    return [null, data]; // [error, result] — error is null on success
  } catch (error) {
    return [error, null]; // error is populated on failure
  }
}

async function processOrder(orderId) {
  // Step 1: Validate the order
  const [validationError, order] = await safeAwait(
    fetch(`https://api.example.com/orders/${orderId}`).then((r) => r.json())
  );

  if (validationError) {
    console.error('Order validation failed:', validationError.message);
    return;
  }

  // Step 2: Charge the customer — different error, different handling
  const [paymentError, receipt] = await safeAwait(
    fetch('https://api.example.com/payments', {
      method: 'POST',
      body: JSON.stringify({ orderId: order.id, amount: order.total }),
    }).then((r) => r.json())
  );

  if (paymentError) {
    // Handle payment failure specifically — maybe alert the user differently
    console.error('Payment failed — order preserved for retry:', paymentError.message);
    return;
  }

  console.log(`Order ${orderId} confirmed. Receipt ID: ${receipt.id}`);
}

// ─── Pattern 3: Propagate errors upward intentionally ───
// Sometimes you WANT the error to bubble up to the caller

async function getProductPrice(productId) {
  const response = await fetch(`https://api.example.com/products/${productId}`);
  if (!response.ok) throw new Error(`Product ${productId} not found`);
  const product = await response.json();
  return product.price;
  // No try/catch here — the caller decides how to handle the failure
}

// The caller owns the error strategy
async function renderProductPage(productId) {
  try {
    const price = await getProductPrice(productId);
    console.log(`Price: $${price}`);
  } catch (error) {
    console.log('Could not load price. Showing "Contact for pricing" instead.');
  }
}

// ─── The slow way: Sequential (bad for independent operations) ───

async function loadDashboardSlowly(userId) {
  console.time('sequential');

  // Each await WAITS for the previous one to finish.
  // Total time = 400ms + 350ms + 300ms = 1050ms
  const userProfile = await fetchUserProfile(userId);       // 400ms
  const recentOrders = await fetchRecentOrders(userId);     // 350ms  
  const notifications = await fetchNotifications(userId);   // 300ms

  console.timeEnd('sequential'); // ~1050ms
  return { userProfile, recentOrders, notifications };
}

// ─── The fast way: Parallel with Promise.all() ───

async function loadDashboardFast(userId) {
  console.time('parallel');

  // All three fetches START at the same time.
  // Total time ≈ max(400ms, 350ms, 300ms) = 400ms
  const [userProfile, recentOrders, notifications] = await Promise.all([
    fetchUserProfile(userId),    // Fires immediately
    fetchRecentOrders(userId),   // Also fires immediately
    fetchNotifications(userId),  // Also fires immediately
  ]);

  // Note: if ANY of these rejects, the whole Promise.all rejects.
  // Use Promise.allSettled if you want partial results on failure.

  console.timeEnd('parallel'); // ~400ms
  return { userProfile, recentOrders, notifications };
}

// ─── When some requests CAN fail without breaking everything ───

async function loadDashboardResilient(userId) {
  const results = await Promise.allSettled([
    fetchUserProfile(userId),
    fetchRecentOrders(userId),
    fetchNotifications(userId),
  ]);

  // allSettled never throws — each result has a status
  const [profileResult, ordersResult, notificationsResult] = results;

  const dashboard = {
    // Show user profile if loaded, otherwise show a fallback
    user: profileResult.status === 'fulfilled'
      ? profileResult.value
      : { name: 'Guest', role: 'unknown' },

    // Show orders if loaded, otherwise show empty state
    orders: ordersResult.status === 'fulfilled'
      ? ordersResult.value
      : [],

    // Notification count can silently fail — not critical
    notificationCount: notificationsResult.status === 'fulfilled'
      ? notificationsResult.value.length
      : 0,
  };

  if (ordersResult.status === 'rejected') {
    console.warn('Orders failed to load:', ordersResult.reason.message);
  }

  return dashboard;
}

// ─── Mock fetch helpers to make this runnable ───
function fetchUserProfile(userId) {
  return new Promise((resolve) =>
    setTimeout(() => resolve({ id: userId, name: 'Alex Rivera', role: 'admin' }), 400)
  );
}
function fetchRecentOrders(userId) {
  return new Promise((resolve) =>
    setTimeout(() => resolve([{ id: 'ORD-001', total: 89.99 }]), 350)
  );
}
function fetchNotifications(userId) {
  return new Promise((resolve) =>
    setTimeout(() => resolve([{ msg: 'Your order shipped' }, { msg: 'Flash sale today' }]), 300)
  );
}

// Run the fast version
loadDashboardFast(7).then((data) => {
  console.log('User:', data.userProfile.name);
  console.log('Orders:', data.recentOrders.length);
  console.log('Notifications:', data.notifications.length);
});

// ─── A production-quality async service with timeout and retry ───

// Utility: Rejects after `ms` milliseconds — used for timeouts
function createTimeoutPromise(ms, operationName) {
  return new Promise((_, reject) =>
    setTimeout(
      () => reject(new Error(`${operationName} timed out after ${ms}ms`)),
      ms
    )
  );
}

// Utility: Retries a Promise-returning function up to `maxAttempts` times
async function withRetry(asyncFn, maxAttempts = 3, delayMs = 500) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await asyncFn(); // Try running the function
    } catch (error) {
      lastError = error;

      const isLastAttempt = attempt === maxAttempts;
      if (isLastAttempt) break;

      console.warn(`Attempt ${attempt} failed. Retrying in ${delayMs}ms...`);
      // Wait before retrying — prevents hammering a struggling server
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }

  throw lastError; // All retries exhausted — propagate the final error
}

// ─── The actual service layer ───
const WEATHER_API_TIMEOUT_MS = 5000;

async function fetchWeatherData(cityName) {
  // Race: the real request vs a timeout — whoever settles first wins
  const weatherPromise = fetch(
    `https://api.openweathermap.org/data/2.5/weather?q=${cityName}&appid=DEMO_KEY`
  ).then((response) => {
    if (!response.ok) {
      throw new Error(`Weather API error: ${response.status} for city '${cityName}'`);
    }
    return response.json();
  });

  return Promise.race([
    weatherPromise,
    createTimeoutPromise(WEATHER_API_TIMEOUT_MS, `fetchWeatherData(${cityName})`),
  ]);
}

// Public API of our weather service — this is what callers use
const weatherService = {
  async getWeather(cityName) {
    // Wrap the fetch in our retry utility — handles transient failures
    const rawData = await withRetry(
      () => fetchWeatherData(cityName),
      3,   // up to 3 attempts
      800  // 800ms between retries
    );

    // Transform the raw API response into a clean shape our app cares about
    return {
      city: rawData.name,
      country: rawData.sys.country,
      temperatureCelsius: Math.round(rawData.main.temp - 273.15),
      description: rawData.weather[0].description,
      humidity: rawData.main.humidity,
      fetchedAt: new Date().toISOString(),
    };
  },

  async getWeatherForMultipleCities(cityNames) {
    // Fetch all cities in parallel — don't make users wait for each one
    const weatherResults = await Promise.allSettled(
      cityNames.map((city) => this.getWeather(city))
    );

    return weatherResults.map((result, index) => ({
      city: cityNames[index],
      success: result.status === 'fulfilled',
      data: result.status === 'fulfilled' ? result.value : null,
      error: result.status === 'rejected' ? result.reason.message : null,
    }));
  },
};

// ─── Usage — clean and readable because the complexity is hidden ───
async function renderWeatherDashboard() {
  const cities = ['London', 'Tokyo', 'New York'];

  console.log(`Fetching weather for: ${cities.join(', ')}`);

  const results = await weatherService.getWeatherForMultipleCities(cities);

  results.forEach(({ city, success, data, error }) => {
    if (success) {
      console.log(`${city}: ${data.temperatureCelsius}°C, ${data.description}`);
    } else {
      console.log(`${city}: Failed to load — ${error}`);
    }
  });
}

renderWeatherDashboard();