Vow
Promises/A+ implementation.
See https://github.com/promises-aplus/promises-spec.
Getting Started
###In the Node.js###
You can install using Node Package Manager (npm):
npm install vow
###In the Browsers###
<script type="text/javascript" src="vow.min.js"></script>
Also RequireJS module format supported.
Vow has been tested in IE6+, Mozilla Firefox 3+, Chrome 5+, Safari 5+, Opera 10+.
API
####Vow.promise([value])####
Create a new promise if no value
given, or create 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(),
fulfilledPromise = Vow.promise('ok'),
anotherPromise = Vow.promise(existingPromise);
###Promise API###
####fulfill(value)####
Fulfill promise with given value
var promise = Vow.promise();
promise.fulfill('completed');
####reject(reason)####
Reject promise with given reason
var promise = Vow.promise();
promise.reject(Error('internal error'));
####isFulfilled()####
Returns whether the promise is fulfilled
var promise = Vow.promise();
promise.isFulfilled();
promise.fulfill('completed');
promise.isFulfilled();
####isRejected()####
Returns whether the promise is rejected
var promise = Vow.promise();
promise.isRejected();
promise.reject(Error('internal error'));
promise.isRejected();
####isResolved()####
Returns whether the promise is fulfilled or rejected
var promise = Vow.promise();
promise.isResolved();
promise.fulfill('completed');
promise.isResolved();
####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])####
Arranges for:
onFulfilled
to be called with the value after promise is fulfilled,onRejected
to be called with the rejection reason after promise is rejected.
Returns a new promise. See Promises/A+ specification for details.
var promise = Vow.promise();
promise.then(
function() { },
function() { });
####fail(onRejected)####
Arranges to call onRejected
on the promise's rejection reason if it is rejected. Shortcut for then(null, onRejected)
.
var promise = Vow.promise();
promise.fail(
function() {
});
promise.reject(Error('error'));
####always(onResolved)####
Arranges to call onResolved
on the promise if it is fulfilled or rejected.
var promise = Vow.promise();
promise.always(
function(promise) {
});
promise.fulfill('ok');
####spread([onFulfilled], [onRejected])####
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) {
});
promise1.fulfill(1);
promise2.fulfill('two');
####done()####
Terminate 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();
####timeout(timeout)####
Returns a new promise that to be rejected after a timeout
if promise does 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) {
});
promiseWithTimeout2.then(function(val) {
});
####sync(withPromise)####
Synchronize promise state with withPromise
state. Shortcut for:
withPromise.then(
function(val) {
promise.fulfill(val);
},
function(err) {
promise.reject(err);
});
###Vow API###
####isPromise(value)####
Returns whether the given value
is a promise.
Vow.isPromise('value');
Vow.isPromise(Vow.promise());
####when(value, [onFulfilled], [onRejected])####
Static equivalent for promise.then. If given value
is not a promise, value
is equivalent to fulfilled promise.
####fail(value, onRejected)####
Static equivalent for promise.fail. If given value
is not a promise, value
is equivalent to fulfilled promise.
####always(value, onResolved)####
Static equivalent for promise.always. If given value
is not a promise, value
is equivalent to fulfilled promise.
####spread(value, [onFulfilled], [onRejected])####
Static equivalent for promise.spread.
If given value
is not a promise, value
is equivalent to fulfilled promise.
####done(value)####
Static equivalent for promise.done.
If given value
is not a promise, value
is equivalent to fulfilled promise.
####isFulfilled(value)####
Static equivalent for promise.isFulfilled.
If given value
is not a promise, value
is equivalent to fulfilled promise.
####isRejected(value)####
Static equivalent for promise.isRejected.
If given value
is not a promise, value
is equivalent to fulfilled promise.
####isResolved(value)####
Static equivalent for promise.isResolved.
If given value
is not a promise, 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
.
####all(promisesOrValues)####
Returns a promise to be fulfilled only after all items in promisesOrValues
is fulfilled, or to be rejected when the any promise is rejected.
promisesOrValues
can be Array:
var promise1 = Vow.promise(),
promise2 = Vow.promise();
Vow.all([promise1, promise2, 3])
.then(function(value) {
});
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) {
});
promise1.fulfill(1);
promise2.fulfill(2);
####allResolved(promisesOrValues)####
Returns a promise to be fulfilled only after all items in promisesOrValues
is resolved.
var promise1 = Vow.promise(),
promise2 = Vow.promise();
Vow.allResolved([promise1, promise2])
.spread(function(promise1, promise2) {
promise1.valueOf();
promise2.valueOf();
});
promise1.reject('error');
promise2.fulfill('ok');
####any(promisesOrValues)####
Returns a promise to be fulfilled only any item in promisesOrValues
is fulfilled, or to be rejected when all items is rejected (with reason of first rejected item).
####timeout(promise, timeout)####
Static equivalent for promise.timeout. If given value
is not a promise, value
is equivalent to fulfilled promise.