You’ve already been exposed to examples of functions implemented in an imperative fashion, and you will continue to see more as the book progresses. While often it’s ideal to write code in a functional way, there are times when the primitives of a library, for the sake of speed or expediency, should be implemented using imperative techniques. Functions are quanta of abstraction, and the most important part of any given function is that it adheres to its contract and fulfills a requirement. No one cares if a variable was mutated deep within the confines of a function and never escaped. Mutation is sometimes necessary, but I view it as a low-level operation—one that should be kept out of sight and out of mind.

This book is not about spewing dogma regarding the virtues of functional programming. I think there are many functional techniques that offer ways to rein in the complexities of software development, but I realize that at times, there are better ways to implement any given individual part (Figure 5-1).

Figure 5-1. An “evolved” programmer knows when to use the right tool

Whenever you’re building an application, it’s always wise to explore the parameters of your personal execution needs to determine if a given implementation technique is appropriate. This book, while about functional programming, advocates above all else a full understanding of your problem and solution spaces to come to an understanding of your best-possible solution. I will discuss this theme throughout Chapter 7, but for now I present a recipe for delicious curry!^[54]

The direction that you curry doesn’t really matter, but the choice will have some implications on your API. For the purposes of this book (and my preference in general), I will curry starting at the rightmost argument and move left. In a language like JavaScript that allows you to pass any number of arguments, right-to-left currying allows you to fix the optional arguments to certain values.

To illustrate what I mean by the difference in argument direction, observe the following two functions:

function leftCurryDiv(n) {
  return function(d) {
    return n/d;
  };
}

function rightCurryDiv(d) {
  return function(n) {
    return n/d;
  };
}

The use of a division operation to illustrate currying works nicely because the result changes if the arguments are switched (i.e., it’s not associative). Using the leftCurryDiv function, observe how the curried parameters produce a result:

var divide10By = leftCurryDiv(10);

The function produced on the initial call, with 10 named divide10By, produces a function that, for all intents and purposes, contains a body pertaining to 10 / ?, where ? is the curried rightmost parameter awaiting a value on the next call:

divide10By(2);
//=> 5

The second invocation of the curried function (named divide10By) now executes the fully populated body 10 / 2, resulting in the value 5. However, if the rightCurryDiv function is used, the behavior changes:

var divideBy10 = rightCurryDiv(10);

Now the body of the curried function named divideBy10 is instead ? / 10, awaiting the leftmost argument before executing:

divideBy10(2);
//=> 0.2

As I mentioned, I will begin currying from the rightmost argument, so my calculations will operate as shown in Figure 5-2.

Another reason for currying from the right is that partial application handles working from the left (partial application will be discussed in greater depth in the next section). Between partial application and currying, I have both directions covered, allowing the full range of parameter specialization. Having said all of that, I’ll presently implement a few functions both manually curried (as in leftCurryDiv and rightCurryDiv) and with an auto-currying function or two that I’ll also implement.

The functions over10 and divideBy10 were both curried by hand. That is, I explicitly wrote the functions to return the right number of functions corresponding to the number of function parameters. Likewise, for the purposes of illustration, my function rightCurryDiv returned a function corresponding to a division function taking two logical arguments. However, there is value in a simple higher-order function that takes a function and returns a function “pinned” to receive only one argument; I’ll call this function curry and implement it as follows:

function curry(fun) {
  return function(arg) {
    return fun(arg);
  };
}

The operation of curry can be summarized as follows:

This seems like a fairly useless function, no? Why not simply use the function directly instead? In many functional programming languages, there are few compelling reasons to provide an unadorned delegation like curry provides, but in JavaScript the story is slightly different. Very often in JavaScript, functions will take some number of expected arguments and an additional number of “specialization” arguments. For example, the JavaScript function parseInt takes a string and returns its equivalent integer:

parseInt('11');
//=> 11

Additionally, parseInt will accept a second argument that defines the radix to use when parsing (i.e., the number base):

parseInt('11', 2);
//=> 3

The preceding call, given a radix value of 2, means that the number is parsed as a binary (base-2) number. Complications arise using parseInt in a first-class way because of that optional second argument, as shown here:

['11','11','11','11'].map(parseInt)
//=> [11, NaN, 3, 4]

The problem here is that in some versions of JavaScript, the function given to Array#map will be invoked with each element of the array, the index of the element, plus the array itself.^[55] So as you might have guessed, the radix argument for parseInt starts with 0 and then becomes 1, 2, and then 3. Ouch! Thankfully, using curry, you can force parseInt to receive only one argument on each call:

['11','11','11','11'].map(curry(parseInt));
//=> [11, 11, 11, 11]

I could have just as easily written a function that takes an arbitrary number of arguments and figures out how to curry the remaining arguments, but I like to be explicit when currying. The reason is that the use of a function like curry allows me to explicitly control the behavior of the function being called by fixing (or ignoring) the optional right-leaning arguments used for specialization.

Take, for example, the act of currying two function parameters using a curry2 function, defined as such:

function curry2(fun) {
  return function(secondArg) {
    return function(firstArg) {
      return fun(firstArg, secondArg);
    };
  };
}

The curry2 function takes a function and curries it up to two parameters deep. Using it to implement a version of the previously defined divideBy10 function is shown here:

function div(n, d) { return n / d }

var div10 = curry2(div)(10);

div10(50);
//=> 5

Just like rightCurryDiv, the div10 function awaits its first argument with a logical body corresponding to ? / 10. And just for the sake of completion, curry2 can also be used to fix the behavior of parseInt so that it handles only binary numbers when parsing:

var parseBinaryString = curry2(parseInt)(2);

parseBinaryString("111");
//=> 7

parseBinaryString("10");
//=> 2

Currying is a useful technique for specifying the specialized behavior of JavaScript functions and for “composing” new functions from existing functions, as I’ll show next.

var plays = [{artist: "Burial", track: "Archangel"},
             {artist: "Ben Frost", track: "Stomp"},
             {artist: "Ben Frost", track: "Stomp"},
             {artist: "Burial", track: "Archangel"},
             {artist: "Emeralds", track: "Snores"},
             {artist: "Burial", track: "Archangel"}];

_.countBy(plays, function(song) {
  return [song.artist, song.track].join(" - ");
});

//=> {"Ben Frost - Stomp": 2,
//    "Burial - Archangel": 3,
//    "Emeralds - Snores": 1}

function songToString(song) {
  return [song.artist, song.track].join(" - ");
}

var songCount = curry2(_.countBy)(songToString);

songCount(plays);
//=> {"Ben Frost - Stomp": 2,
//    "Burial - Archangel": 3,
//    "Emeralds - Snores": 1}

function curry3(fun) {
  return function(last) {
    return function(middle) {
      return function(first) {
        return fun(first, middle, last);
      };
    };
  };
};

var songsPlayed = curry3(_.uniq)(false)(songToString);

songsPlayed(plays);

//=> [{artist: "Burial", track: "Archangel"},
//    {artist: "Ben Frost", track: "Stomp"},
//    {artist: "Emeralds", track: "Snores"}]

       _.uniq(plays, false,  songToString);

curry3(_.uniq)      (false) (songToString);

function toHex(n) {
  var hex = n.toString(16);
  return (hex.length < 2) ? [0, hex].join(''): hex;
}

function rgbToHexString(r, g, b) {
  return ["#", toHex(r), toHex(g), toHex(b)].join('');
}

rgbToHexString(255, 255, 255);
//=> "#ffffff"

var blueGreenish = curry3(rgbToHexString)(255)(200);

blueGreenish(0);
//=> "#00c8ff"

A tangential benefit of currying is that it very oftens lead to fluent functional APIs. In the Haskell programming language, functions are curried by default, so libraries naturally take advantage of that fact. In JavaScript, however, functional APIs must be designed to take advantage of currying and must be documented to show how. However, a general-purpose rule when determining if currying is an appropriate tool for any given circumstance is this: does the API utilize higher-order functions? If the answer is yes, then curried functions, at least to one parameter, are appropriate. Take, for example, the checker function built in Chapter 4. It indeed accepts a function as an argument used to check the validity of a value. Using curried functions to build a fluent checker call is as simple as this:

var greaterThan = curry2(function (lhs, rhs) { return lhs > rhs });
var lessThan    = curry2(function (lhs, rhs) { return lhs < rhs });

By currying two functions that calculate greater-than and less-than, the curried version can be used directly where validator expects a predicate:

var withinRange = checker(
  validator("arg must be greater than 10", greaterThan(10)),
  validator("arg must be less than 20", lessThan(20)));

This use of curried functions is much easier on the eyes than directly using the anonymous versions of the greater-than and less-than calculations. Of course, the withinRange checker works as you might expect:

withinRange(15);
//=> []

withinRange(1);
//=> ["arg must be greater than 10"]

withinRange(100);
//=> ["arg must be less than 20"]

So as you might agree, the use of curried functions can provide tangible benefits in creating fluent interfaces. The closer your code gets to looking like a description of the activity that it’s performing, the better. I will strive to achieve this condition throughout the course of this book.

While it’s nice to provide both curry2 and curry3, perhaps it would be better to provide a function named curryAll that curries at an arbitrary depth. In fact, creating such a function is possible, but in my experience it’s not very practical. In a programming language like Haskell or Shen, where functions are curried automatically, APIs are built to take advantage of arbitrarily curried functions. That JavaScript allows a variable number of arguments to functions actively works against currying in general and is often confusing. In fact, the Underscore library offers a plethora of different function behaviors based on the type and count of the arguments provided to many of its functions, so currying, while not impossible, must be applied with careful attention.

The use of curry2 and curry3 is occasionally useful, and in the presence of an API designed for currying, they can be an elegant approach to functional composition. However, I find it much more common to partially apply functions at arbitrary depths than to curry them, which is what I will discuss next.

Like currying, a discussion of partial application is best started simply. A function that partially applies its first argument is written as follows:^[57]

function partial1(fun, arg1) {
  return function(/* args */) {
    var args = construct(arg1, arguments);
    return fun.apply(fun, args);
  };
}

Observe that the function returned from partial1 captures the argument arg1 from the original call and puts it at the front of the arglist of the executing call. You can see this operation in action in the following:

var over10Part1 = partial1(div, 10);

over10Part1(5);
//=> 2

So again, I’ve re-created the operation of the over10 function by composing a function from another function and a “configuration” argument.^[58] A function to partially apply up to two arguments is implemented similarly:

function partial2(fun, arg1, arg2) {
  return function(/* args */) {
    var args = cat([arg1, arg2], arguments);
    return fun.apply(fun, args);
  };
}

var div10By2 = partial2(div, 10, 2)

div10By2()
//=> 5

Partially applying one or two arguments is typically what you’ll see in practice, but it would be useful to instead capture an arbitrary number of arguments for later execution, as I’ll explain presently.

Unlike currying, which is complicated by varargs in JavaScript, partial application of an arbitrary number of arguments is a legitimate composition strategy. Thankfully, the implementation of a function partial is not significantly more complex than either partial1 nor partial2. In fact, the same basic implementation premise applies:

function partial(fun /*, pargs */) {
  var pargs = _.rest(arguments);

  return function(/* arguments */) {
    var args = cat(pargs, _.toArray(arguments));
    return fun.apply(fun, args);
  };
}

As you might have noticed, the principle is the same: partial captures some number of arguments and returns a function that uses them as the prefix arguments for its final call.^[59] In action, partial works exactly as you might expect:

var over10Partial = partial(div, 10);
over10Partial(2);
//=> 5

While the presence of varargs in JavaScript does not completely defeat the usefulness of partial application, it can still complicate matters, as shown below:^[60]

var div10By2By4By5000Partial = partial(div, 10, 2, 4, 5000);
div10By2By4By5000Partial();
//=> 5

While you might be aware that a number that you’re attempting to partially apply expects a fixed number of arguments, the fact that it will accept any number can at times cause confusion. In fact, the partially applied div function is just called one time with the arguments 10 and 2, and the remaining arguments are simply ignored. Adding partial application as a level of misdirection only exacerbates the confusion. The good news is that I’ve rarely run into this problem in practice.

Recall the validator function from Chapter 4:

validator("arg must be a map", aMap)(42);
//=> false

The validator higher-order function takes a validation predicate and returns an array of the errors encountered along the way. If the error array is empty, then there were no reported errors. validator can also be used for more general purposes, such as the manual validation of arguments to functions:

var zero = validator("cannot be zero", function(n) { return 0 === n });
var number = validator("arg must be a number", _.isNumber);

function sqr(n) {
  if (!number(n)) throw new Error(number.message);
  if (zero(n))    throw new Error(zero.message);

  return n * n;
}

Calls to the sqr function are checked as such:

sqr(10);
//=> 100

sqr(0);
// Error: cannot be zero

sqr('');
// Error: arg must be a number

This is fairly nice to my eyes, but it can be even better using partial application. While there is certainly a class of errors that fall within the purview of essential data-check failures, there is another set of errors that do not. That is, there is a class of errors that pertains to the guarantees of a computation. In the latter case, you would say that there are two types of guarantees:

In English, the relationship between pre- and postconditions is described as follows: given that you’ve provided a function data that it can handle, it will ensure that the return meets a specific criteria.

I showed one function—sqr—that had two preconditions pertaining to the “numberness” and “zeroness” of its lone argument. We could check these conditions every single time, and that might be fine, but really they refer to a guarantee of sqr relative to the context of a running application. Therefore, I can use a new function, condition1, and partial application to attach the preconditions separately from essential calculations:

function condition1(/* validators */) {
  var validators = _.toArray(arguments);

  return function(fun, arg) {
    var errors = mapcat(function(isValid) {
      return isValid(arg) ? [] : [isValid.message];
    }, validators);

    if (!_.isEmpty(errors))
      throw new Error(errors.join(", "));

    return fun(arg);
  };
}

You’ll notice that the function returned from condition1 is meant to take only a single argument. This is done primarily for illustrative purposes, as the vararg version is a bit more complicated and obfuscates the point I’m trying to make.^[61] The point is that the function returned by condition1 takes a function and a set of functions, each created with validator, and either builds an Error or returns the value of the execution of fun. This is a very simple but powerful pattern, used as shown here:

var sqrPre = condition1(
  validator("arg must not be zero", complement(zero)),
  validator("arg must be a number", _.isNumber));

This is a very fluent validation API, as far as JavaScript goes. Very often you’ll find that, through function composition, your code becomes more declarative (i.e., it says what it’s supposed to do rather than how). A run-through of the operation of sqrPre bears out the operation of condition1:

sqrPre(_.identity, 10);
//=> 10

sqrPre(_.identity, '');
// Error: arg must be a number

sqrPre(_.identity, 0);
// Error: arg must not be zero

Recalling the definition of sqr, with its built-in error handling, you might have guessed how we can use sqrPre to check its arguments. If not, then imagine an “unsafe” version of sqr defined as follows:

function uncheckedSqr(n) { return n * n };

uncheckedSqr('');
//=> 0

Clearly, the square of the empty string shouldn’t be 0, even if it can be explained by JavaScript’s foibles. Thankfully, I’ve been building a set of tools, realized in the creation of validator, partial1, condition1, and sqrPre, to solve this particular problem, shown here:^[62]

var checkedSqr = partial1(sqrPre, uncheckedSqr);

The creation of the new function checkedSqr was fully formed through the creation of functions, function-creating functions, and their interplay to build functions anew:

checkedSqr(10);
//=> 100

checkedSqr('');
// Error: arg must be a number

checkedSqr(0);
// Error: arg must not be zero

As shown in the preceding code, the new checkedSqr works exactly like sqr, except that by separating the validity checks from the main calculation, I’ve achieved an ideal level of flexibility. That is, I can now turn off condition checking altogether by not applying conditions to functions at all, or even mix in additional checks at a later time:

var sillySquare = partial1(
  condition1(validator("should be even", isEven)),
  checkedSqr);

Because the result of condition1 is a function expecting another function to delegate to, the use of partial1 combines the two:

sillySquare(10);
//=> 100

sillySquare(11);
// Error: should be even

sillySquare('');
// Error: arg must be a number

sillySquare(0);
// Error: arg must not be zero

Now obviously you wouldn’t want to constrain the squaring of numbers to such a silly degree, but I hope the point is clear. The functions that compose other functions should themselves compose. Before moving on to the next section, it’s worth taking a step back and seeing how to re-implement the command object (from Chapter 4) creation logic with validation:

var validateCommand = condition1(
  validator("arg must be a map", _.isObject),
  validator("arg must have the correct keys", hasKeys('msg', 'type')));

var createCommand = partial(validateCommand, _.identity);

Why use the _.identity function as the logic part of the createCommand function? In JavaScript, much of the safety that we achieve is built via discipline and careful thinking. In the case of createCommand, the intention is to provide a common gateway function used for creating and validating command objects, as shown below:

createCommand({});
// Error: arg must have right keys

createCommand(21);
// Error: arg must be a map, arg must have right keys

createCommand({msg: "", type: ""});
//=> {msg: "", type: ""}

However, using functional composition allows you to later build on top of the existing creation abstraction in order to customize the actual building logic or the validation itself. If you wanted to build a derived command type that required the existence of another key, then you would further compose with the following:

var createLaunchCommand = partial1(
  condition1(
    validator("arg must have the count down", hasKeys('countDown'))),
  createCommand);

And as you might expect, createLaunchCommand works as follows:

createCommand({msg: "", type: ""});
// Error: arg must have the count down

createCommand({msg: "", type: "", countDown: 10});
//=> {msg: "", type: "", countDown: 10}

Whether you use currying or partial application to build functions, there is a common limitation on both: they only compose based on the specialization of one or more of their arguments. However, it’s conceivable that you might want to compose functions based on the relationships between their arguments and their return values. In the next section, I will talk about a compose function that allows the end-to-end stitching of functions.

If you recall from the previous section, I mentioned that preconditions define the constraints under which a function’s operation will produce a value adhering to a different set of constraints. These production constraints are called postconditions. Using condition1 and partial, I was able to build a function (checkedSqr) that checked the input arguments to uncheckedSqr for conformance to its preconditions. However, if I want to define the postconditions of the act of squaring, then I need to define them using condition1 as such:

var sqrPost = condition1(
  validator("result should be a number", _.isNumber),
  validator("result should not be zero", complement(zero)),
  validator("result should be positive", greaterThan(0)));

I can run through each error case manually using the following:

sqrPost(_.identity, 0);
// Error: result should not be zero, result should be positive

sqrPost(_.identity, -1);
// Error: result should be positive

sqrPost(_.identity, '');
// Error: result should be a number, result should be positive

sqrPost(_.identity, 100);
//=> 100

But the question arises: how can I glue the postcondition check function onto the existing uncheckedSqr and sqrPre? The answer, of course, is to use _.compose for the glue: ^[64]

var megaCheckedSqr = _.compose(partial(sqrPost, _.identity), checkedSqr);

And its use is exactly the same as checkedSqr:

megaCheckedSqr(10);
//=> 100

megaCheckedSqr(0);
// Error: arg must not be zero

Except:

megaCheckedSqr(NaN);
// Error: result should be positive

Of course, if the function ever throws a postcondition error, then that means that either my preconditions are under-specified, my postconditions are over-specified, or my internal logic is busted. As the provider of a function, a post-condition failure is always my fault.