What does the lodash flow function do?

Question

I am reading some code that uses _.flow() from lodash and the explanation in the docs just isn't making sense to me.

The doc says

Creates a function that returns the result of invoking the given functions with the this binding of the created function, where each successive invocation is supplied the return value of the previous.

With the example:

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

var addSquare = _.flow([_.add, square]);
addSquare(1, 2);
// => 9

I have read this a few times and I can not work out what it means or how that function returns 9. The closest think I can think of is folding in functional programming but this doesn't look like that. Is there any alternative way of explaining what flow does?

Answer 1

Rewording the definition from the docs in simpler terms: It calls, in order, the methods in the array. It uses the result from each function as the parameters for the next function. In the case of the example given, the steps are as follows:

1. Invokes _.add(1, 2), which returns 3.
2. Passes that return value as the parameter to the next function in the array, which becomes square(3). This returns 9.

Answer 2

Here is the relevant part of the source code for this function:

return function(...args) {
    let index = 0
    let result = length ? funcs[index].apply(this, args) : args[0]
    while (++index < length) {
        result = funcs[index].call(this, result)
    }
    return result
}

So it first applies the first function to the input arguments; then calls the rest of the functions with each taking up the result of the previous stage.

I can see the following benefits from doing it this way: - All the applied functions will use the this argument of the caller in case that is desired. - On definition, it just returns a function. This allows for lazy evaluation. The flow function can be passed around. The actual calculation will take place only when it is applied to the arguments.