You want a better understanding of asynchronous control flow.

Asynchronous control flow is the name of a set of patterns to help control the order of execution of asynchronous code. To manage a programs flow synchronously, you would use if statements and try/catch statements. These work fine for synchronous code because each statement executes and the return value is evaluated before continuing to the next statement. Asynchronous code, however, is code that eventually will fulfill but some (indeterminate) time in the future and so cannot be predictably relied upon to succeed by the next statement or stack frame. To allow for code to be asynchronous, some languages offer the ability to create new threads, which run independently but can communicate with each other. JavaScript’s concurrency model is based on an event loop. The event loop effectively iterates over a task queue, executing each task until there are no tasks left. Tasks can execute small pieces of synchronous code, and subsequently defer the next stage of execution until a new task in the near future.

Two of the biggest paradigms for using callbacks in JavaScript are events and promises. Node.js also heavily utilizes the callback pattern throughout the core library, but does not use promises. Promises (and Node.js style callbacks) are very useful for single-result functions, for example for fs.writeFile, which fires the callback when all of the given contents have been written to the file. Events, which are described in Chapter 18, are used both in the browser and Node.js heavily and are very useful for asynchronous functionality that is fired potentially multiple times—for example, with element.addEventListener('click'), which could fire once or thousands of times during its life. Promises are a recent addition to the language, officially built into ECMAScript 6 and existing for a few years prior through external libraries. Promises are essentially task queues that “promise” a value will at some point be returned from asynchronous code. This chapter covers promises in depth.

First, it is important to understand how asynchronous code works. Essentially, an interpreter given a block of code will execute each statement one directly after the other. While this happens, the interpreter will not be able to do anything else (in a single thread). It will use as much CPU as it can to execute each statement, and when all statements are done it will finish and terminate the program. The problem herein lies that some functions, especially ones that deal with I/O will take a variable amount of time, compared to CPU bound functions, which take a (reasonably) predictable amount of CPU time. Traditional languages that are single threaded and I/O blocking will stop everything and simply wait for the indeterminately timed function to finish, and then proceed with the remainder of the code. Consider Figure 21-1, which illustrates a set of synchronous tasks done in a language that blocks for I/O.

JavaScript mitigates this behavior with the event loop (not to be confused with events in JavaScript). It offers the same behavior with regards to stack frames, in that synchronous code will pile up in stack frames and all be executed as fast as possible. JavaScript’s event loop adds an additional benefit through the task queue and tasks, which get executed in order but after the existing set of stack frames have been executed. In the language, this presents itself as functions like setTimeout(), setInterval(), setImmediate(), and in the case of Node.js process.nextTick(). Through these and other mechanisms, JavaScript uses the callback pattern, where functions can be passed as arguments, which can be executed in the near future, in a new task. This method of deferring functionality effectively makes up a simple concurrency model (i.e., a way to handle asynchronous code) for JavaScript. The event loop in itself does not make JavaScript non-blocking, but provides a layer of asynchronous concurrency, which most APIs (such as the DOM and Node.js) take advantage of .

By using this concurrency model to queue up the completion of I/O operations, JavaScript can execute all of the synchronous code setup first, then idle while waiting for the asynchronous code to complete, and finally fire all of the event handlers, callbacks, or promises that finish the program’s execution. This means I/O-based code will appear to run simultaneously, and much faster than blocking I/O-based code. Consider Figure 21-2 and compare it to Figure 21-1 to see the difference in these paradigms.

You want to know what a promise is and how it works.

Promises are the standard in ECMAScript for dealing with asynchronous task queues. There were many implementations prior to their ratification in the ES6 specification, such as Q, RSVP.js, and Bluebird, but the canonical implementation that features in JavaScript Implementations is the one we will be working with in this chapter.

Promises are essentially a list of functions that get built up programmatically and will be fired one by one when the promise queue starts. A promise is a concept of a type of data that promises to one day be fulfilled (i.e., it is nothing yet, but will soon be something). Promises exist in three states—pending (or “paused”), where the promise queue (function list) is queued up and none are being executed, fulfilled (or “playing”), where callbacks from the promise queue are being fired one by one, and any new tasks are added to the promise queue to be fired very soon, or rejected (or “failing”), where the promise queue is being fired but using the error state functions (explained later in the chapter).

When the promise is created, it is given the ability to resolve or reject, but starts in the pending state. The program has to manually resolve or reject the promise, which will put it into the fulfilled or rejected state respectively. When a promise has been resolved or rejected, it cannot be pending ever again, but it may switch between fulfilled or rejected during its lifetime.

Promises are guaranteed to be asynchronous—each new function added to the promise’s queue is fired on a new task in the event loop (the queue of JavaScript’s underlying concurrency), and so a promise’s queue is a reasonably close parallel to the event loop’s task queue.

See Figure 21-3 for a basic example of a promise. The Promise is created with five callbacks (essentially functions). The promise starts in a pending state, where tasks are added (the blocks marked as “then”) until resolve() is called. It sets the promise to a fulfilled state, and so for every iteration of the event loop task queue , one by one, each callback in the promise queue (the “then”s) is called and completed. Skip ahead to Figures 21-5 and 21-6 to see an in-depth overview of how this sort of promise can be constructed.

One of the interesting parts about promises is that when the state is moved away from pending, it cannot go back into a pending state. Because of this, callbacks (the “then” blocks in the illustrations—each one represents a callback) can be added retrospectively to a promise and will simply execute on the next iteration of the event loop. To put this another way, promises exist for the lifetime of the application (unless they are freed from memory) and will perpetually execute anything in their promise’s queue. This means, as a developer, you don’t necessarily need to care about the current state of a promise. It will still eventually execute the callbacks you’re adding, regardless of whether it has been fulfilled (actually, a promise could remain pending for the lifetime of the code, but this is rare and usually a result of a bug). Figure 21-4 illustrates how this could potentially work, given a similar example as in Figure 21-3.

This feature of a promise continuing to resolve its queue beyond the point of fulfillment reveals an interesting coincidental feature—a promise can be fulfilled before it has anything in its queue. The callbacks can be added post-fulfillment. Refer to Figure 21-5 for an example of how this might work.

Typical synchronous control flow not only includes conditional code paths with if/else but also allows trapping of errors with try/catch. With promises this can also be done using a similar mechanism. Promises can, of course, also be put into the rejected state. When a promise is in the rejected state it will not execute any resolvedActions (then()); instead, it executes the rejectedActions (catch()). When executing any rejectedActions, the promise can be switched back into a fulfilled state (switching from a rejected state) if the rejectedAction returns a value rather than throwing a failure. Consider Figure 21-6, which describes how this process works .

Of course, a rejectedAction doesn’t necessarily always have to put a promise back into a fulfilled state; it can pass the error back into the promise chain, causing the promise to remain in the rejected state, and skipping the next resolvedAction and instead running the next rejectedAction. Similarly, resolvedActions can throw errors to put an already fulfilled promise into a rejected state. Figure 21-7 shows how this might work .

These then()/catch() features closely mimic synchronous code’s try/catch, and they also work to cover some use cases of if/else. You are encouraged in your promises to flip the state of a promise between fulfilled and rejected as you see fit, to help handle what could be considered the “happy path” and the “unhappy path.” Refer to Figures 21-8 and 21-9 for more interesting examples of how this then()/catch() behavior can work.

Catching, resolving, and “rethrowing” are all paradigms of synchronous code, mapped into promises. They can create complex asynchronous workflows. They also become more powerful than try/catch when you consider that you can defer dealing with any errors until the last rejectedAction in your promise, meaning you don’t need to sprinkle rejectedAction callbacks everywhere in your code. Promises can become even more complex when you consider the other powerful feature: Promises can be composed together. The return values of either resolvedActions or rejectedActions can also be a promise, and execution and state is deferred to that promise until it has completed all of its queue, to which it hands back the flow of execution to the originating promise. This can become incredibly complex; refer to Figure 21-10 for a simplified illustration of nested promises.

In Figure 21-10, the promise is fulfilled, but the first resolvedAction (then()) returns a promise. The promise is created, and therefore executed, on the resulting call of the resolvedAction, so it resolves further down the line. During its fulfillment, it needs to complete all of its queue (resolvedActions and rejectedActions) before the originating promise can continue to process its queue. This composition ability makes promises incredibly powerful for handling sequential asynchronous tasks. As mentioned, however, the state of the nested promise determines the state going upstream, so while Figure 21-10 shows the nested promise successfully resolving, Figure 21-11 shows what would happen if the nested promise transforms into a rejected state. In Figure 21-11, you can see that the nested promise is transformed into a rejected state, and subsequently transforms the upstream promise to a rejected state, causing it to skip any subsequent resolvedActions and move to the nearest rejectedAction. This can provide some really interesting control flow, and is especially useful for tasks where you don’t mind about the state of a nested promise. You simply catch the error properly in the upstream promise and return it to its rightful state.

All of these features of promises make them incredibly powerful, but also incredibly complex. Understanding these concepts in their discrete form is key to grasping them. Ensure that you keep these concepts in mind to avoid underutilizing promises and potentially running into problems that could easily be solved by the many flexibilities and power of promises .

You want to be able to create a promise.

The promise constructor function can be used to make new promise instances. It takes one argument, which is a function that it immediately invokes. It gives the function two arguments—the first is a function to call when you want to fulfill the promise—e.g., when the wrapped asynchronous function has completed. The second is a function to call when you want the reject the promise—e.g., when the wrapped asynchronous function has failed with an error. The promise constructor function will return a new instance of promise, which is used to then queue up tasks.

The promise constructor doesn’t actually invoke any asynchronous code, although the resulting callbacks are guaranteed to run on a subsequent iteration of the event loop, and so are asynchronous. The promise constructor simply invokes the given function with the resolve and reject functions, leaving it to the developer to wrap asynchronous commands and turn them into a promise, as shown in the examples.

The callback function is given the two arguments—resolve and reject—so that the callback can manage the desired state of the promise. For example, if you’re making a call to Node.js’ fs.writeFile(), you might call resolve() when the operation has completed, putting the promise into a fulfilled state, unless there is an error, wherein reject(error) would be called, putting the Promise into a rejected state. As discussed earlier in this chapter, this determines the execution flow of the promise, whether it moves to a resolvedAction or a rejectedAction.

You want to be able to add a callback to a promise that will be executed when the promise is resolved.

The Promise.prototype.then() function takes two arguments, both functions. The first function is the resolvedAction, the second is rejectedAction. Only one of these function arguments is ever fired; the other one is never fired. Which one is determined by the state of the promise. The first function argument (the resolvedAction argument) is what to do if the state of the promise at the previous point in the queue was rejected and defaults to a function that returns the first given argument. The second argument is described later in this chapter. resolvedAction will be called with the resolveResult. That is the value that was passed to the resolve() function in the original promise constructor, or the value returned from the last called resolveAction or rejectAction. Whatever the value that is returned from the resolvedAction function becomes the new resolveResult. If resolvedAction throws, then the thrown value will become the rejectResult and the promise will enter a rejected state.

The output is:

then() can be called on a promise in any state. When the promise is in a pending state, it will wait until it is in a fulfilled or rejected before it executes any arguments in a then() function. If it is in the fulfilled state, the queue is executed, one by one, calling each of the resolvedActions (the first argument in a then() call). A promise that is already fulfilled will call the next resolvedAction in the queue. Remember though that a promise can change state to rejected at any time, meaning that, while you can guarantee one of the functions given to then() will be called, you can never guarantee which one it will be. A best practice is to always ensure you manage the outcome of both states at every reasonable opportunity, or at the very least always attempt to put a rejectedAction at the end of the promise chain. See Figure 21-12 illustrates the behaviors of a promise continuously in the fulfilled state.

You want to be able to catch an error from a previous promise or then() that will be executed when the promise is rejected, or an error occurs in the previous then().

As mentioned, the Promise.prototype.then() function takes two arguments, both functions. The second argument is the rejectedAction argument, which is a function that is called if the state of the promise is rejected, and defaults to a function that throws the first given argument. rejectedAction will be called with the rejectResult. That is the value that was either passed to the reject() function in the original promise constructor, or the value that was thrown in the last resolveAction or rejectAction. The value that is returned from this function becomes the new resolveResult, and the promise goes back to a fulfilled state, unless this function throws in which case the value thrown becomes the rejectResult and the promise remains in a rejected state.

The output is:

then() can be called on a promise in any state. When the promise is in a pending state, it will wait until it is in a fulfilled or rejected before it executes any arguments in a then() function. If it is in the rejected state, then the queue is executed, one by one, calling each of the rejectedActions (the second argument in a then() call). A promise that’s already rejected will call the next rejectedAction in the queue. A promise can change state to fulfilled from a rejected state at any time, meaning that, while you can guarantee that one of the functions given to then() will be called, you can never guarantee which one it will be. Figure 21-13 illustrates the behaviors of a promise that rejects with a catch function in place.

Promise.prototype.catch() is a simple shortcut for calling Promise.prototype.then() while omitting the first argument. catch() only takes one argument, a rejectedAction. This will be called only if the promise is in a rejected state. rejectedAction will be called with the rejectResult. That is the value that was either passed to the reject() function in the original promise constructor, or the value that was thrown in the last resolveAction or rejectAction. The value that is returned from this function becomes the new resolveResult, and the promise goes back to a fulfilled state, unless this function throws, in which case the value thrown becomes the rejectResult and the promise remains in a rejected state .

The output is:

Promise.prototype.catch() provided a convenient wrapper for Promise.prototype.then(undefined). Other than the arguments it takes, it behaves identically to its cousin: Promise.prototype.then().

catch() can be called on a promise in any state. When the promise is in a pending state, it will wait until it is fulfilled or rejected before it executes any arguments in a catch() function. If it is in the rejected state, then the queue is executed, one by one, calling each of the rejectedActions. A promise that’s already rejected will call the next rejectedAction in the queue. Figure 21-14 illustrates the behaviors of a promise that rejects with a catch function in place.

You have a value that you’d like to resolve into an immediately fulfilled promise.

Promise.resolve() takes one argument, which can be any value, that becomes the resolveResult as part of a new promise. It returns a new promise, which can then be chained off with then() and catch(). The first resolvedAction will be called with the resolveResult (the first argument given to Promise.resolve()).

The output is:

Promise.resolve() automatically creates a new promise in the fulfilled state with the resolveResult set to the given argument. It offers exactly the same semantics as a new promise in which the resolve() function is immediately called with the given value.

You have a value that you’d like to resolve into an immediately rejected promise.

Promise.reject() takes one argument, which can be any value, that becomes the rejectResult as part of a new promise. It returns a new promise, which can then be chained off with then() and catch(). The first rejectedAction will be called with the rejectResult (the first argument given to Promise.resolve()).

The output is:

Promise.resolve() automatically creates a new promise in the rejected state with the rejectResult set to the given argument. It offers exactly the same semantics as a new promise, in which the reject() function is immediately called with the given value.

Remember, a rejected promise will automatically skip all resolvedActions and head for the first rejectedAction, but if the rejectedAction returns a value and doesn’t throw, then the promise can be put into a fulfilled state. See Figure 21-15.

You have multiple promises that you’d like to execute in serial (one after the other).

As part of the built-in behavior of a promise, if the return value from a resolvedAction or rejectedAction is a promise, then the returned promise has to be fulfilled or rejected, and all of its queue needs to be executed for the upstream promise queue to continue. In addition, if the state of the returned promise can alter the state of the upstream promise; for example, if the upstream promise is fulfilled but the returned promise ultimately ends up as rejected, it will change the state of the upstream promise to rejected.

The output is:

In the code example, data.json’s contents are read, as part of a promise, parsed as JSON, the version number is incremented, and the contents are written back into data.json. The write operation is also wrapped in a promise, but one that is returned as part of a then() (the arrow function without curly braces immediately returns the only statement in its body).

The promise that is returned as part of the write operation dictates the rest of the flow of the parent most promise (the read operation). The first thing required is that the last then() is deferred for execution until the write operation completes, and the child promise is fully resolved with nothing left in its promise queue. The second thing that happens is the last state of the child promise is copied over to its parent, meaning if the child promise (the write file operation in this case) ends up in a rejected state, the parent promise (the read file operation in this case) will inherit that state and become rejected, even if it was originally fulfilled. This sounds like it may cause slip ups, but it is actually a very powerful tool when dealing with multiple, nested, promises. See Figures 21-16 and 21-17 for illustrations on how this might work .

You have a list of promises, and you want to execute code after one of any of those promises resolves to a fulfilled or rejected. You do not care which one resolves first, just as long as one does.

Promise.race() takes one argument, which is an iterable (e.g., an array) of values. Any value that’s an instance of promise will be used to defer the execution of subsequent callbacks, until one of the promises in the iterable is fulfilled or rejected. All values that are not a promise will be converted into a promise using Promise.resolve().

The output is:

Internally, the interpreter calls Promise.resolve on all items in the iterable given to Promise.race(). Any values that aren’t promises are composed into immediately resolving promises, while any that are need to resolve before the promise returned from Promise.all() will be resolved.

The internal implementation (as per the spec) simply iterates through all values, calling Promise.resolve() on them, passing the returned promises resolve and reject as the resolvedHandler and rejectedHandler. A JavaScript implementation would look similar to Listing 21-10.

You have multiple promises that you’d like to execute in parallel (all together at the same time).

Promise. all() takes one argument, which is an iterable (e.g., an array) of values. Any value that’s an instance of promise will be used to defer the resolution of the returned promise, until every promise is fulfilled or rejected.

The output is:

Internally, the interpreter calls Promise.resolve on all items in the iterable given to Promise.all(). Any values that aren’t promises are composed into immediately resolving promises, while any that are need to resolve before the promise returned from Promise.all() will be resolved. Any promises that are in a rejected will put the parent promise into a rejected state.

The internal implementation (as per the spec) simply keeps a list of all elements in the iterable and a counter of all resolved promise values. When each promise is resolved, the counter ticks down until it reaches 0, when the returned promise is resolved. To put this in code, it might look something like Listing 21-12.

You want to be able to generate a promise that delays a certain amount of time before resolving.

The output is:

First, a function is created on Promise.myextensions.delay. This could be set as Promise.delay, but if a later version of JavaScript implements this as a native feature, then there is a risk of incompatibility, so it is much safer to namespace custom extensions onto a new object (it is very unlikely that ECMAScript will ever define Promise.myextensions as anything, but feel free to choose an equally unlikely name, such as a company or organization name).

The first line, other than defining the function, contains is an arrow function that immediately returns a new promise. Only the resolve argument has been defined, because this function can never enter a rejected state, as there is nothing to reject.

The function takes two arguments, value and ms. value (the value to resolve the promise with) is optional, and so we need to write a small piece of detection logic that says if ms (the number of milliseconds to delay by) is undefined, then take the value from value, and treat that as ms, meanwhile set value to undefined. This allows for the two different method signatures: Promise.myextensions.delay(value, ms) and Promise.myextensions.delay(ms).

The core part of the functionality is incredibly simple. It simply calls setTimeout, which takes a callback and a millisecond value for which to wait before executing the callback. The callback function for setTimeout simply calls resolve with the given value. ms is supplied as the second parameter.

You want to be able to create a promise that takes an existing promise, aiming to resolve it within a given time. If the given promise exceeds the given time, the created promise will reject with a timeout.

Brief note about the solution

Perhaps another paragraph

The output is:

First, a function is created on Promise.myextensions.timeout. This could be set as Promise.timeout, but if a later version of JavaScript implements this as a native feature, then there is a risk of incompatibility, so it is much safer to namespace custom extensions onto a new object (it is very unlikely that ECMAScript will ever define Promise.myextensions as anything, but feel free to chose an equally unlikely name, such as a company or organization name).

The first line, other than defining the function, is an arrow function that immediately returns a new promise. The function itself takes two arguments—promise (an underlying promise to chain off of) and ms (the amount of time to wait before rejecting with a timeout error).

The first line of the inner function simply tacks the resolve and reject arguments onto the given promise. This way, if the given promise resolves or rejects, then the created timeout promise will do the same.

The core part of this function looks very simple, but relies on a subtle feature of promises. Effectively, just like the delay function, a setTimeout is called with a callback and ms. The difference here is that this callback call rejects, with a timeout error, to put the promise into a rejected state. The subtle feature of promises that this utilizes, is that a promise constructor’s reject() and resolve() functions have a built-in trap that they can only be called once between them. This means if a codebase (such as this one) called reject() multiple times, only the first reject() would actually count. Similarly if the code called reject() followed by resolve(), the resolve() call would not count. The promise has already moved away from its pending state, so these functions are effectively no-ops (they do nothing) .

Node.js’ asynchronous methods all follow the same callback signatures. The callback is always the last argument, and it is always called with an Error object (or null) as the first argument and an optional mixed value as the second. We can take advantage of this to write a generic wrapper that takes a Node.js-style asynchronous function and resolves or rejects a returned promise. Our method will take one fixed argument—the Node.js-style method—and an infinite number of optional arguments, and return a promise that will execute the behavior of the given method.

The output is:

First, a function is created on Promise.myextensions.denode. This could be set as Promise.denode, but if later version of JavaScript implements this as a native feature, then there is a risk of incompatibility, so it is much safer to namespace custom extensions onto a new object (it is very unlikely that ECMAScript will ever define Promise.myextensions as anything, but feel free to chose an equally unlikely name, such as a company or organization name).

The first line, other than defining the function, is an arrow function that immediately returns a new promise. The function itself takes our fixed method argument, which is the Node.js-style asynchronous function to call. It also uses the rest parameter (described in Chapter 12) to capture all additional arguments into an array.

The main part of the functionality calls our Node.js-style asynchronous function, using the spread operator, so that all arguments are applied to the method, rather than it being passed one array of values. A callback function is also concatenated to the values array, ensuring that the last argument is always the callback that’s used to resolve the promise.

You want to be able to deal with promises, but write them in a synchronous-looking manner using the power of ES6 generators (without callbacks).

Because generators pause the function state until the yielded value calls next(), promises can be used in a very powerful combination with generators, to make a function that yields any time it wants asynchronous behavior to occur. We can write a method that will take a generator function, and iterate over it, each time taking the value and treating it like a promise, only calling next() when the value promise has resolved, and calling throw() when the promise is rejected.

The output is:

First, a function is created on Promise.myextensions.coroutine. This could be set as Promise.coroutine, but if a later version of JavaScript implements this as a native feature, then there is a risk of incompatibility, so it is much safer to namespace custom extensions onto a new object (it is very unlikely that ECMAScript will ever define Promise.myextensions as anything, but feel free to chose an equally unlikely name, such as a company or organization name).

The first line, other than defining the function, is an arrow function that immediately returns another arrow function. The returned arrow function, when called, returns a new promise. The reason the coroutine function returns an arrow function, is to allow composition. Functions can be created, wrapped in the coroutine method, and become new methods that can be executed later on in the code, as demonstrated in the examples. The promise is returned from the returned arrow function to allow nesting of coroutines. A coroutine() that yields to another coroutine() can use this promise to pause its execution.

This line simply starts the iterator, giving it the values passed from the calling arrow function. Generators, as described in Chapter 13, return an instance of GeneratorFunction, which offers the utility to iterate through the generator’s yielded values. This function needs to use that, so it stored the GeneratorFunction instance as iterator.

Inside the iterate function, we get iterator’s next value by calling next(). It is provided the value of the last iteration, so that when the GeneratorFunction resumes, it can deal with the last value that was iterated on. The resulting value is stored as iteration, so that the following lines can determine what to do next. As described in Chapter 13, the resulting value from a GeneratorFunction next() call is an object with two properties: done and value.

If the iteration’s done property is true, that means the iterator has finished all available statements (either it has returned a value or it hit the last line statement inside the function). At this point, coroutine’s promise is resolved with the last value (the return value, or undefined).

If the iteration’s done property is false, that means the iterator has yet to finish, so next() needs to be called again. However before that, the current value needs to be dealt with. Promise.resolve is called on the value, to convert it into a promise (if it isn’t already). Casting everything as a promise simplifies the logic with how to deal with the iterator values, and provides a consistent asynchronous interface for the GeneratorFunction. As a promise, it is then simply a case of calling then(). The iterate function is given as the resolvedAction which will allow it to recurse. The cycle repeats again, and iterator.next() is called with the resolved value. The arrow function is the rejectedAction, and it calls iterator.throw(), which as described in Chapter 13, resumes the GeneratorFunction but with a thrown error.