Serviço de tradução

O objeto Promise representa a conclusão (ou falha) eventual de uma operação assíncrona e o valor que dela resulta.

Ciclo de vida de uma promise

Uma Promise tem três estados:

1. pendente
2. cumprida
3. rejeitada

Quando é criada, uma promise está pendente. Em algum momento no futuro, pode ser resolvida ou rejeitada. Depois de uma promise ser resolvida ou rejeitada uma vez, nunca mais pode voltar a ser resolvida nem rejeitada, e o seu estado também não pode mudar.

Por outras palavras:

1. Quando está pendente, uma promise:
   • pode passar a estar cumprida ou rejeitada.
2. Quando está cumprida, uma promise:
   • não pode passar a nenhum outro estado.
   • tem de ter um valor, que não pode mudar.
3. Quando está rejeitada, uma promise:
   • não pode passar a nenhum outro estado.
   • tem de ter um motivo, que não pode mudar.

Resolver uma promise

Uma promise pode ser resolvida de várias formas:

// Creates a promise that is immediately resolved
Promise.resolve(value);

// Creates a promise that is immediately resolved
new Promise((resolve) => {
  resolve(value);
});

// Chaining a promise leads to a resolved promise
somePromise.then(() => {
  // ...
  return value;
});

Nos exemplos acima, value pode ser qualquer coisa, incluindo um erro, undefined, null ou outra promise. Normalmente, queres resolver com um valor que não seja um erro.

Rejeitar uma promise

Uma promise pode ser rejeitada de várias formas:

// Creates a promise that is immediately rejected
Promise.reject(reason)

// Creates a promise that is immediately rejected
new Promise((_, reject) {
  reject(reason)
})

// Chaining a promise with an error leads to a rejected promise
somePromise.then(() => {
  // ...
  throw reason
})

Nos exemplos acima, reason pode ser qualquer coisa, incluindo um erro, undefined ou null. Normalmente, queres rejeitar com um erro.

Encadear uma promise

Uma promise pode ser continuada com uma ação futura, assim que for resolvida ou rejeitada.

• promise.then() é chamado assim que a promise é resolvida
• promise.catch() é chamado assim que a promise é rejeitada
• promise.finally() é chamado assim que a promise é resolvida ou rejeitada

then

Todas as promises são "thenable". Isto significa que existe uma função then disponível que será executada assim que a promise original for resolvida. Dado promise.then(onResolved), a função de callback onResolved recebe o valor com que a promise original foi resolvida. Isto devolve sempre uma nova promise "encadeada".

Devolver um value a partir do then resolve a promise "encadeada". Lançar um reason no then rejeita a promise "encadeada".

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);
});

const promise2 = promise1.then(function (value) {
  console.log(value);
  // expected output: "Success!"

  return true;
});

Isto regista "Success!" ao fim de aproximadamente 1000 ms. O estado e o valor de promise1 serão resolved e "Success!". O estado e o valor de promise2 serão resolved e true.

Há um segundo argumento disponível que é executado quando a promise original é rejeitada. Dado promise.then(onResolved, onRejected), a função de callback onResolved recebe o valor com que a promise original foi resolvida, ou a função de callback onRejected recebe o motivo pelo qual a promise foi rejeitada.

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return true;
}

function shout(reason) {
  console.error(reason.toUpperCase());
  return false;
}

const promise2 = promise1.then(log, shout);

• Em cerca de metade dos casos, isto regista "Success!" ao fim de aproximadamente 1000 ms.
  • O estado e o valor de promise1 serão resolved e "Success!".
  • O estado e o valor de promise2 serão resolved e true.
• Em cerca de metade dos casos, isto regista imediatamente "NOPE!".
  • O estado e o valor de promise1 serão rejected e Nope!.
  • O estado e o valor de promise2 serão resolved e false.

É importante perceber que, devido às regras do ciclo de vida, quando há um reject, o resolve que chega cerca de 1000 ms depois é silenciosamente ignorado, porque o estado interno não pode mudar depois de a promise ser rejeitada ou resolvida. É importante perceber que devolver um valor a partir de uma promise faz com que esta seja resolvida, e que lançar um valor faz com que seja rejeitada. Quando promise1 é resolvida e existe um onResolved encadeado, then(onResolved), o que se segue é uma nova promise que pode ser resolvida ou rejeitada. Quando promise1 é rejeitada mas existe um onRejected encadeado, then(, onRejected), o que se segue é uma nova promise que pode ser resolvida ou rejeitada.

catch

Por vezes queres capturar erros e só continuar quando a promise original é rejeitada. Dado promise.catch(onCatch), a função de callback onCatch recebe o motivo pelo qual a promise original foi rejeitada. Isto devolve sempre uma nova promise "encadeada".

Devolver um value a partir do catch resolve a promise "encadeada". Lançar um reason no catch rejeita a promise "encadeada".

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return 'done';
}

function recover(reason) {
  console.error(reason.toUpperCase());
  return 42;
}

const promise2 = promise1.catch(recover).then(log);

Em cerca de metade dos casos, isto regista "Success!" ao fim de aproximadamente 1000 ms. Na outra metade dos casos, isto regista imediatamente 42.

• Se promise1 for resolvida, o catch é ignorado e chega-se ao then, que regista o valor.
  • O estado e o valor de promise1 serão resolved e "Success!".
  • O estado e o valor de promise2 serão resolved e "done";
• Se promise1 for rejeitada, o catch é executado, o que devolve um valor, e portanto a cadeia fica agora resolved e chega ao then, que regista o valor.
  • O estado e o valor de promise1 serão rejected e "Nope!".
  • O estado e o valor de promise2 serão resolved e "done";

finally

Por vezes queres executar código depois de uma promise terminar, independentemente de ela ser resolvida ou rejeitada. Dado promise.finally(onSettled), a função de callback onSettled não recebe nada. Isto devolve sempre uma nova promise "encadeada".

Devolver um value a partir do finally copia o estado e o valor da promise original, ignorando o value. Lançar um reason no finally rejeita a promise "encadeada", substituindo qualquer estado e valor, ou motivo, da promise original.

Exemplo

Vários dos métodos em conjunto:

const myPromise = new Promise(function (resolve, reject) {
  const sampleData = [2, 4, 6, 8];
  const randomNumber = Math.round(Math.random() * 5);

  if (sampleData[randomNumber]) {
    resolve(sampleData[randomNumber]);
  } else {
    reject('Sampling did not result in a sample');
  }
});

const finalPromise = myPromise
  .then(function (sampled) {
    // If the random number was 0, 1, 2, or 3, this will be
    // reached and the number 2, 4, 6, or 8 will be logged.
    console.log(`Sampled data: ${sampled}`);
    return 'yay';
  })
  .catch(function (reason) {
    // If the random number was 4 or 5, this will be reached and
    // reason will be "An error occurred". The entire chain will
    // then reject with an Error with the reason as message.
    throw new Error(reason);
  })
  .finally(function () {
    // This will always log after either the sampled data is
    // logged or the error is raised.
    console.log('Promise completed');
  });

• Nos casos em que randomNumber é 0-3:
  • myPromise será resolvida com o valor 2, 4, 6, or 8
  • finalPromise será resolvida com o valor 'yay'
  • Haverá dois registos:
    • Sampled data: ...
    • Promise completed
• Nos casos em que randomNumber é 4-5:
  • myPromise será rejeitada com o motivo 'Sampling did not result in a sample'
  • finalPromise será rejeitada com o motivo Error('Sampling did not result in a sample')
  • Haverá um registo:
    • Promise completed
    • em alguns ambientes, isto dará origem a um registo "uncaught rejected promise: Error('Sampling did not result in a sample')"

Como se mostra acima, o reject funciona com uma string, e uma promise também pode ser rejeitada com um Error.