JavaScript Promises and Async/Await: Finally Explained

Let’s be honest: most of us learned async/await by copying examples until something worked. Let’s fix that and actually understand what’s happening.

The Problem (Why We Need Promises)

JavaScript is single-threaded. This would block everything:

// ❌ Doesn't exist, but imagine
const data = fetchDataSynchronously(); // Everything stops here
console.log(data);

Your entire app freezes waiting for the network. Not good.

The Old Way (Callbacks)

fetchData((error, data) => {
  if (error) {
    handleError(error);
  } else {
    processData(data, (error, result) => {
      if (error) {
        handleError(error);
      } else {
        saveResult(result, (error) => {
          // Welcome to callback hell
        });
      }
    });
  }
});

This is why we have trust issues.

Enter Promises

A Promise represents a future value. It’s like ordering food:

Pending: Order placed, waiting
Fulfilled: Food arrived (success)
Rejected: Restaurant closed (error)

const promise = fetchData();

promise
  .then(data => processData(data))
  .then(result => saveResult(result))
  .catch(error => handleError(error));

Much better!

Creating Promises

function fetchData() {
  return new Promise((resolve, reject) => {
    // Do async work
    setTimeout(() => {
      const data = { user: 'Max' };
      
      if (data) {
        resolve(data);  // Success!
      } else {
        reject(new Error('No data'));  // Failure!
      }
    }, 1000);
  });
}

Rule: Always call either resolve OR reject, never both, only once.

Promise Chaining

fetchUser(id)
  .then(user => fetchPosts(user.id))
  .then(posts => posts.filter(p => p.published))
  .then(published => {
    console.log(`${published.length} posts`);
    return published;
  })
  .catch(error => {
    console.error('Something failed:', error);
  });

Each .then() returns a new Promise. Errors bubble down to .catch().

Common Promise Mistakes

Mistake 1: Forgetting to Return

// ❌ Wrong - breaks the chain
promise
  .then(data => {
    processData(data);  // This returns undefined!
  })
  .then(result => {
    console.log(result);  // undefined
  });

// ✅ Right
promise
  .then(data => processData(data))  // Returns the result
  .then(result => {
    console.log(result);  // The actual result
  });

Mistake 2: Nesting Then

// ❌ Wrong - callback hell again
promise
  .then(data => {
    processData(data).then(result => {
      saveResult(result).then(() => {
        console.log('Done');
      });
    });
  });

// ✅ Right - flat chain
promise
  .then(data => processData(data))
  .then(result => saveResult(result))
  .then(() => console.log('Done'));

Mistake 3: Not Catching Errors

// ❌ Wrong - unhandled rejection
promise.then(data => processData(data));

// ✅ Right - always catch
promise
  .then(data => processData(data))
  .catch(error => handleError(error));

Async/Await: Promises with Sugar

// This...
function getUser() {
  return fetchUser(123)
    .then(user => processUser(user))
    .then(processed => saveUser(processed))
    .catch(error => handleError(error));
}

// ...is the same as this
async function getUser() {
  try {
    const user = await fetchUser(123);
    const processed = await processUser(user);
    const saved = await saveUser(processed);
    return saved;
  } catch (error) {
    handleError(error);
  }
}

async/await is just syntax sugar. Under the hood, it’s still Promises.

Rules of Async/Await

async functions always return a Promise

async function test() {
  return 42;
}

test().then(value => console.log(value));  // 42

await only works inside async functions

// ❌ Wrong
function test() {
  const data = await fetchData();  // Syntax error!
}

// ✅ Right
async function test() {
  const data = await fetchData();
}

await pauses execution (of that function only)

async function example() {
  console.log('1');
  await delay(1000);
  console.log('2');  // Runs after 1 second
}

example();
console.log('3');  // Runs immediately

// Output: 1, 3, 2

Parallel vs Sequential

// Sequential - slow (3 seconds total)
async function sequential() {
  const user = await fetchUser();      // 1 second
  const posts = await fetchPosts();    // 1 second
  const comments = await fetchComments(); // 1 second
}

// Parallel - fast (1 second total)
async function parallel() {
  const [user, posts, comments] = await Promise.all([
    fetchUser(),
    fetchPosts(),
    fetchComments()
  ]);
}

Use Promise.all() when tasks are independent!

Promise Utility Methods

Promise.all()

All or nothing - waits for all Promises, fails if any fail:

const [users, posts, comments] = await Promise.all([
  fetchUsers(),
  fetchPosts(),
  fetchComments()
]);

Promise.allSettled()

Waits for all, doesn’t care about failures:

const results = await Promise.allSettled([
  fetchUsers(),
  fetchPosts(),
  fetchComments()
]);

results.forEach(result => {
  if (result.status === 'fulfilled') {
    console.log(result.value);
  } else {
    console.log(result.reason);
  }
});

Promise.race()

First one wins:

const fastest = await Promise.race([
  fetchFromCDN(),
  fetchFromOrigin()
]);

Promise.any()

First successful one wins (ignores failures):

const data = await Promise.any([
  fetchFromServer1(),
  fetchFromServer2(),
  fetchFromServer3()
]);

Error Handling Patterns

Pattern 1: Try/Catch

async function getUser(id) {
  try {
    const user = await fetchUser(id);
    return user;
  } catch (error) {
    console.error('Failed to fetch user:', error);
    return null;
  }
}

Pattern 2: Catch Individual Promises

async function getUser(id) {
  const user = await fetchUser(id).catch(error => {
    console.error('Fetch failed:', error);
    return null;  // Default value
  });
  
  if (!user) return null;
  
  // Continue with user
}

Pattern 3: Higher-Order Function

function asyncHandler(fn) {
  return async (req, res, next) => {
    try {
      await fn(req, res, next);
    } catch (error) {
      next(error);
    }
  };
}

// Express route
app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await fetchUser(req.params.id);
  res.json(user);
}));

Common Async Patterns

Pattern 1: Retry Logic

async function fetchWithRetry(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fetch(url);
    } catch (error) {
      if (i === retries - 1) throw error;
      await delay(1000 * Math.pow(2, i));  // Exponential backoff
    }
  }
}

Pattern 2: Timeout

function timeout(promise, ms) {
  return Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Timeout')), ms)
    )
  ]);
}

const data = await timeout(fetchData(), 5000);  // Max 5 seconds

Pattern 3: Batching

async function processBatch(items, batchSize = 10) {
  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize);
    await Promise.all(batch.map(item => processItem(item)));
  }
}

Debugging Async Code

Use labels in console.log:

console.log('[fetchUser] Starting...');
const user = await fetchUser();
console.log('[fetchUser] Done:', user);

Use debugger with async/await:

async function test() {
  const data = await fetchData();
  debugger;  // Execution pauses here
  process(data);
}

Much easier than debugging Promise chains!

The Mental Model

Think of await as “pause this function until the Promise resolves, then continue with the result.”

The rest of your program keeps running. Only this function pauses.

Conclusion

Promises are just objects representing future values. Async/await is syntax sugar to make them look synchronous.

Key takeaways:

Always return from .then()
Always catch errors
Use Promise.all() for parallel operations
async/await is usually clearer than .then()

Now go forth and await things! 🚀

P.S. If you’re still confused, that’s normal. This stuff takes practice. Build something async-heavy and it’ll click.