Solicitações de rede, leituras de arquivos e temporizadores terminam mais tarde, mas o JavaScript não pode simplesmente parar e esperar, ou a página congelaria. As promessas do JavaScript oferecem uma maneira organizada de dizer “quando isso terminar, faça aquilo e, se falhar, faça isso”.

Mesmo que você escreva principalmente async e await, você estará usando promessas subjacentes, portanto, entendê-las torna a depuração muito mais fácil. Executamos esses exemplos no Node.js 24 e a saída mostrada vem dessa execução. Eles se comportam da mesma maneira nos navegadores modernos.

O que é uma promessa?

Uma promessa é um espaço reservado para um valor futuro. Pense na campainha que um restaurante lhe dá quando você faz um pedido. Você ainda não tem sua comida, mas segura algo que lhe dirá quando estiver pronta ou que há um problema, e enquanto isso você está livre para fazer outras coisas.

No código, uma função assíncrona retorna uma promessa imediatamente e você anexa o que deve acontecer a seguir:

fetch("/api/user")
  .then((response) => response.json())
  .then((user) => console.log(user.name))
  .catch((error) => console.log("Failed:", error.message));

Os três estados prometidos

Uma promessa que é cumprida ou rejeitada é chamada de resolvida. Uma promessa só pode ser cumprida uma vez. Depois disso, seu estado e valor são fixos e as chamadas posteriores para resolve ou reject são ignoradas.

Crie uma promessa

Você normalmente consome promessas de APIs como fetch, mas criar uma mostra como elas funcionam. O construtor recebe duas funções, resolve e reject:

function fetchUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ id, name: "Asha" });
      } else {
        reject(new Error("Invalid id"));
      }
    }, 100);
  });
}

console.log(fetchUser(1));

// Promise { <pending> }

Registrar a promessa imediatamente mostra que ela ainda está pendente, porque o cronômetro não foi acionado. O valor só pode ser alcançado através de um manipulador ou await. Sempre rejeite com um objeto Error em vez de uma string, pois um Error carrega um rastreamento de pilha que ajuda na depuração.

então, pegue e finalmente

Esses três métodos vinculam manipuladores a uma promessa:

fetchUser(1).then((user) => console.log(user.name));
// Asha

fetchUser(-1)
  .then((user) => console.log("never runs", user))
  .catch((error) => console.log("caught:", error.message))
  .finally(() => console.log("finally"));

// caught: Invalid id
// finally

then é executado em caso de sucesso, catch é executado em caso de falha e finally é executado de qualquer maneira. Isso torna finally o lugar certo para limpeza, como ocultar um botão giratório de carregamento. Não recebe argumentos, porque não deveria se preocupar com o resultado.

Encadeando promessas

A ideia principal é que then sempre retorna uma nova promessa. Qualquer que seja o retorno do seu manipulador, torna-se o valor dessa nova promessa:

Promise.resolve(2)
  .then((n) => n * 10)
  .then((n) => n + 1)
  .then((n) => console.log("chain:", n));

// chain: 21

Se um manipulador retornar outra promessa, a cadeia espera que ela seja resolvida antes de prosseguir. Isto é o que transforma retornos de chamada aninhados em uma sequência simples de etapas:

getUser(id)
  .then((user) => getOrders(user.id))
  .then((orders) => getInvoice(orders[0].id))
  .then((invoice) => console.log(invoice.total))
  .catch(handleError);

Como os erros viajam através de uma cadeia

Uma promessa rejeitada pula cada then até chegar a catch. Jogar dentro de um manipulador também conta como rejeição. E um catch que retorna normalmente coloca a cadeia de volta nos trilhos:

Promise.resolve("start")
  .then(() => {
    throw new Error("step 2 failed");
  })
  .then(() => console.log("skipped"))
  .catch((error) => {
    console.log("caught:", error.message);
    return "recovered";
  })
  .then((value) => console.log("continues:", value));

// caught: step 2 failed
// continues: recovered

Pense nisso como a versão assíncrona de try e catch. Um catch no final geralmente cobre toda a cadeia. Se você deseja apenas registrar um erro e ainda assim falhar, lance-o novamente de dentro do catch.

Promise.all, allSettled, raça e qualquer

Esses métodos estáticos coordenam várias promessas ao mesmo tempo. Todos eles pegam um array e retornam uma promessa.

Para testá-los, usamos dois pequenos ajudantes, um que funciona após um atraso e outro que falha após um atraso:

const wait = (ms, value) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));
const fail = (ms, message) =>
  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms));

Promise.all

await Promise.all([wait(300, "a"), wait(100, "b"), wait(200, "c")]);

// [ 'a', 'b', 'c' ]   took about 300 ms

Dois detalhes a serem observados. Os resultados mantêm a ordem de entrada, mesmo que b tenha terminado primeiro. E o tempo total foi de cerca de 300 ms, o tempo da tarefa mais lenta e não a soma dos 600 ms, pois as três já estavam rodando ao mesmo tempo. Se algum deles rejeita, a coisa toda rejeita imediatamente:

await Promise.all([wait(100, "a"), fail(50, "b failed")]);

// rejected: b failed

Promise.allSettled

Este espera por tudo e reporta cada resultado, para que uma falha não perca o resto. É adequado para um painel onde cada widget é carregado de forma independente:

const results = await Promise.allSettled([wait(50, "a"), fail(50, "b failed")]);
results.map((r) => r.status);

// [ 'fulfilled', 'rejected' ]

Promessa.corrida e Promessa.qualquer

await Promise.race([wait(300, "slow"), wait(100, "fast")]);   // fast
await Promise.any([fail(50, "x"), wait(100, "ok")]);          // ok

A diferença é que race é o primeiro a resolver, mesmo que tenha falhado, enquanto any ignora as falhas desde que algo dê certo. Um uso clássico de race é adicionar um tempo limite a uma solicitação lenta, embora a tarefa mais lenta continue sendo executada em segundo plano, a menos que você a cancele.

Promessas e assíncrono/espera

async e await são uma forma mais legível de trabalhar com as mesmas promessas. Uma função async sempre retorna uma promessa e await pausa essa função até que uma promessa seja estabelecida:

async function showInvoice(id) {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    console.log(orders.length);
  } catch (error) {
    console.log("Failed:", error.message);
  }
}

As rejeições tornam-se erros lançados, então try e catch comuns funcionam. Você ainda precisa de Promise.all para trabalho paralelo, porque aguardar uma chamada após a outra as executa em sequência. Nosso guia JavaScript assíncrono/aguardado se aprofunda nisso.

Promessas e o ciclo de eventos

Os manipuladores de promessa nunca são chamados imediatamente, mesmo quando a promessa já foi cumprida. Eles são executados após o término do código atual e antes de qualquer temporizador. Aqui está a prova:

setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("microtask"));
console.log("sync");

// sync
// microtask
// timeout

O código síncrono é executado primeiro. Em seguida vem a fila de microtarefas, que contém manipuladores de promessas. Só então o loop de eventos seleciona a próxima tarefa, como um cronômetro. Esta é uma pergunta popular em entrevistas e explica por que um setTimeout igual a zero não é realmente imediato.

Promessas versus retornos de chamada

Erros comuns

• Esquecendo de retornar para dentro de then. Sem um return, o próximo passo recebe undefined e não espera pela sua promessa interior.
• Não catch. Isso causa uma rejeição não tratada e, no Node.js, isso interrompe o processo por padrão.
• Aninhamento em vez de encadeamento. Colocar then dentro de then recria o inferno de retorno de chamada. Devolva a promessa e continue a corrente.
• Envolvendo uma promessa em new Promise. Se uma função já retorna uma promessa, basta usá-la.
• Usando forEach com retornos de chamada assíncronos. Não espera. Use for...of ou Promise.all com map, conforme mostrado em nosso guia para métodos de array JavaScript.
• Pensar que uma promessa pode ser cancelada. Não pode por si só. Para solicitações, use AbortController.

Considerações finais

As promessas se resumem a algumas regras: uma promessa é estabelecida uma vez, then retorna uma nova promessa e os erros percorrem a cadeia até que algo os detecte. Uma vez que essas regras pareçam naturais, async e await deixam de ser mágicas. Para praticar, reescreva uma função baseada em retorno de chamada usando promessas, depois busque dois pontos de extremidade com Promise.all e trate uma falha adequadamente.

Perguntas frequentes

Continue aprendendo