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

CKTIS / JavaScript

Registos de resultados de Promise.allSettled()

`Promise.allSettled()` devolve uma promessa que, depois de todas as promessas de entrada terminarem, é cumprida com um array de resultados na ordem de entrada. `status` indica se deves ler `value` ou `reason`.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

Promise.allSettled(iterable)

// Each element of the array that the returned promise fulfills with:
// { status: "fulfilled", value: … }
// { status: "rejected", reason: … }

Promise.allSettled(iterable) é um método estático de Promise que recebe um iterável síncrono, como um array. Trata cada elemento como Promise.resolve() o trataria: adota o desfecho dos objetos thenable e usa os valores simples como valores de cumprimento. Quando todas as promessas de entrada estiverem cumpridas ou rejeitadas, a promessa devolvida é cumprida com um array que contém um resultado por elemento, pela ordem de iteração e não pela ordem de conclusão.

Cada registo é um objeto JavaScript comum. Um registo com status: "fulfilled" tem uma propriedade própria value, mas não uma propriedade própria reason. Com status: "rejected", tem uma propriedade própria reason, mas não uma propriedade própria value. Verifica primeiro status: 0 e undefined podem ser valores de cumprimento válidos, e o motivo da rejeição não tem de ser um Error e também pode ser undefined.

Ao contrário de Promise.all(), uma rejeição individual fica registada no array e não rejeita por si só a promessa agregada. Isto permite conservar os resultados das tarefas independentes bem-sucedidas e tratar as falhas em separado. Um erro ao ler o iterável pode, contudo, rejeitar a promessa agregada em vez de produzir um registo de resultado.

Se a entrada estiver vazia, o método devolve uma promessa já cumprida com [], mas a função passada a .then() continua a ser executada de forma assíncrona. Se a entrada não estiver vazia, com o comportamento padrão das promessas, a promessa agregada ainda está pendente quando o método a devolve, mesmo que já não haja promessas de entrada pendentes. Pode, contudo, ser devolvida já cumprida se o único elemento for uma promessa nativa que Promise.resolve() devolve sem alterações e cujo método próprio then chama de forma síncrona a função de cumprimento.

Exemplos

{
  let finishFirst;
  const first = new Promise((resolve) => { finishFirst = resolve; });
  const second = Promise.reject("offline");
  const batch = Promise.allSettled([first, second, 0]);
  finishFirst("profile");

  batch.then((results) => {
    console.log(JSON.stringify(results));
    for (const result of results) {
      if (result.status === "fulfilled") {
        console.log(`value: ${result.value}`);
      } else {
        console.log(`reason: ${result.reason}`);
      }
    }
  });
}

Resultado

[{"status":"fulfilled","value":"profile"},{"status":"rejected","reason":"offline"},{"status":"fulfilled","value":0}]
value: profile
reason: offline
value: 0

A segunda promessa é rejeitada antes de a primeira ser cumprida, mas o seu registo continua na segunda posição. O valor simples `0` produz um registo com o estado `"fulfilled"`.

Lições relacionadas

  • JavaScript · Lição 15 · Intermédio · Versão: 3

Fontes