async/await en Node

async/await hace que el código asíncrono de Node se lea como código síncrono, manteniendo la semántica de las Promises. La ventaja es la claridad si preservas el contexto de los errores y evitas serializar E/S independientes.

Receta

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);
}

Cuándo usarlo:

• Manejadores HTTP que encadenan llamadas a bases de datos y API
• Scripts que leen configuración, conectan la base de datos y luego inician el servidor
• Reemplazar pirámides .then() anidadas en código existente
• Manejadores de rutas de Express 5 / Fastify 5 con lógica asíncrona

Ejemplo de trabajo

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)); // simula latencia de la base de datos
  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);

Lo que esto demuestra:

• Los manejadores de rutas async devuelven Promises; los errores deben ser capturados por solicitud
• try/catch alrededor de await mapea los fallos a códigos de estado HTTP
• Lanzar instancias de Error preserva los mensajes para clientes y registros
• Cada solicitud aún comparte un hilo; await no bloquea otras solicitudes a menos que esperes serialmente dentro de un bloqueo

Análisis profundo

Cómo funciona

• async function siempre devuelve una Promise, incluso si return 42.
• await pausa la función hasta que la Promise se resuelve, programando el resto como microtareas.
• Los errores lanzados dentro de funciones async se convierten en Promises rechazadas.
• Top-level await en módulos ESM retrasa a los importadores hasta que el módulo termina de inicializarse.

Paralelo vs. Secuencial

// Lento: secuencial (la latencia se acumula)
const a = await fetchA();
const b = await fetchB();
 
// Rápido: E/S independiente paralela
const [a, b] = await Promise.all([fetchA(), fetchB()]);

Notas de TypeScript

// Patrón de resultado tipado para fallos esperados (opcional)
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)) };
  }
}

Errores comunes

• Errores asíncronos no manejados en manejadores HTTP - Express 4 necesitaba envoltura; aún así, captúralos explícitamente. Solución: try/catch o hooks de error del framework (Express 5 mejora esto).
• await secuencial en bucles - for (const id of ids) await fetch(id) es lento. Solución: Promise.all con límite de concurrencia (p-limit).
• E/S asíncrona flotante sin await - "disparar y olvidar" pierde el contexto del error. Solución: void doWork().catch(log) intencionalmente, o await.
• Mezclar callbacks y await torpemente - primero promisificar. Solución: util.promisify o fs/promises.
• Top-level await bloqueando importadores - la inicialización lenta del módulo retrasa el arranque de toda la aplicación. Solución: import() dinámico perezoso para dependencias pesadas.

Alternativas

Preguntas frecuentes

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

Relacionado

• Migración de Callbacks a Promises - conversión de código existente
• Microtareas vs Macrotareas - lo que programa await
• Tipado de Manejadores de Express/Fastify - rutas asíncronas tipadas
• Mejores prácticas del bucle de eventos - reglas de E/S paralela

Versiones de pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.