npm-lodash

1
# Collection Methods
2

3
Iteration and manipulation methods that work on arrays, objects, and other iterable collections. These methods provide a consistent interface for working with different collection types.
4

5
## Capabilities
6

7
### At
8

9
Creates an array of values corresponding to paths of object.
10

11
```javascript { .api }
12
/**
13
 * Creates an array of values corresponding to `paths` of `object`.
14
 * @param object - The object to iterate over
15
 * @param paths - The property paths to pick
16
 * @returns Returns the picked values
17
 */
18
function at<T>(object: T, paths: Array<string | number>): any[];
19
```
20

21
### Count By
22

23
Creates an object composed of keys generated from the results of running each element through iteratee.
24

25
```javascript { .api }
26
/**
27
 * Creates an object composed of keys generated from the results of running
28
 * each element of `collection` thru `iteratee`. The corresponding value of
29
 * each key is the number of times the key was returned by `iteratee`.
30
 * @param collection - The collection to iterate over
31
 * @param iteratee - The iteratee to transform keys
32
 * @returns Returns the composed aggregate object
33
 */
34
function countBy<T>(
35
  collection: T[],
36
  iteratee?: string | ((value: T) => any)
37
): Record<string, number>;
38
```
39

40
### Every
41

42
Checks if predicate returns truthy for all elements of collection.
43

44
```javascript { .api }
45
/**
46
 * Checks if `predicate` returns truthy for **all** elements of `collection`.
47
 * Iteration is stopped once `predicate` returns falsey.
48
 * @param collection - The collection to iterate over
49
 * @param predicate - The function invoked per iteration
50
 * @returns Returns `true` if all elements pass the predicate check, else `false`
51
 */
52
function every<T>(
53
  collection: T[],
54
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
55
): boolean;
56
```
57

58
### Filter
59

60
Iterates over elements of collection, returning an array of all elements predicate returns truthy for.
61

62
```javascript { .api }
63
/**
64
 * Iterates over elements of `collection`, returning an array of all elements
65
 * `predicate` returns truthy for.
66
 * @param collection - The collection to iterate over
67
 * @param predicate - The function invoked per iteration
68
 * @returns Returns the new filtered array
69
 */
70
function filter<T>(
71
  collection: T[],
72
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
73
): T[];
74
```
75

76
### Find
77

78
Iterates over elements of collection, returning the first element predicate returns truthy for.
79

80
```javascript { .api }
81
/**
82
 * Iterates over elements of `collection`, returning the first element
83
 * `predicate` returns truthy for.
84
 * @param collection - The collection to inspect
85
 * @param predicate - The function invoked per iteration
86
 * @param fromIndex - The index to search from
87
 * @returns Returns the matched element, else `undefined`
88
 */
89
function find<T>(
90
  collection: T[],
91
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean),
92
  fromIndex?: number
93
): T | undefined;
94
```
95

96
### Find Last
97

98
Like find except that it iterates over elements from right to left.
99

100
```javascript { .api }
101
/**
102
 * This method is like `find` except that it iterates over elements of
103
 * `collection` from right to left.
104
 * @param collection - The collection to inspect
105
 * @param predicate - The function invoked per iteration
106
 * @param fromIndex - The index to search from
107
 * @returns Returns the matched element, else `undefined`
108
 */
109
function findLast<T>(
110
  collection: T[],
111
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean),
112
  fromIndex?: number
113
): T | undefined;
114
```
115

116
### Flat Map
117

118
Creates a flattened array of values by running each element in collection thru iteratee and flattening the mapped results.
119

120
```javascript { .api }
121
/**
122
 * Creates a flattened array of values by running each element in `collection`
123
 * thru `iteratee` and flattening the mapped results. The iteratee is invoked
124
 * with three arguments: (value, index|key, collection).
125
 * @param collection - The collection to iterate over
126
 * @param iteratee - The function invoked per iteration
127
 * @returns Returns the new flattened array
128
 */
129
function flatMap<T, R>(
130
  collection: T[],
131
  iteratee?: string | ((value: T, index: number, collection: T[]) => R | R[])
132
): R[];
133
```
134

135
### Flat Map Deep
136

137
Like flatMap except that it recursively flattens the mapped results.
138

139
```javascript { .api }
140
/**
141
 * This method is like `flatMap` except that it recursively flattens the
142
 * mapped results.
143
 * @param collection - The collection to iterate over
144
 * @param iteratee - The function invoked per iteration
145
 * @returns Returns the new flattened array
146
 */
147
function flatMapDeep<T, R>(
148
  collection: T[],
149
  iteratee?: string | ((value: T, index: number, collection: T[]) => R | R[])
150
): R[];
151
```
152

153
### Flat Map Depth
154

155
Like flatMap except that it recursively flattens the mapped results up to depth times.
156

157
```javascript { .api }
158
/**
159
 * This method is like `flatMap` except that it recursively flattens the
160
 * mapped results up to `depth` times.
161
 * @param collection - The collection to iterate over
162
 * @param iteratee - The function invoked per iteration
163
 * @param depth - The maximum recursion depth
164
 * @returns Returns the new flattened array
165
 */
166
function flatMapDepth<T, R>(
167
  collection: T[],
168
  iteratee?: string | ((value: T, index: number, collection: T[]) => R | R[]),
169
  depth?: number
170
): R[];
171
```
172

173
### For Each
174

175
Iterates over elements of collection and invokes iteratee for each element.
176

177
```javascript { .api }
178
/**
179
 * Iterates over elements of `collection` and invokes `iteratee` for each element.
180
 * The iteratee is invoked with three arguments: (value, index|key, collection).
181
 * Iteratee functions may exit iteration early by explicitly returning `false`.
182
 * @param collection - The collection to iterate over
183
 * @param iteratee - The function invoked per iteration
184
 * @returns Returns `collection`
185
 */
186
function forEach<T>(
187
  collection: T[],
188
  iteratee?: (value: T, index: number, collection: T[]) => any
189
): T[];
190

191
function forEach<T>(
192
  collection: Record<string, T>,
193
  iteratee?: (value: T, key: string, collection: Record<string, T>) => any
194
): Record<string, T>;
195
```
196

197
### For Each Right
198

199
Like forEach except that it iterates over elements from right to left.
200

201
```javascript { .api }
202
/**
203
 * This method is like `forEach` except that it iterates over elements of
204
 * `collection` from right to left.
205
 * @param collection - The collection to iterate over
206
 * @param iteratee - The function invoked per iteration
207
 * @returns Returns `collection`
208
 */
209
function forEachRight<T>(
210
  collection: T[],
211
  iteratee?: (value: T, index: number, collection: T[]) => any
212
): T[];
213

214
function forEachRight<T>(
215
  collection: Record<string, T>,
216
  iteratee?: (value: T, key: string, collection: Record<string, T>) => any
217
): Record<string, T>;
218
```
219

220
### Group By
221

222
Creates an object composed of keys generated from the results of running each element through iteratee.
223

224
```javascript { .api }
225
/**
226
 * Creates an object composed of keys generated from the results of running
227
 * each element of `collection` thru `iteratee`. The order of grouped values
228
 * is determined by the order they occur in `collection`.
229
 * @param collection - The collection to iterate over
230
 * @param iteratee - The iteratee to transform keys
231
 * @returns Returns the composed aggregate object
232
 */
233
function groupBy<T>(
234
  collection: T[],
235
  iteratee?: string | ((value: T) => any)
236
): Record<string, T[]>;
237
```
238

239
### Includes
240

241
Checks if value is in collection.
242

243
```javascript { .api }
244
/**
245
 * Checks if `value` is in `collection`. If `collection` is a string, it's
246
 * checked for a substring of `value`, otherwise SameValueZero is used for
247
 * equality comparisons.
248
 * @param collection - The collection to inspect
249
 * @param value - The value to search for
250
 * @param fromIndex - The index to search from
251
 * @returns Returns `true` if `value` is found, else `false`
252
 */
253
function includes<T>(collection: T[], value: T, fromIndex?: number): boolean;
254
function includes(collection: string, value: string, fromIndex?: number): boolean;
255
function includes<T>(collection: Record<string, T>, value: T): boolean;
256
```
257

258
### Invoke Map
259

260
Invokes the method at path of each element in collection, returning an array of the results of each invoked method.
261

262
```javascript { .api }
263
/**
264
 * Invokes the method at `path` of each element in `collection`, returning
265
 * an array of the results of each invoked method.
266
 * @param collection - The collection to iterate over
267
 * @param path - The path of the method to invoke
268
 * @param args - The arguments to invoke each method with
269
 * @returns Returns the array of results
270
 */
271
function invokeMap<T>(
272
  collection: T[],
273
  path: string | ((value: T) => any),
274
  ...args: any[]
275
): any[];
276
```
277

278
### Key By
279

280
Creates an object composed of keys generated from the results of running each element through iteratee.
281

282
```javascript { .api }
283
/**
284
 * Creates an object composed of keys generated from the results of running
285
 * each element of `collection` thru `iteratee`. The corresponding value of
286
 * each key is the last element responsible for generating the key.
287
 * @param collection - The collection to iterate over
288
 * @param iteratee - The iteratee to transform keys
289
 * @returns Returns the composed aggregate object
290
 */
291
function keyBy<T>(
292
  collection: T[],
293
  iteratee?: string | ((value: T) => any)
294
): Record<string, T>;
295
```
296

297
### Map
298

299
Creates an array of values by running each element in collection thru iteratee.
300

301
```javascript { .api }
302
/**
303
 * Creates an array of values by running each element in `collection` thru
304
 * `iteratee`. The iteratee is invoked with three arguments:
305
 * (value, index|key, collection).
306
 * @param collection - The collection to iterate over
307
 * @param iteratee - The function invoked per iteration
308
 * @returns Returns the new mapped array
309
 */
310
function map<T, R>(
311
  collection: T[],
312
  iteratee?: string | ((value: T, index: number, collection: T[]) => R)
313
): R[];
314

315
function map<T, R>(
316
  collection: Record<string, T>,
317
  iteratee?: string | ((value: T, key: string, collection: Record<string, T>) => R)
318
): R[];
319
```
320

321
### Order By
322

323
Creates an array of elements, sorted in ascending order by the results of running each element thru each iteratee.
324

325
```javascript { .api }
326
/**
327
 * This method is like `sortBy` except that it allows specifying the sort
328
 * orders of the iteratees to sort by. If `orders` is unspecified, all values
329
 * are sorted in ascending order. Otherwise, specify an order of "desc" for
330
 * descending or "asc" for ascending sort order of corresponding values.
331
 * @param collection - The collection to iterate over
332
 * @param iteratees - The iteratees to sort by
333
 * @param orders - The sort orders of `iteratees`
334
 * @returns Returns the new sorted array
335
 */
336
function orderBy<T>(
337
  collection: T[],
338
  iteratees?: Array<string | ((value: T) => any)>,
339
  orders?: Array<'asc' | 'desc'>
340
): T[];
341
```
342

343
### Partition
344

345
Creates an array of elements split into two groups, the first of which contains elements predicate returns truthy for.
346

347
```javascript { .api }
348
/**
349
 * Creates an array of elements split into two groups, the first of which
350
 * contains elements `predicate` returns truthy for, the second of which
351
 * contains elements `predicate` returns falsey for.
352
 * @param collection - The collection to iterate over
353
 * @param predicate - The function invoked per iteration
354
 * @returns Returns the array of grouped elements
355
 */
356
function partition<T>(
357
  collection: T[],
358
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
359
): [T[], T[]];
360
```
361

362
### Reduce
363

364
Reduces collection to a value which is the accumulated result of running each element thru iteratee.
365

366
```javascript { .api }
367
/**
368
 * Reduces `collection` to a value which is the accumulated result of running
369
 * each element in `collection` thru `iteratee`, where each successive
370
 * invocation is supplied the return value of the previous.
371
 * @param collection - The collection to iterate over
372
 * @param iteratee - The function invoked per iteration
373
 * @param accumulator - The initial value
374
 * @returns Returns the accumulated value
375
 */
376
function reduce<T, R>(
377
  collection: T[],
378
  iteratee: (accumulator: R, value: T, index: number, collection: T[]) => R,
379
  accumulator?: R
380
): R;
381

382
function reduce<T, R>(
383
  collection: Record<string, T>,
384
  iteratee: (accumulator: R, value: T, key: string, collection: Record<string, T>) => R,
385
  accumulator?: R
386
): R;
387
```
388

389
### Reduce Right
390

391
Like reduce except that it iterates over elements from right to left.
392

393
```javascript { .api }
394
/**
395
 * This method is like `reduce` except that it iterates over elements of
396
 * `collection` from right to left.
397
 * @param collection - The collection to iterate over
398
 * @param iteratee - The function invoked per iteration
399
 * @param accumulator - The initial value
400
 * @returns Returns the accumulated value
401
 */
402
function reduceRight<T, R>(
403
  collection: T[],
404
  iteratee: (accumulator: R, value: T, index: number, collection: T[]) => R,
405
  accumulator?: R
406
): R;
407

408
function reduceRight<T, R>(
409
  collection: Record<string, T>,
410
  iteratee: (accumulator: R, value: T, key: string, collection: Record<string, T>) => R,
411
  accumulator?: R
412
): R;
413
```
414

415
### Reject
416

417
The opposite of filter; this method returns the elements of collection that predicate does not return truthy for.
418

419
```javascript { .api }
420
/**
421
 * The opposite of `filter`; this method returns the elements of `collection`
422
 * that `predicate` does **not** return truthy for.
423
 * @param collection - The collection to iterate over
424
 * @param predicate - The function invoked per iteration
425
 * @returns Returns the new filtered array
426
 */
427
function reject<T>(
428
  collection: T[],
429
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
430
): T[];
431
```
432

433
### Sample
434

435
Gets a random element from collection.
436

437
```javascript { .api }
438
/**
439
 * Gets a random element from `collection`.
440
 * @param collection - The collection to sample
441
 * @returns Returns the random element
442
 */
443
function sample<T>(collection: T[]): T | undefined;
444
function sample<T>(collection: Record<string, T>): T | undefined;
445
```
446

447
### Sample Size
448

449
Gets n random elements at unique keys from collection up to the size of collection.
450

451
```javascript { .api }
452
/**
453
 * Gets `n` random elements at unique keys from `collection` up to the
454
 * size of `collection`.
455
 * @param collection - The collection to sample
456
 * @param n - The number of elements to sample
457
 * @returns Returns the random elements
458
 */
459
function sampleSize<T>(collection: T[], n?: number): T[];
460
function sampleSize<T>(collection: Record<string, T>, n?: number): T[];
461
```
462

463
### Shuffle
464

465
Creates an array of shuffled values, using a version of the Fisher-Yates shuffle.
466

467
```javascript { .api }
468
/**
469
 * Creates an array of shuffled values, using a version of the
470
 * [Fisher-Yates shuffle](https://en.wikipedia.org/wiki/Fisher-Yates_shuffle).
471
 * @param collection - The collection to shuffle
472
 * @returns Returns the new shuffled array
473
 */
474
function shuffle<T>(collection: T[]): T[];
475
function shuffle<T>(collection: Record<string, T>): T[];
476
```
477

478
### Size
479

480
Gets the size of collection by returning its length for array-like values or the number of own enumerable string keyed properties for objects.
481

482
```javascript { .api }
483
/**
484
 * Gets the size of `collection` by returning its length for array-like
485
 * values or the number of own enumerable string keyed properties for objects.
486
 * @param collection - The collection to inspect
487
 * @returns Returns the collection size
488
 */
489
function size(collection: any[] | object | string): number;
490
```
491

492
### Some
493

494
Checks if predicate returns truthy for any element of collection.
495

496
```javascript { .api }
497
/**
498
 * Checks if `predicate` returns truthy for **any** element of `collection`.
499
 * Iteration is stopped once `predicate` returns truthy.
500
 * @param collection - The collection to iterate over
501
 * @param predicate - The function invoked per iteration
502
 * @returns Returns `true` if any element passes the predicate check, else `false`
503
 */
504
function some<T>(
505
  collection: T[],
506
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
507
): boolean;
508
```
509

510
### Sort By
511

512
Creates an array of elements, sorted in ascending order by the results of running each element thru each iteratee.
513

514
```javascript { .api }
515
/**
516
 * Creates an array of elements, sorted in ascending order by the results
517
 * of running each element in a collection thru each iteratee.
518
 * @param collection - The collection to iterate over
519
 * @param iteratees - The iteratees to sort by
520
 * @returns Returns the new sorted array
521
 */
522
function sortBy<T>(
523
  collection: T[],
524
  ...iteratees: Array<string | ((value: T) => any)>
525
): T[];
526
```
527

528
## Aliases
529

530
- `each` → `forEach`
531
- `eachRight` → `forEachRight`