npm-lodash

1
# Collection Processing
2

3
Iteration and processing methods for both arrays and objects, including mapping, filtering, grouping, and reduction operations. All collection methods work with arrays, objects, strings, maps, sets, and other iterables.
4

5
## Capabilities
6

7
### Iteration Methods
8

9
Core iteration utilities for processing collections.
10

11
```javascript { .api }
12
/**
13
 * Iterates over elements of `collection` and invokes `iteratee` for each element.
14
 * The iteratee is invoked with three arguments: (value, index|key, collection).
15
 * 
16
 * @param {Array|Object} collection The collection to iterate over
17
 * @param {Function} [iteratee] The function invoked per iteration
18
 * @returns {Array|Object} Returns `collection`
19
 */
20
function forEach(collection: Array|Object, iteratee?: Function): Array|Object;
21

22
/**
23
 * This method is like `forEach` except that it iterates over elements from right to left.
24
 * 
25
 * @param {Array|Object} collection The collection to iterate over
26
 * @param {Function} [iteratee] The function invoked per iteration
27
 * @returns {Array|Object} Returns `collection`
28
 */
29
function forEachRight(collection: Array|Object, iteratee?: Function): Array|Object;
30
```
31

32
### Transformation Methods
33

34
Transform collections into new arrays or structures.
35

36
```javascript { .api }
37
/**
38
 * Creates an array of values by running each element in `collection` thru `iteratee`.
39
 * The iteratee is invoked with three arguments: (value, index|key, collection).
40
 * 
41
 * @param {Array|Object} collection The collection to iterate over
42
 * @param {Function|Object|string} [iteratee] The function invoked per iteration
43
 * @returns {Array} Returns the new mapped array
44
 */
45
function map(collection: Array|Object, iteratee?: Function|Object|string): Array;
46

47
/**
48
 * Creates a flattened array of values by running each element in `collection`
49
 * thru `iteratee` and flattening the mapped results.
50
 * 
51
 * @param {Array|Object} collection The collection to iterate over
52
 * @param {Function|Object|string} [iteratee] The function invoked per iteration
53
 * @returns {Array} Returns the new flattened array
54
 */
55
function flatMap(collection: Array|Object, iteratee?: Function|Object|string): Array;
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
import { map, flatMap } from "lodash";
62

63
// Basic mapping
64
map([1, 2, 3], n => n * 2);
65
// Result: [2, 4, 6]
66

67
// Object mapping
68
map({ 'a': 1, 'b': 2 }, n => n * 2);
69
// Result: [2, 4]
70

71
// Property shorthand
72
const users = [{ name: 'Alice' }, { name: 'Bob' }];
73
map(users, 'name');
74
// Result: ['Alice', 'Bob']
75

76
// Flat mapping
77
flatMap([1, 2], n => [n, n]);
78
// Result: [1, 1, 2, 2]
79
```
80

81
### Filtering Methods
82

83
Filter collections based on predicates.
84

85
```javascript { .api }
86
/**
87
 * Iterates over elements of `collection`, returning an array of all elements
88
 * `predicate` returns truthy for.
89
 * 
90
 * @param {Array|Object} collection The collection to iterate over
91
 * @param {Function|Object|string} [predicate] The function invoked per iteration
92
 * @returns {Array} Returns the new filtered array
93
 */
94
function filter(collection: Array|Object, predicate?: Function|Object|string): Array;
95

96
/**
97
 * The opposite of `filter`; this method returns the elements of `collection`
98
 * that `predicate` does **not** return truthy for.
99
 * 
100
 * @param {Array|Object} collection The collection to iterate over
101
 * @param {Function|Object|string} [predicate] The function invoked per iteration
102
 * @returns {Array} Returns the new filtered array
103
 */
104
function reject(collection: Array|Object, predicate?: Function|Object|string): Array;
105

106
/**
107
 * Creates an array of two arrays, the first of which contains the elements of
108
 * the given collection for which the predicate returns truthy, the second of which
109
 * contains the elements for which the predicate returns falsy.
110
 * 
111
 * @param {Array|Object} collection The collection to iterate over
112
 * @param {Function|Object|string} [predicate] The function invoked per iteration
113
 * @returns {Array} Returns the array of grouped elements
114
 */
115
function partition(collection: Array|Object, predicate?: Function|Object|string): Array[];
116
```
117

118
### Search Methods
119

120
Find elements in collections.
121

122
```javascript { .api }
123
/**
124
 * Iterates over elements of `collection`, returning the first element
125
 * `predicate` returns truthy for.
126
 * 
127
 * @param {Array|Object} collection The collection to inspect
128
 * @param {Function|Object|string} [predicate] The function invoked per iteration
129
 * @param {number} [fromIndex=0] The index to search from
130
 * @returns {*} Returns the matched element, else `undefined`
131
 */
132
function find(collection: Array|Object, predicate?: Function|Object|string, fromIndex?: number): any;
133

134
/**
135
 * This method is like `find` except that it iterates over elements from right to left.
136
 * 
137
 * @param {Array|Object} collection The collection to inspect
138
 * @param {Function|Object|string} [predicate] The function invoked per iteration
139
 * @param {number} [fromIndex=collection.length-1] The index to search from
140
 * @returns {*} Returns the matched element, else `undefined`
141
 */
142
function findLast(collection: Array|Object, predicate?: Function|Object|string, fromIndex?: number): any;
143

144
/**
145
 * Checks if `value` is in `collection`. If `collection` is a string, it's
146
 * checked for a substring of `value`.
147
 * 
148
 * @param {Array|Object|string} collection The collection to inspect
149
 * @param {*} value The value to search for
150
 * @param {number} [fromIndex=0] The index to search from
151
 * @returns {boolean} Returns `true` if `value` is found, else `false`
152
 */
153
function includes(collection: Array|Object|string, value: any, fromIndex?: number): boolean;
154
```
155

156
### Testing Methods
157

158
Test collections against predicates.
159

160
```javascript { .api }
161
/**
162
 * Checks if `predicate` returns truthy for **all** elements of `collection`.
163
 * Iteration is stopped once `predicate` returns falsey.
164
 * 
165
 * @param {Array|Object} collection The collection to iterate over
166
 * @param {Function|Object|string} [predicate] The function invoked per iteration
167
 * @returns {boolean} Returns `true` if all elements pass the predicate check, else `false`
168
 */
169
function every(collection: Array|Object, predicate?: Function|Object|string): boolean;
170

171
/**
172
 * Checks if `predicate` returns truthy for **any** element of `collection`.
173
 * Iteration is stopped once `predicate` returns truthy.
174
 * 
175
 * @param {Array|Object} collection The collection to iterate over
176
 * @param {Function|Object|string} [predicate] The function invoked per iteration
177
 * @returns {boolean} Returns `true` if any element passes the predicate check, else `false`
178
 */
179
function some(collection: Array|Object, predicate?: Function|Object|string): boolean;
180
```
181

182
### Reduction Methods
183

184
Reduce collections to single values.
185

186
```javascript { .api }
187
/**
188
 * Reduces `collection` to a value which is the accumulated result of running
189
 * each element in `collection` thru `iteratee`.
190
 * 
191
 * @param {Array|Object} collection The collection to iterate over
192
 * @param {Function} [iteratee] The function invoked per iteration
193
 * @param {*} [accumulator] The initial value
194
 * @returns {*} Returns the accumulated value
195
 */
196
function reduce(collection: Array|Object, iteratee?: Function, accumulator?: any): any;
197

198
/**
199
 * This method is like `reduce` except that it iterates over elements from right to left.
200
 * 
201
 * @param {Array|Object} collection The collection to iterate over
202
 * @param {Function} [iteratee] The function invoked per iteration
203
 * @param {*} [accumulator] The initial value
204
 * @returns {*} Returns the accumulated value
205
 */
206
function reduceRight(collection: Array|Object, iteratee?: Function, accumulator?: any): any;
207
```
208

209
**Usage Examples:**
210

211
```javascript
212
import { reduce, reduceRight } from "lodash";
213

214
// Sum array
215
reduce([1, 2, 3], (sum, n) => sum + n, 0);
216
// Result: 6
217

218
// Group by property
219
reduce([
220
  { name: 'Alice', dept: 'IT' },
221
  { name: 'Bob', dept: 'HR' },
222
  { name: 'Charlie', dept: 'IT' }
223
], (result, person) => {
224
  (result[person.dept] || (result[person.dept] = [])).push(person);
225
  return result;
226
}, {});
227
// Result: { IT: [Alice, Charlie], HR: [Bob] }
228

229
// Reduce from right
230
reduceRight([1, 2, 3, 4], (acc, n) => acc + n);
231
// Result: 10
232
```
233

234
### Grouping Methods
235

236
Group collections by criteria.
237

238
```javascript { .api }
239
/**
240
 * Creates an object composed of keys generated from the results of running
241
 * each element of `collection` thru `iteratee`.
242
 * 
243
 * @param {Array|Object} collection The collection to iterate over
244
 * @param {Function|Object|string} [iteratee] The iteratee to transform keys
245
 * @returns {Object} Returns the composed aggregate object
246
 */
247
function groupBy(collection: Array|Object, iteratee?: Function|Object|string): Object;
248

249
/**
250
 * Creates an object composed of keys generated from the results of running
251
 * each element of `collection` thru `iteratee`. The corresponding value of
252
 * each key is the last element responsible for generating the key.
253
 * 
254
 * @param {Array|Object} collection The collection to iterate over
255
 * @param {Function|Object|string} [iteratee] The iteratee to transform keys
256
 * @returns {Object} Returns the composed aggregate object
257
 */
258
function keyBy(collection: Array|Object, iteratee?: Function|Object|string): Object;
259

260
/**
261
 * Creates an object composed of keys generated from the results of running
262
 * each element of `collection` thru `iteratee`. The corresponding value of
263
 * each key is the number of times the key was returned by `iteratee`.
264
 * 
265
 * @param {Array|Object} collection The collection to iterate over
266
 * @param {Function|Object|string} [iteratee] The iteratee to transform keys
267
 * @returns {Object} Returns the composed aggregate object
268
 */
269
function countBy(collection: Array|Object, iteratee?: Function|Object|string): Object;
270
```
271

272
**Usage Examples:**
273

274
```javascript
275
import { groupBy, keyBy, countBy } from "lodash";
276

277
const users = [
278
  { name: 'Alice', age: 25, active: true },
279
  { name: 'Bob', age: 30, active: false },
280
  { name: 'Charlie', age: 25, active: true }
281
];
282

283
// Group by property
284
groupBy(users, 'age');
285
// Result: { '25': [Alice, Charlie], '30': [Bob] }
286

287
// Key by property (last element wins)
288
keyBy(users, 'age');
289
// Result: { '25': Charlie, '30': Bob }
290

291
// Count by property
292
countBy(users, 'active');
293
// Result: { 'true': 2, 'false': 1 }
294

295
// Group by computed value
296
groupBy(['one', 'two', 'three'], 'length');
297
// Result: { '3': ['one', 'two'], '5': ['three'] }
298
```
299

300
### Sorting Methods
301

302
Sort collections with custom criteria.
303

304
```javascript { .api }
305
/**
306
 * Creates an array of elements, sorted in ascending order by the results of
307
 * running each element in a collection thru each iteratee.
308
 * 
309
 * @param {Array|Object} collection The collection to iterate over
310
 * @param {...(Function|Object|string)} [iteratees] The iteratees to sort by
311
 * @returns {Array} Returns the new sorted array
312
 */
313
function sortBy(collection: Array|Object, ...iteratees: (Function|Object|string)[]): Array;
314

315
/**
316
 * This method is like `sortBy` except that it allows specifying the sort
317
 * orders of the iteratees.
318
 * 
319
 * @param {Array|Object} collection The collection to iterate over
320
 * @param {Array|Function|Object|string} [iteratees] The iteratees to sort by
321
 * @param {Array} [orders] The sort orders of `iteratees`
322
 * @returns {Array} Returns the new sorted array
323
 */
324
function orderBy(collection: Array|Object, iteratees?: Array|Function|Object|string, orders?: Array): Array;
325
```
326

327
### Sampling Methods
328

329
Get random elements from collections.
330

331
```javascript { .api }
332
/**
333
 * Gets a random element from `collection`.
334
 * 
335
 * @param {Array|Object} collection The collection to sample
336
 * @returns {*} Returns the random element
337
 */
338
function sample(collection: Array|Object): any;
339

340
/**
341
 * Gets `n` random elements at unique keys from `collection` up to the
342
 * size of `collection`.
343
 * 
344
 * @param {Array|Object} collection The collection to sample
345
 * @param {number} [n=1] The number of elements to sample
346
 * @returns {Array} Returns the random elements
347
 */
348
function sampleSize(collection: Array|Object, n?: number): Array;
349

350
/**
351
 * Creates an array of shuffled values, using a version of the Fisher-Yates shuffle.
352
 * 
353
 * @param {Array|Object} collection The collection to shuffle
354
 * @returns {Array} Returns the new shuffled array
355
 */
356
function shuffle(collection: Array|Object): Array;
357
```
358

359
### Size Methods
360

361
Get collection sizes.
362

363
```javascript { .api }
364
/**
365
 * Gets the size of `collection` by returning its length for array-like
366
 * values or the number of own enumerable string keyed properties for objects.
367
 * 
368
 * @param {Array|Object|string} collection The collection to inspect
369
 * @returns {number} Returns the collection size
370
 */
371
function size(collection: Array|Object|string): number;
372
```
373

374
### Invocation Methods
375

376
Invoke methods on collection elements.
377

378
```javascript { .api }
379
/**
380
 * Invokes the method at `path` of each element in `collection`, returning
381
 * an array of the results of each invoked method.
382
 * 
383
 * @param {Array|Object} collection The collection to iterate over
384
 * @param {Array|Function|string} path The path of the method to invoke or the function invoked per iteration
385
 * @param {...*} [args] The arguments to invoke each method with
386
 * @returns {Array} Returns the array of results
387
 */
388
function invokeMap(collection: Array|Object, path: Array|Function|string, ...args: any[]): Array;
389
```