async/await in Node

async/await makes asynchronous Node code read like synchronous code while keeping Promise semantics - the win is clarity if you preserve error context and avoid serializing independent I/O.

Recipe

async function fetchUser(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json() as Promise<{ id: string; name: string }>;
}
 
try {
  const user = await fetchUser('42');
  console.log(user.name);
} catch (err) {
  console.error('fetchUser failed:', err);
}

When to reach for this:

• HTTP handlers that chain database and API calls
• Scripts that read config, connect DB, then start server
• Replacing nested .then() pyramids in brownfield code
• Express 5 / Fastify 5 route handlers with async logic

Working Example

import { createServer } from 'node:http';
 
interface User { id: string; name: string }
 
const users = new Map<string, User>([['1', { id: '1', name: 'Ada' }]]);
 
async function getUser(id: string): Promise<User> {
  await new Promise((r) => setTimeout(r, 10)); // simulate DB latency
  const user = users.get(id);
  if (!user) throw new Error(`User ${id} not found`);
  return user;
}
 
const server = createServer(async (req, res) => {
  try {
    const id = req.url?.split('/').pop() ?? '';
    const user = await getUser(id);
    res.writeHead(200, { 'content-type': 'application/json' });
    res.end(JSON.stringify(user));
  } catch (err) {
    const message = err instanceof Error ? err.message : 'Unknown error';
    const status = message.includes('not found') ? 404 : 500;
    res.writeHead(status, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ error: message }));
  }
});
 
server.listen(3000);

What this demonstrates:

• async route handlers return Promises - errors must be caught per request
• try/catch around await maps failures to HTTP status codes
• Throwing Error instances preserves messages for clients and logs
• Each request still shares one thread - await does not block other requests unless you await serially inside a lock

Deep Dive

How It Works

• async function always returns a Promise - even if you return 42.
• await pauses the function until the Promise settles, scheduling the remainder as microtasks.
• Errors thrown inside async functions become rejected Promises.
• Top-level await in ESM modules delays importers until the module finishes initializing.

Parallel vs Sequential

// Slow: sequential (latency adds up)
const a = await fetchA();
const b = await fetchB();
 
// Fast: parallel independent I/O
const [a, b] = await Promise.all([fetchA(), fetchB()]);

TypeScript Notes

// Typed Result pattern for expected failures (optional)
type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
 
async function safeFetch(url: string): Promise<Result<unknown>> {
  try {
    const res = await fetch(url);
    return { ok: true, value: await res.json() };
  } catch (error) {
    return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
  }
}

Gotchas

• Unhandled async errors in HTTP handlers - Express 4 needed wrapping; still catch explicitly. Fix: try/catch or framework error hooks (Express 5 improves this).
• Sequential await in loops - for (const id of ids) await fetch(id) is slow. Fix: Promise.all with concurrency limit (p-limit).
• Floating async I/O without await - fire-and-forget loses error context. Fix: void doWork().catch(log) intentionally, or await.
• Mixing callbacks and await awkwardly - promisify first. Fix: util.promisify or fs/promises.
• Top-level await blocking importers - slow module init delays entire app boot. Fix: lazy dynamic import() for heavy deps.

Alternatives

FAQs

throw new Error('DB failed', { cause: originalErr });

Related

• Callbacks vs Promises Migration - brownfield conversion
• Microtasks vs Macrotasks - what await schedules
• Typing Express/Fastify Handlers - typed async routes
• Event Loop Best Practices - parallel I/O rules

External Related Links

• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js Learn Guides - Official learning path.
• Node.js Best Practices (GitHub) - Curated production best practices.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.
• Node.js the Right Way - Server-side JavaScript fundamentals.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

WTI5a1pXZDFhV1JsY3k1cGIzeGpaMmx2T0RRMWZESXdNall3Tnc9PQ==