Taking a lesson from the implementation of trampoline from Chapter 6, I can implement a lazy variant of _.chain that will not run any target methods until a variant of _.value is called:

function LazyChain(obj) {
  this._calls  = [];
  this._target = obj;
}

The constructor for the LazyChain object is simple enough; it takes a target object like _.chain and sets up an empty call array. While the operation of trampoline from Chapter 6 operated on an implicit chain of calls, LazyChain works with an explicit array of…something. However, the question remains as to what it is that I put into the _calls array. The most logical choice is, of course, functions, as shown below:

LazyChain.prototype.invoke = function(methodName /*, args */) {
  var args = _.rest(arguments);

  this._calls.push(function(target) {
    var meth = target[methodName];

    return meth.apply(target, args);
  });

  return this;
};

The LazyChain#invoke method is fairly straightforward, but I could stand to walk through it. The arguments to LazyChain#invoke are a method name in the form of a string, and any additional arguments to the method. What LazyChain#invoke does is to “wrap” up the actual method call in a closure and push it onto the _calls array. Observe what the _calls array looks like after a single invocation of LazyChain#invoke here:

new LazyChain([2,1,3]).invoke('sort')._calls;
//=> [function (target) { ... }]

As shown, the only element in the _calls array after adding one link to the lazy chain is a single function that corresponds to a deferred Array#sort method call on the array [2,1,3].

A function that wraps some behavior for later execution is typically called a thunk^[91] (see Figure 8-1). The thunk that’s stored in _calls expects some intermediate target that will serve as the object receiving the eventual method call.

Figure 8-1. A thunk is a function waiting to be called

While thunks are not always functions in every programming language that supports them, in JavaScript it makes sense to implement them as such because functions are readily available.

Since the thunk is waiting to be called, why don’t I just call it to see what happens:

new LazyChain([2,1,3]).invoke('sort')._calls[0]();

// TypeError: Cannot read property 'sort' of undefined

Well, that was less than satisfying. The problem is that directly calling the thunk is not enough to make it execute properly. If you’ll recall, the thunk expected a target object to execute its closed-over method on. To make it work, I would need to somehow pass the original array as an argument to the thunk, as shown in Figure 8-2.

Figure 8-2. To make the LazyChain work, I have to find a way to loop the original object back into the call

I could satisfy the argument lookback manually by pasting the array into the thunk call as in the following:

new LazyChain([2,1,3]).invoke('sort')._calls[0]([2,1,3]);

//=> [1, 2, 3]

Placing the argument directly into the thunk call seems not only like cheating, but also like a terrible API. Instead, I can use the _.reduce function to provide the loopback argument not only to the initial thunk, but also every intermediate call on the _calls array:

LazyChain.prototype.force = function() {
  return _.reduce(this._calls, function(target, thunk) {
    return thunk(target);
  }, this._target);
};

The LazyChain#force function is the execution engine for the lazy chaining logic. As shown in Figure 8-3, the use of _.reduce nicely provides the same kind of trampolining logic as demonstrated in Chapter 6. Starting with the initial target object, the thunk calls are called, one by one, with the result of the previous call.

Figure 8-3. Using reduce allows me to pass the intermediate result forward into each thunk

Now that LazyChain#force is in place, observe what happens when it is used to “terminate” a lazy chain:

new LazyChain([2,1,3]).invoke('sort').force();

//=> [1, 2, 3]

Excellent! The logic seems sound, but what happens when more links are added to the chain? Observe:

new LazyChain([2,1,3])
  .invoke('concat', [8,5,7,6])
  .invoke('sort')
  .invoke('join', ' ')
  .force();

//=> "1 2 3 5 6 7 8"

I can chain as long as I want while remaining mindful of the way that the types change from one link to the next. I mentioned earlier that LazyChain was lazy in its execution. While you might see how that is indeed the case because thunks are stored in the _calls array and never executed until LazyChain#force, it’s still better to show it actually being lazy. First, let me implement a lazy version of _.tap that works with LazyChain instances:

LazyChain.prototype.tap = function(fun) {
  this._calls.push(function(target) {
    fun(target);
    return target;
  });

  return this;
}

The operation of LazyChain#tap is similar to LazyChain#invoke because the actual work (i.e., calling a function and returning the target) is wrapped in a thunk. I show how tap works below:

new LazyChain([2,1,3])
  .invoke('sort')
  .tap(alert)
  .force();

// alert box pops up
//=> "1,2,3"

But what happens if I never call LazyChain#force?

var deferredSort = new LazyChain([2,1,3])
  .invoke('sort')
  .tap(alert);

deferredSort;
//=> LazyChain

Nothing happens! I can hold onto deferredSort as long as I want and it’ll never execute until I explicitly invoke it:

// ... in the not too distant future

deferredSort.force();

// alert box pops up
//=> [1, 2, 3]

This operation is very similar to the way that something like jQuery promises work. Before I talk a little bit about promises, however, I want to explore an easy extension to LazyChain that allows me to, well, chain lazy chains to other lazy chains. That is, keeping in mind that at the heart of a LazyChain is just an array of thunks, I can change the constructor to concatenate the arrays when presented with another LazyChain as its argument:

function LazyChainChainChain(obj) {
  var isLC = (obj instanceof LazyChain);

  this._calls  = isLC ? cat(obj._calls, []) : [];
  this._target = isLC ? obj._target : obj;
}

LazyChainChainChain.prototype = LazyChain.prototype;

That is, if the argument to the constructor is another LazyChain instance, then just steal its call chain and target object. Observe the chaining of chains:

new LazyChainChainChain(deferredSort)
  .invoke('toString')
  .force();

// an alert box pops up
//=> "1,2,3"

Allowing chains to compose in this way is a very powerful idea. It allows you to build up a library of discrete behaviors without worrying about the final result. There are other ways to enhance LazyChain, such as caching the result and providing an interface that does not rely on strings, but I leave that as an exercise for the reader.

While LazyChain and LazyChainChainChain are useful for packaging the description of a computation for later execution, jQuery^[92] provides something called a promise that works similarly, but slightly differently. That is, jQuery promises are intended to provide a fluent API for sequencing asynchronous operations that run concurrent to the main program logic.

First, the simplest way to look at a promise is that it represents an unfulfilled activity. As shown in the following code, jQuery allows the creation of promises via $.Deferred:

var longing = $.Deferred();

I can now grab a promise from the Deferred:

longing.promise();
//=> Object

The object returned is the handle to the unfulfilled action:

longing.promise().state();
//=> "pending"

As shown, the promise is in a holding pattern. The reason for this is of course that the promise was never fulfilled. I can do so simply by resolving it:

longing.resolve("<3");

longing.promise().state();
//=> "resolved"

At this point, the promise has been fulfilled and the value is accessible:

longing.promise().done(note);
// NOTE: <3
//=> <the promise itself>

The Deferred#done method is just one of many useful chaining methods available in the promise API. I will not go into depth about jQuery promises, but a more complicated example could help to show how they differ from lazy chains. One way to build a promise in jQuery is to use the $.when function to start a promise chain, as shown here:

function go() {
  var d = $.Deferred();

  $.when("")
   .then(function() {
     setTimeout(function() {
       console.log("sub-task 1");
     }, 5000)
   })
   .then(function() {
     setTimeout(function() {
       console.log("sub-task 2");
     }, 10000)
   })
   .then(function() {
     setTimeout(function() {
       d.resolve("done done done done");
     }, 15000)
   })

  return d.promise();
}

The promise chain built in the go function is very simple-minded. That is, all I’ve done is to tell jQuery to kick off three asynchronous tasks, each delayed by increasingly longer timings. The Deferred#then methods each take a function and execute them immediately. Only in the longest-running task is the Deferred instance resolved. Running go illustrates this example:

var yearning = go().done(note);

I tacked on a done call to the promise that will get called whenever the promise is resolved. However, immediately after running go, nothing appears to have happened. That’s because due to the timeouts in the subtasks, the console logging has not yet occurred. I can check the promise state using the aptly named state method:

yearning.state();
//=> "pending"

As you might expect, the state is still pending. After a few seconds, however:

// (console) sub-task 1

The timeout of the first subtask triggers and a notification is printed to the console.

yearning.state();
//=> "pending"

Of course, because the other two actions in the original promise chain are awaiting timeouts, the state is still pending. However, again waiting for some number of seconds to pass shows the following:

// (console) sub-task 2

// ... ~5 seconds later

// NOTE: done done done done

Eventually, the final link in the deferred chain is called, and the done notification is printed by the note function. Checking the state one more time reveals the following:

yearning.state();
//=> "resolved"

Of course, the promise has been resolved because the final subtask ran and called resolve on the original Deferred instance. This sequence of events is very different from that presented using LazyChain. That is, a LazyChain represents a strict sequence of calls that calculate a value. Promises, on the other hand, also represent a sequence of calls, but differ in that once they are executed, the value is available on demand.

Further, jQuery’s promise API is meant to define aggregate tasks composed of some number of asynchronous subtasks. The subtasks themselves execute, as possible, concurrently. However, the aggregate task is not considered completed until every subtask has finished and a value is delivered to the promise via the resolve method.

A lazy chain also represents an aggregate task composed of subtasks, but they, once forced, are always run one after the other. The difference between the two can be summarized as the difference between aggregating highly connected tasks (LazyChain) versus loosely related (Deferred) tasks.

Most of jQuery’s asynchronous API calls now return promises, so the result of an async call is chainable according to the promise API. However, the complete specification of this API is outside the scope of this book.

The complication in determining a common shape to flow between nodes of a different sort is not picking a type (a regular object will do), but what to put into it. One choice is the data that flows between each node; in the negativeSqr example, the object would look like the following:

{values: [42, 1764, undefined, -1764]}

But what else is needed? I would say that a useful piece of data to keep around would be the state, or target object used as the common target between nodes. Figure 8-9 shows a way to visualize how actions could be composed, even in the face of disparate input and output shapes.

Figure 8-9. The shape flowing between actions is made to be stable using a context object

The last node (i.e., results) operates much in the same way as force in that it pulls the answer out of the action object into the real world. In the case of the negativeSqr function, the way to get the final answer is to retrieve the last element of the values element or just return the state:

{values: [42, 1764, undefined, -1764],
 state:  -1764}

Now, the implementation of the actions function to manage these intermediate states is a hybrid of the pipeline and lazyChain implementations, as shown here:

function actions(acts, done) {
  return function (seed) {
    var init = { values: [], state: seed };

    var intermediate = _.reduce(acts, function (stateObj, action) {
      var result = action(stateObj.state);
      var values = cat(stateObj.values, [result.answer]);

      return { values: values, state: result.state };
    }, init);

    var keep = _.filter(intermediate.values, existy);

    return done(keep, intermediate.state);
  };
};

The actions function expects an array of functions, each taking a value and returning a function that augments the intermediate state object. The actions function then reduces over all of the functions in the array and builds up an intermediate state object, as shown here:

...
    var intermediate = _.reduce(acts, function (stateObj, action) {
      var result = action(stateObj.state);
      var values = cat(stateObj.values, [result.answer]);

      return { values: values, state: result.state };
    }, init);
...

During this process, actions expects the result from each function to be an object of two keys: answer and state. The answer value corresponds to the result of calling the function and the state value represents what the new state looks like after the “action” is performed. For a function like note, the state does not change. The intermediate state object might have some bogus answers in it (e.g., the answer of note is undefined), so actions filters those out:

...
    var keep = _.filter(intermediate.values, existy);

    return done(keep, intermediate.state);
...

Finally, actions passes the filtered values (called keep) and state into the done function to garner a final result. I could have only passed the state or values into the done function, but I like to pass both for maximum flexibility, and because it helps for illustration.

To demonstrate how actions works, I’ll need to break apart negativeSqr and recompose it as a series of actions. First, the sqr function obviously doesn’t know anything about a state object, so I’ll need to create an adapter function, called mSqr:^[98]

function mSqr() {
  return function(state) {
    var ans = sqr(state);
    return {answer: ans, state: ans};
  }
}

I can now use actions just to perform a double-squaring operation:

var doubleSquareAction = actions(
  [mSqr(),
   mSqr()],
  function(values) {
    return values;
});

doubleSquareAction(10);
//=> [100, 10000]

Since I returned the values array directly, the result of doubleSquareAction is all of the intermediate states (specifically the square of 10 and the square of the square of 10). However, this is almost the same as pipeline. The real magic comes when mixing functions of differing shapes:

function mNote() {
  return function(state) {
    note(state);
    return {answer: undefined, state: state};
  }
}

The answer of the mNote function is, of course, undefined, since it is a function used for printing; however, the state is just passed along. The mNeg function should by now seem apparent:

function mNeg() {
  return function(state) {
    return {answer: -state, state: -state};
  }
}

And now composing these new functions into actions is shown here:

var negativeSqrAction = actions([mSqr(), mNote(), mNeg()],
  function(_, state) {
    return state;
  });

Its usage is shown here:

negativeSqrAction(9);
// NOTE: 81
//=> -81

Using the actions paradigm for composition is a general way to compose functions of different shapes. Sadly, the preceding code seems like a lot of ceremony to achieve the effects needed. Fortunately, there is a better way to define an action, without needing to know the details of how a state object is built and avoiding the pile of boilerplate that goes along with that knowledge.

In this section, I’ll define a function, lift, that takes two functions: a function to provide the result of some action given a value, and another function to provide what the new state looks like. The lift function will be used to abstract away the management of the state object used as the intermediate representation of actions. The implementation of lift is quite small:

function lift(answerFun, stateFun) {
  return function(/* args */) {
    var args = _.toArray(arguments);

    return function(state) {
      var ans = answerFun.apply(null, construct(state, args));
      var s = stateFun ? stateFun(state) : ans;

      return {answer: ans, state: s};
    };
  };
};

lift looks like it’s curried (i.e., it returns a function), and indeed it is. There is no reason to curry lift except to provide a nicer interface, as I’ll show in a moment. In fact, using lift, I can more nicely redefine mSqr, mNote, and mNeg:

var mSqr2  = lift(sqr);
var mNote2 = lift(note, _.identity);
var mNeg2  = lift(function(n) { return -n });

In the case of sqr and the negation function, both the answer and the state are the same value, so I only needed to supply the answer function. In the case of note, however, the answer (undefined) is clearly not the state value, so using _.identity allows me to specify that it’s a pass-through action.

The new actions compose via actions:

var negativeSqrAction2 = actions([mSqr2(), mNote2(), mNeg2()],
  function(_, state) {
    return state;
  });

And their usage is the same as before:

negativeSqrAction(100);
// NOTE: 10000
//=> -10000

If I want to use lift and actions to implement a stackAction, then I could do so as follows:

var push = lift(function(stack, e) { return construct(e, stack) });

The push function returns a new array, masquerading as a stack, with the new element at the front. Since the intermediate state is also the answer, there is no need to supply a state function. The implementation of pop needs both:

var pop = lift(_.first, _.rest);

Since I’m simulating a stack via an array, the pop answer is the first element. Conversely, the state function _.rest return the new stack with the top element removed. I can now use these two functions to compose two pushes and one pop, as follows:

var stackAction = actions([
  push(1),
  push(2),
  pop()
  ],
  function(values, state) {
    return values;
  });

Amazingly, by using the actions function, I’ve captured the sequence of stack events as a value that has not yet been realized. To realize the result is as simple as this:

stackAction([]);

//=> [[1], [2, 1], 2]

As shown, the stackAction is just a function and can now be composed with other functions to build higher-level behaviors. Since I’ve decided to return all of the intermediate answers, the resulting return value can participate in a vast array of composition scenarios:

pipeline(
  []
  , stackAction
  , _.chain)
.each(function(elem) {
  console.log(polyToString(elem))
});

// (console) [[1],      // the stack after push(1)
// (console)  [2, 1],   // the stack after push(2)
// (console)  2]        // the result of pop([2, 1])

This is almost like magic, but by deconstructing it, I’ve tried to show that it really isn’t magical at all. Instead, composing functions of different shapes is possible using a common intermediate type and a couple of functions—lift and actions—to manage them along the way. This management allows me to convert a problem that would typically be a problem of control flow in keeping the types straight, into a problem of data flow—the whole point of this chapter (Piponi 2010).