What is really the difference between underscore _.each and _.map?

Question

I'm using UnderscoreJs. Consider this code:

var docs = [     {name : 'Anders', niche : 'Web Development'},      {name : 'Johnny', niche : 'Design'},      {name : 'Eric', niche : 'PhotoShop'} ];  var newDocs = _.map(docs, function (doc){     delete doc.niche;     return doc; }); 

It doesn't matter if I use .each or .map here. The outcome is exactly the same.

What is really the difference between the two in the case above?

Answer 1

map is intended to be a functional mapping method: its function argument should return a value, but is not expected to have any side-effects.

each is just a functional replacement for an imperative for loop: its purpose is to have an effect, and it is not expected to return any value.

For example, this would be a more appropriate use for map:

var docs = getDocs(); var docTitles = _.map(docs, function (doc){     return doc.title; }); // expect `docs` to be unchanged 

Whereas this would be an appropriate use for each:

var docs = getDocs(); _.each(docs, function (doc){     delete doc.niche; }); // expect `docs` to be altered. 

Answer 2

_.each(list, iteratee)

Iterates over a list of elements, yielding each in turn to an iteratee function.

Each invocation of iteratee is called with three arguments: (element, index, list). If list is a JavaScript object, iteratee's arguments will be (value, key, list). Returns the list for chaining.

_.each({one: 1, two: 2, three: 3}, alert); => alerts each number value in turn... 

_.map(list, iteratee)

Produces a new array of values by mapping each value in list through a transformation function (iteratee).

If list is a JavaScript object, iteratee's arguments will be (value, key, list).

_.map({one: 1, two: 2, three: 3}, function(num, key){ return num * 3; }); => [3, 6, 9] 

see documentation