npm-lodash

1
# Array Methods
2

3
Comprehensive utilities for working with arrays including chunking, flattening, set operations, and element manipulation.
4

5
## Capabilities
6

7
### Array Chunking & Slicing
8

9
#### chunk
10
Creates an array of elements split into groups of the length of size.
11

12
```javascript { .api }
13
/**
14
 * Creates an array of elements split into groups of the length of size
15
 * @param array - The array to process
16
 * @param size - The length of each chunk
17
 * @returns Returns the new array of chunks
18
 */
19
function chunk(array, size = 1);
20
```
21

22
#### slice
23
Creates a slice of array from start up to, but not including, end.
24

25
```javascript { .api }
26
/**
27
 * Creates a slice of array from start up to, but not including, end
28
 * @param array - The array to slice
29
 * @param start - The start position
30
 * @param end - The end position
31
 * @returns Returns the slice of array
32
 */
33
function slice(array, start = 0, end = array.length);
34
```
35

36
#### take & drop
37
Extract or remove elements from array beginning/end.
38

39
```javascript { .api }
40
/**
41
 * Creates a slice of array with n elements taken from the beginning
42
 * @param array - The array to query
43
 * @param n - The number of elements to take
44
 * @returns Returns the slice of array
45
 */
46
function take(array, n = 1);
47

48
/**
49
 * Creates a slice of array with n elements dropped from the beginning
50
 * @param array - The array to query  
51
 * @param n - The number of elements to drop
52
 * @returns Returns the slice of array
53
 */
54
function drop(array, n = 1);
55

56
/**
57
 * Creates a slice of array with n elements taken from the end
58
 * @param array - The array to query
59
 * @param n - The number of elements to take
60
 * @returns Returns the slice of array
61
 */
62
function takeRight(array, n = 1);
63

64
/**
65
 * Creates a slice of array with n elements dropped from the end
66
 * @param array - The array to query
67
 * @param n - The number of elements to drop
68
 * @returns Returns the slice of array
69
 */
70
function dropRight(array, n = 1);
71
```
72

73
### Array Cleaning & Filtering
74

75
#### compact
76
Creates an array with all falsey values removed.
77

78
```javascript { .api }
79
/**
80
 * Creates an array with all falsey values removed
81
 * @param array - The array to compact
82
 * @returns Returns the new array of filtered values
83
 */
84
function compact(array);
85
```
86

87
#### without
88
Creates an array excluding all given values.
89

90
```javascript { .api }
91
/**
92
 * Creates an array excluding all given values using SameValueZero for equality comparisons
93
 * @param array - The array to inspect
94
 * @param values - The values to exclude
95
 * @returns Returns the new array of filtered values
96
 */
97
function without(array, ...values);
98
```
99

100
#### pull & remove
101
Remove elements from array (mutating or non-mutating).
102

103
```javascript { .api }
104
/**
105
 * Removes all given values from array using SameValueZero for equality comparisons
106
 * @param array - The array to modify
107
 * @param values - The values to remove
108
 * @returns Returns array
109
 */
110
function pull(array, ...values);
111

112
/**
113
 * Removes all elements from array that predicate returns truthy for
114
 * @param array - The array to modify
115
 * @param predicate - The function invoked per iteration
116
 * @returns Returns an array of removed elements
117
 */
118
function remove(array, predicate);
119
```
120

121
### Array Flattening
122

123
#### flatten
124
Flattens array a single level deep.
125

126
```javascript { .api }
127
/**
128
 * Flattens array a single level deep
129
 * @param array - The array to flatten
130
 * @returns Returns the new flattened array
131
 */
132
function flatten(array);
133

134
/**
135
 * Recursively flattens array
136
 * @param array - The array to flatten
137
 * @returns Returns the new flattened array
138
 */
139
function flattenDeep(array);
140

141
/**
142
 * Recursively flattens array up to depth times
143
 * @param array - The array to flatten
144
 * @param depth - The maximum recursion depth
145
 * @returns Returns the new flattened array
146
 */
147
function flattenDepth(array, depth = 1);
148
```
149

150
### Array Set Operations
151

152
#### uniq
153
Creates a duplicate-free version of an array.
154

155
```javascript { .api }
156
/**
157
 * Creates a duplicate-free version of an array
158
 * @param array - The array to inspect
159
 * @returns Returns the new duplicate free array
160
 */
161
function uniq(array);
162

163
/**
164
 * Like uniq but accepts iteratee for computing uniqueness
165
 * @param array - The array to inspect
166
 * @param iteratee - The iteratee invoked per element
167
 * @returns Returns the new duplicate free array
168
 */
169
function uniqBy(array, iteratee);
170

171
/**
172
 * Like uniq but accepts comparator for comparing elements
173
 * @param array - The array to inspect
174
 * @param comparator - The comparator invoked per element
175
 * @returns Returns the new duplicate free array
176
 */
177
function uniqWith(array, comparator);
178
```
179

180
#### difference
181
Creates an array of unique array values not included in the other given arrays.
182

183
```javascript { .api }
184
/**
185
 * Creates an array of unique array values not included in the other given arrays
186
 * @param array - The array to inspect
187
 * @param values - The values to exclude
188
 * @returns Returns the new array of filtered values
189
 */
190
function difference(array, ...values);
191

192
/**
193
 * Like difference but accepts iteratee for computing differences
194
 * @param array - The array to inspect
195
 * @param values - The values to exclude
196
 * @param iteratee - The iteratee invoked per element
197
 * @returns Returns the new array of filtered values
198
 */
199
function differenceBy(array, values, iteratee);
200

201
/**
202
 * Like difference but accepts comparator for comparing elements
203
 * @param array - The array to inspect
204
 * @param values - The values to exclude
205
 * @param comparator - The comparator invoked per element
206
 * @returns Returns the new array of filtered values
207
 */
208
function differenceWith(array, values, comparator);
209
```
210

211
#### intersection
212
Creates an array of unique values that are included in all given arrays.
213

214
```javascript { .api }
215
/**
216
 * Creates an array of unique values that are included in all given arrays
217
 * @param arrays - The arrays to inspect
218
 * @returns Returns the new array of intersecting values
219
 */
220
function intersection(...arrays);
221

222
/**
223
 * Like intersection but accepts iteratee for computing intersections
224
 * @param arrays - The arrays to inspect (last parameter is iteratee)
225
 * @returns Returns the new array of intersecting values
226
 */
227
function intersectionBy(...arrays);
228

229
/**
230
 * Like intersection but accepts comparator for comparing elements
231
 * @param arrays - The arrays to inspect (last parameter is comparator)
232
 * @returns Returns the new array of intersecting values
233
 */
234
function intersectionWith(...arrays);
235
```
236

237
#### union & xor
238
Union and symmetric difference operations.
239

240
```javascript { .api }
241
/**
242
 * Creates an array of unique values from all given arrays
243
 * @param arrays - The arrays to inspect
244
 * @returns Returns the new array of combined values
245
 */
246
function union(...arrays);
247

248
/**
249
 * Creates an array of unique values that is the symmetric difference of the given arrays
250
 * @param arrays - The arrays to inspect
251
 * @returns Returns the new array of filtered values
252
 */
253
function xor(...arrays);
254
```
255

256
### Array Searching & Indexing
257

258
#### indexOf & findIndex
259
Find element positions in arrays.
260

261
```javascript { .api }
262
/**
263
 * Gets the index at which the first occurrence of value is found in array
264
 * @param array - The array to inspect
265
 * @param value - The value to search for
266
 * @param fromIndex - The index to search from
267
 * @returns Returns the index of the matched value, else -1
268
 */
269
function indexOf(array, value, fromIndex = 0);
270

271
/**
272
 * Returns the index of the first element predicate returns truthy for
273
 * @param array - The array to inspect
274
 * @param predicate - The function invoked per iteration
275
 * @param fromIndex - The index to search from
276
 * @returns Returns the index of the found element, else -1
277
 */
278
function findIndex(array, predicate, fromIndex = 0);
279

280
/**
281
 * Like findIndex but searches from right to left
282
 * @param array - The array to inspect
283
 * @param predicate - The function invoked per iteration
284
 * @param fromIndex - The index to search from
285
 * @returns Returns the index of the found element, else -1
286
 */
287
function findLastIndex(array, predicate, fromIndex = array.length - 1);
288
```
289

290
### Array Transformation & Zipping
291

292
#### zip & unzip
293
Group corresponding elements from arrays.
294

295
```javascript { .api }
296
/**
297
 * Creates an array of grouped elements
298
 * @param arrays - The arrays to process
299
 * @returns Returns the new array of grouped elements
300
 */
301
function zip(...arrays);
302

303
/**
304
 * Creates an array of grouped elements, the inverse of zip
305
 * @param array - The array of grouped elements to process
306
 * @returns Returns the new array of regrouped elements
307
 */
308
function unzip(array);
309

310
/**
311
 * Like zip but accepts iteratee to specify how grouped values should be combined
312
 * @param arrays - The arrays to process (last parameter is iteratee)
313
 * @returns Returns the new array of grouped elements
314
 */
315
function zipWith(...arrays);
316
```
317

318
#### zipObject
319
Creates an object composed from arrays of property identifiers and values.
320

321
```javascript { .api }
322
/**
323
 * Creates an object composed from arrays of property identifiers and values
324
 * @param props - The property identifiers
325
 * @param values - The property values
326
 * @returns Returns the new object
327
 */
328
function zipObject(props, values);
329

330
/**
331
 * Like zipObject but supports property paths
332
 * @param props - The property identifiers
333
 * @param values - The property values
334
 * @returns Returns the new object
335
 */
336
function zipObjectDeep(props, values);
337
```
338

339
### Array Utilities
340

341
#### fill
342
Fills elements of array with value.
343

344
```javascript { .api }
345
/**
346
 * Fills elements of array with value from start up to, but not including, end
347
 * @param array - The array to fill
348
 * @param value - The value to fill array with
349
 * @param start - The start position
350
 * @param end - The end position
351
 * @returns Returns array
352
 */
353
function fill(array, value, start = 0, end = array.length);
354
```
355

356
#### reverse
357
Reverses array so that the first element becomes the last.
358

359
```javascript { .api }
360
/**
361
 * Reverses array so that the first element becomes the last
362
 * @param array - The array to modify
363
 * @returns Returns array
364
 */
365
function reverse(array);
366
```
367

368
#### join
369
Converts all elements in array into a string separated by separator.
370

371
```javascript { .api }
372
/**
373
 * Converts all elements in array into a string separated by separator
374
 * @param array - The array to convert
375
 * @param separator - The element separator
376
 * @returns Returns the joined string
377
 */
378
function join(array, separator = ',');
379
```
380

381
#### first & last (head & tail)
382
Get first and last elements.
383

384
```javascript { .api }
385
/**
386
 * Gets the first element of array
387
 * @param array - The array to query
388
 * @returns Returns the first element of array
389
 */
390
function head(array);
391

392
/**
393
 * Gets the last element of array
394
 * @param array - The array to query
395
 * @returns Returns the last element of array
396
 */
397
function last(array);
398

399
/**
400
 * Gets all but the first element of array
401
 * @param array - The array to query
402
 * @returns Returns the slice of array
403
 */
404
function tail(array);
405

406
/**
407
 * Gets all but the last element of array
408
 * @param array - The array to query
409
 * @returns Returns the slice of array
410
 */
411
function initial(array);
412
```
413

414
### Sorted Array Methods
415

416
#### sortedIndex
417
Uses binary search to determine the lowest index at which value should be inserted into array.
418

419
```javascript { .api }
420
/**
421
 * Uses binary search to determine the lowest index at which value should be inserted into array
422
 * @param array - The sorted array to inspect
423
 * @param value - The value to evaluate
424
 * @returns Returns the index at which value should be inserted into array
425
 */
426
function sortedIndex(array, value);
427

428
/**
429
 * Like sortedIndex but accepts iteratee for computing sort ranking
430
 * @param array - The sorted array to inspect
431
 * @param value - The value to evaluate
432
 * @param iteratee - The iteratee invoked per element
433
 * @returns Returns the index at which value should be inserted into array
434
 */
435
function sortedIndexBy(array, value, iteratee);
436
```
437

438
#### sortedUniq
439
Creates a duplicate-free version of an array using SameValueZero for equality comparisons.
440

441
```javascript { .api }
442
/**
443
 * Creates a duplicate-free version of an array using SameValueZero for equality comparisons
444
 * @param array - The sorted array to inspect
445
 * @returns Returns the new duplicate free array
446
 */
447
function sortedUniq(array);
448

449
/**
450
 * Like sortedUniq but accepts iteratee for computing uniqueness
451
 * @param array - The sorted array to inspect
452
 * @param iteratee - The iteratee invoked per element
453
 * @returns Returns the new duplicate free array
454
 */
455
function sortedUniqBy(array, iteratee);
456
```
457

458
### Array Concatenation & Building
459

460
#### concat
461
Creates a new array concatenating array with any additional arrays and/or values.
462

463
```javascript { .api }
464
/**
465
 * Creates a new array concatenating array with any additional arrays and/or values
466
 * @param array - The array to concatenate
467
 * @param values - The values to concatenate
468
 * @returns Returns the new concatenated array
469
 */
470
function concat(array, ...values);
471
```
472

473
#### fromPairs
474
Returns an object composed from key-value pairs.
475

476
```javascript { .api }
477
/**
478
 * Returns an object composed from key-value pairs
479
 * @param pairs - The key-value pairs
480
 * @returns Returns the new object
481
 */
482
function fromPairs(pairs);
483
```
484

485
### Conditional Array Operations
486

487
#### dropWhile
488
Creates a slice of array excluding elements dropped from the beginning.
489

490
```javascript { .api }
491
/**
492
 * Creates a slice of array excluding elements dropped from the beginning
493
 * @param array - The array to query
494
 * @param predicate - The function invoked per iteration
495
 * @returns Returns the slice of array
496
 */
497
function dropWhile(array, predicate);
498
```
499

500
#### dropRightWhile
501
Creates a slice of array excluding elements dropped from the end.
502

503
```javascript { .api }
504
/**
505
 * Creates a slice of array excluding elements dropped from the end
506
 * @param array - The array to query
507
 * @param predicate - The function invoked per iteration
508
 * @returns Returns the slice of array
509
 */
510
function dropRightWhile(array, predicate);
511
```
512

513
#### takeWhile
514
Creates a slice of array with elements taken from the beginning.
515

516
```javascript { .api }
517
/**
518
 * Creates a slice of array with elements taken from the beginning
519
 * @param array - The array to query
520
 * @param predicate - The function invoked per iteration
521
 * @returns Returns the slice of array
522
 */
523
function takeWhile(array, predicate);
524
```
525

526
#### takeRightWhile
527
Creates a slice of array with elements taken from the end.
528

529
```javascript { .api }
530
/**
531
 * Creates a slice of array with elements taken from the end
532
 * @param array - The array to query
533
 * @param predicate - The function invoked per iteration
534
 * @returns Returns the slice of array
535
 */
536
function takeRightWhile(array, predicate);
537
```
538

539
### Array Searching & Indexing
540

541
#### lastIndexOf
542
Gets the index at which the last occurrence of value is found in array.
543

544
```javascript { .api }
545
/**
546
 * Gets the index at which the last occurrence of value is found in array
547
 * @param array - The array to inspect
548
 * @param value - The value to search for
549
 * @param fromIndex - The index to search from
550
 * @returns Returns the index of the matched value, else -1
551
 */
552
function lastIndexOf(array, value, fromIndex = array.length - 1);
553
```
554

555
#### sortedIndexOf
556
Performs a binary search of a sorted array and returns the index of the first matching value.
557

558
```javascript { .api }
559
/**
560
 * Performs a binary search of a sorted array and returns the index of the first matching value
561
 * @param array - The sorted array to inspect
562
 * @param value - The value to search for
563
 * @returns Returns the index of the matched value, else -1
564
 */
565
function sortedIndexOf(array, value);
566
```
567

568
#### sortedLastIndex
569
Uses a binary search to determine the highest index at which value should be inserted.
570

571
```javascript { .api }
572
/**
573
 * Uses a binary search to determine the highest index at which value should be inserted
574
 * @param array - The sorted array to inspect
575
 * @param value - The value to evaluate
576
 * @returns Returns the index at which value should be inserted
577
 */
578
function sortedLastIndex(array, value);
579
```
580

581
#### sortedLastIndexBy
582
Like sortedLastIndex but accepts iteratee for computing the sort ranking.
583

584
```javascript { .api }
585
/**
586
 * Like sortedLastIndex but accepts iteratee for computing the sort ranking
587
 * @param array - The sorted array to inspect
588
 * @param value - The value to evaluate
589
 * @param iteratee - The iteratee invoked per element
590
 * @returns Returns the index at which value should be inserted
591
 */
592
function sortedLastIndexBy(array, value, iteratee);
593
```
594

595
#### sortedLastIndexOf
596
Like lastIndexOf but performs a binary search on a sorted array.
597

598
```javascript { .api }
599
/**
600
 * Like lastIndexOf but performs a binary search on a sorted array
601
 * @param array - The sorted array to inspect
602
 * @param value - The value to search for
603
 * @returns Returns the index of the matched value, else -1
604
 */
605
function sortedLastIndexOf(array, value);
606
```
607

608
### Advanced Array Manipulation
609

610
#### pullAll
611
Removes all given values from array using SameValueZero for equality comparisons.
612

613
```javascript { .api }
614
/**
615
 * Removes all given values from array using SameValueZero for equality comparisons
616
 * @param array - The array to modify
617
 * @param values - The values to remove
618
 * @returns Returns array
619
 */
620
function pullAll(array, values);
621
```
622

623
#### pullAllBy
624
Like pullAll but accepts iteratee for specifying how elements are compared.
625

626
```javascript { .api }
627
/**
628
 * Like pullAll but accepts iteratee for specifying how elements are compared
629
 * @param array - The array to modify
630
 * @param values - The values to remove
631
 * @param iteratee - The iteratee invoked per element
632
 * @returns Returns array
633
 */
634
function pullAllBy(array, values, iteratee);
635
```
636

637
#### pullAt
638
Removes elements from array corresponding to indexes and returns an array of removed elements.
639

640
```javascript { .api }
641
/**
642
 * Removes elements from array corresponding to indexes and returns an array of removed elements
643
 * @param array - The array to modify
644
 * @param indexes - The indexes of elements to remove
645
 * @returns Returns the new array of removed elements
646
 */
647
function pullAt(array, ...indexes);
648
```
649

650
### Set Operations (Extended)
651

652
#### unionBy
653
Like union but accepts iteratee for specifying how elements are compared.
654

655
```javascript { .api }
656
/**
657
 * Like union but accepts iteratee for specifying how elements are compared
658
 * @param arrays - The arrays to inspect
659
 * @param iteratee - The iteratee invoked per element
660
 * @returns Returns the new array of combined values
661
 */
662
function unionBy(...arrays, iteratee);
663
```
664

665
#### unionWith
666
Like union but accepts comparator for specifying how elements are compared.
667

668
```javascript { .api }
669
/**
670
 * Like union but accepts comparator for specifying how elements are compared
671
 * @param arrays - The arrays to inspect
672
 * @param comparator - The comparator invoked per element
673
 * @returns Returns the new array of combined values
674
 */
675
function unionWith(...arrays, comparator);
676
```
677

678
#### xorBy
679
Like xor but accepts iteratee for specifying how elements are compared.
680

681
```javascript { .api }
682
/**
683
 * Like xor but accepts iteratee for specifying how elements are compared
684
 * @param arrays - The arrays to inspect
685
 * @param iteratee - The iteratee invoked per element
686
 * @returns Returns the new array of filtered values
687
 */
688
function xorBy(...arrays, iteratee);
689
```
690

691
#### xorWith
692
Like xor but accepts comparator for specifying how elements are compared.
693

694
```javascript { .api }
695
/**
696
 * Like xor but accepts comparator for specifying how elements are compared
697
 * @param arrays - The arrays to inspect
698
 * @param comparator - The comparator invoked per element
699
 * @returns Returns the new array of filtered values
700
 */
701
function xorWith(...arrays, comparator);
702
```
703

704
#### unzipWith
705
Like unzip but accepts iteratee to specify how regrouped values should be combined.
706

707
```javascript { .api }
708
/**
709
 * Like unzip but accepts iteratee to specify how regrouped values should be combined
710
 * @param array - The array of grouped elements to process
711
 * @param iteratee - The function to combine regrouped values
712
 * @returns Returns the new array of regrouped elements
713
 */
714
function unzipWith(array, iteratee);
715
```
716

717
## Usage Examples
718

719
```javascript
720
import { 
721
  chunk, compact, difference, flatten, uniq, 
722
  zip, head, last, indexOf, take, drop 
723
} from "lodash";
724

725
// Chunking arrays
726
const items = [1, 2, 3, 4, 5, 6, 7, 8];
727
const batches = chunk(items, 3);
728
// Result: [[1, 2, 3], [4, 5, 6], [7, 8]]
729

730
// Cleaning arrays
731
const mixed = [0, 1, false, 2, '', 3, null, 4, undefined, 5];
732
const clean = compact(mixed);
733
// Result: [1, 2, 3, 4, 5]
734

735
// Set operations
736
const arr1 = [1, 2, 3, 4];
737
const arr2 = [2, 3, 5, 6];
738
const diff = difference(arr1, arr2);
739
// Result: [1, 4]
740

741
// Flattening
742
const nested = [1, [2, 3], [4, [5, 6]]];
743
const flat = flatten(nested);
744
// Result: [1, 2, 3, 4, [5, 6]]
745
const deepFlat = flattenDeep(nested);
746
// Result: [1, 2, 3, 4, 5, 6]
747

748
// Deduplication
749
const duplicates = [1, 2, 2, 3, 3, 3, 4];
750
const unique = uniq(duplicates);
751
// Result: [1, 2, 3, 4]
752

753
// Zipping arrays
754
const names = ['John', 'Jane'];
755
const ages = [30, 25];
756
const pairs = zip(names, ages);
757
// Result: [['John', 30], ['Jane', 25]]
758

759
// Array access
760
const numbers = [10, 20, 30, 40, 50];
761
const first = head(numbers);    // 10
762
const lastItem = last(numbers); // 50
763
const firstThree = take(numbers, 3); // [10, 20, 30]
764
const skipTwo = drop(numbers, 2);    // [30, 40, 50]
765
```