Module: UWA/Promise

UWA/Promise

A Promise wrapper with a similar API.

Example

// 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}

Returns a promise that resolves when the first promise in the iterable resolves.

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