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

CKTIS / JavaScript

Promise.prototype.finally — limpeza após a conclusão de uma promessa

Promise.prototype.finally executa uma função depois de uma promessa ser cumprida ou rejeitada. Permite fazer uma limpeza comum que normalmente preserva o resultado original, embora uma falha na limpeza o possa substituir.

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.finally(onFinally)

Promise.prototype.finally regista onFinally, chamada de forma assíncrona depois de a promessa ser cumprida ou rejeitada. A função não recebe argumentos: nem o valor nem o motivo da rejeição. Nas promessas padrão, o método devolve uma nova promessa sem alterar a original.

Um valor normal devolvido por onFinally é ignorado. Se a função terminar com sucesso, a cadeia preserva o valor original ou o motivo da rejeição. Se devolver uma promessa ou um thenable, a cadeia aguarda pela sua resolução. Uma exceção lançada ou uma rejeição substitui o resultado original por uma nova rejeição; se ficar pendente para sempre, bloqueia a continuação da cadeia.

Não é equivalente a then(onFinally, onFinally): essas funções recebem um argumento e o resultado pode substituir o valor anterior. finally() não trata um erro por si só — usa catch() na cadeia devolvida. O processamento padrão de promessas ignora um argumento que não seja uma função.

O método faz parte de ECMAScript desde ES2018, não de Web APIs. A especificação da linguagem não confirma o suporte num browser específico; a presença de Node 24 num repositório também não o comprova. No exemplo, "ignored" não substitui 42, e a segunda limpeza não elimina a rejeição.

Exemplos

Promise.resolve(42)
  .finally(() => {
    console.log("cleanup");
    return "ignored";
  })
  .then((value) => {
    console.log(value);
    return Promise.reject("failure");
  })
  .finally(() => {
    console.log("cleanup after rejection");
  })
  .catch((reason) => console.log(reason));

Resultado

cleanup
42
cleanup after rejection
failure

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