Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
ES6-compatible and Promises/A+ implementation for Node.js and browsers
JavaScript Other

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
benchmarks
lib
test
.gitignore
.travis.yml
Makefile
README.md
package.json
vow.min.js

README.md

Vow Build Status

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(), // create a new promise
    fulfilledPromise = Vow.promise('ok'), // create a new fulfilled promise
    anotherPromise = Vow.promise(existingPromise); // anotherPromise is equal an existingPromise

Promise API

fulfill(value)

Fulfill promise with given value

var promise = Vow.promise();
promise.fulfill('completed'); // fulfill promise with 'completed' value

reject(reason)

Reject promise with given reason

var promise = Vow.promise();
promise.reject(Error('internal error')); // reject promise with Error object

isFulfilled()

Returns whether the promise is fulfilled

var promise = Vow.promise();
promise.isFulfilled(); // returns false
promise.fulfill('completed');
promise.isFulfilled(); // returns true

isRejected()

Returns whether the promise is rejected

var promise = Vow.promise();
promise.isRejected(); // returns false
promise.reject(Error('internal error'));
promise.isRejected(); // returns true

isResolved()

Returns whether 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])

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() { }, // to be called after promise is fulfilled
    function() { }); // to be called after promise is rejected

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() { // to be called after promise is rejected
    });
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) { // to be called after promise is fulfilled or rejected
    });
promise.fulfill('ok'); // or promise.reject(Error('error'));

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) {
    // arg1 should be "1", arg2 should be "'two'"
});

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(); // exception to be throwed

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) {
    // promiseWithTimeout to be rejected after 50ms
});

promiseWithTimeout2.then(function(val) {
    // promiseWithTimeout to be fulfilled with "'ok'" value
});

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'); // returns false
Vow.isPromise(Vow.promise()); // returns true

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) {
        // 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 items in promisesOrValues is 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 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.

Something went wrong with that request. Please try again.