Using the Promise class

I recommend to take a look at MDN's Promise docs which offer a good starting point for using Promises. Alternatively, I am sure there are many tutorials available online.:)

Note: Modern browsers already support ECMAScript 6 specification of Promises (see the MDN docs linked above) and I assume that you want to use the native implementation, without 3rd party libraries.

As for an actual example...

The basic principle works like this:

1. Your API is called


2. You create a new Promise object, this object takes a single function as constructor parameter


3. Your provided function is called by the underlying implementation and the function is given two functions - resolve and reject


4. Once you do your logic, you call one of these to either fullfill the Promise or reject it with an error

This might seem like a lot so here is an actual example.

exports.getUsers = function getUsers () {

  // Return the Promise right away, unless you really need to

  // do something before you create a new Promise, but usually

  // this can go into the function below

  return new Promise((resolve, reject) => {

    // reject and resolve are functions provided by the Promise

    // implementation. Call only one of them.



    // Do your logic here - you can do WTF you want.:)

    connection.query('SELECT * FROM Users', (err, result) => {

      // PS. Fail fast! Handle errors first, then move to the

      // important stuff (that's a good practice at least)

      if (err) {

        // Reject the Promise with an error

        return reject(err)

      }



      // Resolve (or fulfill) the promise with data

      return resolve(result)

    })

  })

}



// Usage:

exports.getUsers()  // Returns a Promise!

  .then(users => {

    // Do stuff with users

  })

  .catch(err => {

    // handle errors

  })

Using the async/await language feature (Node.js >=7.6)

In Node.js 7.6, the v8 JavaScript compiler was upgraded with async/await support. You can now declare functions as being async, which means they automatically return a Promise which is resolved when the async function completes execution. Inside this function, you can use the await keyword to wait until another Promise resolves.

Here is an example:

exports.getUsers = async function getUsers() {

  // We are in an async function - this will return Promise

  // no matter what.



  // We can interact with other functions which return a

  // Promise very easily:

  const result = await connection.query('select * from users')



  // Interacting with callback-based APIs is a bit more

  // complicated but still very easy:

  const result2 = await new Promise((resolve, reject) => {

    connection.query('select * from users', (err, res) => {

      return void err ? reject(err) : resolve(res)

    })

  })

  // Returning a value will cause the promise to be resolved

  // with that value

  return result

}