README: perhaps illustrate the problem and why q is the solution

[jrburke]

Great new README! It would have really helped me dive into q easier. I'm wondering if it makes sense to give a quick intro into the problem q helps solve. Here is a shot at it, but probably needs a bit of massaging, feel free to disregard too if I got the overall message wrong.

---

If a function cannot return a value or throw an exception without blocking, it can return a promise instead. A promise is an object that represents the return value or the thrown exception that the function may eventually provide. A promise can also be used as a proxy for a remote object to overcome latency.

So, instead of writing code like this:

asyncCall1(function (value1) {
    asyncCall2(value1, function(value2) {
        asynCall3(value2, function(value3) {
            asynCall4(value3, function(value4) {
                //Do something with value4
            });
        });
    });
});

You can write code like so:

q.call(asyncCall1)
    .then(asyncCall2)
    .then(asyncCall3)
    .then(asynCall4)
    .then(function(value4) {
        //Do something with value4
    })
    .end();

with the added benefit of being able to let errors propagate to top level error handlers. Focus more on your code logic and less on handling function callbacks.

---

[domenic]

I humbly submit my presentation as either a link to include, or as a source from which examples can be plagiarized at will.

[kriskowal]

@jrburke I like the idea of a problem statement, but I hesitate to characterize the benefits of using promises to just addressing the pyramid of doom, particularly because other libraries like @caolan’s async do that job pretty well. It’s a worthy problem to solve, but error propagation, reducing "chat delays" in distributed programs, POLA, and OCap philosophy are all part of the value. What you see is just the beginning: promise-aware debuggers and visualizers, progress monitors, cancellation propagation, and such other things fit in the architecture of a promise library.

@DomenicDenicola I think lifting examples is the better strategy. A lot of the preamble is specific to folks coming from ".Net". I want to keep the sale’s pitch in the README, and I think the tutorial is it. We could rotate the reference and examples out and into the Wiki.

[domenic]

@kriskowal Agreed. I think slides 42--68 are the most relevant.

[jrburke]

@kriskowal sure. for me as a newbie, the pyramid of doom was enough to get me into q, but I'm really fine with whatever you think might work. I am just suggesting giving a bit more context before talking about promises. In any case though, thanks for the README update!

[kriskowal]

@jrburke I’ll give it a shot. Thanks for the idea.