JavaScript Promise API
Aprenda a Promise API do JavaScript: Promise.all, allSettled, race, any, além de resolve e reject. Compare fast-fail vs allSettled com exemplos executáveis e uma tabela de quando usar cada método.
A classe Promise disponibiliza vários métodos estáticos para combinar e criar promises. Em vez de encadear múltiplos .then() chains manualmente, você passa um array de promises para um combinador e recebe de volta uma única promise que se resolve quando o grupo atinge um estado definido.
Esta página cobre os quatro combinadores — Promise.all, Promise.allSettled, Promise.race e Promise.any — além dos dois helpers de criação Promise.resolve e Promise.reject. Se você é novo em promises, comece com JavaScript: Promises primeiro.
Os exemplos abaixo usam
.then()/.catch()para que o fluxo de controle seja explícito. Em código real, você normalmente leria o resultado comasync/await.
Escolhendo o combinador certo
| Método | Resolve quando… | Rejeita quando… | Uso típico |
|---|---|---|---|
Promise.all | todas as promises são cumpridas | qualquer promise é rejeitada (fast-fail) | Você precisa de todos os resultados e uma falha deve cancelar tudo |
Promise.allSettled | todas as promises se resolvem (nunca rejeita) | — | Você quer todos os resultados, sucesso ou falha |
Promise.race | a primeira promise se resolve (cumprida ou rejeitada) | a primeira promise é rejeitada primeiro | Timeouts, "o primeiro a responder vence" |
Promise.any | a primeira promise é cumprida | todas as promises são rejeitadas | Primeiro resultado bem-sucedido, ignorando falhas individuais |
A distinção principal: Promise.all faz fast-fail — ela rejeita no instante em que qualquer entrada é rejeitada, mesmo que outras promises ainda estejam pendentes. Se em vez disso você quiser aguardar todas as promises independentemente, use Promise.allSettled.
Utilizando Promise.all para Tarefas Concorrentes
Promise.all é um método essencial para lidar com múltiplas promises de forma concorrente. Quando você precisa executar várias operações assíncronas e só prosseguir após todas elas serem concluídas com sucesso, Promise.all é a ferramenta certa.
Como Implementar Promise.all
Abaixo está um exemplo que demonstra como usar Promise.all para lidar com múltiplas requisições de API simultaneamente:
Neste exemplo, Promise.all recebe um array de promises e resolve em um array com seus resultados na mesma ordem da entrada (não na ordem em que foram concluídas). Se qualquer promise for rejeitada, Promise.all rejeita imediatamente com o motivo dessa primeira rejeição — os resultados das demais são descartados. Veja Tratamento de erros com promises para saber como se recuperar dessas falhas.
Dominando Promise.allSettled
Diferente de Promise.all, o método Promise.allSettled retorna uma promise que se resolve após todas as promises fornecidas terem sido cumpridas ou rejeitadas, com um array de objetos que descrevem o resultado de cada promise.
Exemplo de Promise.allSettled
Veja como você pode usar Promise.allSettled:
Observação: Promise.allSettled nunca rejeita. Ela sempre resolve com um array de objetos de resultado, cada um contendo uma propriedade status ('fulfilled' ou 'rejected') e uma propriedade value ou reason.
Este método é especialmente útil quando você precisa garantir que todas as promises sejam processadas até o fim, independentemente de serem cumpridas ou rejeitadas.
Implementando Promise.race
Promise.race é outra ferramenta poderosa que permite lidar com múltiplas promises, resolvendo ou rejeitando assim que uma das promises no iterável se resolve ou é rejeitada.
Como Usar Promise.race
Abaixo está uma aplicação prática de Promise.race:
Este método é ideal para cenários em que você precisa do resultado mais rápido entre múltiplas operações assíncronas — por exemplo, fazer uma corrida entre uma requisição e uma promise de timeout. Note que race se resolve na primeira promise a se resolver, seja ela cumprida ou rejeitada.
Obtendo o Primeiro Sucesso com Promise.any
Promise.any é o contraponto otimista de Promise.race. Ela ignora rejeições e resolve com o valor da primeira promise a ser cumprida. Ela só rejeita se todas as promises forem rejeitadas, caso em que lança um AggregateError cuja propriedade .errors contém todos os motivos individuais.
Como Usar Promise.any
Use Promise.any quando você tem várias fontes para os mesmos dados (por exemplo, servidores espelho) e só se importa com o primeiro que tiver sucesso.
Criando Promises com resolve e reject
Promise.resolve(value) e Promise.reject(reason) são atalhos para criar uma promise já resolvida sem o boilerplate de new Promise(executor).
Promise.resolve(value)retorna uma promise que já está cumprida comvalue. Sevaluefor em si um thenable, ele é "adotado" e seguido.Promise.reject(reason)retorna uma promise que já está rejeitada comreason.
Esses helpers são comumente usados para retornar um valor em cache de uma função que de outra forma seria assíncrona, ou para iniciar uma cadeia .then().
Criando um Polyfill para Promise.allSettled
Nem todos os ambientes suportam Promise.allSettled nativamente. Por isso, implementar um polyfill pode garantir compatibilidade em diferentes ambientes JavaScript.
Polyfill para Promise.allSettled
Veja como você pode criar um polyfill simples:
Este polyfill fornece uma funcionalidade básica em que cada promise é tratada individualmente e resolvida para seu respectivo resultado, garantindo que o comportamento de allSettled seja imitado de forma eficaz.
Ao integrar essas técnicas avançadas de promises e compreender os mecanismos subjacentes dos polyfills, você pode elevar seu código JavaScript a um novo patamar. Esses métodos não apenas aumentam a confiabilidade do código, mas também oferecem controle refinado sobre operações assíncronas, abrindo caminho para aplicações web mais robustas.