kriskowal/q — Issue #42: README: perhaps illustrate the problem and why q is the solution
Author: jrburke
Created: 2012-01-18 18:44:31+00:00
State: open

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:

```javascript
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:

```javascript
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.

------