npm-lodash

1
# Array Operations
2

3
Comprehensive array manipulation utilities including transformation, filtering, set operations, and sorting functions. All array methods return new arrays without modifying the original.
4

5
## Capabilities
6

7
### Union Operations
8

9
Combines arrays into a single array with unique values, providing different comparison strategies.
10

11
```javascript { .api }
12
/**
13
 * Creates an array of unique values, in order, from all given arrays using
14
 * SameValueZero for equality comparisons.
15
 * 
16
 * @param {...Array} [arrays] The arrays to inspect
17
 * @returns {Array} Returns the new array of combined values
18
 */
19
function union(...arrays: Array[]): Array;
20

21
/**
22
 * This method is like `union` except that it accepts `iteratee` which is
23
 * invoked for each element of each `arrays` to generate the criterion by which
24
 * uniqueness is computed. The iteratee is invoked with one argument: (value).
25
 * 
26
 * @param {...Array} [arrays] The arrays to inspect
27
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
28
 * @returns {Array} Returns the new array of combined values
29
 */
30
function unionBy(...arrays: Array[], iteratee: Function|Object|string): Array;
31

32
/**
33
 * This method is like `union` except that it accepts `comparator` which
34
 * is invoked to compare elements of `arrays`. The comparator is invoked
35
 * with two arguments: (arrVal, othVal).
36
 * 
37
 * @param {...Array} [arrays] The arrays to inspect
38
 * @param {Function} [comparator] The comparator invoked per element
39
 * @returns {Array} Returns the new array of combined values
40
 */
41
function unionWith(...arrays: Array[], comparator: Function): Array;
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
import { union, unionBy, unionWith, isEqual } from "lodash";
48

49
// Basic union - removes duplicates
50
union([2, 1], [4, 2], [1, 2]);
51
// Result: [2, 1, 4]
52

53
// Union with iteratee - use Math.floor to compare
54
unionBy([2.1, 1.2], [4.3, 2.4], Math.floor);
55
// Result: [2.1, 1.2, 4.3]
56

57
// Union with property shorthand
58
unionBy([{ 'x': 1 }], [{ 'x': 2 }, { 'x': 1 }], 'x');
59
// Result: [{ 'x': 1 }, { 'x': 2 }]
60

61
// Union with custom comparator
62
const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
63
const others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }];
64
unionWith(objects, others, isEqual);
65
// Result: [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]
66
```
67

68
### Array Chunking
69

70
Splits arrays into smaller groups of specified size.
71

72
```javascript { .api }
73
/**
74
 * Creates an array of elements split into groups the length of `size`.
75
 * If `array` can't be split evenly, the final chunk will be the remaining elements.
76
 * 
77
 * @param {Array} array The array to process
78
 * @param {number} [size=1] The length of each chunk
79
 * @returns {Array} Returns the new array of chunks
80
 */
81
function chunk(array: Array, size?: number): Array[];
82
```
83

84
### Array Compacting
85

86
Removes falsey values from arrays.
87

88
```javascript { .api }
89
/**
90
 * Creates an array with all falsey values removed. The values `false`, `null`,
91
 * `0`, `""`, `undefined`, and `NaN` are falsey.
92
 * 
93
 * @param {Array} array The array to compact
94
 * @returns {Array} Returns the new array of filtered values
95
 */
96
function compact(array: Array): Array;
97
```
98

99
### Array Concatenation
100

101
Combines arrays and values into a new array.
102

103
```javascript { .api }
104
/**
105
 * Creates a new array concatenating `array` with any additional arrays
106
 * and/or values.
107
 * 
108
 * @param {Array} array The array to concatenate
109
 * @param {...*} [values] The values to concatenate
110
 * @returns {Array} Returns the new concatenated array
111
 */
112
function concat(array: Array, ...values: any[]): Array;
113
```
114

115
### Difference Operations
116

117
Creates arrays of values not included in other arrays.
118

119
```javascript { .api }
120
/**
121
 * Creates an array of `array` values not included in the other given arrays
122
 * using SameValueZero for equality comparisons.
123
 * 
124
 * @param {Array} array The array to inspect
125
 * @param {...Array} [values] The values to exclude
126
 * @returns {Array} Returns the new array of filtered values
127
 */
128
function difference(array: Array, ...values: Array[]): Array;
129

130
/**
131
 * This method is like `difference` except that it accepts `iteratee` which
132
 * is invoked for each element of `array` and `values` to generate the criterion
133
 * by which they're compared.
134
 * 
135
 * @param {Array} array The array to inspect
136
 * @param {...Array} [values] The values to exclude
137
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
138
 * @returns {Array} Returns the new array of filtered values
139
 */
140
function differenceBy(array: Array, ...values: Array[], iteratee: Function|Object|string): Array;
141

142
/**
143
 * This method is like `difference` except that it accepts `comparator`
144
 * which is invoked to compare elements of `array` to `values`.
145
 * 
146
 * @param {Array} array The array to inspect
147
 * @param {...Array} [values] The values to exclude
148
 * @param {Function} [comparator] The comparator invoked per element
149
 * @returns {Array} Returns the new array of filtered values
150
 */
151
function differenceWith(array: Array, ...values: Array[], comparator: Function): Array;
152
```
153

154
### Drop Operations
155

156
Creates slices of arrays with elements dropped from the beginning or end.
157

158
```javascript { .api }
159
/**
160
 * Creates a slice of `array` with `n` elements dropped from the beginning.
161
 * 
162
 * @param {Array} array The array to query
163
 * @param {number} [n=1] The number of elements to drop
164
 * @returns {Array} Returns the slice of `array`
165
 */
166
function drop(array: Array, n?: number): Array;
167

168
/**
169
 * Creates a slice of `array` with `n` elements dropped from the end.
170
 * 
171
 * @param {Array} array The array to query
172
 * @param {number} [n=1] The number of elements to drop
173
 * @returns {Array} Returns the slice of `array`
174
 */
175
function dropRight(array: Array, n?: number): Array;
176

177
/**
178
 * Creates a slice of `array` excluding elements dropped from the beginning.
179
 * Elements are dropped until `predicate` returns falsey.
180
 * 
181
 * @param {Array} array The array to query
182
 * @param {Function|Object|string} [predicate] The function invoked per iteration
183
 * @returns {Array} Returns the slice of `array`
184
 */
185
function dropWhile(array: Array, predicate?: Function|Object|string): Array;
186

187
/**
188
 * Creates a slice of `array` excluding elements dropped from the end.
189
 * Elements are dropped until `predicate` returns falsey.
190
 * 
191
 * @param {Array} array The array to query
192
 * @param {Function|Object|string} [predicate] The function invoked per iteration
193
 * @returns {Array} Returns the slice of `array`
194
 */
195
function dropRightWhile(array: Array, predicate?: Function|Object|string): Array;
196
```
197

198
### Array Filling
199

200
Fills elements of arrays with a specified value.
201

202
```javascript { .api }
203
/**
204
 * Fills elements of `array` with `value` from `start` up to, but not
205
 * including, `end`.
206
 * 
207
 * @param {Array} array The array to fill
208
 * @param {*} value The value to fill `array` with
209
 * @param {number} [start=0] The start position
210
 * @param {number} [end=array.length] The end position
211
 * @returns {Array} Returns `array`
212
 */
213
function fill(array: Array, value: any, start?: number, end?: number): Array;
214
```
215

216
### Index Finding
217

218
Finds indexes of elements in arrays.
219

220
```javascript { .api }
221
/**
222
 * This method is like `find` except that it returns the index of the first
223
 * element `predicate` returns truthy for instead of the element itself.
224
 * 
225
 * @param {Array} array The array to inspect
226
 * @param {Function|Object|string} [predicate] The function invoked per iteration
227
 * @param {number} [fromIndex=0] The index to search from
228
 * @returns {number} Returns the index of the found element, else -1
229
 */
230
function findIndex(array: Array, predicate?: Function|Object|string, fromIndex?: number): number;
231

232
/**
233
 * This method is like `findIndex` except that it iterates over elements
234
 * from right to left.
235
 * 
236
 * @param {Array} array The array to inspect
237
 * @param {Function|Object|string} [predicate] The function invoked per iteration
238
 * @param {number} [fromIndex=array.length-1] The index to search from
239
 * @returns {number} Returns the index of the found element, else -1
240
 */
241
function findLastIndex(array: Array, predicate?: Function|Object|string, fromIndex?: number): number;
242
```
243

244
### Array Flattening
245

246
Flattens nested arrays to specified depths.
247

248
```javascript { .api }
249
/**
250
 * Flattens `array` a single level deep.
251
 * 
252
 * @param {Array} array The array to flatten
253
 * @returns {Array} Returns the new flattened array
254
 */
255
function flatten(array: Array): Array;
256

257
/**
258
 * Recursively flattens `array`.
259
 * 
260
 * @param {Array} array The array to flatten
261
 * @returns {Array} Returns the new flattened array
262
 */
263
function flattenDeep(array: Array): Array;
264

265
/**
266
 * Recursively flatten `array` up to `depth` times.
267
 * 
268
 * @param {Array} array The array to flatten
269
 * @param {number} [depth=1] The maximum recursion depth
270
 * @returns {Array} Returns the new flattened array
271
 */
272
function flattenDepth(array: Array, depth?: number): Array;
273
```
274

275
### Intersection Operations
276

277
Creates arrays of unique values included in all given arrays.
278

279
```javascript { .api }
280
/**
281
 * Creates an array of unique values that are included in all given arrays
282
 * using SameValueZero for equality comparisons.
283
 * 
284
 * @param {...Array} [arrays] The arrays to inspect
285
 * @returns {Array} Returns the new array of intersecting values
286
 */
287
function intersection(...arrays: Array[]): Array;
288

289
/**
290
 * This method is like `intersection` except that it accepts `iteratee`
291
 * which is invoked for each element of each `arrays` to generate the criterion
292
 * by which they're compared.
293
 * 
294
 * @param {...Array} [arrays] The arrays to inspect
295
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
296
 * @returns {Array} Returns the new array of intersecting values
297
 */
298
function intersectionBy(...arrays: Array[], iteratee: Function|Object|string): Array;
299

300
/**
301
 * This method is like `intersection` except that it accepts `comparator`
302
 * which is invoked to compare elements of `arrays`.
303
 * 
304
 * @param {...Array} [arrays] The arrays to inspect
305
 * @param {Function} [comparator] The comparator invoked per element
306
 * @returns {Array} Returns the new array of intersecting values
307
 */
308
function intersectionWith(...arrays: Array[], comparator: Function): Array;
309
```
310

311
### Basic Array Operations  
312

313
Core array methods for searching and converting arrays.
314

315
```javascript { .api }
316
/**
317
 * Gets the index at which the first occurrence of `value` is found in `array` using SameValueZero for equality comparisons. If `fromIndex` is negative, it's used as the offset from the end of `array`.
318
 * 
319
 * @param {Array} array The array to inspect
320
 * @param {*} value The value to search for
321
 * @param {number} [fromIndex=0] The index to search from
322
 * @returns {number} Returns the index of the matched value, else `-1`
323
 */
324
function indexOf(array: Array, value: any, fromIndex?: number): number;
325

326
/**
327
 * This method is like `indexOf` except that it iterates over elements of `array` from right to left.
328
 * 
329
 * @param {Array} array The array to inspect
330
 * @param {*} value The value to search for  
331
 * @param {number} [fromIndex=array.length-1] The index to search from
332
 * @returns {number} Returns the index of the matched value, else `-1`
333
 */
334
function lastIndexOf(array: Array, value: any, fromIndex?: number): number;
335

336
/**
337
 * Converts all elements in `array` into a string separated by `separator`.
338
 * 
339
 * @param {Array} array The array to convert
340
 * @param {string} [separator=','] The element separator
341
 * @returns {string} Returns the joined string
342
 */
343
function join(array: Array, separator?: string): string;
344
```
345

346
### Array Access
347

348
Gets elements from specific positions in arrays.
349

350
```javascript { .api }
351
/**
352
 * Gets the first element of `array`.
353
 * 
354
 * @param {Array} array The array to query
355
 * @returns {*} Returns the first element of `array`
356
 */
357
function head(array: Array): any;
358

359
/**
360
 * Gets the last element of `array`.
361
 * 
362
 * @param {Array} array The array to query
363
 * @returns {*} Returns the last element of `array`
364
 */
365
function last(array: Array): any;
366

367
/**
368
 * Gets all but the first element of `array`.
369
 * 
370
 * @param {Array} array The array to query
371
 * @returns {Array} Returns the slice of `array`
372
 */
373
function tail(array: Array): Array;
374

375
/**
376
 * Gets all but the last element of `array`.
377
 * 
378
 * @param {Array} array The array to query
379
 * @returns {Array} Returns the slice of `array`
380
 */
381
function initial(array: Array): Array;
382

383
/**
384
 * Creates an array of elements corresponding to the given keys, or indexes, of `collection`.
385
 * 
386
 * @param {Object} object The object to iterate over
387
 * @param {...(string|string[])} [paths] The property paths to pick
388
 * @returns {Array} Returns the picked values
389
 */
390
function at(object: Object, ...paths: Array<string|string[]>): Array;
391
```
392

393
### Unique Operations
394

395
Creates duplicate-free versions of arrays.
396

397
```javascript { .api }
398
/**
399
 * Creates a duplicate-free version of an array, using SameValueZero
400
 * for equality comparisons, in which only the first occurrence of each element is kept.
401
 * 
402
 * @param {Array} array The array to inspect
403
 * @returns {Array} Returns the new duplicate free array
404
 */
405
function uniq(array: Array): Array;
406

407
/**
408
 * This method is like `uniq` except that it accepts `iteratee` which is
409
 * invoked for each element in `array` to generate the criterion by which
410
 * uniqueness is computed.
411
 * 
412
 * @param {Array} array The array to inspect
413
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
414
 * @returns {Array} Returns the new duplicate free array
415
 */
416
function uniqBy(array: Array, iteratee?: Function|Object|string): Array;
417

418
/**
419
 * This method is like `uniq` except that it accepts `comparator` which
420
 * is invoked to compare elements of `array`.
421
 * 
422
 * @param {Array} array The array to inspect
423
 * @param {Function} [comparator] The comparator invoked per element
424
 * @returns {Array} Returns the new duplicate free array
425
 */
426
function uniqWith(array: Array, comparator?: Function): Array;
427
```
428

429
### Array Exclusion
430

431
Creates arrays excluding specified values.
432

433
```javascript { .api }
434
/**
435
 * Creates an array excluding all given values using SameValueZero
436
 * for equality comparisons.
437
 * 
438
 * @param {Array} array The array to inspect
439
 * @param {...*} [values] The values to exclude
440
 * @returns {Array} Returns the new array of filtered values
441
 */
442
function without(array: Array, ...values: any[]): Array;
443
```
444

445
### Symmetric Difference
446

447
Creates arrays of unique values that is the symmetric difference of given arrays.
448

449
```javascript { .api }
450
/**
451
 * Creates an array of unique values that is the symmetric difference of the given arrays.
452
 * The order of result values is determined by the order they occur in the arrays.
453
 * 
454
 * @param {...Array} [arrays] The arrays to inspect
455
 * @returns {Array} Returns the new array of filtered values
456
 */
457
function xor(...arrays: Array[]): Array;
458

459
/**
460
 * This method is like `xor` except that it accepts `iteratee` which is
461
 * invoked for each element of each `arrays` to generate the criterion by which
462
 * by which they're compared.
463
 * 
464
 * @param {...Array} [arrays] The arrays to inspect
465
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
466
 * @returns {Array} Returns the new array of filtered values
467
 */
468
function xorBy(...arrays: Array[], iteratee: Function|Object|string): Array;
469

470
/**
471
 * This method is like `xor` except that it accepts `comparator` which is
472
 * invoked to compare elements of `arrays`.
473
 * 
474
 * @param {...Array} [arrays] The arrays to inspect
475
 * @param {Function} [comparator] The comparator invoked per element
476
 * @returns {Array} Returns the new array of filtered values
477
 */
478
function xorWith(...arrays: Array[], comparator: Function): Array;
479
```
480

481
### Array Zipping
482

483
Creates arrays of grouped elements.
484

485
```javascript { .api }
486
/**
487
 * Creates an array of grouped elements, the first of which contains the first
488
 * elements of the given arrays, the second of which contains the second
489
 * elements of the given arrays, and so on.
490
 * 
491
 * @param {...Array} [arrays] The arrays to process
492
 * @returns {Array} Returns the new array of grouped elements
493
 */
494
function zip(...arrays: Array[]): Array[];
495

496
/**
497
 * This method is like `zip` except that it accepts `iteratee` to specify
498
 * how grouped values should be combined.
499
 * 
500
 * @param {...Array} [arrays] The arrays to process
501
 * @param {Function} [iteratee] The function to combine grouped values
502
 * @returns {Array} Returns the new array of grouped elements
503
 */
504
function zipWith(...arrays: Array[], iteratee: Function): Array;
505

506
/**
507
 * This method is like `zip` except that it accepts an array of grouped
508
 * elements and creates an array regrouping the elements to their pre-zip configuration.
509
 * 
510
 * @param {Array} array The array of grouped elements to process
511
 * @returns {Array} Returns the new array of regrouped elements
512
 */
513
function unzip(array: Array): Array[];
514

515
/**
516
 * This method is like `unzip` except that it accepts `iteratee` to specify
517
 * how regrouped values should be combined.
518
 * 
519
 * @param {Array} array The array of grouped elements to process
520
 * @param {Function} [iteratee] The function to combine regrouped values
521
 * @returns {Array} Returns the new array of regrouped elements
522
 */
523
function unzipWith(array: Array, iteratee?: Function): Array;
524

525
/**
526
 * The inverse of `toPairs`; this method returns an object composed from key-value `pairs`.
527
 * 
528
 * @param {Array} pairs The key-value pairs
529
 * @returns {Object} Returns the new object
530
 */
531
function fromPairs(pairs: Array): Object;
532

533
/**
534
 * This method is like `fromPairs` except that it accepts two arrays,
535
 * one of property identifiers and one of corresponding values.
536
 * 
537
 * @param {Array} [props=[]] The property identifiers
538
 * @param {Array} [values=[]] The property values
539
 * @returns {Object} Returns the new object
540
 */
541
function zipObject(props?: Array, values?: Array): Object;
542

543
/**
544
 * This method is like `zipObject` except that it supports property paths.
545
 * 
546
 * @param {Array} [props=[]] The property identifiers
547
 * @param {Array} [values=[]] The property values
548
 * @returns {Object} Returns the new object  
549
 */
550
function zipObjectDeep(props?: Array, values?: Array): Object;
551
```