mako-vow

Promises/A+ proposal compatible promises library, forked to include 'fulfill' and fix a context issue

npm install mako-vow
6 downloads in the last week
14 downloads in the last month

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

notify(value)

Notify promise for progress with given value

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], [onProgress])

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.
  • onProgress to be called with the value when promise is notified for progress.

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)

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'));

progress(onProgress)

Shortcut for then(null, null, onProgress).

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

delay(delay)

Returns a new promise that to be fulfilled after a delay milliseconds if promise is fulfilled, or immediately rejected if promise is rejected.

timeout(timeout)

Returns a new promise that to be rejected after a timeout milliseconds 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], [onProgress])

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.

progress(value, onProgress)

Static equivalent for promise.progress. 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.

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 returned value if value is a promise
  • will be rejected if function throw exception
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 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).

delay(value, delay)

Static equivalent for promise.delay. If given value is not a promise, value is equivalent to fulfilled promise.

timeout(value, timeout)

Static equivalent for promise.timeout. If given value is not a promise, value is equivalent to fulfilled promise.

npm loves you