Implementation of Promises/A+ specification

Implementation of Promises/A+ specification

The promise() function

The promise() function returns callable object(function) that has method .then(onFulfilled, onRejected)

The promise is created either as (case #1):

var prom = promise();

or as (case #2)

var prom = promise( function( resolve:function, reject:function ) {...} );

To fulfill/resolve the promise in case #1

call it as prom(true, params). Where the params is an array of values that will be applied to onFulfilled callback functions registered by .then() method.

To reject the promise in case #1

call it as prom(false, params). Where the params is an array of values that will be applied to onRejected callbacks registered by .then() method.

To resolve or reject the promise in case #2

Simply call resolve(result) or reject(error) callback functions from your function body.

Promise methods

The promise() function returns function-object that has the following methods by itself:

promise.then
(onFulfilled : function(data) [, onRejected: function(err) ] ) : promise

Appends fulfillment and rejection handlers/callbacks to the promise, and returns a new promise. Either one of these handlers will be invoked on promise completion.

promise.catch
(onError: function(err) ) : promise

Appends rejection handler to the promise, and returns a new promise.

promise.finally
(onResolved: function(dataOrErr) ) : promise

Appends "resolved" handler to the promise, and returns a new promise. This handler will be called on completion of  the promise, either successfully or with error.

promise.when
( promise1, promise2, promise3, … ) : promise

Static method, returns new promise that will be fulfilled when all arguments(promises) will be fullfiled. If either one of promises is rejected it will rejected too.

Redefined View/Element.request() functions

The promise.tis also redefines the Element.request() method – http get/post/put/delete call. So with this module included the Element.request() can be called in one of three forms:

  1. element.request( callback: function, httpcmd , url: string [, params: object [, headers: object] ] ) : true | false
    – asynchronous request with server response delivered to callback function.
  2. element.request( timeout: integer, httpcmd , url: string [, params: object [, headers: object] ] ) : (data, status)
    – synchronous request with server response delivered as first return value and http status code as second.
  3. element.request( httpcmd , url: string [, params: object [, headers: object] ] ) : promise,
    – asynchronous request, server response is delivered to the onsuccess callback registered by .then(onsuccess,onfailure) call of the promise.
  4. view.request( params: map  ) : promise,
    – asynchronous request, server response is delivered to the onsuccess callback registered by .then(onsuccess,onfailure) call of the promise.

promise() and await

await operator allows to awoid using callbacks with promises and write asynchronous logic in linear fashion:

function getRemoteTexts(url)
{
  try {
    var text = await view.request { url: url, output: #string };
    stdout.println("complete:", text);
  } catch(e) {
    stdout.println("got error:", e);
  }
}
// starting the task:
getRemoteTexts("http://sciter.com/test/text.txt");
stdout.println("task started");

When you will run this code snippet in Sciter you will see following output in console:

> task started
> complete: {content of test/text.txt file }

"> task started" will appear first as any function that contains await inside gets automatically converted to Task function.  

Invocation of Task function competes immediately and body of the function gets queued for future execution.

When execution hits await statement the task gets postponed until view.request completion (promise resolving).

In other words: await is the way of waiting for promise to be resolved.