Can't wrap my head around "lift" in Ramda.js

Bergi's answer is great. But another way to think about this is to get a little more specific. Ramda really needs to include a non-list example in its documentation, as lists don't really capture this.

Lets take a simple function:

var add3 = (a, b, c) => a + b + c;

This operates on three numbers. But what if you had containers holding numbers? Perhaps we have Maybes. We can't simply add them together:

const Just = Maybe.Just, Nothing = Maybe.Nothing;
add3(Just(10), Just(15), Just(17)); //=> ERROR!

(Ok, this is Javascript, it will not actually throw an error here, just try to concatenate thing it shouldn't... but it definitely doesn't do what you want!)

If we could lift that function up to the level of containers, it would make our life easier. What Bergi pointed out as lift3 is implemented in Ramda with liftN(3, fn), and a gloss, lift(fn) that simply uses the arity of the function supplied. So, we can do:

const madd3 = R.lift(add3);
madd3(Just(10), Just(15), Just(17)); //=> Just(42)
madd3(Just(10), Nothing(), Just(17)); //=> Nothing()

But this lifted function doesn't know anything specific about our containers, only that they implement ap. Ramda implements ap for lists in a way similar to applying the function to the tuples in the crossproduct of the lists, so we can also do this:

madd3([100, 200], [30, 40], [5, 6, 7]);
//=> [135, 136, 137, 145, 146, 147, 235, 236, 237, 245, 246, 247]

That is how I think about lift. It takes a function that works at the level of some values and lifts it up to a function that works at the level of containers of those values.

Thanks to the answers from Scott Sauyet and Bergi, I wrapped my head around it. In doing so, I felt there were still hoops to jump to put all the pieces together. I will document some questions I had in the journey, hope it could be of help to some.

Here's the example of R.lift we try to understand:

var madd3 = R.lift((a, b, c) => a + b + c);
madd3([1,2,3], [1,2,3], [1]); //=> [3, 4, 5, 4, 5, 6, 5, 6, 7]

To me, there are three questions to be answered before understanding it.

1. Fantasy-land's Apply spec (I will refer to it as Apply) and what Apply#ap does
2. Ramda's R.ap implementation and what does Array has to do with the Apply spec
3. What role does currying play in R.lift

Understanding the Apply spec

In fantasy-land, an object implements Apply spec when it has an ap method defined (that object also has to implement Functor spec by defining a map method).

The ap method has the following signature:

ap :: Apply f => f a ~> f (a -> b) -> f b

In fantasy-land's type signature notation:

• => declares type constraints, so f in the signature above refers to type Apply
• ~> declares method declaration, so ap should be a function declared on Apply which wraps around a value which we refer to as a (we will see in the example below, some fantasy-land's implementations of ap are not consistent with this signature, but the idea is the same)

Let's say we have two objects v and u (v = f a; u = f (a -> b)) thus this expression is valid v.ap(u), some things to notice here:

• v and u both implement Apply. v holds a value, u holds a function but they have the same 'interface' of Apply (this will help in understanding the next section below, when it comes to R.ap and Array)
• The value a and function a -> b are ignorant of Apply, the function just transforms the value a. It's the Apply that puts value and function inside the container and ap that extracts them out, invokes the function on the value and puts them back in.

Understanding Ramda's R.ap

The signature of R.ap has two cases:

1. Apply f => f (a → b) → f a → f b: This is very similar to the signature of Apply#ap in last section, the difference is how ap is invoked (Apply#ap vs. R.ap) and the order of params.
2. [a → b] → [a] → [b]: This is the version if we replace Apply f with Array, remember that the value and function has to be wrapped in the same container in the previous section? That's why when using R.ap with Arrays, the first argument is a list of functions, even if you want to apply only one function, put it in an Array.

Let's look at one example, I'm using Maybe from ramada-fantasy, which implements Apply, one inconsistency here is that Maybe#ap's signature is: ap :: Apply f => f (a -> b) ~> f a -> f b. Seems some other fantasy-land implementations also follow this, however, it shouldn't affect our understanding:

const R = require('ramda');
const Maybe = require('ramda-fantasy').Maybe;

const a = Maybe.of(2);
const plus3 = Maybe.of(x => x + 3);
const b = plus3.ap(a);  // invoke Apply#ap
const b2 = R.ap(plus3, a);  // invoke R.ap

console.log(b);  // Just { value: 5 }
console.log(b2);  // Just { value: 5 }

Understanding the example of R.lift

In R.lift's example with arrays, a function with arity of 3 is passed to R.lift: var madd3 = R.lift((a, b, c) => a + b + c);, how does it work with the three arrays [1, 2, 3], [1, 2, 3], [1]? Also note that it's not curried.

Actually inside source code of R.liftN (which R.lift delegates to), the function passed in is auto-curried, then it iterates through the values (in our case, three arrays), reducing to a result: in each iteration it invokes ap with the curried function and one value (in our case, one array). It's hard to explain in words, let's see the equivalent in code:

const R = require('ramda');

const madd3 = (x, y, z) => x + y + z;

// example from R.lift
const result = R.lift(madd3)([1, 2, 3], [1, 2, 3], [1]);

// this is equivalent of the calculation of 'result' above,
// R.liftN uses reduce, but the idea is the same
const result2 = R.ap(R.ap(R.ap([R.curry(madd3)], [1, 2, 3]), [1, 2, 3]), [1]);

console.log(result);  // [ 3, 4, 5, 4, 5, 6, 5, 6, 7 ]
console.log(result2);  // [ 3, 4, 5, 4, 5, 6, 5, 6, 7 ]

Once the expression of calculating result2 is understood, the example will become clear.

Here's another example, using R.lift on Apply:

const R = require('ramda');
const Maybe = require('ramda-fantasy').Maybe;

const madd3 = (x, y, z) => x + y + z;
const madd3Curried = Maybe.of(R.curry(madd3));
const a = Maybe.of(1);
const b = Maybe.of(2);
const c = Maybe.of(3);
const sumResult = madd3Curried.ap(a).ap(b).ap(c);  // invoke #ap on Apply
const sumResult2 = R.ap(R.ap(R.ap(madd3Curried, a), b), c);  // invoke R.ap
const sumResult3 = R.lift(madd3)(a, b, c);  // invoke R.lift, madd3 is auto-curried

console.log(sumResult);  // Just { value: 6 }
console.log(sumResult2);  // Just { value: 6 }
console.log(sumResult3);  // Just { value: 6 }

A better example suggested by Scott Sauyet in the comments (he provides quite some insights, I suggest you read them) would be easier to understand, at least it points the reader to the direction that R.lift calculates the Cartesian product for Arrays.

var madd3 = R.lift((a, b, c) => a + b + c);
madd3([100, 200], [30, 40, 50], [6, 7]); //=> [136, 137, 146, 147, 156, 157, 236, 237, 246, 247, 256, 257]

Hope this helps.

lift/liftN "lifts" an ordinary function into an Applicative context.

// lift1 :: (a -> b) -> f a -> f b
// lift1 :: (a -> b) -> [a] -> [b]
function lift1(fn) {
    return function(a_x) {
        return R.ap([fn], a_x);
    }
}

Now the type of ap (f (a->b) -> f a -> f b) isn't easy to understand either, but the list example should be understandable.

The interesting thing here is that you pass in a list and get back a list, so you can repeatedly apply this as long as the function(s) in the first list have the correct type:

// lift2 :: (a -> b -> c) -> f a -> f b -> f c
// lift2 :: (a -> b -> c) -> [a] -> [b] -> [c]
function lift2(fn) {
    return function(a_x, a_y) {
        return R.ap(R.ap([fn], a_x), a_y);
    }
}

And lift3, which you implicitly used in your example, works the same - now with ap(ap(ap([fn], a_x), a_y), a_z).