Promises/A+

http://www.slideshare.net/domenicdenicola/callbacks-promises...

http://www.slideshare.net/domenicdenicola/promises-promises with video at http://www.youtube.com/watch?v=MNxnHbyzhuo

http://www.slideshare.net/domenicdenicola/boom-promisesa-was... which is more inspirational and motivational than practical

Otherwise, in the Q readme we try for a "graduated tutorial" approach; would welcome any feedback you have to make it more friendly. We try to relegate the "list of functions" to the API reference at https://github.com/kriskowal/q/wiki/API-Reference

The source should be fairly annotated and is structured similar to Backbone.js, so it might be useful to take a look through and see where/how those functions are being used.

The author of Promises/A+ also wrote a nice blost post on his You're Missing the Point of Promises [3]

Promises are actually a part of a of a very well understood programming mechanism that involves Futures and Deferred as well[4]

[1] http://blog.jcoglan.com/2013/03/30/callbacks-are-imperative-...

[2] https://news.ycombinator.com/item?id=5466872

[3] https://gist.github.com/domenic/3889970

[4] http://en.wikipedia.org/wiki/Future_%28programming%29

    promisesFunc().done(function(){ // execute on completion }

    q.when(promisesFunc).then( function(){ // do stuff } )

You can retrieve the results of promises in parallel, serially, or via some combination of both. That's part of their power versus straight callbacks which enforce a serial approach.

Check out this link to q's documentation: https://github.com/kriskowal/q#combination

I tend to find that the biggest problem with promise libraries is writing code with lots of jumps and more advanced control flow. If you are using an explicit continuation-based approach then doing a jump (for a loop or for breaking out early) is just a matter of calling the appropriate continuation. On the other hand, promises naturally tend to prefer the sort of code where there is only a single return statement at the end (unless you abuse the error handling system but there are all sort of problems if you do that)

$.when()

http://api.jquery.com/jQuery.when/

That API isn't written into the Promises/A+ spec because it doesn't need to be. That spec is the minimal things necessary for multiple promise implementations to be interoperable.

    db.load()
        .then(setupDB)
        .then(collectData);

You are currently basically throwing away the value you `resolve` with, where you should instead resolve with what would be the return value if it was a sync function so you can `.then` the function that takes the return value and returns a promise to be resolved with its return value.

    // Sync
    var foo = function () { return 'foo' };
    var addBar = function (foo) { return foo + 'bar'; }
    addBar(foo()) == 'foobar'

    // Promise using Q
    var foo = function () { return Q.resolve('foo') };
    var addBar = function (foo) { return Q.resolve(foo + 'bar'); }
    foo.then(addBar).done(function (result) {
        result == 'foobar'
    });

This is not to say that it invalidates your library or that every promise library has to comply to A+ or that A+ is the only good way to design promises in JS.

That said, I somewhat agree (although in JavaScript it should be `undefined`, not `null`). If we were starting clean, instead of with tons of code in the wild that did `.then(null, onRejected)` or `.then(false, onRejected)`, we would have the resulting promise be rejected with a `TypeError` if `onFulfilled` was neither `undefined` nor a function.