npm-lodash

1
# Collection Methods
2

3
Powerful iteration and transformation methods that work with arrays, objects, and other collections. These methods provide the foundation for data processing and functional programming patterns.
4

5
## Capabilities
6

7
### Core Iteration
8

9
#### forEach
10
Iterates over elements of collection and invokes iteratee for each element.
11

12
```javascript { .api }
13
/**
14
 * Iterates over elements of collection and invokes iteratee for each element
15
 * @param collection - The collection to iterate over
16
 * @param iteratee - The function invoked per iteration
17
 * @returns Returns collection
18
 */
19
function forEach(collection, iteratee);
20

21
/**
22
 * Like forEach but iterates over elements from right to left
23
 * @param collection - The collection to iterate over
24
 * @param iteratee - The function invoked per iteration
25
 * @returns Returns collection
26
 */
27
function forEachRight(collection, iteratee);
28

29
// Aliases
30
const each = forEach;
31
const eachRight = forEachRight;
32
```
33

34
#### map
35
Creates an array of values by running each element in collection through iteratee.
36

37
```javascript { .api }
38
/**
39
 * Creates an array of values by running each element in collection through iteratee
40
 * @param collection - The collection to iterate over
41
 * @param iteratee - The function invoked per iteration
42
 * @returns Returns the new mapped array
43
 */
44
function map(collection, iteratee);
45
```
46

47
### Filtering & Finding
48

49
#### filter
50
Iterates over elements of collection, returning an array of all elements predicate returns truthy for.
51

52
```javascript { .api }
53
/**
54
 * Iterates over elements of collection, returning an array of all elements predicate returns truthy for
55
 * @param collection - The collection to iterate over
56
 * @param predicate - The function invoked per iteration
57
 * @returns Returns the new filtered array
58
 */
59
function filter(collection, predicate);
60

61
/**
62
 * The opposite of filter; creates an array of elements predicate returns falsey for
63
 * @param collection - The collection to iterate over
64
 * @param predicate - The function invoked per iteration
65
 * @returns Returns the new filtered array
66
 */
67
function reject(collection, predicate);
68
```
69

70
#### find
71
Iterates over elements of collection, returning the first element predicate returns truthy for.
72

73
```javascript { .api }
74
/**
75
 * Iterates over elements of collection, returning the first element predicate returns truthy for
76
 * @param collection - The collection to iterate over
77
 * @param predicate - The function invoked per iteration
78
 * @param fromIndex - The index to search from
79
 * @returns Returns the matched element, else undefined
80
 */
81
function find(collection, predicate, fromIndex = 0);
82

83
/**
84
 * Like find except that it iterates over elements from right to left
85
 * @param collection - The collection to iterate over
86
 * @param predicate - The function invoked per iteration
87
 * @param fromIndex - The index to search from
88
 * @returns Returns the matched element, else undefined
89
 */
90
function findLast(collection, predicate, fromIndex = collection.length - 1);
91
```
92

93
### Testing & Validation
94

95
#### every & some
96
Tests whether elements pass a predicate test.
97

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

107
/**
108
 * Checks if predicate returns truthy for any element of collection
109
 * @param collection - The collection to iterate over
110
 * @param predicate - The function invoked per iteration
111
 * @returns Returns true if any element passes the predicate check, else false
112
 */
113
function some(collection, predicate);
114
```
115

116
#### includes
117
Checks if value is in collection.
118

119
```javascript { .api }
120
/**
121
 * Checks if value is in collection using SameValueZero for equality comparisons
122
 * @param collection - The collection to inspect
123
 * @param value - The value to search for
124
 * @param fromIndex - The index to search from
125
 * @returns Returns true if value is found, else false
126
 */
127
function includes(collection, value, fromIndex = 0);
128
```
129

130
### Aggregation & Reduction
131

132
#### reduce
133
Reduces collection to a value which is the accumulated result of running each element through iteratee.
134

135
```javascript { .api }
136
/**
137
 * Reduces collection to a value which is the accumulated result of running each element through iteratee
138
 * @param collection - The collection to iterate over
139
 * @param iteratee - The function invoked per iteration
140
 * @param accumulator - The initial value
141
 * @returns Returns the accumulated value
142
 */
143
function reduce(collection, iteratee, accumulator);
144

145
/**
146
 * Like reduce except that it iterates over elements from right to left
147
 * @param collection - The collection to iterate over
148
 * @param iteratee - The function invoked per iteration
149
 * @param accumulator - The initial value
150
 * @returns Returns the accumulated value
151
 */
152
function reduceRight(collection, iteratee, accumulator);
153
```
154

155
#### size
156
Gets the size of collection by returning its length for array-like values or the number of own enumerable string keyed properties for objects.
157

158
```javascript { .api }
159
/**
160
 * Gets the size of collection
161
 * @param collection - The collection to inspect
162
 * @returns Returns the collection size
163
 */
164
function size(collection);
165
```
166

167
### Grouping & Organization
168

169
#### groupBy
170
Creates an object composed of keys generated from the results of running each element through iteratee.
171

172
```javascript { .api }
173
/**
174
 * Creates an object composed of keys generated from the results of running each element through iteratee
175
 * @param collection - The collection to iterate over
176
 * @param iteratee - The iteratee to transform keys
177
 * @returns Returns the composed aggregate object
178
 */
179
function groupBy(collection, iteratee);
180

181
/**
182
 * Creates an object composed of keys generated from the results of running each element through iteratee
183
 * @param collection - The collection to iterate over
184
 * @param iteratee - The iteratee to transform keys
185
 * @returns Returns the composed aggregate object
186
 */
187
function keyBy(collection, iteratee);
188

189
/**
190
 * Creates an object composed of keys generated from the results of running each element through iteratee
191
 * @param collection - The collection to iterate over
192
 * @param iteratee - The iteratee to transform keys
193
 * @returns Returns the composed aggregate object
194
 */
195
function countBy(collection, iteratee);
196
```
197

198
#### partition
199
Creates an array of two arrays, the first of which contains elements predicate returns truthy for.
200

201
```javascript { .api }
202
/**
203
 * Creates an array of two arrays, the first of which contains elements predicate returns truthy for
204
 * @param collection - The collection to iterate over
205
 * @param predicate - The function invoked per iteration
206
 * @returns Returns the array of grouped elements
207
 */
208
function partition(collection, predicate);
209
```
210

211
### Sorting
212

213
#### sortBy
214
Creates an array of elements, sorted in ascending order by the results of running each element through each iteratee.
215

216
```javascript { .api }
217
/**
218
 * Creates an array of elements, sorted in ascending order by the results of running each element through each iteratee
219
 * @param collection - The collection to iterate over
220
 * @param iteratees - The iteratees to sort by
221
 * @returns Returns the new sorted array
222
 */
223
function sortBy(collection, ...iteratees);
224

225
/**
226
 * Creates an array of elements, sorted by iteratees in orders
227
 * @param collection - The collection to iterate over
228
 * @param iteratees - The iteratees to sort by
229
 * @param orders - The sort orders of iteratees
230
 * @returns Returns the new sorted array
231
 */
232
function orderBy(collection, iteratees, orders);
233
```
234

235
### Sampling
236

237
#### sample
238
Gets a random element from collection.
239

240
```javascript { .api }
241
/**
242
 * Gets a random element from collection
243
 * @param collection - The collection to sample
244
 * @returns Returns the random element
245
 */
246
function sample(collection);
247

248
/**
249
 * Gets n random elements at unique keys from collection up to the size of collection
250
 * @param collection - The collection to sample
251
 * @param n - The number of elements to sample
252
 * @returns Returns the random elements
253
 */
254
function sampleSize(collection, n = 1);
255

256
/**
257
 * Creates an array of shuffled values, using a version of the Fisher-Yates shuffle
258
 * @param collection - The collection to shuffle
259
 * @returns Returns the new shuffled array
260
 */
261
function shuffle(collection);
262
```
263

264
### FlatMap Operations
265

266
#### flatMap
267
Creates a flattened array of values by running each element through iteratee and flattening the mapped results.
268

269
```javascript { .api }
270
/**
271
 * Creates a flattened array of values by running each element through iteratee and flattening the mapped results
272
 * @param collection - The collection to iterate over
273
 * @param iteratee - The function invoked per iteration
274
 * @returns Returns the new flattened array
275
 */
276
function flatMap(collection, iteratee);
277

278
/**
279
 * Like flatMap but recursively flattens the mapped results
280
 * @param collection - The collection to iterate over
281
 * @param iteratee - The function invoked per iteration
282
 * @returns Returns the new flattened array
283
 */
284
function flatMapDeep(collection, iteratee);
285

286
/**
287
 * Like flatMap but recursively flattens the mapped results up to depth times
288
 * @param collection - The collection to iterate over
289
 * @param iteratee - The function invoked per iteration
290
 * @param depth - The maximum recursion depth
291
 * @returns Returns the new flattened array
292
 */
293
function flatMapDepth(collection, iteratee, depth = 1);
294
```
295

296
### Method Invocation
297

298
#### invokeMap
299
Invokes the method at path of each element in collection.
300

301
```javascript { .api }
302
/**
303
 * Invokes the method at path of each element in collection
304
 * @param collection - The collection to iterate over
305
 * @param path - The path of the method to invoke
306
 * @param args - The arguments to invoke each method with
307
 * @returns Returns the array of results
308
 */
309
function invokeMap(collection, path, ...args);
310
```
311

312
## Iteratee Shorthand
313

314
Lodash collection methods support several shorthand syntaxes for common operations:
315

316
```javascript { .api }
317
// Property shorthand - gets property value
318
map(users, 'name');           // → ['John', 'Jane', 'Bob']
319

320
// Path shorthand - gets nested property value  
321
map(users, 'profile.age');    // → [30, 25, 35]
322

323
// Object shorthand - partial deep comparison
324
filter(users, { active: true });         // → users where active === true
325
filter(users, { role: 'admin' });        // → admin users
326

327
// Array shorthand - [path, value] for matchesProperty
328
filter(users, ['role', 'admin']);        // → admin users
329
```
330

331
## Usage Examples
332

333
```javascript
334
import { 
335
  map, filter, find, groupBy, reduce, sortBy,
336
  every, some, partition, sample, flatMap
337
} from "lodash";
338

339
const users = [
340
  { name: 'John', age: 30, role: 'admin', active: true },
341
  { name: 'Jane', age: 25, role: 'user', active: true },
342
  { name: 'Bob', age: 35, role: 'user', active: false },
343
  { name: 'Alice', age: 28, role: 'admin', active: true }
344
];
345

346
// Transform collections
347
const names = map(users, 'name');
348
// Result: ['John', 'Jane', 'Bob', 'Alice']
349

350
const adults = filter(users, user => user.age >= 30);
351
// Result: [{ name: 'John', age: 30, ... }, { name: 'Bob', age: 35, ... }]
352

353
// Find elements
354
const admin = find(users, { role: 'admin' });
355
// Result: { name: 'John', age: 30, role: 'admin', active: true }
356

357
// Group data
358
const byRole = groupBy(users, 'role');
359
// Result: { admin: [...], user: [...] }
360

361
// Aggregate data
362
const totalAge = reduce(users, (sum, user) => sum + user.age, 0);
363
// Result: 118
364

365
// Sort collections
366
const byAge = sortBy(users, 'age');
367
// Result: users sorted by age ascending
368

369
// Test collections
370
const allActive = every(users, 'active');      // false
371
const someActive = some(users, 'active');      // true
372

373
// Split collections
374
const [active, inactive] = partition(users, 'active');
375
// active: users with active: true, inactive: users with active: false
376

377
// Sample collections
378
const randomUser = sample(users);              // Random user
379
const twoUsers = sampleSize(users, 2);         // Two random users
380

381
// FlatMap operations
382
const tags = [
383
  { name: 'Post 1', tags: ['js', 'web'] },
384
  { name: 'Post 2', tags: ['react', 'js'] }
385
];
386
const allTags = flatMap(tags, 'tags');
387
// Result: ['js', 'web', 'react', 'js']
388

389
// Complex operations
390
const activeAdminNames = users
391
  |> filter(%, { active: true })
392
  |> filter(%, { role: 'admin' })
393
  |> map(%, 'name');
394
// Using pipeline operator for clarity
395
```