fist.util.promise v0.0.2

fist.util.promise

JS Promises/A+ implementation

Instance API

• promise
• then
• resolve
• fulfill
• reject
• always
• done
• fail
• isFulfilled
• isPending
• isRejected
• isResolved

Static API

• allFulfilled
• allResolved
• create
• resolve
• fulfill
• reject
• when
• invoke

###Instance API###

####new Promise()#### Constructor, creates a new promise object

promise = new Promise();

####promise.then([onFulfilled], [onRejected])#### See https://github.com/promises-aplus/promises-spec#the-then-method

promise2 = promise1.then(onFulfilled, onRejected);

####promise.resolve([value])#### Resolves the promise according to promise resolution procedure

promise.resolve(42);

####promise.fulfill([result])#### Fulfills promise with result

promise.fulfill(42);

####promise.reject([reason])#### Rejects promise with reason

promise.reject( new Error("Awesome exception") );

####promise.always([onResolved])#### Calls reason when the promise will be resolved

promise.always(function (promise) {
    console.log( promise.isFulfilled() );
});

####promise.done([onFulfilled], [onRejected])#### Terminates promise chaining, if the last promise was rejected, an exception will be thrown

promise.then(function () {
    throw 42;
}).done();

####promise.fail([onRejected])#### Simple shortcut for promise.then(undefined, onRejected);

promise.fail(myFallback);

####promise.isFulfilled()#### Returns true if the promise is in fulfilled state

promise.fulfill();
promise.isFulfilled();  //  -> true

####promise.isPending()#### Returns true if promise is in pending state

promise = new Promise();
promise.isPending();  //  ->  true
promise.resolve()
promise.isPending();  //  -> false

####promise.isRejected()#### Returns true if the promise is in rejected state

promise.reject();
promise.isRejected(); //  -> true

####promise.isResolved()#### Returns true if the promise is in one of resolved or rejected states

promise = new Promise();

promise.isResolved(); //  -> false
promise.fulfill();
promise.isResolved(); //  -> true

promise = new Promise();
promise.reject();
promise.isResolved(); //  -> true

###Static API###

####Promise.allFulfilled(promises)#### Creates a new promise to be fulfilled when all given promises will be fulfilled. Promise will be rejected if any of given promises will be rejected

promise1 = new Promise();
promise1.fulfill(6);
promise2 = new Promise();

Promise.allFulfilled([5, promise1, promise2]).then(function (results) {
    console.log(results); // [5, 6, 7];
});

setTimeout(function () {
    promise2.fulfill(7);
}, 100);

####Promise.allResolved(promises)#### Creates a new promise to be resolved when all given promises will bew resolved

promise1 = new Promise();
promise1.reject(6);
promise2 = new Promise();

Promise.allResolved([5, promise1, promise2]).then(function (results) {
    console.log(results.map(function (promise) {
        return promise.valueOf();
    })); // [5, 6, 7];
});

setTimeout(function () {
    promise2.fulfill(7);
}, 100);

####Promise.create([result])#### Creates a new promise and resolves it, if given value is thenable

Promise.create(5);  // -> {Promise}

####Promise.resolve([value])#### Resolves value and returns a new promise

promise = Promise.resolve(42);

####Promise.fulfill([result])#### Fulfills a new promise with given result

Promise.fulfill(42);

####Promise.reject([reason])#### Creates a new promise and rejects it with given reason

Promise.reject(42);

####Promise.when([result], [onFulfilled], [onRejected])#### Creates a new promise to be resolved when result will be resolved according to promise resolution procedure. onFulfilled and onRejected callbacks can be passed.

Promise.when(42, function (result) {
    console.log(result); // -> 42
});

####Promise.invoke(fn)#### Calls the given function and resolves new promise with returned value

Promise.invoke(function (result) {
    return result;
}, null, 42).then(function (res) {
    console.log(res); // -> 42
})