expand all / collapse all

vow

version
0.4.15
author
Filatov Dmitry dfilatov@yandex-team.ru
license
exports
Object {
Deferred
Class

The Deferred class is used to encapsulate newly-created promise object along with functions that resolve, reject or notify it.

constructor
Function ()

You can use vow.defer() instead of using this constructor.

new vow.Deferred() gives the same result as vow.defer().

instance methods
promise
Function () → vow:Promise

Returns the corresponding promise.

returns
vow:Promise
resolve
Function (value)

Resolves the corresponding promise with the given value.

arguments
value
*
example
var defer = vow.defer(),
    promise = defer.promise();

promise.then(function(value) {
    // value is "'success'" here
});

defer.resolve('success');
reject
Function (reason)

Rejects the corresponding promise with the given reason.

arguments
reason
*
example
var defer = vow.defer(),
    promise = defer.promise();

promise.fail(function(reason) {
    // reason is "'something is wrong'" here
});

defer.reject('something is wrong');
notify
Function (value)

Notifies the corresponding promise with the given value.

arguments
value
*
example
var defer = vow.defer(),
    promise = defer.promise();

promise.progress(function(value) {
    // value is "'20%'", "'40%'" here
});

defer.notify('20%');
defer.notify('40%');
Promise
Class

The Promise class is used when you want to give to the caller something to subscribe to, but not the ability to resolve or reject the deferred.

constructor
Function (resolver)

You should use this constructor directly only if you are going to use vow as DOM Promises implementation. In other case you should use vow.defer() and defer.promise() methods.

example
function fetchJSON(url) {
    return new vow.Promise(function(resolve, reject, notify) {
        var xhr = new XMLHttpRequest();
        xhr.open('GET', url);
        xhr.responseType = 'json';
        xhr.send();
        xhr.onload = function() {
            if(xhr.response) {
                resolve(xhr.response);
            }
            else {
                reject(new TypeError());
            }
        };
    });
}
instance methods
valueOf
Function () → *

Returns the value of the fulfilled promise or the reason in case of rejection.

returns
*
isResolved
Function () → Boolean

Returns true if the promise is resolved.

returns
Boolean
isFulfilled
Function () → Boolean

Returns true if the promise is fulfilled.

returns
Boolean
isRejected
Function () → Boolean

Returns true if the promise is rejected.

returns
Boolean
then
Function (onFulfilled, onRejected, onProgress, ctx) → vow:Promise

Adds reactions to the promise.

arguments
onFulfilledoptional
Function

Callback that will be invoked with a provided value after the promise has been fulfilled

onRejectedoptional
Function

Callback that will be invoked with a provided reason after the promise has been rejected

onProgressoptional
Function

Callback that will be invoked with a provided value after the promise has been notified

ctxoptional
Object

Context of the callbacks execution

returns
vow:Promise

A new promise, see https://github.com/promises-aplus/promises-spec for details

catch
Function (onRejected, ctx) → vow:Promise

Adds only a rejection reaction. This method is a shorthand for promise.then(undefined, onRejected).

arguments
onRejected
Function

Callback that will be called with a provided 'reason' as argument after the promise has been rejected

ctxoptional
Object

Context of the callback execution

returns
vow:Promise
fail
Function (onRejected, ctx) → vow:Promise

Adds only a rejection reaction. This method is a shorthand for promise.then(null, onRejected). It's also an alias for catch.

arguments
onRejected
Function

Callback to be called with the value after promise has been rejected

ctxoptional
Object

Context of the callback execution

returns
vow:Promise
always
Function (onResolved, ctx) → vow:Promise

Adds a resolving reaction (for both fulfillment and rejection).

arguments
onResolved
Function

Callback that will be invoked with the promise as an argument, after the promise has been resolved.

ctxoptional
Object

Context of the callback execution

returns
vow:Promise
progress
Function (onProgress, ctx) → vow:Promise

Adds a progress reaction.

arguments
onProgress
Function

Callback that will be called with a provided value when the promise has been notified

ctxoptional
Object

Context of the callback execution

returns
vow:Promise
spread
Function (onFulfilled, onRejected, ctx) → vow:Promise

Like promise.then, but "spreads" the array into a variadic value handler. It is useful with the vow.all and the vow.allResolved methods.

arguments
onFulfilledoptional
Function

Callback that will be invoked with a provided value after the promise has been fulfilled

onRejectedoptional
Function

Callback that will be invoked with a provided reason after the promise has been rejected

ctxoptional
Object

Context of the callbacks execution

returns
vow:Promise
example
var defer1 = vow.defer(),
    defer2 = vow.defer();

vow.all([defer1.promise(), defer2.promise()]).spread(function(arg1, arg2) {
    // arg1 is "1", arg2 is "'two'" here
});

defer1.resolve(1);
defer2.resolve('two');
done
Function (onFulfilled, onRejected, onProgress, ctx)

Like then, but terminates a chain of promises. If the promise has been rejected, this method throws it's "reason" as an exception in a future turn of the event loop.

arguments
onFulfilledoptional
Function

Callback that will be invoked with a provided value after the promise has been fulfilled

onRejectedoptional
Function

Callback that will be invoked with a provided reason after the promise has been rejected

onProgressoptional
Function

Callback that will be invoked with a provided value after the promise has been notified

ctxoptional
Object

Context of the callbacks execution

example
var defer = vow.defer();
defer.reject(Error('Internal error'));
defer.promise().done(); // exception to be thrown
delay
Function (delay) → vow:Promise

Returns a new promise that will be fulfilled in delay milliseconds if the promise is fulfilled, or immediately rejected if the promise is rejected.

arguments
delay
Number
returns
vow:Promise
timeout
Function (timeout) → vow:Promise

Returns a new promise that will be rejected in timeout milliseconds if the promise is not resolved beforehand.

arguments
timeout
Number
returns
vow:Promise
example
var defer = vow.defer(),
    promiseWithTimeout1 = defer.promise().timeout(50),
    promiseWithTimeout2 = defer.promise().timeout(200);

setTimeout(
    function() {
        defer.resolve('ok');
    },
    100);

promiseWithTimeout1.fail(function(reason) {
    // promiseWithTimeout to be rejected in 50ms
});

promiseWithTimeout2.then(function(value) {
    // promiseWithTimeout to be fulfilled with "'ok'" value
});
class methods
cast
Function (value) → vow:Promise

Coerces the given value to a promise, or returns the value if it's already a promise.

arguments
value
*
returns
vow:Promise
all
Function (iterable) → vow:Promise

Returns a promise, that will be fulfilled only after all the items in iterable are fulfilled. If any of the iterable items gets rejected, then the returned promise will be rejected.

arguments
iterable
Array | Object
returns
vow:Promise
race
Function (iterable) → vow:Promise

Returns a promise, that will be fulfilled only when any of the items in iterable are fulfilled. If any of the iterable items gets rejected, then the returned promise will be rejected.

arguments
iterable
Array
returns
vow:Promise
resolve
Function (value) → vow:Promise

Returns a promise that has already been resolved with the given value. If value is a promise, the returned promise will have value's state.

arguments
value
*
returns
vow:Promise
reject
Function (reason) → vow:Promise

Returns a promise that has already been rejected with the given reason.

arguments
reason
*
returns
vow:Promise
defer
Function () → vow:Deferred

Creates a new deferred. This method is a factory method for vow:Deferred class. It's equivalent to new vow.Deferred().

returns
vow:Deferred
when
Function (value, onFulfilled, onRejected, onProgress, ctx) → vow:Promise

Static equivalent to promise.then. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
onFulfilledoptional
Function

Callback that will be invoked with a provided value after the promise has been fulfilled

onRejectedoptional
Function

Callback that will be invoked with a provided reason after the promise has been rejected

onProgressoptional
Function

Callback that will be invoked with a provided value after the promise has been notified

ctxoptional
Object

Context of the callbacks execution

returns
vow:Promise
fail
Function (value, onRejected, ctx) → vow:Promise

Static equivalent to promise.fail. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
onRejected
Function

Callback that will be invoked with a provided reason after the promise has been rejected

ctxoptional
Object

Context of the callback execution

returns
vow:Promise
always
Function (value, onResolved, ctx) → vow:Promise

Static equivalent to promise.always. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
onResolved
Function

Callback that will be invoked with the promise as an argument, after the promise has been resolved.

ctxoptional
Object

Context of the callback execution

returns
vow:Promise
progress
Function (value, onProgress, ctx) → vow:Promise

Static equivalent to promise.progress. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
onProgress
Function

Callback that will be invoked with a provided value after the promise has been notified

ctxoptional
Object

Context of the callback execution

returns
vow:Promise
spread
Function (value, onFulfilled, onRejected, ctx) → vow:Promise

Static equivalent to promise.spread. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
onFulfilledoptional
Function

Callback that will be invoked with a provided value after the promise has been fulfilled

onRejectedoptional
Function

Callback that will be invoked with a provided reason after the promise has been rejected

ctxoptional
Object

Context of the callbacks execution

returns
vow:Promise
done
Function (value, onFulfilled, onRejected, onProgress, ctx)

Static equivalent to promise.done. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
onFulfilledoptional
Function

Callback that will be invoked with a provided value after the promise has been fulfilled

onRejectedoptional
Function

Callback that will be invoked with a provided reason after the promise has been rejected

onProgressoptional
Function

Callback that will be invoked with a provided value after the promise has been notified

ctxoptional
Object

Context of the callbacks execution

isPromise
Function (value) → Boolean

Checks whether the given value is a promise-like object

arguments
value
*
returns
Boolean
example
vow.isPromise('something'); // returns false
vow.isPromise(vow.defer().promise()); // returns true
vow.isPromise({ then : function() { }); // returns true
cast
Function (value) → vow:Promise

Coerces the given value to a promise, or returns the value if it's already a promise.

arguments
value
*
returns
vow:Promise
valueOf
Function (value) → *

Static equivalent to promise.valueOf. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
returns
*
isFulfilled
Function (value) → Boolean

Static equivalent to promise.isFulfilled. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
returns
Boolean
isRejected
Function (value) → Boolean

Static equivalent to promise.isRejected. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
returns
Boolean
isResolved
Function (value) → Boolean

Static equivalent to promise.isResolved. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
returns
Boolean
resolve
Function (value) → vow:Promise

Returns a promise that has already been resolved with the given value. If value is a promise, the returned promise will have value's state.

arguments
value
*
returns
vow:Promise
fulfill
Function (value) → vow:Promise

Returns a promise that has already been fulfilled with the given value. If value is a promise, the returned promise will be fulfilled with the fulfill/rejection value of value.

arguments
value
*
returns
vow:Promise
reject
Function (reason) → vow:Promise

Returns a promise that has already been rejected with the given reason. If reason is a promise, the returned promise will be rejected with the fulfill/rejection value of reason.

arguments
reason
*
returns
vow:Promise
invoke
Function (fn, args) → vow:Promise

Invokes the given function fn with arguments args

arguments
fn
Function
argsoptional
...*
returns
vow:Promise
example
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
Function (iterable) → vow:Promise

Returns a promise, that will be fulfilled only after all the items in iterable are fulfilled. If any of the iterable items gets rejected, the promise will be rejected.

arguments
iterable
Array | Object
returns
vow:Promise
examples

with array:

var defer1 = vow.defer(),
    defer2 = vow.defer();

vow.all([defer1.promise(), defer2.promise(), 3])
    .then(function(value) {
         // value is "[1, 2, 3]" here
    });

defer1.resolve(1);
defer2.resolve(2);

with object:

var defer1 = vow.defer(),
    defer2 = vow.defer();

vow.all({ p1 : defer1.promise(), p2 : defer2.promise(), p3 : 3 })
    .then(function(value) {
         // value is "{ p1 : 1, p2 : 2, p3 : 3 }" here
    });

defer1.resolve(1);
defer2.resolve(2);
allResolved
Function (iterable) → vow:Promise

Returns a promise, that will be fulfilled only after all the items in iterable are resolved.

arguments
iterable
Array | Object
returns
vow:Promise
example
var defer1 = vow.defer(),
    defer2 = vow.defer();

vow.allResolved([defer1.promise(), defer2.promise()]).spread(function(promise1, promise2) {
    promise1.isRejected(); // returns true
    promise1.valueOf(); // returns "'error'"
    promise2.isFulfilled(); // returns true
    promise2.valueOf(); // returns "'ok'"
});

defer1.reject('error');
defer2.resolve('ok');
any
Function (iterable) → vow:Promise

Returns a promise, that will be fulfilled if any of the items in iterable is fulfilled. If all of the iterable items get rejected, the promise will be rejected (with the reason of the first rejected item).

arguments
iterable
Array
returns
vow:Promise
anyResolved
Function (iterable) → vow:Promise

Returns a promise, that will be fulfilled only when any of the items in iterable is fulfilled. If any of the iterable items gets rejected, the promise will be rejected.

arguments
iterable
Array
returns
vow:Promise
delay
Function (value, delay) → vow:Promise

Static equivalent to promise.delay. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
delay
Number
returns
vow:Promise
timeout
Function (value, timeout) → vow:Promise

Static equivalent to promise.timeout. If value is not a promise, then value is treated as a fulfilled promise.

arguments
value
*
timeout
Number
returns
vow:Promise
}