Promises/A+ implementation. See https://github.com/promises-aplus/promises-spec.
###In Node.js### You can install using Node Package Manager (npm):
npm install vow
###In Browsers###
<script type="text/javascript" src="vow.min.js"></script>
It also supports RequireJS module format and YM module format.
Vow has been tested in IE6+, Mozilla Firefox 3+, Chrome 5+, Safari 5+, Opera 10+.
####Vow.promise([value])####
Creates a new promise if no value
given, or creates a new fulfilled promise if the value
is not a promise, or returns value
if the given value
is a promise.
var promise = Vow.promise(), // creating a new promise
fulfilledPromise = Vow.promise('ok'), // creating a new fulfilled promise
anotherPromise = Vow.promise(existingPromise); // anotherPromise is equal to the existingPromise
###Promise API###
####fulfill(value)####
Fulfills promise with given value
var promise = Vow.promise();
promise.fulfill('completed'); // fulfilling promise with 'completed' value
####reject(reason)####
Rejects promise with given reason
var promise = Vow.promise();
promise.reject(Error('internal error')); // rejecting promise with Error object
####notify(value)####
Notifies promise about progress with given value
var promise = Vow.promise();
promise.notify(20); // notifying promise with 20 value
####isFulfilled()#### Returns true if the promise is fulfilled
var promise = Vow.promise();
promise.isFulfilled(); // returns false
promise.fulfill('completed');
promise.isFulfilled(); // returns true
####isRejected()#### Returns true if the promise is rejected
var promise = Vow.promise();
promise.isRejected(); // returns false
promise.reject(Error('internal error'));
promise.isRejected(); // returns true
####isResolved()#### Returns true if the promise is fulfilled or rejected
var promise = Vow.promise();
promise.isResolved(); // returns false
promise.fulfill('completed'); // or promise.reject(Error('internal error'));
promise.isResolved(); // returns true
####valueOf()#### Returns value of the promise:
- value of fulfillment, if promise is fullfilled
- reason of rejection, if promise is rejected
- undefined, if promise is not resolved
####then([onFulfilled], [onRejected], [onProgress], [context])#### Are arranged for:
onFulfilled
to be called with the value after promise is fulfilled,onRejected
to be called with the rejection reason after promise is rejected.onProgress
to be called with the value when promise is notified about progress.context
context of callbacks
Returns a new promise. See Promises/A+ specification for details.
var promise = Vow.promise();
promise.then(
function() { }, // to be called after promise is fulfilled
function() { }, // to be called after promise is rejected
function() { } // to be called when promise is notified
);
####fail(onRejected, [context])####
Arranges to call onRejected
with given context
on the promise rejection reason if it is rejected. Shortcut for then(null, onRejected)
.
var promise = Vow.promise();
promise.fail(
function() { // to be called after promise is rejected
});
promise.reject(Error('error'));
####always(onResolved, [context])####
Arranges to call onResolved
with given context
on the promise if it is fulfilled or rejected.
var promise = Vow.promise();
promise.always(
function(promise) { // to be called after promise is fulfilled or rejected
});
promise.fulfill('ok'); // or promise.reject(Error('error'));
####progress(onProgress, [context])####
Arranges to call onProgress
with given context
on the promise if it is notified.
Shortcut for then(null, null, onProgress)
.
var promise = Vow.promise();
promise.notify(
function(val) { // to be called when promise is notified
console.log('performed ' + val + '% of the job'); // -> performed 20% of the job
});
promise.notify(20);
####spread([onFulfilled], [onRejected], [context])#### Like "then", but "spreads" the array into a variadic value handler. It useful with Vow.all, Vow.allResolved methods.
var promise1 = Vow.promise(),
promise2 = Vow.promise();
Vow.all([promise1, promise2]).spread(function(arg1, arg2) {
// arg1 should be "1", arg2 should be "'two'"
});
promise1.fulfill(1);
promise2.fulfill('two');
####done([onFulfilled], [onRejected], [onProgress], [context])#### Terminates a chain of promises. If the promise is rejected, throws it as an exception in a future turn of the event loop.
var promise = Vow.promise();
promise.reject(Error('Internal error'));
promise.done(); // exception to be thrown
####delay(delay)####
Returns a new promise that will be fulfilled in delay
milliseconds if the promise is fulfilled, or immediately rejected if promise is rejected.
####timeout(timeout)####
Returns a new promise that will be rejected in timeout
milliseconds if the promise is not resolved beforehand.
var promise = Vow.promise(),
promiseWithTimeout1 = promise.timeout(50),
promiseWithTimeout2 = promise.timeout(200);
setTimeout(
function() {
promise.fulfill('ok');
},
100);
promiseWithTimeout1.fail(function(e) {
// promiseWithTimeout to be rejected in 50ms
});
promiseWithTimeout2.then(function(val) {
// promiseWithTimeout to be fulfilled with "'ok'" value
});
####sync(withPromise)####
Synchronizes promise state with withPromise
state. Shortcut for:
withPromise.then(
function(val) {
promise.fulfill(val);
},
function(err) {
promise.reject(err);
});
###Vow API###
####isPromise(value)####
Returns true if the given value
is a promise.
Vow.isPromise('value'); // returns false
Vow.isPromise(Vow.promise()); // returns true
####when(value, [onFulfilled], [onRejected], [onProgress], [context])####
Static equivalent to promise.then. If given value
is not a promise, then value
is equivalent to fulfilled promise.
####fail(value, onRejected, [context])####
Static equivalent to promise.fail. If given value
is not a promise, then value
is equivalent to fulfilled promise.
####always(value, onResolved, [context])####
Static equivalent to promise.always. If given value
is not a promise, then value
is equivalent to fulfilled promise.
####progress(value, onProgress, [context])####
Static equivalent to promise.progress. If given value
is not a promise, then value
is equivalent to fulfilled promise.
####spread(value, [onFulfilled], [onRejected], [context])####
Static equivalent to promise.spread.
If given value
is not a promise, then value
is equivalent to fulfilled promise.
####done(value, [onFulfilled], [onRejected], [onProgress], [context]])####
Static equivalent to promise.done.
If given value
is not a promise, then value
is equivalent to fulfilled promise.
####isFulfilled(value)####
Static equivalent to promise.isFulfilled.
If given value
is not a promise, then value
is equivalent to fulfilled promise.
####isRejected(value)####
Static equivalent to promise.isRejected.
If given value
is not a promise, then value
is equivalent to fulfilled promise.
####isResolved(value)####
Static equivalent to promise.isResolved.
If given value
is not a promise, then value
is equivalent to fulfilled promise.
####fulfill(value)####
Returns a promise that has already been fulfilled with the given value
. If value
is a promise, returned promise will be fulfilled with fulfill/rejection value of given promise.
####reject(reason)####
Returns a promise that has already been rejected with the given reason
. If reason
is a promise, returned promise will be rejected with fulfill/rejection value of given promise.
####resolve(value)####
Returns a promise that has already been fulfilled with the given value
. If value
is a promise, returns promise
.
####invoke(fn, ...args)####
Invokes a given function fn
with arguments args
. Returned promise:
- will be fulfilled with returned value if value is not a promise
- will be rejected if function throw exception
- value will be returned if value is a promise
var promise1 = Vow.invoke(function(value) {
return value;
}, 'ok'),
promise2 = Vow.invoke(function() {
throw Error();
});
promise1.isFulfilled(); // true
promise1.valueOf(); // 'ok'
promise2.isRejected(); // true
promise2.valueOf(); // instance of Error
####all(promisesOrValues)####
Returns a promise to be fulfilled only after all the items in promisesOrValues
are fulfilled, or to be rejected when any of the promises is rejected.
promisesOrValues
can be Array:
var promise1 = Vow.promise(),
promise2 = Vow.promise();
Vow.all([promise1, promise2, 3])
.then(function(value) {
// value is [1, 2, 3]
});
promise1.fulfill(1);
promise2.fulfill(2);
or Object:
var promise1 = Vow.promise(),
promise2 = Vow.promise();
Vow.all({ a : promise1, b : promise2, c : 3 })
.then(function(value) {
// value is { a : 1, b : 2, c : 3 }
});
promise1.fulfill(1);
promise2.fulfill(2);
####allResolved(promisesOrValues)####
Returns a promise to be fulfilled only after all the items in promisesOrValues
are resolved.
var promise1 = Vow.promise(),
promise2 = Vow.promise();
Vow.allResolved([promise1, promise2])
.spread(function(promise1, promise2) {
promise1.valueOf(); // returns 'error'
promise2.valueOf(); // returns 'ok'
});
promise1.reject('error');
promise2.fulfill('ok');
####any(promisesOrValues)####
Returns a promise to be fulfilled only when any of the items in promisesOrValues
are fulfilled, or to be rejected when all the items are rejected (with the reason of the first rejected item).
####delay(value, delay)####
Static equivalent to promise.delay. If given value
is not a promise, then value
is equivalent to fulfilled promise.
####timeout(value, timeout)####
Static equivalent to promise.timeout. If given value
is not a promise, then value
is equivalent to fulfilled promise.