Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Promise.any — o primeiro resultado bem-sucedido

Promise.any aceita um objeto iterável e devolve uma promise cumprida com o primeiro resultado bem-sucedido que o método observa. As rejeições das entradas não terminam a espera, a menos que todas sejam rejeitadas; nesse caso, o resultado é rejeitado com AggregateError.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

Promise.any(iterable)

Promise.any(iterable) é um método estático de Promise, introduzido no ECMAScript 2021 (ES12). Aceita um objeto iterável síncrono, como um array de promises, valores simples ou objetos com um método then (thenables). Os valores são convertidos através de Promise.resolve; não passes funções à espera que o método as invoque.

A promise devolvida assume o valor do primeiro resultado bem-sucedido que Promise.any observa, que não é necessariamente o que ocorreu mais cedo. Se passares duas promises normais já cumpridas e o método nativo Promise.resolve devolver ambas sem alterações, vence a primeira na ordem de iteração, mesmo que tenha sido cumprida depois da segunda. O método nativo Promise.resolve devolve uma promise sem alterações se o valor da sua propriedade constructor for idêntico ao valor de this na chamada. Não verifica de que ambiente de execução (realm) vem a promise. Se a primeira promise vier de outro realm e tiver o seu construtor predefinido, o método local Promise.resolve envolve-a numa nova promise. Isto atrasa a reação ao seu cumprimento, pelo que a segunda pode vencer se for devolvida sem alterações. Mas, se a propriedade constructor da primeira promise tiver como valor o Promise local, o método local Promise.resolve devolve-a sem alterações apesar da sua origem. Em Promise.race, a rejeição de uma entrada pode determinar o resultado se o método a observar antes de qualquer outro cumprimento ou rejeição. Em Promise.any, as rejeições das entradas só fazem com que o resultado seja rejeitado com AggregateError quando todas as entradas tiverem sido rejeitadas, incluindo quando há apenas uma entrada e esta é rejeitada. O método não cancela as restantes operações após um sucesso.

Se todas as entradas forem rejeitadas, o resultado é rejeitado com AggregateError. O respetivo array errors contém as razões pela ordem das entradas, não pela ordem das rejeições. Promise.any([]) devolve uma promise já rejeitada com um array errors vazio; os handlers continuam a ser executados de forma assíncrona. Um erro ao ler o iterador também pode rejeitar o resultado, sem AggregateError.

Utiliza este método quando basta um resultado bem-sucedido. Trata a ausência de sucesso com try/catch em torno de await ou com .catch(). A especificação da linguagem não confirma o suporte num navegador específico: verifica o ambiente de destino, por exemplo com typeof Promise.any === "function". A presença de Node 24 num repositório não comprova o suporte nos navegadores.

Exemplos

async function main() {
  const value = await Promise.any([
    Promise.reject("offline"),
    Promise.resolve("ready")
  ]);
  console.log(value);

  try {
    await Promise.any([
      Promise.reject("first"),
      Promise.reject("second")
    ]);
  } catch (error) {
    console.log(error instanceof AggregateError);
    console.log(JSON.stringify(error.errors));
  }
}

main().catch(console.error);

Resultado

ready
true
["first","second"]

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes