Promise

Esta tradução está incompleta. Ajude a traduzir este artigo em inglês

Promise é um objeto usado para processamento assíncrono. Um Promise (de "promessa") representa um valor que pode estar disponível agora, no futuro ou nunca.

Nota: Esse artigo descreve o construtor Promise,os métodos e propriedades de tais objetos. Para aprender sobre como promises funcionam e como utilizá-los, é aconselhavel a leitura de utilizando promises. O construtor é utilizado para embrulhar funções sem suporte ao conceito "promise".

Sintaxe

new Promise(/* executor */ function(resolve, reject) { ... });

Parâmetros

executor

Uma função que recebe dois argumentos resolve e reject. Esta função é executada imediatamente pela implementação do Promise, passando as funções resolve e rejectexecutor é chamado antes que o construtor de Promise retorne o objeto criado.  

As funções resolve e reject, quando chamadas, resolvem (em caso de sucesso) ou rejeitam (quando ocorre um erro) a promessa, respectivamente. O executor começa o trabalho assíncrono que, quando concluído, chama uma das funções resolve ou reject para definir o estado da promessa.

Descrição

Um Promise representa um proxy para um valor que não é necessariamente conhecido quando a promessa é criada. Isso permite a associação de métodos de tratamento para eventos da ação assíncrona num caso eventual de sucesso ou de falha. Isto permite que métodos assíncronos retornem valores como métodos síncronos: ao invés do valor final, o método assíncrono retorna uma promessa ao valor em algum momento no futuro.

Um Promise está em um destes estados: 

  • pending (pendente): Estado inicial, que não foi realizada nem rejeitada.
  • fulfilled (realizada): sucesso na operação.
  • rejected (rejeitado):  falha na operação.
  • settled (estabelecida): Que foi realizada ou rejeitada.

Uma promessa pendente pode se tornar realizada com um valor ou rejeitada por um motivo (erro). Quando um desses estados ocorre, o método then do Promise é chamado, e ele chama o método de tratamento associado ao estado (rejected ou resolved).  (Se a promessa foi realizada ou rejeitada quando o método de tratamento correspondente for associado, o método será chamado, deste forma não há uma condição de competição entre uma operação assíncrona e seus manipuladores que estão sendo associados.)

Como os métodos Promise.prototype.then e Promise.prototype.catch  retornam promises, eles podem ser encadeados — uma operação chamada composição.

Propriedades

Promise.length
Propriedade length cujo valor é sempre 1 (número de argumentos do método construtor).
Promise.prototype
Representa o protótipo para o método construtor da Promise.

Métodos

Promise.all(lista)
Retorna uma promise que é resolvida quando todas as promises no argumento lista forem resolvidas ou rejeitada assim que uma das promises da lista for rejeitada. Se a promise retornada for resolvida, ela é resolvida com um array dos valores das promises resolvidas da lista. Se a promise for rejeitada, ela é rejeitada com o motivo da primeira promise que foi rejeitada na lista. Este método pode ser útil para agregar resultados de múltiplas promises.
Promise.race(lista)
Retorna uma promise que resolve ou rejeita assim que uma das promises do argumento lista resolve ou rejeita, com um valor ou o motivo daquela promise.
Promise.reject(motivo)
Retorna um objeto Promise que foi rejeitado por um dado motivo.
Promise.resolve(valor)
Retorna um objeto Promise que foi resolvido com um dado valor. Se o valor é thenable (possui um método then), a promise retornada "seguirá" este método, adotando esse estado eventual; caso contrário a promise retornada será realizada com o valor. Geralmente, se você quer saber se um valor é uma promise ou não, utilize Promise.resolve(valor) e trabalhe com a valor de retorno que é sempre uma promise.

Protótipo Promise

Propriedades

Promise.prototype.constructor
Retorna a função que cria uma instância. Isso é a função padrão Promise.

Métodos

Promise.prototype.catch(onRejected)
Adiciona um callback que trata rejeição para a promise e, retorna uma nova promise resolvendo o valor retornado do callback, se ele for chamado, ou para seu valor original de conclusão se a promise for realizada.
Promise.prototype.then(onFulfilled, onRejected)
Adiciona os métodos de tratamento da realização e rejeição da promise e, retorna uma nova promise resolvendo para o valor do método chamado.

Exemplos

Criando uma Promise

Este pequeno exemplo mostra o mecanismo de uma Promise. O método testPromise() é chamado cada vez que <button> é clicado. Isso cria uma promise que resolverá, usando window.setTimeout(), o contador de promise promiseCount (iniciando em 1) a cada 1 a 3s randomicamente. O construtor Promise() é usado para criar a promise.

A realização da promise é simplesmente registrada, por meio de configuração na função callback de realização  usando p1.then(). Alguns logs mostram como a parte síncrona do método é desacoplada da conclusão assíncrona da promise.

var promiseCount = 0;
function testPromise() {
  var thisPromiseCount = ++promiseCount;

  var log = document.getElementById('log');
  log.insertAdjacentHTML('beforeend', thisPromiseCount + 
      ') Started (<small>Sync code started</small>)<br/>');

  // Criamos uma nova promise: prometemos a contagem dessa promise (após aguardar 3s)
  var p1 = new Promise(
    // a função resolve() é chamada com a capacidade para resolver ou 
    // rejeitar a promise
    function(resolve, reject) {       
      log.insertAdjacentHTML('beforeend', thisPromiseCount + 
          ') Promise started (<small>Async code started</small>)<br/>');
      // Isto é apenas um exemplo para criar assincronismo
      window.setTimeout(
        function() {
          // Cumprimos a promessa !
          resolve(thisPromiseCount)
        }, Math.random() * 2000 + 1000);
    });

  // definimos o que fazer quando a promise for realizada
  p1.then(
    // apenas logamos a mensagem e o valor
    function(val) {
      log.insertAdjacentHTML('beforeend', val +
          ') Promise fulfilled (<small>Async code terminated</small>)<br/>');
    });

  log.insertAdjacentHTML('beforeend', thisPromiseCount + 
      ') Promise made (<small>Sync code terminated</small>)<br/>');
}

Este exemplo é executado pelo click do botão. Você precisa de uma versão de navegedor com suporte a Promise. Clicando algumas vezes no botão num curto intervalo de tempo, você verá as diferentes promises sendo realizadas uma após a outra.

Carregando uma imagem com XHR

Outro simples exemplo usando Promise e XMLHTTPRequest para carregar imagens está disponível no repositório GitHub MDN promise-test. Você também pode vê-lo em ação. Cada passo é comentado e lhe permite acompanhar de perto a arquitetura de Promise e XHR.

Especificações

Especificação Status Comentário
domenic/promises-unwrapping Draft Standardization work is taking place here.
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Promise' in that specification.
Padrão Initial definition in an ECMA standard.

Compatibilidade de Navegador

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
PromiseChrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support 19Safari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
Promise() constructorChrome Full support 32Edge Full support 12Firefox Full support 29
Notes
Full support 29
Notes
Notes Constructor requires a new operator since version 37.
IE No support NoOpera Full support 19Safari Full support 8
Notes
Full support 8
Notes
Notes Constructor requires a new operator since version 10.
WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29
Notes
Full support 29
Notes
Notes Constructor requires a new operator since version 37.
Opera Android Full support 19Safari iOS Full support 8
Notes
Full support 8
Notes
Notes Constructor requires a new operator since version 10.
Samsung Internet Android Full support 2.0nodejs Full support 0.12
Notes
Full support 0.12
Notes
Notes Constructor requires a new operator since version 4.
all()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support 19Safari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
allSettled()Chrome Full support 76Edge Full support 79Firefox Full support 71IE No support NoOpera Full support 63Safari Full support 13WebView Android Full support 76Chrome Android Full support 76Firefox Android No support NoOpera Android Full support 54Safari iOS Full support 13Samsung Internet Android No support Nonodejs Full support 12.9.0
anyChrome Full support 85Edge No support NoFirefox Full support 79IE No support NoOpera No support NoSafari Full support 14WebView Android Full support 85Chrome Android Full support 85Firefox Android No support NoOpera Android No support NoSafari iOS Full support 14Samsung Internet Android No support Nonodejs No support No
catch()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support 19Safari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
finally()Chrome Full support 63Edge Full support 18Firefox Full support 58IE No support NoOpera Full support 50Safari Full support 11.1WebView Android Full support 63Chrome Android Full support 63Firefox Android Full support 58Opera Android Full support 46Safari iOS Full support 11.3Samsung Internet Android Full support 8.0nodejs Full support 10.0.0
race()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support 19Safari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
reject()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support 19Safari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
resolve()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support 19Safari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
then()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support 19Safari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Veja também