Promise Que Nunca se Resolve

Q: O Express 5 captura erros assíncronos automaticamente?

Melhorado em relação ao Express 4, mas ainda use try/catch + next(err) ou o padrão express-async-errors por segurança.

Q: Como encontrar qual requisição trava?

Registre requestId no início e no fim da cadeia de middleware; a falta do log de "fim" implica a rota.

Q: AbortSignal pode ajudar?

Sim - passe signal para fetch e drivers de banco de dados que suportam cancelamento quando o cliente desconecta.

Q: Jest open handles?

--detectOpenHandles encontra timers e servidores deixados abertos após os testes.

Q: Promises de pool de workers?

O processo pai aguarda a resposta de worker.postMessage com timeout; termine o worker em caso de travamento.

Requisições travam quando uma Promise nunca resolve ou rejeita - callback ausente, reject esquecido, cliente de banco de dados abandonado ou deadlock esperando por si mesma. No Express 5, o cliente atinge o timeout enquanto o servidor mantém conexões e slots do pool.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// RUIM: Promise manual sem caminho de reject
function fetchLegacy(): Promise<string> {
  return new Promise((resolve) => {
    legacyLib.getData((err: Error | null, data: string) => {
      if (!err) resolve(data);
      // caminho de erro nunca rejeita - trava para sempre em caso de erro
    });
  });
}
 
// BOM: envolve com resolve + reject
function fetchLegacyFixed(): Promise<string> {
  return new Promise((resolve, reject) => {
    legacyLib.getData((err: Error | null, data: string) => {
      if (err) reject(err);
      else resolve(data);
    });
  });
}

// Wrapper de Timeout
async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
  let timer: NodeJS.Timeout;
  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(() => reject(new Error(`timeout após ${ms}ms`)), ms);
  });
  try {
    return await Promise.race([p, timeout]);
  } finally {
    clearTimeout(timer!);
  }
}

Quando usar isso:

Latência p95 aumenta com CPU estável (requisições esperando, não computando)
Contagem de conexões abertas cresce enquanto RPS está estável
Teste de integração trava até o timeout do Jest
Após envolver bibliotecas estilo callback em Promises

Exemplo de Trabalho

import express from "express";
import { Pool } from "pg";
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 10 });
const app = express();
 
// BUG: cliente nunca é liberado se a query lançar um erro antes da liberação na ordem errada
app.get("/orders-bug/:id", async (req, res) => {
  const client = await pool.connect();
  const result = await client.query("SELECT * FROM orders WHERE id = $1", [req.params.id]);
  if (!result.rows[0]) {
    // esqueceu client.release() no retorno antecipado - o pool se esgota com o tempo
    return res.status(404).json({ error: { code: "NOT_FOUND" } });
  }
  client.release();
  res.json({ data: result.rows[0] });
});
 
// CORREÇÃO: try/finally sempre libera
app.get("/orders/:id", async (req, res, next) => {
  const client = await pool.connect();
  try {
    const result = await client.query("SELECT * FROM orders WHERE id = $1", [req.params.id]);
    if (!result.rows[0]) return res.status(404).json({ error: { code: "NOT_FOUND" } });
    res.json({ data: result.rows[0] });
  } finally {
    client.release();
  }
});
 
// BUG: falta de await - dispara e esquece, erros não tratados
app.post("/notify-bug", (req, res) => {
  sendEmail(req.body.email); // retorna Promise, não aguardado
  res.status(202).json({ accepted: true });
});
 
async function sendEmail(to: string) {
  await new Promise((r) => setTimeout(r, 100));
  if (!to.includes("@")) throw new Error("invalid email");
}
 
// CORREÇÃO
app.post("/notify", async (req, res, next) => {
  try {
    await sendEmail(req.body.email);
    res.status(202).json({ accepted: true });
  } catch (err) {
    next(err);
  }
});

O que isso demonstra:

Retorno antecipado sem client.release() vaza conexões do pool
try/finally garante a liberação mesmo em caso de 404
Falta de await em manipuladores de rota assíncronos causa rejeições não tratadas
Erros assíncronos do Express 5 precisam de next(err) ou wrapper

Mergulho Profundo

Como Funciona

Promise se resolve cumprida ou rejeitada; caso contrário, await bloqueia para sempre
Loop de eventos permanece ativo se houver Promises pendentes ou handles ativos
Pool pg connect() espera quando todos os clientes estão ocupados e nunca liberados
Express não aguarda Promises retornadas a menos que você use o padrão de middleware assíncrono com propagação de erros

Travamento vs. Lentidão

Sinal	Travamento (nunca se resolve)	Lentidão (resolve tarde)
CPU	Baixa	Pode estar alta
Pool	Slots nunca retornam	Slots retornam após atraso
Rastreamento	Linha reta em um await	Span da consulta DB longo

Passos de Depuração

1. node --inspect + pause durante o travamento - inspecionar pilha assíncrona
2. Registrar pool ativo: pool.totalCount, pool.idleCount, pool.waitingCount
3. trace_unhandled_rejections em staging
4. Adicionar withTimeout em torno de chamadas externas suspeitas

Notas de TypeScript

// Express 5: a tipagem do manipulador assíncrono ainda precisa de encaminhamento explícito de erros
import type { RequestHandler } from "express";
 
const handler: RequestHandler = async (req, res, next) => {
  try {
    await work();
    res.json({ ok: true });
  } catch (e) {
    next(e);
  }
};

Armadilhas

Construtor de Promise apenas com ramo resolve - APIs de Callback que erram silenciosamente travam. Correção: Sempre reject(err).
forEach com callback assíncrono - Não aguarda; corre e perde erros. Correção: for...of com await ou Promise.all.
Início de transação sem commit/rollback - Conexão mantida até o timeout. Correção: try { ... commit } catch { rollback } finally { release }.
Deadlock na mesma conexão - Aguardar query enquanto a transação está aberta no mesmo cliente incorretamente intercalada. Correção: Um fluxo sequencial por cliente.
Ignorar pool.waitingCount - Métrica atinge 10+ enquanto idleCount é 0. Correção: Liberar clientes; diminuir concorrência.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`util.promisify`	APIs de callback do core do Node	Callbacks complexos com múltiplos argumentos
`async`/`await` apenas	Código novo	Biblioteca de callback legada sem promisify
Pacote `p-timeout`	Helper de timeout padrão	Você prefere um wrapper de 10 linhas
Fluxos reativos	Pipelines de eventos complexos	Rotas CRUD simples

FAQs

O Express 5 captura erros assíncronos automaticamente?

Melhorado em relação ao Express 4, mas ainda use try/catch + next(err) ou o padrão express-async-errors por segurança.

Como encontrar qual requisição trava?

Registre requestId no início e no fim da cadeia de middleware; a falta do log de "fim" implica a rota.

Comportamento do Fastify?

Fastify aguarda manipuladores assíncronos e mapeia rejeições para o manipulador de erros - ainda assim, libere clientes de banco de dados em finally.

O que é pool waitingCount?

Requisições enfileiradas para um cliente livre. Sustentado > 0 significa vazamento ou pool pequeno demais.

AbortSignal pode ajudar?

Sim - passe signal para fetch e drivers de banco de dados que suportam cancelamento quando o cliente desconecta.

Armadilhas do Promise.race?

A requisição lenta perdida ainda executa a menos que seja abortada - combine com AbortController.

Jest open handles?

--detectOpenHandles encontra timers e servidores deixados abertos após os testes.

graphql trava?

Resolver aguardando outro resolver nos mesmos dataloaders sem batching - verifique N+1 e deadlock.

Promises de pool de workers?

O processo pai aguarda a resposta de worker.postMessage com timeout; termine o worker em caso de travamento.

Mitigação em produção?

Timeout do servidor HTTP + timeout ocioso do balanceador de carga + statement_timeout do banco de dados.

Relacionados

Noções Básicas de Depuração - anexar inspetor
Exaustão do Pool de Conexões - métricas do pool
Interrupção de Produção por Rejeição Não Tratada - consequências da falta de await
Timeouts em Todos os Lugares - timeouts de fronteira
Tratamento de Erros no Express - erros assíncronos

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// RUIM: Promise manual sem caminho de reject
function fetchLegacy(): Promise<string> {
  return new Promise((resolve) => {
    legacyLib.getData((err: Error | null, data: string) => {
      if (!err) resolve(data);
      // caminho de erro nunca rejeita - trava para sempre em caso de erro
    });
  });
}
 
// BOM: envolve com resolve + reject
function fetchLegacyFixed(): Promise<string> {
  return new Promise((resolve, reject) => {
    legacyLib.getData((err: Error | null, data: string) => {
      if (err) reject(err);
      else resolve(data);
    });
  });
}

// Wrapper de Timeout
async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
  let timer: NodeJS.Timeout;
  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(() => reject(new Error(`timeout após ${ms}ms`)), ms);
  });
  try {
    return await Promise.race([p, timeout]);
  } finally {
    clearTimeout(timer!);
  }
}

Quando usar isso:

Latência p95 aumenta com CPU estável (requisições esperando, não computando)
Contagem de conexões abertas cresce enquanto RPS está estável
Teste de integração trava até o timeout do Jest
Após envolver bibliotecas estilo callback em Promises

Exemplo de Trabalho

import express from "express";
import { Pool } from "pg";
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 10 });
const app = express();
 
// BUG: cliente nunca é liberado se a query lançar um erro antes da liberação na ordem errada
app.get("/orders-bug/:id", async (req, res) => {
  const client = await pool.connect();
  const result = await client.query("SELECT * FROM orders WHERE id = $1", [req.params.id]);
  if (!result.rows[0]) {
    // esqueceu client.release() no retorno antecipado - o pool se esgota com o tempo
    return res.status(404).json({ error: { code: "NOT_FOUND" } });
  }
  client.release();
  res.json({ data: result.rows[0] });
});
 
// CORREÇÃO: try/finally sempre libera
app.get("/orders/:id", async (req, res, next) => {
  const client = await pool.connect();
  try {
    const result = await client.query("SELECT * FROM orders WHERE id = $1", [req.params.id]);
    if (!result.rows[0]) return res.status(404).json({ error: { code: "NOT_FOUND" } });
    res.json({ data: result.rows[0] });
  } finally {
    client.release();
  }
});
 
// BUG: falta de await - dispara e esquece, erros não tratados
app.post("/notify-bug", (req, res) => {
  sendEmail(req.body.email); // retorna Promise, não aguardado
  res.status(202).json({ accepted: true });
});
 
async function sendEmail(to: string) {
  await new Promise((r) => setTimeout(r, 100));
  if (!to.includes("@")) throw new Error("invalid email");
}
 
// CORREÇÃO
app.post("/notify", async (req, res, next) => {
  try {
    await sendEmail(req.body.email);
    res.status(202).json({ accepted: true });
  } catch (err) {
    next(err);
  }
});

O que isso demonstra:

Retorno antecipado sem client.release() vaza conexões do pool
try/finally garante a liberação mesmo em caso de 404
Falta de await em manipuladores de rota assíncronos causa rejeições não tratadas
Erros assíncronos do Express 5 precisam de next(err) ou wrapper

Mergulho Profundo

Como Funciona

Promise se resolve cumprida ou rejeitada; caso contrário, await bloqueia para sempre
Loop de eventos permanece ativo se houver Promises pendentes ou handles ativos
Pool pg connect() espera quando todos os clientes estão ocupados e nunca liberados
Express não aguarda Promises retornadas a menos que você use o padrão de middleware assíncrono com propagação de erros

Travamento vs. Lentidão

Sinal	Travamento (nunca se resolve)	Lentidão (resolve tarde)
CPU	Baixa	Pode estar alta
Pool	Slots nunca retornam	Slots retornam após atraso
Rastreamento	Linha reta em um await	Span da consulta DB longo

Passos de Depuração

1. node --inspect + pause durante o travamento - inspecionar pilha assíncrona
2. Registrar pool ativo: pool.totalCount, pool.idleCount, pool.waitingCount
3. trace_unhandled_rejections em staging
4. Adicionar withTimeout em torno de chamadas externas suspeitas

Notas de TypeScript

// Express 5: a tipagem do manipulador assíncrono ainda precisa de encaminhamento explícito de erros
import type { RequestHandler } from "express";
 
const handler: RequestHandler = async (req, res, next) => {
  try {
    await work();
    res.json({ ok: true });
  } catch (e) {
    next(e);
  }
};

Armadilhas

Construtor de Promise apenas com ramo resolve - APIs de Callback que erram silenciosamente travam. Correção: Sempre reject(err).
forEach com callback assíncrono - Não aguarda; corre e perde erros. Correção: for...of com await ou Promise.all.
Início de transação sem commit/rollback - Conexão mantida até o timeout. Correção: try { ... commit } catch { rollback } finally { release }.
Deadlock na mesma conexão - Aguardar query enquanto a transação está aberta no mesmo cliente incorretamente intercalada. Correção: Um fluxo sequencial por cliente.
Ignorar pool.waitingCount - Métrica atinge 10+ enquanto idleCount é 0. Correção: Liberar clientes; diminuir concorrência.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`util.promisify`	APIs de callback do core do Node	Callbacks complexos com múltiplos argumentos
`async`/`await` apenas	Código novo	Biblioteca de callback legada sem promisify
Pacote `p-timeout`	Helper de timeout padrão	Você prefere um wrapper de 10 linhas
Fluxos reativos	Pipelines de eventos complexos	Rotas CRUD simples

FAQs

O Express 5 captura erros assíncronos automaticamente?

Melhorado em relação ao Express 4, mas ainda use try/catch + next(err) ou o padrão express-async-errors por segurança.

Como encontrar qual requisição trava?

Registre requestId no início e no fim da cadeia de middleware; a falta do log de "fim" implica a rota.

Comportamento do Fastify?

Fastify aguarda manipuladores assíncronos e mapeia rejeições para o manipulador de erros - ainda assim, libere clientes de banco de dados em finally.

O que é pool waitingCount?

Requisições enfileiradas para um cliente livre. Sustentado > 0 significa vazamento ou pool pequeno demais.

AbortSignal pode ajudar?

Sim - passe signal para fetch e drivers de banco de dados que suportam cancelamento quando o cliente desconecta.

Armadilhas do Promise.race?

A requisição lenta perdida ainda executa a menos que seja abortada - combine com AbortController.

Jest open handles?

--detectOpenHandles encontra timers e servidores deixados abertos após os testes.

graphql trava?

Resolver aguardando outro resolver nos mesmos dataloaders sem batching - verifique N+1 e deadlock.

Promises de pool de workers?

O processo pai aguarda a resposta de worker.postMessage com timeout; termine o worker em caso de travamento.

Mitigação em produção?

Timeout do servidor HTTP + timeout ocioso do balanceador de carga + statement_timeout do banco de dados.

Relacionados

Noções Básicas de Depuração - anexar inspetor
Exaustão do Pool de Conexões - métricas do pool
Interrupção de Produção por Rejeição Não Tratada - consequências da falta de await
Timeouts em Todos os Lugares - timeouts de fronteira
Tratamento de Erros no Express - erros assíncronos

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Promise Que Nunca se Resolve

Buscar na documentação

Promise Que Nunca se Resolve