Underscore.js _.tap() function what is a method chain?

Question

The Underscore.js documentation explains that the _.tap() function "taps" into a method chain. http://underscorejs.org/#tap

I have trouble following their example:

_.chain([1,2,3,200])
  .filter(function(num) { return num % 2 == 0; })
  .tap(alert)
  .map(function(num) { return num * num })
  .value();
=> // [2, 200] (alerted)
=> [4, 40000]

What is the method chain in this context? I always thought of method chaining as the concept of chaining methods off of one another: object.foo().bar().baz().

I have seen examples using this method: module.exports = _.tap {}, (connectors) ->, so does this "tap" into the object literal's method chain?

Answer 1

From the fine manual:

Chaining
[...]
Calling chain will cause all future method calls to return wrapped objects. When you've finished the computation, use value to retrieve the final value.

So chaining in the Underscore context is the same as chaining elsewhere except that you're chaining Underscore methods on a wrapped object. You start by calling _.chain to get your wrapper:

_(obj).chain()

then you call Underscore methods on what _.chain returns and they will return wrapped objects as well:

_(obj).chain()
      .filter(function(x) { ... })
      .map(function(x) { ... })
      ...

and finally you call _.value to unwrap the chaining-wrapper:

var result = _(obj).chain()
                   .filter(function(x) { ... })
                   .map(function(x) { ... })
                   ...
                   .value();

Back to _.tap. All tap does is this:

_.tap = function(obj, interceptor) {
  interceptor(obj);
  return obj;
};

so it calls the passed function, interceptor on the value being iterated over and returns what is being iterated over without doing anything to it. _.tap is the same as:

.map(function(x, func) { func(x); return x })

but it makes your intention clear. In effect, _.tap lets you peek into the data passing through the method chain without altering that data.