API Docs for: 0.0.1
Show:

Promise Class

Module: lib/promise.s
Parent Module: js-ext

Provides additional Promise-methods. These are extra methods which are not part of the PromiseA+ specification, But are all Promise/A+ compatable.

Copyright (c) 2014 ITSA - https://github.com/itsa New BSD License - http://choosealicense.com/licenses/bsd-3-clause/

Item Index

Methods

Methods

chainFns

(
  • funcs
  • [finishAll=false]
)
Promise static

Returns a Promise which chains the function-calls. Like an automated Promise-chain. Invokes the functionreferences in a chain. You MUST supply function-references, it doesn't matter wheter these functions return a Promise or not. Any returnvalues are passed through to the next function.

Cautious: you need to pass function-references, not invoke them! chainFns will invoke them when the time is ready. Regarding to this, there is a difference with using Promise.all() where you should pass invoked Promises.

If one of the functions returns a Promise, the chain will wait its execution for this function to be resolved.

If you need specific context or arguments: use Function.bind for these items. If one of the items returns a rejected Promise, by default: the whole chain rejects and following functions in the chain will not be invoked. When finishAll is set true the chain will always continue even with rejected Promises.

Returning functionvalues are passed through the chain adding them as an extra argument to the next function in the chain (argument is added on the right)

Parameters:

  • funcs Function[]

    an array of function-references

  • [finishAll=false] Boolean optional

    to force the chain to continue, even if one of the functions returns a rejected Promise

Returns:

Promise:

on success: o {Object} returnvalue of the laste item in the Promisechain on failure an Error object reason {Error}

Example:

var a = [], p1, p2, p3;
p1 = function(a) {
    return new Promise(function(resolve, reject) {
        I.later(function() {
            console.log('resolving promise p1: '+a);
            resolve(a);
        }, 1000);
    });
};
p2 = function(b, r) {
    var value = b+r;
    console.log('returning p2: '+value);
    return value;
};
p3 = function(c, r) {
    return new Promise(function(resolve, reject) {
        I.later(function() {
            var value = b+r;
            console.log('resolving promise p3: '+value);
            resolve(value);
        }, 1000);
    });
};
a.push(p1.bind(undefined, 100));
a.push(p2.bind(undefined, 200));
a.push(p3.bind(undefined, 300));
Promise.chainFns(a).then(
    function(r) {
        console.log('chain resolved with '+r);
    },
    function(err) {
        console.log('chain-error '+err);
    }
);

finally

(
  • finallyback
)
Promise

Promise which can be put at the very end of a chain, even after .catch(). Will invoke the callback function regardless whether the chain resolves or rejects.

The argument of the callback will be either its fulfilled or rejected argument, but it is wisely not to handle it. The results should have been handled in an earlier step of the chain: .finally() basicly means you want to execute code after the chain, regardless whether it's resolved or rejected.

Note: .finally() does not return a Promise: it should be used as the very last step of a Promisechain. If you need an intermediate method, you should take .thenFulfill().

Parameters:

  • finallyback Function

    the callbackfunctio to be invoked.

Returns:

finishAll

(
  • items
)
Promise static

Returns a Promise that always fulfills. It is fulfilled when ALL items are resolved (either fulfilled or rejected). This is useful for waiting for the resolution of multiple promises, such as reading multiple files in Node.js or making multiple XHR requests in the browser. Because -on the contrary of Promise.all- finishAll waits until all single Promises are resolved, you can handle all promises, even if some gets rejected.

Parameters:

  • items Any

    an array of any kind of items, promises or not. If a value is not a promise, its transformed into a resolved promise.

Returns:

Promise:

A promise for an array of all the fulfillment items:

  • Fulfilled: o {Object}
    • fulfilled {Array} all fulfilled responses, any item that was rejected will have a value of undefined
    • rejected {Array} all rejected responses, any item that was fulfilled will have a value of undefined
  • Rejected: this promise never rejects

manage

(
  • [callbackFn]
  • [stayActive=false]
)
Promise static

Returns a Promise with 5 additional methods:

promise.fulfill promise.reject promise.callback promise.setCallback promise.pending promise.stayActive --> force the promise not to resolve in the specified time

With Promise.manage, you get a Promise which is managable from outside, not inside as Promise A+ work. You can invoke promise.callback() which will invoke the original passed-in callbackFn - if any. promise.fulfill() and promise.reject() are meant to resolve the promise from outside, just like deferred can do.

If stayActive is defined, the promise will only be resolved after this specified time (ms). When fulfill or reject is called, it will be applied after this specified time.

Parameters:

  • [callbackFn] Function optional

    invoked everytime promiseinstance.callback() is called. You may as weel (re)set this method atny time lare by using promise.setCallback()

  • [stayActive=false] Boolean optional

    specified time to wait before the promise really gets resolved

Returns:

Promise:

with three handles: fulfill, reject and callback.

Example:

var promise = Promise.manage(
    function(msg) {
        alert(msg);
    }
);

promise.then(
    function() {
        // promise is fulfilled, no further actions can be taken
    }
);

setTimeout(function() {
    promise.callback('hey, I\'m still busy');
}, 1000);

setTimeout(function() {
    promise.fulfill();
}, 2000);

thenFulfill

(
  • [response]
)
Promise

Will always return a fulfilled Promise.

Typical usage will be by making it part of a Promisechain: it makes the chain go into its fulfilled phase.

Parameters:

  • [response] Object optional

    parameter to pass through which overrules the original Promise-response.

Returns:

Promise:

Resolved Promise. response will be passed trough as parameter when set. When not set: in case the original Promise resolved, its parameter is passed through. in case of a rejection, no parameter will be passed through.

Example:

promise1 .then(promise2) .thenFulfill() .then(handleFulfilled, handleRejected) // handleFulfilled always gets invoked