jpromise

jPromise
==========

A Promise Library that is actually spec compliant with the latest versions of the spec...

A library conforming to the Promise/A spec.

Tested in Chrome, Firefox, Safari, and IE8/9/10.

This is a promise library that is speedy quick, doesn't hold onto scopes everywhere all willy-nilly, and is also quite flexible.

* p Constructor
* Creates a new deferred object
* dfd.promise()
* Returns the promise for a given deferred object. The promise object is not able to access some of the deferrer's methods, such as resolve and reject.
* dfd.resolve(arg)
* Resolves the deferred object. When the deferred object gets resolved, callbacks on dfd.then, dfd.done, and dfd.always will get called with arg.
* dfd.reject(arg)
* Rejects the deferred object. When the deferred object gets resolved, callbacks on dfd.then, dfd.fail, and dfd.always will get called with arg.
* dfd.progress(arg)
* Progresses the deferred object (like a resolve but can be called multiple times). When the deferred object gets resolved, callbacks on dfd.notify will get called with arg.
* dfd.done(cb) and promise.done(cb)
* Creates a callback for when the deferred object gets resolved. The cb function will get called with the arg that the deferred object was resolved with.
* dfd.fail(cb) and promise.fail(cb)
* Creates a callback for when the deferred object gets rejected. The cb function will get called with the arg that the deferred object was rejected with.
* dfd.progress(cb) and promise.progress(cb)
* Creates a callback for when the deferred object gets notified. The cb function will get called with the arg that the deferred object was notified with.

$3

``
//Stashes on the global _ on the property Dfd...
//The closure also returns the Dfd constructor and could be munged to work in AMD/Common if we gave a...
var p = require('jpromise');

var dfd = new p();

var pro = dfd.promise();

pro.always(function(data) {
console.log("always", data);
});

pro.done(function(data) {
console.log("done", data);
});

pro.fail(function(data) {
console.log("fail", data);
});

pro.progress(function(data) {
console.log("progress", data);
});

setTimeout(function() {
dfd.notify("foo");

console.log("state", dfd.state());

dfd.resolve("bar");

pro.done(function(data) {
console.log("after Done", data);
});

console.log("state", dfd.state());

}, 500);

//returns in console:
// progress "foo"
// state 0
// always "bar"
// done "bar"
// after Done "bar"
// state 1

``

$3

* You can done/fail/progress/then on the dfd as well as the promise, but you can only resolve/reject/notify on the dfd
* You cannot escalate the promise into the dfd, it is a one way street
* You can get the promise from the dfd multiple times and it will always return the same promise instance
* You can bind at any point even after a dfd has resolved/rejected and it will instantly return
* This sucker is about 3x as fast/efficient as jQuery's Deferred piece clocking in at about 100k ops a second