Promise objects can be in one of three states:

Consider this code segment similar to the one we'll use later in this chapter:

notes.read(req.query.key)
.then(note => { return filterNote(note); })
.then(note => { return swedishChefSpeak(note); })
.then(note => {
    res.render('noteview', {
        title: note ? note.title : "",
        notekey: req.query.key,
        note: note
    });
})
.catch(err => { next(err); });

There are several places where errors can occur in this little bit of code. The notes.read function has several possible failure modes: the filterNote function might want to raise an alarm if it detects a cross-site scripting attack. The Swedish chef could be on strike. There could be a failure in res.render or the template being used. But we have only one way to catch and report errors. Are we missing something?

The Promise class automatically captures errors, sending them down the chain of operations attached to Promise. If the Promise class has an error on its hands, it skips over the .then functions and will instead invoke the first .catch function it finds. In other words, using instances of Promise provides a higher assurance of capturing and reporting errors. With the older convention, error reporting was trickier, and it was easy to forget to add correct error handling.

The problem being addressed is that asynchronous coding in JavaScript results in the Pyramid of Doom. This coding pattern looks like simple ordinary function calls, ones that would execute in linear order from top to bottom. Instead, the pyramid is a nest of code that could execute in any order depending on the whims of event processing.

To explain, let's reiterate the example Ryan Dahl gave as the primary Node.js idiom:

db.query('SELECT ..etc..', function(err, resultSet) {
   if (err) {
      // Instead, errors arrive here
   } else {
      // Instead, results arrive here
    }
});
// We WANT the errors or results to arrive here

The purpose—to avoid blocking the event loop with a long operation—has an excellent solution here: to defer processing the results or errors until "later". But this solution created this pyramid-shaped problem.

If the resultSet requires asynchronous processing, there's another layer of callbacks and so on, until this becomes a little pyramid. The problem is that results and errors land in the callback. Rather than delivering them to the next line of code, the errors and results are buried.

Promise objects help flatten the code so that it no longer takes a pyramidal shape. They also capture errors, ensuring delivery to a useful location. But those errors and results are still buried inside an anonymous function and do not get delivered to the next line of code.

The ECMAScript Committee is working on a proposal for ES-2016 to add two new keywords, await and async, that should give us the ability to land asynchronous errors and results in the place they belong: the next line of code. Refer to the official documentation at https://tc39.github.io/ecmascript-asyncawait/ for details.

As proposed, you might be able to write the following code:

async UserFind(params) {
   return await dbLookupFunction(params);
}
var userData = async UserFind({ email });

While the Promise class is a big step forward, it doesn't solve everyone's needs. Additional libraries are becoming available with extra functionality or to wrap existing libraries so they return Promise objects.

Here are a few libraries to help you sail through commonly encountered scenarios: