Reglas de asincronía y bucle de eventos

Node.js maneja E/S concurrente en un solo hilo por proceso. Estas reglas mantienen el bucle de eventos receptivo bajo carga.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

import { readFile } from "node:fs/promises";
import pLimit from "p-limit";
 
const limit = pLimit(10);
 
export async function processBatch(ids: string[]) {
  await Promise.all(ids.map((id) => limit(() => handleOne(id))));
}

Cuándo usarlo:

• Los manejadores de solicitudes realizan trabajo de archivo, red o CPU.
• Los workers procesan mensajes de cola en paralelo.
• Aparecen picos de latencia bajo carga concurrente.

Ejemplo práctico

// src/files/serve-config.ts - BUENO
import { readFile } from "node:fs/promises";
 
let cached: string | null = null;
 
export async function getConfig(): Promise<string> {
  if (cached) return cached;
  cached = await readFile(new URL("./defaults.json", import.meta.url), "utf8");
  return cached;
}

// MALO - bloquea el bucle de eventos por solicitud
import { readFileSync } from "node:fs";
 
export function getConfigSync() {
  return readFileSync("./defaults.json", "utf8");
}

// src/workers/outbound.ts
import pLimit from "p-limit";
 
const httpLimit = pLimit(20);
 
export async function notifyAll(urls: string[]) {
  await Promise.all(
    urls.map((url) =>
      httpLimit(async () => {
        const res = await fetch(url, { signal: AbortSignal.timeout(5_000) });
        if (!res.ok) throw new Error(`notify failed ${res.status}`);
      }),
    ),
  );
}

Lo que esto demuestra:

• Lectura asíncrona de archivos con caché a nivel de módulo después de la primera carga.
• p-limit limita la concurrencia de HTTP saliente a 20.
• AbortSignal.timeout evita promesas colgadas.

Análisis profundo

Cómo funciona

• JavaScript se ejecuta en un solo hilo; el trabajo síncrono prolongado retrasa todas las solicitudes.
• La E/S asíncrona se delega al pool de hilos/kernel de libuv; las devoluciones de llamada se reanudan en el bucle.
• Promise.all en 10,000 tareas aún programa 10,000 operaciones: concurrencia limitada.
• El trabajo intensivo en CPU pertenece a worker_threads o workers externos.

Reglas de un vistazo

Notas de TypeScript

• Habilitar @typescript-eslint/no-floating-promises en CI.
• Los wrappers de limit deben tipar el retorno de Promise<T> de las tareas limitadas.

Errores comunes

• Async "disparar y olvidar" - void doWork() pierde errores. Solución: await, .catch con registro, o encolar el trabajo.
• Bcrypt síncrono en ruta de autenticación - 100ms de CPU por inicio de sesión bajo carga. Solución: hash asíncrono o pool de workers.
• Promise.all ilimitado en DB - Agota el pool de conexiones. Solución: tamaño del pool + límite de concurrencia alineados.
• Inanición de microtareas - Bucle infinito de queueMicrotask. Solución: revisión de código; nunca microtareas síncronas recursivas.
• JSON.parse bloqueante en cuerpo enorme - CPU efectivamente síncrona. Solución: límites de tamaño en el proxy inverso y middleware de análisis.

Alternativas

Preguntas frecuentes

Relacionado

• Lista de verificación de reglas del proyecto Node - reglas 4-5
• Reglas de la API - reglas de tiempo de espera para manejadores
• Reglas de registro y observabilidad - registra métricas de retraso del bucle

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