nginstack

Class: Promise

Promise

new Promise(executor)

Um Promise é utilizado em operações assíncronas. Ele representa uma operação que ainda não foi concluída, mas que se espera que ocorra em um futuro breve. Ele pode estar em um dos três estados:

  • pendente: estado inicial, ainda não concluído ou rejeitado.
  • realizado: sucesso na operação.
  • rejeitado: falha na operação.
    Mais detalhes e exemplos podem ser obtidos em https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise. Importante: esta implementação de Promise é voltada para o uso nas APIs do Web Framework e não tem o objetivo de ser uma API de Promise de uso geral. Ela difere da especificação Promises/A+ quanto a execução dos eventos onFulfilled or onRejected (2.2.4). Diferentemente da especificação, nesta API eles são chamados dentro da pilha do contexto de execução, mais precisamente após a execução dos eventos de processos, quando o controle da execução retorna para a camada do Web Framework.
Parameters:
Name Type Argument Description
executor function <nullable>

Função opcional que receberá como parâmetro duas funções: resolve e reject. A primeira deve ser chamada para indicar o resultado do Promise e a segunda para indicar uma eventual rejeição. Essas duas funções devem ser chamadas apenas quando a operação for completada.
Author:
  • Adaptação da implementação do zousan (https://github.com/bluejava/zousan). Esta classe deve ser utilizada de forma temporária até a migração para o V8 que dará suporte nativo a API de promises.

Methods

<static> all(promises)

Retorna um Promise que é resolvido quando todos os promises informados forem resolvidos ou rejeitado assim que um dos Promises informados for rejeitado. Se o promise retornado for resolvido, ele é resolvido com um array dos valores de todos os promises resolvidos informados. Se o promise for rejeitado, ele é rejeitado com o motivo do primeiro promise que for rejeitado na lista. Este método pode ser útil para agregar resultados de múltiplos promises.

Parameters:
Name Type Description
promises Array.<Promise>

Promises a serem avaliados.
Returns:

Um promise resolvido com um array os valores de todos os promises informados resolvidos, na mesma ordem, ou rejeitado com a primeira rejeição dos promises informados.

Type
Promise
Example
var p1 = Promise.resolve(1);
 var p2 = 2;
 var p3 = new Promise(function (resolve, reject) {
   longOperation(resolve.bind(null, 3));
 });
 Promise.all([p1, p2, p3]).then(function (values) {
   long.info(values); // [1, 2, 3]
 });

<static> processEventQueue()

Executa os listeners dos promises resolvidos ou rejeitados. Importante: esse método é executado automaticamente pelo Web Framework e não deve ser executado manualmente.

<static> reject(reason)

Cria um Promise rejeitado pelo motivo informado. Para fins de depuração e normalização, é útil que reason seja uma instância de Error

Parameters:
Name Type Description
reason *

Motivo da rejeição do Promise a ser criado.
Returns:

Promise rejeitado com o motivo informado.

Type
Promise

<static> resolve(value)

Cria um Promise resolvido com o valor informado.

Parameters:
Name Type Description
value *

Valor a ser resolvido pelo Promise.
Returns:

Promise resolvido com o valor informado.

Type
Promise
Example
var promise = Promise.resolve(['A', 'B', 'C']);
 promise.then(function(value) {
   log.info(value[0]); // 'A'
 });

'catch'(onRejected)

Informa um callback que tratará apenas os casos de rejeição e retorna um novo promise com o resultado desse callback. Seu uso é equivalente a chamar Promise.prototype.then(undefined, onRejected).

Parameters:
Name Type Description
onRejected function

Função que receberá o motivo da rejeição do Promise.
Returns:

Promise com o valor ou a rejeição indicada por onRejected.

Type
Promise
Example
var p = new Promise(function(resolve, reject) {
   resolve('Sucesso');
 });
 p.then(function(value) {
  log.info(value); // 'Sucesso'
  throw new Error('Falha');
}).catch(function (e) {
  log.error(e); // Error('Falha')
  return 'Novo sucesso';
}).then(function (value){
  log.info(value); // 'Novo sucesso'
}, function () {
  log.info('Não é disparado devido ao catch');
});

'finally'(handler)

Informa um callback que será chamado com o valor resolvido ou o motivo da rejeição e retorna um novo promise com o resultado desse callback. Seu uso é equivalente a chamar Promise.prototype.then(handler, handler).

Parameters:
Name Type Description
handler function

Callback que será chamando quando o promise for resolvido ou rejeitado.
Returns:

Promise com o valor ou rejeição indicada por handler.

Type
Promise

then(onFulfilled, onRejected)

Adiciona as funções responsáveis por tratar a resolução e rejeição deste promise e retorna um novo promise que será resolvido para o valor retornado pelas funções informadas ou o valor originalmente resolvido para este promise caso a função relevante onFulfilled ou onRejected estiver undefined.

Parameters:
Name Type Argument Description
onFulfilled function

Função que receberá o valor do Promise quando ele for realizado.
onRejected function <nullable>

Função que receberá o valor do Promise quando ele for rejeitado.
Returns:
Type
Promise