jio

A promise lib.

npm install jio
6 downloads in the last week
12 downloads in the last month

jio

Promises/A+ implementation. See https://github.com/promises-aplus/promises-spec.

Fork from Vow

Getting Started

You can install using Node Package Manager (npm):

npm install jio

API

jio.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 = jio.promise(), // creating a new promise
    fulfilledPromise = jio.promise('ok'), // creating a new fulfilled promise
    anotherPromise = jio.promise(existingPromise); // anotherPromise is equal to the existingPromise

Promise API

fulfill(value)

Fulfills promise with given value

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

reject(reason)

Rejects promise with given reason

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

notify(value)

Notifies promise about progress with given value

var promise = jio.promise();
promise.notify(20); // notifying promise with 20 value

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 = jio.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
    );

callback([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

NOT returns a new promise, just return current promise.

always(onResolved, [context])

Arranges to call onResolved with given context on the promise if it is fulfilled or rejected.

var promise = jio.promise();
promise.always(
    function(value) { // to be called after promise is fulfilled or rejected
    });
promise.fulfill('ok'); // or promise.reject(Error('error'));

alwaysCallback(onResolved, [context])

Arranges to call onResolved with given context on the promise if it is fulfilled or rejected.

var promise = jio.promise();
promise.alwaysCallback(
    function(value) { // to be called after promise is fulfilled or rejected
    });
promise.fulfill('ok'); // or promise.reject(Error('error'));

NOT returns a new promise, just return current promise.

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 = jio.promise();
promise.progress(
    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 jio.all, jio.allResolved methods.

var promise1 = jio.promise(),
    promise2 = jio.promise();

jio.all([promise1, promise2]).spread(function(arg1, arg2) {
    // arg1 should be "1", arg2 should be "'two'"
});

promise1.fulfill(1);
promise2.fulfill('two');

spreadCallback([onFulfilled], [onRejected], [context])

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

var promise1 = jio.promise(),
    promise2 = jio.promise();

jio.all([promise1, promise2]).spreadCallback(function(arg1, arg2) {
    // arg1 should be "1", arg2 should be "'two'"
});

promise1.fulfill(1);
promise2.fulfill('two');

NOT returns a new promise, just return current promise.

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 = jio.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);
    },
    function(val) {
        promise.notify(val);
    });

jio API

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.

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 = jio.promise(),
    promise2 = jio.promise();

jio.all([promise1, promise2, 3])
    .then(function(value) {
        // value is [1, 2, 3]
    });

promise1.fulfill(1);
promise2.fulfill(2);

or Object:

var promise1 = jio.promise(),
    promise2 = jio.promise();

jio.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 = jio.promise(),
    promise2 = jio.promise();

jio.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.

npm loves you