0
# Lodash FlatMap
1

2
The lodash method `flatMap` exported as a Node.js module. Creates an array of flattened values by running each element in collection through iteratee and concating its result to the other mapped values. Part of lodash's modularized package series for selective imports.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const flatMap = require('lodash.flatmap');
15
```
16

17
For ES modules:
18

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

23
## Basic Usage
24

25
```javascript
26
const flatMap = require('lodash.flatmap');
27

28
// Transform and flatten array elements
29
function duplicate(n) {
30
  return [n, n];
31
}
32

33
const result = flatMap([1, 2], duplicate);
34
// => [1, 1, 2, 2]
35

36
// With objects
37
const users = [
38
  { name: 'alice', tags: ['admin', 'user'] },
39
  { name: 'bob', tags: ['user', 'guest'] }
40
];
41

42
const allTags = flatMap(users, user => user.tags);
43
// => ['admin', 'user', 'user', 'guest']
44
```
45

46
## Capabilities
47

48
### FlatMap Function
49

50
Creates an array of flattened values by running each element in collection through iteratee and concating its result to the other mapped values.
51

52
```javascript { .api }
53
/**
54
 * Creates an array of flattened values by running each element in collection
55
 * through iteratee and concating its result to the other mapped values.
56
 * The iteratee is invoked with three arguments: (value, index|key, collection).
57
 * 
58
 * @param {Array|Object} collection - The collection to iterate over
59
 * @param {Function|string|Object} [iteratee=_.identity] - The function invoked per iteration
60
 * @returns {Array} Returns the new flattened array
61
 */
62
function flatMap(collection, iteratee);
63
```
64

65
**Parameters:**
66

67
- **collection** `{Array|Object}` - The collection to iterate over. Can be arrays, array-like objects, or plain objects. Falsey values are treated as empty collections. Numeric values are treated as empty collections.
68
- **iteratee** `{Function|string|Object}` - The function invoked per iteration. Can be:
69
  - **Function**: `(value, index|key, collection) => any` - Custom transformation function receiving three arguments
70
  - **string**: Property path for extracting values (e.g., `'tags'` to extract `obj.tags`)
71
  - **Object**: Plain object to match properties against using deep equality
72
  - **Default**: `_.identity` if not provided (returns the values as-is)
73

74
**Return Value:**
75

76
- **Type**: `Array`
77
- **Description**: Returns a new flattened array with results from mapping each element and flattening by one level
78

79
**Iteratee Function Signature:**
80

81
When providing a function as the iteratee:
82

83
```javascript { .api }
84
/**
85
 * @param {*} value - The current element being processed
86
 * @param {number|string} index - The index of the element (for arrays) or key (for objects)  
87
 * @param {Array|Object} collection - The collection being iterated over
88
 * @returns {*} The transformed value(s) to be flattened
89
 */
90
function iteratee(value, index, collection);
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
const flatMap = require('lodash.flatmap');
97

98
// Basic array transformation
99
const numbers = flatMap([1, 2, 3], n => [n, n * 2]);
100
// => [1, 2, 2, 4, 3, 6]
101

102
// Object collection
103
const data = { a: [1, 2], b: [3, 4] };
104
const result = flatMap(data, arr => arr);
105
// => [1, 2, 3, 4]
106

107
// String property extraction
108
const objects = [
109
  { values: ['a', 'b'] },
110
  { values: ['c', 'd'] }
111
];
112
const extracted = flatMap(objects, 'values');
113
// => ['a', 'b', 'c', 'd']
114

115
// Object matching (iteratee as Object)
116
const users = [
117
  { name: 'alice', active: true, roles: ['admin'] },
118
  { name: 'bob', active: false, roles: ['user'] },
119
  { name: 'charlie', active: true, roles: ['user', 'moderator'] }
120
];
121
const activeUserRoles = flatMap(users, { active: true });
122
// => [{ name: 'alice', active: true, roles: ['admin'] }, { name: 'charlie', active: true, roles: ['user', 'moderator'] }]
123

124
// Empty collections and edge cases
125
const empty = flatMap([], n => [n, n]);
126
// => []
127

128
const nullish = flatMap(null);
129
// => []
130

131
const undefinedValue = flatMap(undefined);
132
// => []
133

134
const numeric = flatMap(1);
135
// => []
136

137
// Nested arrays (only flattens one level)
138
const nested = flatMap([[1, [2]], [3, [4]]], arr => arr);
139
// => [1, [2], 3, [4]]
140

141
// Object with length property (treated as object, not array-like)
142
const objWithLength = { length: [1, 2], other: [3, 4] };
143
const objResult = flatMap(objWithLength, val => val);
144
// => [1, 2, 3, 4]
145
```
146

147
**Error Handling:**
148

149
- Does not throw explicit errors for invalid inputs
150
- Handles `null`, `undefined`, and empty collections gracefully by returning empty arrays
151
- Numeric values for collection are treated as empty and return empty arrays
152
- Non-array-like return values from iteratee are treated as single elements
153
- Objects with non-number length properties are iterated as objects, not arrays
154
- Uses internal lodash type checking for safe operations
155

156
**Performance Characteristics:**
157

158
- **Time Complexity**: O(n * m) where n is collection size and m is average result size per element
159
- **Space Complexity**: O(result_size) for the flattened output array
160
- **Flattening Depth**: Only flattens one level deep (not recursive)
161
- Single-pass iteration with immediate flattening