Module: UWA/Promise

// 1. Simple usage example
var promise = new UWA.Promise(function(resolve, reject) {
    // do a thing, possibly async, then...

    if (isValid()) { // everything turned out fine
        resolve("Stuff worked!");
    } else {
        reject(Error("It broke"));
    }
});

promise.then(function(result) {
    console.log(result); // "Stuff worked!"
}, function(err) {
    console.log(err); // Error: "It broke"
});

// 2. Concrete usage example using UWA.Data.request
function getUrl(url) {

    // Return a new promise.
    return new UWA.Promise(function(resolve, reject) {

        UWA.Data.request(url, {
            onComplete: resolve,
            onFailure: reject,
            onTimeout: reject
        });
    });
}

getUrl('http://example.com').then(
    function success() {
        console.log('getUrl success', arguments);
    },
    function fail() {
        console.log('getUrl fail', arguments);
    }
);

Index

Methods

<static> UWA.Promise#catch(onRejected) → {UWA.Promise}

Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.

Parameters

Name	Type	Description
onRejected	Function	-

Returns

a new wrapped promise

Type

UWA.Promise

<static> UWA.Promise#then(onFullfilled, onRejected) → {UWA.Promise}

Appends fullfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler.

Parameters

Name	Type	Description
onFullfilled	Function	Callback to execute when the promise is fullfilled
onRejected	Function	Callback to execute when the promise is rejected

Returns

a new wrapped promise

Type

UWA.Promise

<static> UWA.Promise#fail()

Alias of catch

Use this if you support ES3 browsers

<static> UWA.Promise#finally(onFullfilledOrRejected) → {UWA.Promise}

The passed callback will always be called (without argument), wether the promise resolves or not.

Parameters

Name	Type	Description
onFullfilledOrRejected	Function	function to execute

Returns

a new wrapped promise

Type

UWA.Promise

<static> UWA.Promise#fin()

Alias of finally

Use this if you support ES3 browsers

<static> UWA.Promise#done(onFullfilled, onRejected) → {UWA.Promise}

Like then, but will raise any unhandled error/rejection

This method is not in the ES6 Promise standard.

Parameters

Name	Type	Description
onFullfilled	Function	function to execute when the promise is resolved
onRejected	Function	function to execute when the promise is rejected

Returns

a new wrapped promise

Type

UWA.Promise

<static> UWA.Promise#spread(onFullfilled, onRejected) → {UWA.Promise}

Like then, but if the result is an array, it will be spread as arguments to the success callback

Parameters

Name	Type	Description
onFullfilled	Function
onRejected	Function

Returns

to continue the promise chain

Type

UWA.Promise

<static> UWA.Promise.race(iterable) → {UWA.Promise}

Make a Promise that fulfills as soon as any item fulfills, or rejects as soon as any item rejects, whichever happens first.

Example

var p1 = new UWA.Promise(function(resolve, reject) {
    setTimeout(resolve, 500, "one");
});

var p2 = new UWA.Promise(function(resolve, reject) {
    setTimeout(resolve, 100, "two");
});

UWA.Promise.race([p1, p2]).then(function(value) {
  // value == "two"
});

Parameters

Name	Type	Description
iterable	Object

Returns

a new wrapped promise

Type

UWA.Promise

<static> UWA.Promise.all(iterable) → {UWA.Promise}

Returns a promise that resolves when all of the promises in iterable have resolved. The result is passed an array of values from all the promises. If something passed in the iterable array is not a promise, it's converted to one by Promise.cast. If any of the passed in promises rejects, the all Promise should also reject (and receives the value of the promise that rejected.

Example

var p = new UWA.Promise(function(resolve, reject) {
    resolve(3);
});

UWA.Promise.all([true, p]).then(function(values) {
  // values == [ true, 3 ]
});

Parameters

Name	Type	Description
iterable	Object	-

Returns

Type

UWA.Promise

<static> UWA.Promise.reject(reason) → {UWA.Promise}

Returns a Promise object that is rejected with the given reason.

Parameters

Name	Type	Description
reason	Object	-

Returns

Type

UWA.Promise

<static> UWA.Promise.resolve(value) → {UWA.Promise}

Returns a Promise object that is resolved with the given value. If the value is a thenable (i.e. has a then method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value.

Parameters

Name	Type	Description
value	Object	-

Returns

Type

UWA.Promise

<static> UWA.Promise.cast(value) → {UWA.Promise}

Casts a value to a UWA.Promise. If it's already an UWA.Promise, it will return the argument as it is. If it's a native, unwrapped promise, it will wrap it in an UWA.Promise. If it is another value, it will return a resolved UWA.Promise with this value.

Example

UWA.Promise.cast(3).then(function(result) {
    // result == 3;
});

UWA.Promise.cast(someForeignPromise).finally(function () {
    // ...
});

Parameters

Name	Type	Description
value	Void	-

Returns

Type

UWA.Promise

<static> UWA.Promise.deferred() → {Object}

Return an object with a property "promise" initialized with a UWA.Promise, and two properties "resolve" and "reject" initialized with two functions that repectively resolve and reject the promise.

Example

// deferred allow you to handle the resolve and reject outsise of the
// resolver function to create more complexe Promise behavior.
function getUrl(url) {

    // Return a new promise.
    var dfd = UWA.Promise.deferred(),
        data = UWA.Data.request(url, {
            onComplete: dfd.resolve,
            onFailure: dfd.reject,
            onTimeout: dfd.reject
        });

    return dfd.promise;
}

getUrl('http://example.com').then(
    function success() {
        console.log('getUrl success', arguments);
    },
    function fail() {
        console.log('getUrl fail', arguments);
    }
);

Returns

Type

Object

<static> UWA.Promise.allSettled(promises) → {UWA.Promise}

Returns a promise always resolved when all given promises are settled (resolved or rejected). The result is an array of objects either { state: "fulfilled", value: v } or { state: "rejected", reason: r }

This method is not in the ES6 Promise standard.

Parameters

Name	Type	Description
promises	Array	a list of promises (like Promise.all, values will be cast to Promise)

Returns

a new always resolved wrapped promise with a list containing the state of all given promises

Type

UWA.Promise