Promise Class
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
- chainFns static
- finally
- finishAll static
- manage static
- thenFulfill
Methods
chainFns
-
funcs -
[finishAll=false]
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:
-
funcsFunction[]an array of function-references
-
[finishAll=false]Boolean optionalto force the chain to continue, even if one of the functions returns a rejected Promise
Returns:
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 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:
-
finallybackFunctionthe callbackfunctio to be invoked.
Returns:
finishAll
-
items
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:
-
itemsAnyan array of any kind of items, promises or not. If a value is not a promise, its transformed into a resolved promise.
Returns:
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
- fulfilled {Array} all fulfilled responses, any item that was rejected will have a value of
- Rejected: this promise never rejects
manage
-
[callbackFn] -
[stayActive=false]
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:
Returns:
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]
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 optionalparameter to pass through which overrules the original Promise-response.
Returns:
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