Table of Contents for

Node.js 8 the Right Way

Simplifying Code Flows with Promises

In this section, you’ll add another API to your lib/search.js file. Like the /search/books API from last section, this /suggest API will hit your Elasticsearch cluster for information, but this time we’ll use Promises rather than callbacks to manage asynchronous control flow.

Fulfilling Promises

To understand Promises, it helps to start with a brief review of JavaScript code flow and the mechanisms for structuring it. Whenever a regular JavaScript function starts executing, it will finish in one of two ways: either it will run to completion (success) or it will throw an exception (failure).

For synchronous code this is good enough, but for asynchronous code we need a bit more. The Node.js core module callbacks use two arguments to reflect these two cases; e.g., (err, data) => {...}. And EventEmitters use different event types (like data and error) to distinguish success and failure modes.

Promises offer yet another way to manage asynchronous results. A Promise is an object that encapsulates these two possible results (success and failure) for an operation. Once the associated operation has completed, the Promise will either be resolved (success case) or rejected (error case). When using a Promise, you attach callback functions for these cases using .then() and .catch(), respectively.

Let’s take a look at a quick example.

Here we’re creating a new Promise, passing in an anonymous callback function that is invoked immediately. The resolve and reject parameters are callback functions you should invoke to resolve or reject the Promise, respectively. The value you pass to these functions will be sent forward to any .then() or .catch() handlers.

Let’s add those next.

Now, whenever the Promise is settled, the appropriate callback will be invoked. Importantly, it doesn’t matter whether the Promise has already been settled when you attach handlers with .then() and .catch(). If the Promise has already been settled, those handlers will be called right away. But if the Promise has yet to be settled, then those handlers will wait to be called when it is. Contrast this with a typical EventEmitter—if you attached your .on(’error’) handler too late, you’ll simply miss out on handling the event.

A Promise can only ever be settled once. That is, once a Promise has been resolved or rejected, it can’t be resolved or rejected again. This doesn’t stop you from attaching more callbacks using .then() or .catch(), but it does guarantee that any particular callback added this way will be invoked at most once. Once again, contrast this with a typical EventEmitter, which may emit many data or error events.

That’s enough theory for now. Let’s see Promises in action.

Using a Promise with request

Start by adding the following shell code to your lib/search.js below the previous /search/books API to create the /suggest API endpoint.

As with the /searchi/books API, this API takes two parameters: the :field for which we want suggestions and the :query to suggest from.

Now, inside the shell we need to construct the Elasticsearch request body and the rest of the options to send through request.

This request body is designed to trigger Elasticsearch’s Search Suggesters feature.^[69] Setting the size parameter to zero informs Elasticsearch that we don’t want any matching documents returned, just the suggestions.

Elasticsearch’s Suggest API allows you to request multiple kinds of suggestions in the same request, but here we’re submitting only one. If the request succeeds, we expect to get back a JSON object that contains something like the following, which resulted from an authors search for the string lipman:

To get this result, let’s use request like we did for the /search/books API, but this time we’ll use a Promise. Add the following code after creating the options object.

This code proceeds in two parts. First we create the Promise, then we attach callbacks to it.

In the Promise-creation part, we call out to request just like in the previous API. But this time, instead of handling the results directly, we either reject or resolve the Promise.

The two rejection cases are the same as before. If the Elasticsearch cluster is unreachable, then the err object will be populated. On the other hand, if the request is malformed, then the err object will be null but the statusCode will be something other than 200 OK. In both cases, we want to reject the Promise so that any .catch() handlers are invoked.

Notice that the object passed to reject has a single key called error that includes the error details. This is a design choice that I’ll explain in a bit. When calling reject for a Promise, you’re free to give it any value you like (or none at all).

In the event that Elasticsearch was reachable and returned a 200 OK status code, we resolve the Promise.

Once the Promise has been created, we attach a .then() and a .catch() handler. The .then() handler sets the Express response status to 200, then extracts and serializes the suggest.suggestions object returned from Elasticsearch.

The .catch() handler extracts the .error property of the object provided. It does this using the destructuring assignment technique we used earlier when extracting the _source documents in the /search/books API. Inside the callback, we use the error object to set the response status code and body.

Save your lib/search.js if you haven’t already. To review, your /suggest API code should look like the following:

Once you save the file, nodemon should pick up the changes and restart the service automatically. Now we can hit the service with curl and jq.

First, let’s try finding author suggestions for the string lipman.

If you see this, great! Things are working as expected.

Of course, you can use jq to extract just the text of the suggestions if you like.

Next, let’s look at a module called request-promise, which streamlines the use of Promises with the request module for issuing requests.

Replacing request with request-promise

Recall in the last section, where we created a Promise to abstract out the fulfillment of the asynchronous request from the handling of the success and failure cases. In practice, you won’t usually use new Promise() to create a Promise for a bit of asynchronous functionality. It’s considerably more common for Promises to be created by factory methods.

For example, you can use the static method Promise.resolve to create a new Promise and immediately resolve it.

In the case of request, there’s a module called request-promise that wraps the various request methods to return Promises instead of taking a callback. To use it, start by installing it with npm.

Next, add a require line to the top of your lib/search.js to pull it in as a constant named rp.

Now it’s a drop-in replacement for the Promise-creating code we used in the previous section. This simplifies the whole block down to just this:

This is the reason that I elected to wrap the rejection value in an object whose .error property contained the error—so that we could use request-promise as a replacement.

For the rest of the APIs in this chapter, we’ll use request-promise rather than regular request. Now let’s move on to building out the API endpoints for working with book bundles. Unlike the /search/books and /suggest APIs, which only retrieved data from Elasticsearch, the bundle APIs will need to create, update, and delete records as well.