O bloco Monitorar uma promessa fica aguardando (de forma assíncrona) algum processamento, normalmente demorado, e retorna o valor da promessa resolvida no parâmetro Sucesso ou rejeitada, no parâmetro Erro.

Após criar a promessa com o bloco Criar Promessa, o fluxo irá ocorrer e ao final, o bloco Atribuir valor para a promessa deve ser utilizado para informar ao bloco Monitorar uma promessa se foi resolvida ou rejeitada.

Figura 1 - Bloco Monitorar uma promessa

Compatibilidade

• Bloco cliente: cronapi.util.monitorPromise()

Retorno

Retorna o objeto da promessa na variável ("item") definida no retorno dos parâmetros das entradas de comando Sucesso, caso a promessa seja resolvida, e Erro, caso a promessa seja rejeitada.

Parâmetros

Promessa

Recebe o objeto da promessa criado a partir do bloco Criar Promessa.

• Posição: 1
• Inglês: Promise
• Tipo: objeto
• Exemplo: bloco Criar Promessa.

Sucesso

Executa uma ação caso a promessa seja resolvida.

• Posição: 2
• Inglês: Success
• Tipo: comando com retorno ("item") / Command with return ("item")
• Exemplo: informar o usuário que o processo foi finalizado com sucesso.

Erro

Executa uma ação caso a promessa seja rejeitada.

• Posição: 3
• Inglês: Error
• Tipo: comando com retorno ("item") / Command with return ("item")
• Exemplo: Informar o usuário que o processo foi rejeitado.

Exemplo 1

Na função da figura abaixo estamos criando e monitorando uma promessa até que uma requisição REST seja concluída. Caso a requisição REST (destaque 3 da figura 2) retorne os dados corretamente (status 200), a promessa será definida como "Resolvida", caso não retorne (status 404 ou 500), a promessa será definida como "Rejeitada".

Nesse exemplo, a requisição apenas retornará o texto "Retornei da requisição.". Incluímos alguns blocos de imprime para descrever melhor o fluxo.

Figura 2 - Utilizando o bloco Monitorar uma promessa para aguardar o retorno de uma requisição REST

1. A variável "promessa" é criada com o objeto da promessa. Nesse momento o objeto da promessa está com o status definido como "pending" (pendente).
2. O bloco Monitorar uma Promessa ficará "ouvindo" a promessa criada até que a promessa mude seu status de "pendente" para "resolve" ou "reject". O conteúdo da entrada de comando Sucesso será executado quando o status da promessa mudar para "resolve", caso mude para "reject", será executado a entrada de comando Erro. 
   A variável "item" do retorno das entradas de comandos Sucesso e Erro será alimentada pelo conteúdo informado no parâmetro Valor do bloco Atribuir valor para a promessa (passo 3).
3. É feito uma requisição REST e executará a entrada de comando com base no sucesso ou erro dessa requisição.
   1. Sucesso: imprime um texto informando o sucesso da requisição e o conteúdo obtido, em seguida, o bloco Atribuir valor para a promessa muda o status da promessa para "resolve" e informa o Valor da promessa com o retorno da requisição REST. 
   2. Erro: imprime um texto informando o erro da requisição e o que retornou, em seguida, o bloco Atribuir valor para a promessa muda o status da promessa para "reject" e informa o Valor da promessa com o retorno da requisição REST.
4. O bloco Imprime é utilizado apenas para informar que está fora do fluxo da promessa e, por se tratar de uma execução assíncrona, será executado primeiro.

Se tivermos sucesso na requisição do bloco Obter conteúdo da URL (destaque 2 da figura 2), o console do navegador exibirá o conteúdo da figura 2.1.

Figura 2.1 - Sucesso na requisição da função da figura 2

Se não tivermos sucesso na requisição do bloco Obter conteúdo da URL (destaque 2 da figura 2), o console do navegador exibirá o conteúdo da figura 2.2.

Figura 2.2 - Erro na requisição da função da figura 2

Exemplo 2

Um dos objetivos das promessas é realizar uma operação de forma assíncrona. Porém, os blocos clientes que chamam funções do Cronapp possuem uma característica que os torna síncronos. Em geral, isso não costuma ser um problema, mas caso a sua aplicação necessite realizar chamadas de funções assíncronas, mostraremos como fazer esse pequeno ajuste.

Nesse exemplo, foram criadas duas funções: uma que cria uma promessa, monitora seu progresso e chama outra função, e outra que executa o processamento, resolve ou rejeita a promessa e, ao final, retorna para o fluxo principal.

Incluímos também alguns blocos de imprime para descrever melhor o fluxo.

Figura 3 - Utilizando o bloco Monitorar uma promessa para aguardar chamada de função

1. A variável "promessa" é criada com o objeto da promessa. Nesse momento o objeto da promessa está com o status definido como "pending" (pendente).
2. O bloco Monitorar uma Promessa ficará "ouvindo" a promessa criada até que a promessa mude seu status de "pendente" para "resolve" ou "reject". O conteúdo da entrada de comando Sucesso será executado quando o status da promessa mudar para "resolve", caso mude para "reject", será executado a entrada de comando Erro.
3. Uma função responsável por executar algum processamento demorado é chamada, passamos por parâmetro o objeto da promessa.

Figura 3.1 - Atribuindo status da promessa em outra função

1. Utilizamos o bloco Dormir por 5 segundos para simular algum processamento, em seguida, utilizamos o bloco Inteiro aleatório para retornar o número "1" ou "2", simulando um resultado desse processamento.
2. O bloco Se faça verifica o resultado do processamento para resolver ou rejeitar a promessa.
   1. Caso o número aleatório seja definido como "1", o bloco Atribuir valor para a promessa irá resolver a promessa e informar no parâmetro Valor o próprio número aleatório.
   2. Caso o número aleatório seja definido como "2", o bloco Atribuir valor para a promessa irá rejeitar a promessa e informar no parâmetro Valor o próprio número aleatório.

Após a execução de algum bloco Atribuir valor para a promessa, a promessa já possui um status definido. A função secundária finaliza e retorna para a função principal e o bloco Monitorar uma Promessa realiza alguma ação com base no tipo da promessa.

Finalizado o fluxo, o resultado da promessa, quando resolvido, será igual ao apresentado na figura 3.2: A promessa começa a ser monitorada, o fluxo secundário (processamento) é chamado e o fluxo principal aguarda o fim do processamento para finalizar.

Figura 3.2 - Resultado ao executar função Monitorar Promessa

Perceba que o texto "Término" do fluxo principal só foi impresso após a finalização do fluxo secundário, isso ocorre, pois, ao chamar a função "Processamento" (destaque 3 da figura 3), um comando "await" (destaque 1 da figura 3.3) é incluído antes da chamada da função no JavaScript, forçando o fluxo a aguardar esse processamento. Isso ocorrerá ao utilizar funções do próprio arquivo blockly (Categoria Funções) ou ao utilizar os blocos de programação Chamar Bloco (Sem retorno) e Chamar Bloco (Com retorno).

Figura 3.3 - Removendo o comando await na chamada da função Processamento

Uma forma high-code de tratar isso é remover o "await" (destaque 1 da figura 3.3) antes da chamada da função. Ao executar novamente sem o "await", o fluxo principal continua em execução em paralelo ao fluxo da função "Processamento", veja na figura 3.4 que o "Término" é impresso durante a execução do processamento, não mais no final.

Figura 3.4 - Resultado ao executar função MonitorarPromessa sem o comando await na chamada da função Processamento

Saiba mais

Veja detalhes sobre o conceito de Promessas no JavaScript em Promise.