npm-lodash

1
# Object Utilities
2

3
Object manipulation including property access, assignment, merging, and transformation utilities. These methods provide safe and flexible ways to work with JavaScript objects.
4

5
## Capabilities
6

7
### Property Assignment
8

9
Assign properties from source objects to target objects.
10

11
```javascript { .api }
12
/**
13
 * Assigns own enumerable string keyed properties of source objects to the
14
 * destination object. Source objects are applied from left to right.
15
 * 
16
 * @param {Object} object The destination object
17
 * @param {...Object} [sources] The source objects
18
 * @returns {Object} Returns `object`
19
 */
20
function assign(object: Object, ...sources: Object[]): Object;
21

22
/**
23
 * This method is like `assign` except that it iterates over own and
24
 * inherited source properties.
25
 * 
26
 * @param {Object} object The destination object
27
 * @param {...Object} [sources] The source objects
28
 * @returns {Object} Returns `object`
29
 */
30
function assignIn(object: Object, ...sources: Object[]): Object;
31

32
/**
33
 * This method is like `assign` except that it accepts `customizer`
34
 * which is invoked to produce the assigned values.
35
 * 
36
 * @param {Object} object The destination object
37
 * @param {...Object} [sources] The source objects
38
 * @param {Function} [customizer] The function to customize assigned values
39
 * @returns {Object} Returns `object`
40
 */
41
function assignWith(object: Object, ...sources: Object[], customizer: Function): Object;
42

43
/**
44
 * This method is like `assignIn` except that it accepts `customizer`
45
 * which is invoked to produce the assigned values.
46
 * 
47
 * @param {Object} object The destination object
48
 * @param {...Object} [sources] The source objects
49
 * @param {Function} [customizer] The function to customize assigned values
50
 * @returns {Object} Returns `object`
51
 */
52
function assignInWith(object: Object, ...sources: Object[], customizer: Function): Object;
53
```
54

55
### Property Access
56

57
Get and set object properties safely.
58

59
```javascript { .api }
60
/**
61
 * Gets the value at `path` of `object`. If the resolved value is
62
 * `undefined`, the `defaultValue` is returned in its place.
63
 * 
64
 * @param {Object} object The object to query
65
 * @param {Array|string} path The path of the property to get
66
 * @param {*} [defaultValue] The value returned for `undefined` resolved values
67
 * @returns {*} Returns the resolved value
68
 */
69
function get(object: Object, path: Array|string, defaultValue?: any): any;
70

71
/**
72
 * Sets the value at `path` of `object`. If a portion of `path` doesn't exist,
73
 * it's created. Arrays are created for missing index properties while objects
74
 * are created for all other missing properties.
75
 * 
76
 * @param {Object} object The object to modify
77
 * @param {Array|string} path The path of the property to set
78
 * @param {*} value The value to set
79
 * @returns {Object} Returns `object`
80
 */
81
function set(object: Object, path: Array|string, value: any): Object;
82

83
/**
84
 * This method is like `set` except that it accepts `customizer` which is
85
 * invoked to produce the objects of `path`.
86
 * 
87
 * @param {Object} object The object to modify
88
 * @param {Array|string} path The path of the property to set
89
 * @param {*} value The value to set
90
 * @param {Function} [customizer] The function to customize assigned values
91
 * @returns {Object} Returns `object`
92
 */
93
function setWith(object: Object, path: Array|string, value: any, customizer?: Function): Object;
94

95
/**
96
 * Removes the property at `path` of `object`.
97
 * 
98
 * @param {Object} object The object to modify
99
 * @param {Array|string} path The path of the property to unset
100
 * @returns {boolean} Returns `true` if the property is deleted, else `false`
101
 */
102
function unset(object: Object, path: Array|string): boolean;
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
import { get, set, unset } from "lodash";
109

110
const obj = { a: { b: { c: 3 } } };
111

112
// Safe property access
113
get(obj, 'a.b.c'); // 3
114
get(obj, 'a.b.d', 'default'); // 'default'
115
get(obj, ['a', 'b', 'c']); // 3
116

117
// Property setting
118
set(obj, 'a.b.d', 4);
119
// obj is now { a: { b: { c: 3, d: 4 } } }
120

121
// Property removal
122
unset(obj, 'a.b.c');
123
// obj is now { a: { b: { d: 4 } } }
124
```
125

126
### Property Checking
127

128
Check for property existence.
129

130
```javascript { .api }
131
/**
132
 * Checks if `path` is a direct property of `object`.
133
 * 
134
 * @param {Object} object The object to query
135
 * @param {Array|string} path The path to check
136
 * @returns {boolean} Returns `true` if `path` exists, else `false`
137
 */
138
function has(object: Object, path: Array|string): boolean;
139

140
/**
141
 * Checks if `path` is a direct or inherited property of `object`.
142
 * 
143
 * @param {Object} object The object to query
144
 * @param {Array|string} path The path to check
145
 * @returns {boolean} Returns `true` if `path` exists, else `false`
146
 */
147
function hasIn(object: Object, path: Array|string): boolean;
148
```
149

150
### Property Selection
151

152
Select or omit properties from objects.
153

154
```javascript { .api }
155
/**
156
 * Creates an object composed of the picked `object` properties.
157
 * 
158
 * @param {Object} object The source object
159
 * @param {...(string|string[])} [paths] The property paths to pick
160
 * @returns {Object} Returns the new object
161
 */
162
function pick(object: Object, ...paths: (string|string[])[]): Object;
163

164
/**
165
 * Creates an object composed of the `object` properties `predicate` returns
166
 * truthy for.
167
 * 
168
 * @param {Object} object The source object
169
 * @param {Function|Object|string} [predicate] The function invoked per property
170
 * @returns {Object} Returns the new object
171
 */
172
function pickBy(object: Object, predicate?: Function|Object|string): Object;
173

174
/**
175
 * The opposite of `pick`; this method creates an object composed of the
176
 * own and inherited enumerable property paths of `object` that are not omitted.
177
 * 
178
 * @param {Object} object The source object
179
 * @param {...(string|string[])} [paths] The property paths to omit
180
 * @returns {Object} Returns the new object
181
 */
182
function omit(object: Object, ...paths: (string|string[])[]): Object;
183

184
/**
185
 * The opposite of `pickBy`; this method creates an object composed of
186
 * the own and inherited enumerable string keyed properties of `object` that
187
 * `predicate` doesn't return truthy for.
188
 * 
189
 * @param {Object} object The source object
190
 * @param {Function|Object|string} [predicate] The function invoked per property
191
 * @returns {Object} Returns the new object
192
 */
193
function omitBy(object: Object, predicate?: Function|Object|string): Object;
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
import { pick, pickBy, omit, omitBy } from "lodash";
200

201
const user = { name: 'Alice', age: 25, email: 'alice@example.com', password: 'secret' };
202

203
// Pick specific properties
204
pick(user, ['name', 'email']);
205
// Result: { name: 'Alice', email: 'alice@example.com' }
206

207
// Pick by predicate
208
pickBy(user, value => typeof value === 'string');
209
// Result: { name: 'Alice', email: 'alice@example.com', password: 'secret' }
210

211
// Omit specific properties
212
omit(user, ['password']);
213
// Result: { name: 'Alice', age: 25, email: 'alice@example.com' }
214

215
// Omit by predicate
216
omitBy(user, value => typeof value === 'string');
217
// Result: { age: 25 }
218
```
219

220
### Object Merging
221

222
Merge objects deeply or shallowly.
223

224
```javascript { .api }
225
/**
226
 * This method is like `assign` except that it recursively merges own and
227
 * inherited enumerable string keyed properties of source objects into the
228
 * destination object.
229
 * 
230
 * @param {Object} object The destination object
231
 * @param {...Object} [sources] The source objects
232
 * @returns {Object} Returns `object`
233
 */
234
function merge(object: Object, ...sources: Object[]): Object;
235

236
/**
237
 * This method is like `merge` except that it accepts `customizer` which
238
 * is invoked to produce the merged values of the destination and source properties.
239
 * 
240
 * @param {Object} object The destination object
241
 * @param {...Object} [sources] The source objects
242
 * @param {Function} [customizer] The function to customize assigned values
243
 * @returns {Object} Returns `object`
244
 */
245
function mergeWith(object: Object, ...sources: Object[], customizer: Function): Object;
246
```
247

248
### Default Values
249

250
Assign default properties to objects.
251

252
```javascript { .api }
253
/**
254
 * Assigns own and inherited enumerable string keyed properties of source
255
 * objects to the destination object for all destination properties that
256
 * resolve to `undefined`.
257
 * 
258
 * @param {Object} object The destination object
259
 * @param {...Object} [sources] The source objects
260
 * @returns {Object} Returns `object`
261
 */
262
function defaults(object: Object, ...sources: Object[]): Object;
263

264
/**
265
 * This method is like `defaults` except that it recursively assigns
266
 * default properties.
267
 * 
268
 * @param {Object} object The destination object
269
 * @param {...Object} [sources] The source objects
270
 * @returns {Object} Returns `object`
271
 */
272
function defaultsDeep(object: Object, ...sources: Object[]): Object;
273
```
274

275
### Object Keys and Values
276

277
Extract keys, values, and pairs from objects.
278

279
```javascript { .api }
280
/**
281
 * Creates an array of the own enumerable property names of `object`.
282
 * 
283
 * @param {Object} object The object to query
284
 * @returns {Array} Returns the array of property names
285
 */
286
function keys(object: Object): Array;
287

288
/**
289
 * Creates an array of the own and inherited enumerable property names of `object`.
290
 * 
291
 * @param {Object} object The object to query
292
 * @returns {Array} Returns the array of property names
293
 */
294
function keysIn(object: Object): Array;
295

296
/**
297
 * Creates an array of the own enumerable string keyed property values of `object`.
298
 * 
299
 * @param {Object} object The object to query
300
 * @returns {Array} Returns the array of property values
301
 */
302
function values(object: Object): Array;
303

304
/**
305
 * Creates an array of the own and inherited enumerable string keyed property
306
 * values of `object`.
307
 * 
308
 * @param {Object} object The object to query
309
 * @returns {Array} Returns the array of property values
310
 */
311
function valuesIn(object: Object): Array;
312

313
/**
314
 * Creates an array of own enumerable string keyed-value pairs for `object`.
315
 * 
316
 * @param {Object} object The object to query
317
 * @returns {Array} Returns the key-value pairs
318
 */
319
function toPairs(object: Object): Array;
320

321
/**
322
 * Creates an array of own and inherited enumerable string keyed-value pairs
323
 * for `object`.
324
 * 
325
 * @param {Object} object The object to query
326
 * @returns {Array} Returns the key-value pairs
327
 */
328
function toPairsIn(object: Object): Array;
329
```
330

331
### Object Creation
332

333
Create new objects with specific prototypes.
334

335
```javascript { .api }
336
/**
337
 * Creates an object that inherits from the `prototype` object. If a
338
 * `properties` object is given, its own enumerable string keyed properties
339
 * are assigned to the created object.
340
 * 
341
 * @param {Object} prototype The object to inherit from
342
 * @param {Object} [properties] The properties to assign to the object
343
 * @returns {Object} Returns the new object
344
 */
345
function create(prototype: Object, properties?: Object): Object;
346
```
347

348
### Object Inversion
349

350
Invert object key-value relationships.
351

352
```javascript { .api }
353
/**
354
 * Creates an object composed of the inverted keys and values of `object`.
355
 * If `object` contains duplicate values, subsequent values overwrite
356
 * property assignments of previous values.
357
 * 
358
 * @param {Object} object The object to invert
359
 * @returns {Object} Returns the new inverted object
360
 */
361
function invert(object: Object): Object;
362

363
/**
364
 * This method is like `invert` except that the inverted object is generated
365
 * from the results of running each element of `object` thru `iteratee`.
366
 * 
367
 * @param {Object} object The object to invert
368
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
369
 * @returns {Object} Returns the new inverted object
370
 */
371
function invertBy(object: Object, iteratee?: Function|Object|string): Object;
372
```
373

374
### Function Properties
375

376
Get function property names from objects.
377

378
```javascript { .api }
379
/**
380
 * Creates an array of function property names from own enumerable properties
381
 * of `object`.
382
 * 
383
 * @param {Object} object The object to inspect
384
 * @returns {Array} Returns the function names
385
 */
386
function functions(object: Object): Array;
387

388
/**
389
 * Creates an array of function property names from own and inherited
390
 * enumerable properties of `object`.
391
 * 
392
 * @param {Object} object The object to inspect
393
 * @returns {Array} Returns the function names
394
 */
395
function functionsIn(object: Object): Array;
396
```
397

398
### Object Iteration
399

400
Iterate over object properties.
401

402
```javascript { .api }
403
/**
404
 * Iterates over own enumerable string keyed properties of an object and
405
 * invokes `iteratee` for each property.
406
 * 
407
 * @param {Object} object The object to iterate over
408
 * @param {Function} [iteratee] The function invoked per iteration
409
 * @returns {Object} Returns `object`
410
 */
411
function forOwn(object: Object, iteratee?: Function): Object;
412

413
/**
414
 * This method is like `forOwn` except that it iterates over properties in reverse order.
415
 * 
416
 * @param {Object} object The object to iterate over
417
 * @param {Function} [iteratee] The function invoked per iteration
418
 * @returns {Object} Returns `object`
419
 */
420
function forOwnRight(object: Object, iteratee?: Function): Object;
421

422
/**
423
 * Iterates over own and inherited enumerable string keyed properties of an
424
 * object and invokes `iteratee` for each property.
425
 * 
426
 * @param {Object} object The object to iterate over
427
 * @param {Function} [iteratee] The function invoked per iteration
428
 * @returns {Object} Returns `object`
429
 */
430
function forIn(object: Object, iteratee?: Function): Object;
431

432
/**
433
 * This method is like `forIn` except that it iterates over properties in reverse order.
434
 * 
435
 * @param {Object} object The object to iterate over
436
 * @param {Function} [iteratee] The function invoked per iteration
437
 * @returns {Object} Returns `object`
438
 */
439
function forInRight(object: Object, iteratee?: Function): Object;
440
```
441

442
### Object Search
443

444
Find properties in objects.
445

446
```javascript { .api }
447
/**
448
 * This method is like `find` except that it returns the key of the first
449
 * element `predicate` returns truthy for instead of the element itself.
450
 * 
451
 * @param {Object} object The object to inspect
452
 * @param {Function|Object|string} [predicate] The function invoked per iteration
453
 * @returns {string|undefined} Returns the key of the matched element, else `undefined`
454
 */
455
function findKey(object: Object, predicate?: Function|Object|string): string|undefined;
456

457
/**
458
 * This method is like `findKey` except that it iterates over elements in reverse order.
459
 * 
460
 * @param {Object} object The object to inspect
461
 * @param {Function|Object|string} [predicate] The function invoked per iteration
462
 * @returns {string|undefined} Returns the key of the matched element, else `undefined`
463
 */
464
function findLastKey(object: Object, predicate?: Function|Object|string): string|undefined;
465
```
466

467
### Object Transformation
468

469
Transform objects with custom logic.
470

471
```javascript { .api }
472
/**
473
 * An alternative to `reduce`; this method transforms `object` to a new
474
 * `accumulator` object which is the result of running each of its own
475
 * enumerable string keyed properties thru `iteratee`.
476
 * 
477
 * @param {Object} object The object to iterate over
478
 * @param {Function} [iteratee] The function invoked per iteration
479
 * @param {*} [accumulator] The custom accumulator value
480
 * @returns {*} Returns the accumulated value
481
 */
482
function transform(object: Object, iteratee?: Function, accumulator?: any): any;
483

484
/**
485
 * The opposite of `mapValues`; this method creates an object with the same values
486
 * as `object` and keys generated by running each own enumerable string keyed
487
 * property of `object` thru `iteratee`.
488
 * 
489
 * @param {Object} object The object to iterate over
490
 * @param {Function|Object|string} [iteratee] The function invoked per iteration
491
 * @returns {Object} Returns the new mapped object
492
 */
493
function mapKeys(object: Object, iteratee?: Function|Object|string): Object;
494

495
/**
496
 * Creates an object with the same keys as `object` and values generated by
497
 * running each own enumerable string keyed property of `object` thru `iteratee`.
498
 * 
499
 * @param {Object} object The object to iterate over
500
 * @param {Function|Object|string} [iteratee] The function invoked per iteration
501
 * @returns {Object} Returns the new mapped object
502
 */
503
function mapValues(object: Object, iteratee?: Function|Object|string): Object;
504

505
/**
506
 * This method is like `get` except that if the resolved value is a function
507
 * it's invoked with the `this` binding of its parent object and its result is returned.
508
 * 
509
 * @param {Object} object The object to query
510
 * @param {Array|string} path The path of the property to resolve
511
 * @param {*} [defaultValue] The value returned for `undefined` resolved values
512
 * @returns {*} Returns the resolved value
513
 */
514
function result(object: Object, path: Array|string, defaultValue?: any): any;
515
```
516

517
### Method Invocation
518

519
Invoke methods on objects.
520

521
```javascript { .api }
522
/**
523
 * Invokes the method at `path` of `object`.
524
 * 
525
 * @param {Object} object The object to query
526
 * @param {Array|string} path The path of the method to invoke
527
 * @param {...*} [args] The arguments to invoke the method with
528
 * @returns {*} Returns the result of the invoked method
529
 */
530
function invoke(object: Object, path: Array|string, ...args: any[]): any;
531
```
532

533
### Property Updates
534

535
Update object properties with functions.
536

537
```javascript { .api }
538
/**
539
 * This method is like `set` except that accepts `updater` to produce the
540
 * value to set.
541
 * 
542
 * @param {Object} object The object to modify
543
 * @param {Array|string} path The path of the property to set
544
 * @param {Function} updater The function to produce the updated value
545
 * @returns {Object} Returns `object`
546
 */
547
function update(object: Object, path: Array|string, updater: Function): Object;
548

549
/**
550
 * This method is like `update` except that it accepts `customizer` which is
551
 * invoked to produce the objects of `path`.
552
 * 
553
 * @param {Object} object The object to modify
554
 * @param {Array|string} path The path of the property to set
555
 * @param {Function} updater The function to produce the updated value
556
 * @param {Function} [customizer] The function to customize assigned values
557
 * @returns {Object} Returns `object`
558
 */
559
function updateWith(object: Object, path: Array|string, updater: Function, customizer?: Function): Object;
560
```