0
# Collection Functions
1

2
Iteration and transformation utilities that work with arrays, objects, and other collections, including mapping, filtering, reducing, and grouping operations.
3

4
## Capabilities
5

6
### Collection Transformation
7

8
Core functions for transforming collections through mapping, filtering, and reduction operations.
9

10
```javascript { .api }
11
/**
12
 * Creates an array of values by running each element through iteratee
13
 * @param {Array|Object} collection - The collection to iterate over
14
 * @param {Function} iteratee - The function invoked per iteration
15
 * @returns {Array} Returns the new mapped array
16
 */
17
function map(collection, iteratee);
18

19
/**
20
 * Iterates over elements of collection, returning an array of all elements predicate returns truthy for
21
 * @param {Array|Object} collection - The collection to iterate over
22
 * @param {Function} predicate - The function invoked per iteration
23
 * @returns {Array} Returns the new filtered array
24
 */
25
function filter(collection, predicate);
26

27
/**
28
 * Reduces collection to a value which is the accumulated result of running each element through iteratee
29
 * @param {Array|Object} collection - The collection to iterate over
30
 * @param {Function} iteratee - The function invoked per iteration
31
 * @param {*} accumulator - The initial value
32
 * @returns {*} Returns the accumulated value
33
 */
34
function reduce(collection, iteratee, accumulator);
35

36
/**
37
 * Like reduce but iterates over elements from right to left
38
 * @param {Array|Object} collection - The collection to iterate over
39
 * @param {Function} iteratee - The function invoked per iteration
40
 * @param {*} accumulator - The initial value
41
 * @returns {*} Returns the accumulated value
42
 */
43
function reduceRight(collection, iteratee, accumulator);
44

45
/**
46
 * The opposite of filter; returns elements predicate does NOT return truthy for
47
 * @param {Array|Object} collection - The collection to iterate over
48
 * @param {Function} predicate - The function invoked per iteration
49
 * @returns {Array} Returns the new filtered array
50
 */
51
function reject(collection, predicate);
52
```
53

54
### Collection Iteration
55

56
Functions for iterating over collections with various patterns.
57

58
```javascript { .api }
59
/**
60
 * Iterates over elements of collection and invokes iteratee for each element
61
 * @param {Array|Object} collection - The collection to iterate over
62
 * @param {Function} iteratee - The function invoked per iteration
63
 * @returns {Array|Object} Returns collection
64
 */
65
function forEach(collection, iteratee);
66

67
/**
68
 * Like forEach but iterates over elements from right to left
69
 * @param {Array|Object} collection - The collection to iterate over
70
 * @param {Function} iteratee - The function invoked per iteration
71
 * @returns {Array|Object} Returns collection
72
 */
73
function forEachRight(collection, iteratee);
74

75
/**
76
 * Alias for forEach
77
 * @param {Array|Object} collection - The collection to iterate over
78
 * @param {Function} iteratee - The function invoked per iteration
79
 * @returns {Array|Object} Returns collection
80
 */
81
function each(collection, iteratee);
82

83
/**
84
 * Alias for forEachRight
85
 * @param {Array|Object} collection - The collection to iterate over
86
 * @param {Function} iteratee - The function invoked per iteration
87
 * @returns {Array|Object} Returns collection
88
 */
89
function eachRight(collection, iteratee);
90
```
91

92
### Collection Testing
93

94
Functions for testing collection elements against predicates.
95

96
```javascript { .api }
97
/**
98
 * Checks if predicate returns truthy for all elements of collection
99
 * @param {Array|Object} collection - The collection to iterate over
100
 * @param {Function} predicate - The function invoked per iteration
101
 * @returns {boolean} Returns true if all elements pass the predicate check
102
 */
103
function every(collection, predicate);
104

105
/**
106
 * Checks if predicate returns truthy for any element of collection
107
 * @param {Array|Object} collection - The collection to iterate over
108
 * @param {Function} predicate - The function invoked per iteration
109
 * @returns {boolean} Returns true if any element passes the predicate check
110
 */
111
function some(collection, predicate);
112

113
/**
114
 * Checks if value is in collection
115
 * @param {Array|Object|string} collection - The collection to inspect
116
 * @param {*} value - The value to search for
117
 * @param {number} fromIndex - The index to search from
118
 * @returns {boolean} Returns true if value is found
119
 */
120
function includes(collection, value, fromIndex);
121
```
122

123
### Collection Search
124

125
Functions for finding elements within collections.
126

127
```javascript { .api }
128
/**
129
 * Iterates over elements of collection, returning the first element predicate returns truthy for
130
 * @param {Array|Object} collection - The collection to inspect
131
 * @param {Function} predicate - The function invoked per iteration
132
 * @param {number} fromIndex - The index to search from
133
 * @returns {*} Returns the matched element, else undefined
134
 */
135
function find(collection, predicate, fromIndex);
136

137
/**
138
 * Like find but iterates over elements from right to left
139
 * @param {Array|Object} collection - The collection to inspect
140
 * @param {Function} predicate - The function invoked per iteration
141
 * @param {number} fromIndex - The index to search from
142
 * @returns {*} Returns the matched element, else undefined
143
 */
144
function findLast(collection, predicate, fromIndex);
145
```
146

147
### Collection Grouping
148

149
Functions for organizing collection elements into groups.
150

151
```javascript { .api }
152
/**
153
 * Creates an object composed of keys generated from the results of running each element through iteratee
154
 * @param {Array|Object} collection - The collection to iterate over
155
 * @param {Function} iteratee - The iteratee to transform keys
156
 * @returns {Object} Returns the composed aggregate object
157
 */
158
function groupBy(collection, iteratee);
159

160
/**
161
 * Creates an object composed of keys generated from the results of running each element through iteratee
162
 * @param {Array|Object} collection - The collection to iterate over
163
 * @param {Function} iteratee - The iteratee to transform keys
164
 * @returns {Object} Returns the composed aggregate object
165
 */
166
function keyBy(collection, iteratee);
167

168
/**
169
 * Creates an object with the same keys as object and values generated by running each property through iteratee
170
 * @param {Array|Object} collection - The collection to iterate over
171
 * @param {Function} iteratee - The iteratee to transform keys
172
 * @returns {Object} Returns the composed aggregate object
173
 */
174
function countBy(collection, iteratee);
175

176
/**
177
 * Creates an array of elements split into two groups
178
 * @param {Array|Object} collection - The collection to iterate over
179
 * @param {Function} predicate - The function invoked per iteration
180
 * @returns {Array} Returns the array of grouped elements
181
 */
182
function partition(collection, predicate);
183
```
184

185
### Flat Mapping
186

187
Functions that combine mapping and flattening operations.
188

189
```javascript { .api }
190
/**
191
 * Creates a flattened array of values by running each element through iteratee
192
 * @param {Array|Object} collection - The collection to iterate over
193
 * @param {Function} iteratee - The iteratee to transform elements
194
 * @returns {Array} Returns the new flattened array
195
 */
196
function flatMap(collection, iteratee);
197

198
/**
199
 * Like flatMap but recursively flattens the mapped results
200
 * @param {Array|Object} collection - The collection to iterate over
201
 * @param {Function} iteratee - The iteratee to transform elements
202
 * @returns {Array} Returns the new flattened array
203
 */
204
function flatMapDeep(collection, iteratee);
205

206
/**
207
 * Like flatMap but recursively flattens the mapped results up to depth times
208
 * @param {Array|Object} collection - The collection to iterate over
209
 * @param {Function} iteratee - The iteratee to transform elements
210
 * @param {number} depth - The maximum recursion depth
211
 * @returns {Array} Returns the new flattened array
212
 */
213
function flatMapDepth(collection, iteratee, depth);
214
```
215

216
### Collection Sorting
217

218
Functions for sorting collection elements.
219

220
```javascript { .api }
221
/**
222
 * Creates an array of elements, sorted in ascending order by the results of running each element through iteratee
223
 * @param {Array|Object} collection - The collection to iterate over
224
 * @param {Function|Function[]} iteratees - The iteratees to sort by
225
 * @returns {Array} Returns the new sorted array
226
 */
227
function sortBy(collection, ...iteratees);
228

229
/**
230
 * Creates an array of elements, sorted by multiple criteria
231
 * @param {Array|Object} collection - The collection to iterate over
232
 * @param {Function[]} iteratees - The iteratees to sort by
233
 * @param {string[]} orders - The sort orders of iteratees
234
 * @returns {Array} Returns the new sorted array
235
 */
236
function orderBy(collection, iteratees, orders);
237
```
238

239
### Collection Sampling
240

241
Functions for randomly sampling elements from collections.
242

243
```javascript { .api }
244
/**
245
 * Gets a random element from collection
246
 * @param {Array|Object} collection - The collection to sample
247
 * @returns {*} Returns the random element
248
 */
249
function sample(collection);
250

251
/**
252
 * Gets n random elements at unique keys from collection up to the size of collection
253
 * @param {Array|Object} collection - The collection to sample
254
 * @param {number} n - The number of elements to sample
255
 * @returns {Array} Returns the random elements
256
 */
257
function sampleSize(collection, n);
258

259
/**
260
 * Creates an array of shuffled values, using a version of the Fisher-Yates shuffle
261
 * @param {Array|Object} collection - The collection to shuffle
262
 * @returns {Array} Returns the new shuffled array
263
 */
264
function shuffle(collection);
265
```
266

267
### Collection Size and Invocation
268

269
Utility functions for collection size and method invocation.
270

271
```javascript { .api }
272
/**
273
 * Gets the size of collection by returning its length for array-like values or the number of own enumerable string keyed properties for objects
274
 * @param {Array|Object|string} collection - The collection to inspect
275
 * @returns {number} Returns the collection size
276
 */
277
function size(collection);
278

279
/**
280
 * Invokes the method at path of each element in collection
281
 * @param {Array|Object} collection - The collection to iterate over
282
 * @param {Array|Function|string} path - The path of the method to invoke or the function invoked per iteration
283
 * @param {...*} args - The arguments to invoke each method with
284
 * @returns {Array} Returns the array of results
285
 */
286
function invokeMap(collection, path, ...args);
287
```
288

289
## Usage Examples
290

291
### Basic Collection Operations
292

293
```javascript
294
import { map, filter, reduce, groupBy } from "lodash-es";
295

296
const users = [
297
  { name: "Alice", age: 25, department: "engineering" },
298
  { name: "Bob", age: 30, department: "sales" },
299
  { name: "Charlie", age: 35, department: "engineering" },
300
  { name: "Diana", age: 28, department: "marketing" }
301
];
302

303
// Transform collection
304
const names = map(users, "name"); // ["Alice", "Bob", "Charlie", "Diana"]
305
const ages = map(users, user => user.age * 2); // [50, 60, 70, 56]
306

307
// Filter collection
308
const engineers = filter(users, { department: "engineering" });
309
const seniors = filter(users, user => user.age >= 30);
310

311
// Reduce collection
312
const totalAge = reduce(users, (sum, user) => sum + user.age, 0); // 118
313
const avgAge = totalAge / users.length; // 29.5
314

315
// Group collection
316
const byDepartment = groupBy(users, "department");
317
/* {
318
  engineering: [Alice, Charlie],
319
  sales: [Bob],
320
  marketing: [Diana]
321
} */
322
```
323

324
### Advanced Collection Operations
325

326
```javascript
327
import { partition, sortBy, orderBy, countBy, every, some } from "lodash-es";
328

329
const products = [
330
  { name: "Laptop", price: 999, category: "electronics", inStock: true },
331
  { name: "Book", price: 29, category: "books", inStock: false },
332
  { name: "Phone", price: 699, category: "electronics", inStock: true },
333
  { name: "Notebook", price: 5, category: "books", inStock: true }
334
];
335

336
// Partition into two groups
337
const [inStock, outOfStock] = partition(products, "inStock");
338

339
// Sort by single criterion
340
const byPrice = sortBy(products, "price");
341

342
// Sort by multiple criteria
343
const sorted = orderBy(products, ["category", "price"], ["asc", "desc"]);
344

345
// Count by category
346
const counts = countBy(products, "category");
347
// { electronics: 2, books: 2 }
348

349
// Test all elements
350
const allAffordable = every(products, product => product.price < 1000); // true
351
const someExpensive = some(products, product => product.price > 500); // true
352
```
353

354
### Iteratee Shorthand
355

356
```javascript
357
import { map, filter, find, sortBy } from "lodash-es";
358

359
const users = [
360
  { name: "Alice", profile: { age: 25, active: true } },
361
  { name: "Bob", profile: { age: 30, active: false } },
362
  { name: "Charlie", profile: { age: 35, active: true } }
363
];
364

365
// Property string shorthand
366
const names = map(users, "name"); // ["Alice", "Bob", "Charlie"]
367

368
// Deep property path shorthand
369
const ages = map(users, "profile.age"); // [25, 30, 35]
370

371
// Object match shorthand
372
const activeUsers = filter(users, { "profile.active": true });
373

374
// Array match shorthand
375
const specificUser = find(users, ["name", "Bob"]);
376

377
// Sort by nested property
378
const sortedByAge = sortBy(users, "profile.age");
379
```
380

381
### Chaining Collections
382

383
```javascript
384
import { chain } from "lodash-es";
385

386
const sales = [
387
  { product: "Laptop", amount: 999, region: "North" },
388
  { product: "Phone", amount: 699, region: "South" },
389
  { product: "Laptop", amount: 999, region: "South" },
390
  { product: "Tablet", amount: 399, region: "North" }
391
];
392

393
const result = chain(sales)
394
  .groupBy("region")
395
  .mapValues(regionSales => 
396
    chain(regionSales)
397
      .sumBy("amount")
398
      .value()
399
  )
400
  .value();
401
// { North: 1398, South: 1698 }
402
```