Perigos de usar async/await dentro de forEach em operações assíncronas

Quando se trata de manipulação assíncrona de listas em JavaScript, uma prática bastante comum, mas altamente problemática, é usar o método forEach com funções assíncronas. A ideia de disparar operações paralelas dentro de um forEach soa eficiente à primeira vista, especialmente para quem quer processar múltiplos arquivos ou requisições ao mesmo tempo. Contudo, essa abordagem tem várias armadilhas que podem comprometer a confiabilidade do seu código.

---

O problema clássico: expectativas versus realidade

Muitos desenvolvedores, ao verem que o código 'funciona', acabam pensando que tudo está sob controle. Mas a verdade é que o forEach não lida com promessas retornadas de funções assíncronas da maneira que imaginamos. Ele simplesmente ignora o fato de que a callback assíncrona retorna uma promessa. Como consequência, a função principal pode terminar sua execução antes de todas as operações assíncronas serem concluídas. A decisão fica mais saudável quando o time consegue medir o impacto depois.

Essa situação pode gerar efeitos colaterais inesperados, como logs fora de ordem, operações incompletas ou até mesmo erros de concorrência em contextos mais sensíveis.

---

Diagnóstico: por que o forEach não funciona com async/await?

O método forEach foi concebido para execução síncrona. Quando você passa uma função assíncrona, ela é invocada, mas a promessa retornada não é aguardada pelo forEach. Assim, o fluxo de execução continua, e a função que chamou o forEach pode já ter retornado antes que as operações assíncronas terminem.

O uso de await dentro de uma callback de forEach não faz com que a próxima iteração espere a conclusão da anterior, nem garante a finalização de todas as tarefas antes do término da função envolvente.

Como fazer certo: alternativas práticas

Para leitura sequencial, a solução é usar um loop for...of, que permite o uso de await de forma natural e garantida. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar.

async function printFiles() {
  const files = await getFilePaths(). for (const file of files) {
    const contents = await fs.readFile(file, 'utf8'). console.log(contents). }
}

Se o objetivo é processamento paralelo, o caminho é usar map() para transformar os arquivos em promessas e, depois, aguardar todas com Promise.all. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

async function printFiles() {
  const files = await getFilePaths(). await Promise.all(files.map(async (file) => {
    const contents = await fs.readFile(file, 'utf8'). console.log(contents). })). }

O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Tradeoffs e considerações

• Leitura sequencial garante ordem e evita sobrecarga de recursos.
• Leitura paralela acelera processamento, mas pode sobrecarregar a infraestrutura, além de dificultar o controle de erros específicos.
• Sempre avalie o impacto na sua aplicação e o ambiente onde ela opera.

Erros comuns e armadilhas

• Esquecer que forEach não aguarda promessas.
• Usar Promise.all sem lidar com erros específicos de cada operação.
• Misturar processamento sequencial e paralelo sem entender as implicações de performance.

Encerrando

Entender o comportamento de cada método assíncrono é vital para evitar problemas de execução e bugs difíceis de rastrear. Em operações assíncronas, prefira for...of para sequências e Promise.all para paralelismo controlado. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Se você já enfrentou problemas com esse padrão, compartilhe sua experiência. Melhor ainda, teste seu código com logs de início e fim das operações para garantir que a execução está conforme esperado. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta.