0
# Lodash Map
1

2
Lodash Map provides the `_.map` method as a standalone module for creating arrays of values by running each element in a collection through an iteratee function. It supports both arrays and objects, with multiple iteratee formats including functions, object shorthands, and property paths.
3

4
## Package Information
5

6
- **Package Name**: lodash.map
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.map`
10

11
## Core Imports
12

13
```javascript
14
var map = require('lodash.map');
15
```
16

17
For ES6 modules:
18

19
```javascript
20
import map from 'lodash.map';
21
```
22

23
## Basic Usage
24

25
```javascript
26
var map = require('lodash.map');
27

28
// Basic array transformation with function
29
function square(n) {
30
  return n * n;
31
}
32

33
map([4, 8], square);
34
// => [16, 64]
35

36
// Object transformation
37
map({ 'a': 4, 'b': 8 }, square);
38
// => [16, 64] (iteration order is not guaranteed)
39

40
// Property extraction using string shorthand
41
var users = [
42
  { 'user': 'barney' },
43
  { 'user': 'fred' }
44
];
45

46
map(users, 'user');
47
// => ['barney', 'fred']
48
```
49

50
## Capabilities
51

52
### Map Function
53

54
Creates an array of values by running each element in `collection` through `iteratee`. The iteratee is invoked with three arguments: (value, index|key, collection).
55

56
```javascript { .api }
57
/**
58
 * Creates an array of values by running each element in collection through iteratee
59
 * @param {Array|Object} collection - The collection to iterate over
60
 * @param {Function|Object|string} [iteratee=_.identity] - The function invoked per iteration
61
 * @returns {Array} Returns the new mapped array
62
 */
63
function map(collection, iteratee);
64
```
65

66
**Parameters:**
67
- `collection` (Array|Object): The collection to iterate over. Can be an array, array-like object, or plain object
68
- `iteratee` (Function|Object|string, optional): The function invoked per iteration. Defaults to identity function if not provided
69

70
**Returns:**
71
- Array: Returns the new mapped array containing the results of applying the iteratee to each element
72

73
**Iteratee Function Signature:**
74
When using a function as iteratee, it receives three arguments:
75
- `value`: The current element value
76
- `index|key`: The index of the element (for arrays) or property key (for objects)  
77
- `collection`: The collection being iterated over
78

79
**Iteratee Shorthand Options:**
80
- **Function**: Custom transformation function `(value, index, collection) => transformedValue`
81
- **String**: Property path shorthand like `'user'` extracts that property from each element
82
- **Object**: Matches object shorthand like `{active: true}` filters elements matching the object
83
- **Undefined/null**: Uses identity function, effectively creating a shallow copy
84

85
**Usage Examples:**
86

87
```javascript
88
var map = require('lodash.map');
89

90
// Function iteratee
91
function square(n) {
92
  return n * n;
93
}
94
map([4, 8], square);
95
// => [16, 64]
96

97
// Object collection
98
map({ 'a': 4, 'b': 8 }, square);
99
// => [16, 64] (iteration order is not guaranteed)
100

101
// String property path shorthand
102
var users = [
103
  { 'user': 'barney' },
104
  { 'user': 'fred' }
105
];
106
map(users, 'user');
107
// => ['barney', 'fred']
108

109
// Object matching shorthand
110
var data = [
111
  { 'name': 'apple', 'organic': true },
112
  { 'name': 'banana', 'organic': false },
113
  { 'name': 'carrot', 'organic': true }
114
];
115
map(data, { 'organic': true });
116
// => [true, false, true]
117

118
// Identity function (shallow copy)
119
map([1, 2, 3]);
120
// => [1, 2, 3]
121

122
// Array-like objects
123
map('hello', function(char) { return char.toUpperCase(); });
124
// => ['H', 'E', 'L', 'L', 'O']
125
```
126

127
**Performance Notes:**
128
- Uses optimized `arrayMap` implementation for arrays
129
- Uses `baseMap` implementation for objects and array-like objects
130
- Integrates with lodash's iteratee system for shorthand support via `getIteratee`
131

132
**Compatibility:**
133
- Works with arrays, array-like objects (like strings, arguments), and plain objects
134
- Maintains compatibility with lodash's iteratee shorthand syntax
135
- Follows lodash's iteration order conventions (arrays maintain order, objects do not guarantee order)