1. Its a promise library. It gives you a Promise class, a PromiseResolver and some tools to convert node functions to promises or to support dual promise/callback API.
2. Its super-fast and has full stack traces that go back until the beginning of the async event chain
5. Yes, promises are confusing. I'm going to write a straight-forward introduction (that uses bluebird) this weekend. But once you get past the new words and definitions, promises are actually not complicated at all. Infact, here is a short intro:
How are promises different? Instead of writing your functions to take callbacks, you write functions that return promises. Imagine that node's fs.readFile returned a promise instead of taking a callback. Then this code:
fs.readFile(file, function(err, res) {
if (err) handleError();
doStuffWith(res);
});
Still not good enough? What if I told you... that if you return something from inside the .then() callback, then you'll get a promise for that thing?
Say you want to get a line from a file:
var linePromise = fs.readFile(file).then(function(data) {
return data.toString.split('\n')[line];
});
var beginsWithHelloPromise = linePromise.then(function(line) {
return /^hello/.test(line);
});
Thats pretty cool. But the coolest thing is probably this: if you return a promise from within `.then`, you will get that promise outside of `.then`:
function readUploadAndSave(file, url, otherPath) {
// read the file
var filePromise = fs.readFile(file);
// upload it when done reading
var uploaded = filePromise.then(function(content) {
return uploadData(url, content);
});
// also save to another place locally
var savedLocal = filePromise.then(function(res) {
return fs.saveFile(res, otherPath)
});
// return a promise that "succeeds" when both saving and uploading succeed:
return Bluebird.join(uploaded, savedLocal);
}
readUploadAndSave(file, url, otherPath).then(function() {
console.log("Success!");
}, function(err) {
// This function will catch *ALL* errors, from the above
// operations including any exceptions thrown inside .then
console.log("Oops, it failed.", err);
});
Now its easier to understand the chaining. At the end of every function passed to a `.then()`, return a promise. Lets make our code even shorter:
function readUploadAndSave(file, url, otherPath) {
// read the file
return fs.readFile(file).then(
// upload and save when done reading
return Bluebird.join(uploadData(url, content),
fs.saveFile(res, otherPath));
});
}
What if we want to make sure the data is uploaded first before saving?
function readUploadAndSave(file, url, otherPath) {
// read the file
var uploadedPromise = fs.readFile(file).then(
// return promise that its uploaded
return uploadData(url, content);
});
return uploadedPromise.then(function() {
// return promise that its saved.
return fs.saveFile(res, otherPath);
});
}
Or even shorter, skip the temporary promise variables and chain .then the way we chain `stream.pipe` in node:
function readUploadAndSave(file, url, otherPath) {
// read the file
return fs.readFile(file).then(
// then upload it
return uploadData(url, content);
}).then(function() { // after its uploaded
// save it
return fs.saveFile(res, otherPath);
});
}
And similarly to how in a stream.pipe chain the last stream is returned, in promise pipes the last returned promise is returned.
Thats all you need, really. The rest is just converting callback-taking functions to promise-returning functions and using the stuff above to do your control flow.
Ah, and also, you can also return values in case of an error. So for example, to write readFileOrDefault (which returns a default value if for example the file doesn't exist) you would do this:
I like your examples. As one who is casually familiar with promises, I would find it helpful to see more promise patterns/recipes. In particular, how about a blog post on the promise equivalents to the https://github.com/caolan/async Collections and Control Flow methods (since that library seems to be heavily used in the node community)? Would a higher level promises utility library be appropriate or overkill?
Yes, I could include that in my guide. Since promises are actual values, most of the tools in async.js become unnecessary and you can just use whatever you're using for regular values, like your regular array.map / array.reduce functions combined with some promise tools like .all
You already have async.waterfall and async.auto with .then and .spread chaining.
files.getLastTwoVersions(filename)
.then(function(items) {
// fetch versions in parallel
var v1 = versions.get(items.last),
v2 = versions.get(items.previous);
return [v1, v2];
})
.spread(function(v1, v2) {
// both of these are now complete.
return diffService.compare(v1.blob, v2.blob)
})
.then(function(diff) {
// voila, diff is ready.
});
async.map is straightforward.
// download all items, then get their names
var pNames = ids.map(function(id) {
return getItem(id).then(function(result) {
return result.name;
});
});
// wait for things to complete:
Promise.all(pNames).then(function(names) {
// we now have all the names.
});
If you want to wait for the previous item to download first (ala .mapSeries) thats also pretty straightforward: you just need the previous download to complete, then run the next download, then extract the item name, and thats exactly what you express in the code:
// start with current being an "empty" already-fulfilled promise
var current = Promise.fulfilled();
var namePromises = ids.map(function(id) {
// wait for the previous download to complete, then get the next
// item, then extract its name.
current = current
.then(function() { return getItem(id); })
.then(function(item) { return item.name; });
return current;
});
Promise.all(namePromises).then(function(names) {
// use all names here.
});
The only thing that remains is mapLimit - which is a bit harder to write - but still not that hard:
var queued = [], parallel = 3;
var namePromises = ids.map(function(id) {
// How many items must be complete before fetching the next?
// The queued, minus those running in parallel, plus one of the parallel slots.
var minComplete = Math.max(0, queued.length - parallel + 1);
// when enough items are complete, queue another request
// for an item, then get the item's name.
return Promise.some(queued, minComplete)
.then(function() {
var download = getItem(id);
queued.push(download);
return download;
}).then(function(item) {
return item.name;
});
});
Promise.all(namePromises).then(function(names) {
// use all names here.
});
Is a library needed? Probably, but only for mapLimit.
