JavaScript async/await: A Complete Guide

What is async/await?

async/await is syntactic sugar built on top of promises. It allows you to write asynchronous code that looks synchronous, making it easier to read and understand. The async keyword declares an asynchronous function, and awaitpauses execution until a promise resolves.

// Traditional Promise approach
function fetchUser() {
  return fetch('/api/user')
    .then(response => response.json())
    .then(data => {
      console.log('User:', data);
      return data;
    });
}

...

async Functions

An async function is a function declared with the async keyword. It always returns a promise, even if you return a primitive value.

// async function declaration
async function getData() {
  return 'Hello, World!';
}

// async function expression
const getData2 = async function() {
  return 'Hello from expression!';
};

...

The await Keyword

The await keyword can only be used inside async functions. It pauses the execution of the async function until the promise resolves, then returns the resolved value.

async function fetchMultipleResources() {
  console.log('Starting fetch...');
  
  // These run sequentially (not in parallel)
  const userResponse = await fetch('/api/user');
  const user = await userResponse.json();
  console.log('User loaded:', user.name);
  
  const postsResponse = await fetch('/api/posts');
  const posts = await postsResponse.json();
...

Error Handling with try/catch

In async functions, use traditional try/catch blocks for error handling. This is much cleaner than chaining .catch() methods.

// ❌ Without proper error handling
async function riskyOperation() {
  const response = await fetch('/api/data');
  const data = await response.json();
  return data;
}

// ✅ With proper error handling
async function safeOperation() {
  try {
...

Converting Promises to async/await

// Original promise chain
function getUserData() {
  return fetch('/api/user')
    .then(response => {
      if (!response.ok) {
        throw new Error('Failed to fetch user');
      }
      return response.json();
    })
    .then(user => {
...

Sequential vs Parallel Execution

// Sequential execution (slower)
async function sequentialOperations() {
  console.time('Sequential');
  
  const user1 = await fetch('/api/users/1').then(r => r.json());
  const user2 = await fetch('/api/users/2').then(r => r.json());
  const user3 = await fetch('/api/users/3').then(r => r.json());
  
  console.timeEnd('Sequential');
  return [user1, user2, user3];
...

Top-level await

In modern JavaScript (ES2022+), you can use await at the top level of modules, outside of async functions. This is useful for module initialization.

// config.js
export const config = await fetch('/api/config').then(r => r.json());

// main.js
import { config } from './config.js';

// config is already resolved when imported
console.log('App config:', config);

// In browsers, use type="module"
...

Async Iterators and Generators

// Async generator function
async function* asyncGenerator() {
  yield await Promise.resolve('First');
  yield await Promise.resolve('Second');
  yield await Promise.resolve('Third');
}

// Using async generator
async function processAsyncGenerator() {
  for await (const value of asyncGenerator()) {
...

Common Patterns and Best Practices

async function retryAsync(fn, maxRetries = 3, delay = 1000) {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries) {
        throw error;
      }
      console.log(`Attempt ${i + 1} failed, retrying...`);
      await new Promise(resolve => setTimeout(resolve, delay));
...

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

async function fetchWithTimeout(url, timeoutMs = 5000) {
...

Real-World Example: API Service

class ApiService {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseURL}${endpoint}`;
    
    const response = await fetch(url, {
      headers: {
...

async/await vs Promises: When to Use What

// Perfectly valid to mix both approaches
async function complexOperation() {
  // Use async/await for sequential operations
  const user = await fetch('/api/user').then(r => r.json());
  
  // Use Promise.all for parallel operations
  const [posts, comments] = await Promise.all([
    fetch(`/api/posts?userId=${user.id}`).then(r => r.json()),
    fetch(`/api/comments?userId=${user.id}`).then(r => r.json())
  ]);
...