jspromise

Promises/A+ implementation

npm install jspromise
38 downloads in the last week
38 downloads in the last month
JSPromise [![Build Status](https://travis-ci.org/golyshevd/JSPromise.png?branch=v2.0.x)](https://travis-ci.org/golyshevd/JSPromise)
=========

[JS Promises/A+](https://github.com/promises-aplus/promises-spec) implementation

[Instance API](#instance-api-1)
---------
  * [promise](#new-jspromise)
  * [then](#promisethenonfulfilled-onrejected)
  * [resolve](#promiseresolvevalue)
  * [fulfill](#promisefulfillresult)
  * [reject](#promiserejectreason)
  * [always](#promisealwaysonresolved)
  * [done](#promisedoneonfulfilled-onrejected)
  * [fail](#promisefailonrejected)
  * [isFulfilled](#promiseisfulfilled)
  * [isPending](#promiseispending)
  * [isRejected](#promiseisrejected)
  * [isResolved](#promiseisresolved)

[Static API](#static-api-1)
---------
  * [allFulfilled](#jspromiseallfulfilledpromises)
  * [allResolved](#jspromiseallresolvedpromises)
  * [create](#jspromisecreateresult)
  * [resolve](#jspromiseresolvevalue)
  * [fulfill](#jspromisefulfillresult)
  * [reject](#jspromiserejectreason)
  * [when](#jspromisewhenresult-onfulfilled-onrejected)
  * [invoke](#jspromiseinvokefn)

###Instance API###

####```new JSPromise()```####
Constructor, creates a new promise object
```js
promise = new JSPromise();
```

####```promise.then([onFulfilled], [onRejected])```####
See [https://github.com/promises-aplus/promises-spec#the-then-method](https://github.com/promises-aplus/promises-spec#the-then-method)
```js
promise2 = promise1.then(onFulfilled, onRejected);
```

####```promise.resolve([value])```####
Resolves the promise according to [promise resolution procedure](https://github.com/promises-aplus/promises-spec#the-promise-resolution-procedure)
```js
promise.resolve(42);
```

####```promise.fulfill([result])```####
Fulfills promise with ```result```
```js
promise.fulfill(42);
```

####```promise.reject([reason])```####
Rejects promise with ```reason```
```js
promise.reject( new Error("Awesome exception") );
```

####```promise.always([onResolved])```####
Calls ```reason``` when the promise will be resolved
```js
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
```js
promise.then(function () {
    throw 42;
}).done();
```

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

####```promise.isFulfilled()```####
Returns ```true``` if the promise is in fulfilled state
```js
promise.fulfill();
promise.isFulfilled();  //  -> true
```

####```promise.isPending()```####
Returns ```true``` if promise is in pending state
```js
promise = new JSPromise();
promise.isPending();  //  ->  true
promise.resolve()
promise.isPending();  //  -> false
```

####```promise.isRejected()```####
Returns ```true``` if the promise is in rejected state
```js
promise.reject();
promise.isRejected(); //  -> true
```

####```promise.isResolved()```####
Returns ```true``` if the promise is in one of resolved or rejected states
```js
promise = new JSPromise();

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

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

###Static API###

####```JSPromise.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
```js
promise1 = new JSPromise();
promise1.fulfill(6);
promise2 = new JSPromise();

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

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

####```JSPromise.allResolved(promises)```####
Creates a new promise to be resolved when all given promises will bew resolved
```js
promise1 = new JSPromise();
promise1.reject(6);
promise2 = new JSPromise();

JSPromise.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);
```

####```JSPromise.create([result])```####
Creates a new promise and resolves it, if given value is thenable
```js
JSPromise.create(5);  // -> {JSPromise}
```

####```JSPromise.resolve([value])```####
Resolves value and returns a new promise
```js
promise = JSPromise.resolve(42);
```

####```JSPromise.fulfill([result])```####
Fulfills a new promise with given result
```js
JSPromise.fulfill(42);
```

####```JSPromise.reject([reason])```####
Creates a new promise and rejects it with given reason
```js
JSPromise.reject(42);
```

####```JSPromise.when([result], [onFulfilled], [onRejected])```####
Creates a new promise to be resolved when ```result``` will be resolved according to [promise resolution procedure](https://github.com/promises-aplus/promises-spec#the-promise-resolution-procedure).
onFulfilled and onRejected callbacks can be passed.
```js
JSPromise.when(42, function (result) {
    console.log(result); // -> 42
});
```

####```JSPromise.invoke(fn)```####
Calls the given function and resolves new promise with returned value
```js
JSPromise.invoke(function (result) {
    return result;
}, null, 42).then(function (res) {
    console.log(res); // -> 42
})
```
npm loves you