async/await em Node

async/await torna o código assíncrono do Node parecido com código síncrono, mantendo a semântica de Promises - a vantagem é a clareza se você preservar o contexto de erro e evitar serializar I/O independente.

Receita

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 falhou:', err);
}

Quando usar isso:

• Manipuladores HTTP que encadeiam chamadas de banco de dados e API
• Scripts que leem configuração, conectam ao DB e então iniciam o servidor
• Substituindo pirâmides aninhadas de .then() em código brownfield
• Manipuladores de rota Express 5 / Fastify 5 com lógica assíncrona

Exemplo de Trabalho

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 latência do DB
  const user = users.get(id);
  if (!user) throw new Error(`Usuário ${id} não encontrado`);
  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 : 'Erro desconhecido';
    const status = message.includes('não encontrado') ? 404 : 500;
    res.writeHead(status, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ error: message }));
  }
});
 
server.listen(3000);

O que isso demonstra:

• Manipuladores de rota async retornam Promises - erros devem ser capturados por solicitação
• try/catch em torno de await mapeia falhas para códigos de status HTTP
• Lançar instâncias de Error preserva mensagens para clientes e logs
• Cada solicitação ainda compartilha uma thread - await não bloqueia outras solicitações, a menos que você use await sequencialmente dentro de um lock

Mergulho Profundo

Como Funciona

• async function sempre retorna uma Promise - mesmo que você return 42.
• await pausa a função até que a Promise seja resolvida, agendando o restante como microtarefas.
• Erros lançados dentro de funções async se tornam Promises rejeitadas.
• Top-level await em módulos ESM atrasa os importadores até que o módulo termine de inicializar.

Paralelo vs Sequencial

// Lento: sequencial (latência se acumula)
const a = await fetchA();
const b = await fetchB();
 
// Rápido: I/O independente paralelo
const [a, b] = await Promise.all([fetchA(), fetchB()]);

Notas de TypeScript

// Padrão Result tipado para falhas esperadas (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)) };
  }
}

Armadilhas

• Erros assíncronos não tratados em manipuladores HTTP - Express 4 precisava de wrapping; ainda assim, capture explicitamente. Correção: try/catch ou hooks de erro do framework (Express 5 melhora isso).
• await sequencial em loops - for (const id of ids) await fetch(id) é lento. Correção: Promise.all com limite de concorrência (p-limit).
• I/O assíncrono flutuante sem await - fire-and-forget perde o contexto de erro. Correção: void doWork().catch(log) intencionalmente, ou await.
• Mistura estranha de callbacks e await - promisse primeiro. Correção: util.promisify ou fs/promises.
• Top-level await bloqueando importadores - inicialização lenta do módulo atrasa o boot completo do aplicativo. Correção: import() dinâmico e preguiçoso para dependências pesadas.

Alternativas

FAQs

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

Relacionado

• Migração de Callbacks vs Promises - conversão brownfield
• Microtasks vs Macrotasks - o que await agenda
• Tipando Manipuladores Express/Fastify - rotas async tipadas
• Melhores Práticas do Event Loop - regras de I/O paralelo

Versões da Pilha: 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.