npm-lodash

1
# Object Methods
2

3
Deep object manipulation including property access, merging, transformation, and introspection. These methods provide powerful tools for working with complex nested objects and data structures.
4

5
## Capabilities
6

7
### Property Access
8

9
#### get
10
Gets the value at path of object.
11

12
```javascript { .api }
13
/**
14
 * Gets the value at path of object. If the resolved value is undefined, the defaultValue is returned in its place
15
 * @param object - The object to query
16
 * @param path - The path of the property to get
17
 * @param defaultValue - The value returned for undefined resolved values
18
 * @returns Returns the resolved value
19
 */
20
function get(object, path, defaultValue);
21
```
22

23
#### set
24
Sets the value at path of object.
25

26
```javascript { .api }
27
/**
28
 * Sets the value at path of object. If a portion of path doesn't exist, it's created
29
 * @param object - The object to modify
30
 * @param path - The path of the property to set
31
 * @param value - The value to set
32
 * @returns Returns object
33
 */
34
function set(object, path, value);
35

36
/**
37
 * Like set except that it accepts customizer which is invoked to produce the objects of path
38
 * @param object - The object to modify
39
 * @param path - The path of the property to set
40
 * @param value - The value to set
41
 * @param customizer - The function to customize assigned values
42
 * @returns Returns object
43
 */
44
function setWith(object, path, value, customizer);
45
```
46

47
#### has
48
Checks if path is a direct property of object.
49

50
```javascript { .api }
51
/**
52
 * Checks if path is a direct property of object
53
 * @param object - The object to query
54
 * @param path - The path to check
55
 * @returns Returns true if path exists, else false
56
 */
57
function has(object, path);
58

59
/**
60
 * Checks if path is a direct or inherited property of object
61
 * @param object - The object to query
62
 * @param path - The path to check
63
 * @returns Returns true if path exists, else false
64
 */
65
function hasIn(object, path);
66
```
67

68
#### at
69
Creates an array of values corresponding to paths of object.
70

71
```javascript { .api }
72
/**
73
 * Creates an array of values corresponding to paths of object
74
 * @param object - The object to iterate over
75
 * @param paths - The property paths to pick
76
 * @returns Returns the picked values
77
 */
78
function at(object, ...paths);
79
```
80

81
### Property Extraction
82

83
#### keys & values
84
Gets the own enumerable property names and values of object.
85

86
```javascript { .api }
87
/**
88
 * Creates an array of the own enumerable property names of object
89
 * @param object - The object to query
90
 * @returns Returns the array of property names
91
 */
92
function keys(object);
93

94
/**
95
 * Creates an array of the own and inherited enumerable property names of object
96
 * @param object - The object to query
97
 * @returns Returns the array of property names
98
 */
99
function keysIn(object);
100

101
/**
102
 * Creates an array of the own enumerable string keyed property values of object
103
 * @param object - The object to query
104
 * @returns Returns the array of property values
105
 */
106
function values(object);
107

108
/**
109
 * Creates an array of the own and inherited enumerable string keyed property values of object
110
 * @param object - The object to query
111
 * @returns Returns the array of property values
112
 */
113
function valuesIn(object);
114
```
115

116
#### toPairs
117
Creates an array of own enumerable string keyed-value pairs for object.
118

119
```javascript { .api }
120
/**
121
 * Creates an array of own enumerable string keyed-value pairs for object
122
 * @param object - The object to query
123
 * @returns Returns the key-value pairs
124
 */
125
function toPairs(object);
126

127
/**
128
 * Creates an array of own and inherited enumerable string keyed-value pairs for object
129
 * @param object - The object to query
130
 * @returns Returns the key-value pairs
131
 */
132
function toPairsIn(object);
133
```
134

135
### Property Selection
136

137
#### pick
138
Creates an object composed of the picked object properties.
139

140
```javascript { .api }
141
/**
142
 * Creates an object composed of the picked object properties
143
 * @param object - The source object
144
 * @param paths - The property paths to pick
145
 * @returns Returns the new object
146
 */
147
function pick(object, ...paths);
148

149
/**
150
 * Creates an object composed of the object properties predicate returns truthy for
151
 * @param object - The source object
152
 * @param predicate - The function invoked per property
153
 * @returns Returns the new object
154
 */
155
function pickBy(object, predicate);
156
```
157

158
#### omit
159
Creates an object composed of the own and inherited enumerable property paths that are not omitted.
160

161
```javascript { .api }
162
/**
163
 * Creates an object composed of the own and inherited enumerable property paths that are not omitted
164
 * @param object - The source object
165
 * @param paths - The property paths to omit
166
 * @returns Returns the new object
167
 */
168
function omit(object, ...paths);
169

170
/**
171
 * The opposite of pickBy; creates an object composed of the own and inherited enumerable string keyed properties of object that predicate doesn't return truthy for
172
 * @param object - The source object
173
 * @param predicate - The function invoked per property
174
 * @returns Returns the new object
175
 */
176
function omitBy(object, predicate);
177
```
178

179
### Object Merging
180

181
#### assign
182
Assigns own enumerable string keyed properties of source objects to the destination object.
183

184
```javascript { .api }
185
/**
186
 * Assigns own enumerable string keyed properties of source objects to the destination object
187
 * @param object - The destination object
188
 * @param sources - The source objects
189
 * @returns Returns object
190
 */
191
function assign(object, ...sources);
192

193
/**
194
 * Like assign except that it iterates over own and inherited source properties
195
 * @param object - The destination object
196
 * @param sources - The source objects
197
 * @returns Returns object
198
 */
199
function assignIn(object, ...sources);
200

201
/**
202
 * Like assign but accepts customizer which is invoked to produce the assigned values
203
 * @param object - The destination object
204
 * @param sources - The source objects
205
 * @param customizer - The function to customize assigned values
206
 * @returns Returns object
207
 */
208
function assignWith(object, sources, customizer);
209
```
210

211
#### merge
212
Recursively merges own and inherited enumerable string keyed properties of source objects into the destination object.
213

214
```javascript { .api }
215
/**
216
 * Recursively merges own and inherited enumerable string keyed properties of source objects into the destination object
217
 * @param object - The destination object
218
 * @param sources - The source objects
219
 * @returns Returns object
220
 */
221
function merge(object, ...sources);
222

223
/**
224
 * Like merge but accepts customizer which is invoked to produce the merged values
225
 * @param object - The destination object
226
 * @param sources - The source objects
227
 * @param customizer - The function to customize assigned values
228
 * @returns Returns object
229
 */
230
function mergeWith(object, sources, customizer);
231
```
232

233
### Object Defaults
234

235
#### defaults
236
Assigns properties of source objects to the destination object for all destination properties that resolve to undefined.
237

238
```javascript { .api }
239
/**
240
 * Assigns properties of source objects to the destination object for all destination properties that resolve to undefined
241
 * @param object - The destination object
242
 * @param sources - The source objects
243
 * @returns Returns object
244
 */
245
function defaults(object, ...sources);
246

247
/**
248
 * Like defaults except that it recursively assigns default properties
249
 * @param object - The destination object
250
 * @param sources - The source objects
251
 * @returns Returns object
252
 */
253
function defaultsDeep(object, ...sources);
254
```
255

256
### Object Transformation
257

258
#### mapKeys & mapValues
259
Creates an object with the same values/keys as object and keys/values generated by running each property through iteratee.
260

261
```javascript { .api }
262
/**
263
 * Creates an object with the same values as object and keys generated by running each own enumerable string keyed property of object through iteratee
264
 * @param object - The object to iterate over
265
 * @param iteratee - The function invoked per iteration
266
 * @returns Returns the new mapped object
267
 */
268
function mapKeys(object, iteratee);
269

270
/**
271
 * Creates an object with the same keys as object and values generated by running each own enumerable string keyed property of object through iteratee
272
 * @param object - The object to iterate over
273
 * @param iteratee - The function invoked per iteration
274
 * @returns Returns the new mapped object
275
 */
276
function mapValues(object, iteratee);
277
```
278

279
#### transform
280
An alternative to reduce; this method transforms object to a new accumulator object.
281

282
```javascript { .api }
283
/**
284
 * An alternative to reduce; this method transforms object to a new accumulator object which is the result of running each of its own enumerable string keyed properties through iteratee
285
 * @param object - The object to iterate over
286
 * @param iteratee - The function invoked per iteration
287
 * @param accumulator - The custom accumulator value
288
 * @returns Returns the accumulated value
289
 */
290
function transform(object, iteratee, accumulator);
291
```
292

293
### Object Inversion
294

295
#### invert
296
Creates an object composed of the inverted keys and values of object.
297

298
```javascript { .api }
299
/**
300
 * Creates an object composed of the inverted keys and values of object
301
 * @param object - The object to invert
302
 * @returns Returns the new inverted object
303
 */
304
function invert(object);
305

306
/**
307
 * Like invert except that the inverted object is generated from the results of running each element of object through iteratee
308
 * @param object - The object to invert
309
 * @param iteratee - The iteratee invoked per element
310
 * @returns Returns the new inverted object
311
 */
312
function invertBy(object, iteratee);
313
```
314

315
### Object Searching
316

317
#### findKey
318
Like find except that it returns the key of the first element predicate returns truthy for instead of the element itself.
319

320
```javascript { .api }
321
/**
322
 * Like find except that it returns the key of the first element predicate returns truthy for instead of the element itself
323
 * @param object - The object to inspect
324
 * @param predicate - The function invoked per iteration
325
 * @returns Returns the key of the matched element, else undefined
326
 */
327
function findKey(object, predicate);
328

329
/**
330
 * Like findKey except that it iterates over elements of a collection in the opposite order
331
 * @param object - The object to inspect
332
 * @param predicate - The function invoked per iteration
333
 * @returns Returns the key of the matched element, else undefined
334
 */
335
function findLastKey(object, predicate);
336
```
337

338
### Object Iteration
339

340
#### forIn & forOwn
341
Iterates over own and inherited / own enumerable string keyed properties of an object.
342

343
```javascript { .api }
344
/**
345
 * Iterates over own and inherited enumerable string keyed properties of an object and invokes iteratee for each property
346
 * @param object - The object to iterate over
347
 * @param iteratee - The function invoked per iteration
348
 * @returns Returns object
349
 */
350
function forIn(object, iteratee);
351

352
/**
353
 * Like forIn except that it iterates over properties in the opposite order
354
 * @param object - The object to iterate over
355
 * @param iteratee - The function invoked per iteration
356
 * @returns Returns object
357
 */
358
function forInRight(object, iteratee);
359

360
/**
361
 * Iterates over own enumerable string keyed properties of an object and invokes iteratee for each property
362
 * @param object - The object to iterate over
363
 * @param iteratee - The function invoked per iteration
364
 * @returns Returns object
365
 */
366
function forOwn(object, iteratee);
367

368
/**
369
 * Like forOwn except that it iterates over properties in the opposite order
370
 * @param object - The object to iterate over
371
 * @param iteratee - The function invoked per iteration
372
 * @returns Returns object
373
 */
374
function forOwnRight(object, iteratee);
375
```
376

377
### Function Properties
378

379
#### functions
380
Creates an array of function property names from own enumerable properties of object.
381

382
```javascript { .api }
383
/**
384
 * Creates an array of function property names from own enumerable properties of object
385
 * @param object - The object to inspect
386
 * @returns Returns the function names
387
 */
388
function functions(object);
389

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

398
### Method Invocation
399

400
#### invoke
401
Invokes the method at path of object.
402

403
```javascript { .api }
404
/**
405
 * Invokes the method at path of object
406
 * @param object - The object to query
407
 * @param path - The path of the method to invoke
408
 * @param args - The arguments to invoke the method with
409
 * @returns Returns the result of the invoked method
410
 */
411
function invoke(object, path, ...args);
412
```
413

414
### Property Updates
415

416
#### update
417
Like set except that it accepts updater to produce the value to set.
418

419
```javascript { .api }
420
/**
421
 * Like set except that it accepts updater to produce the value to set
422
 * @param object - The object to modify
423
 * @param path - The path of the property to set
424
 * @param updater - The function to produce the updated value
425
 * @returns Returns object
426
 */
427
function update(object, path, updater);
428

429
/**
430
 * Like update but accepts customizer which is invoked to produce the objects of path
431
 * @param object - The object to modify
432
 * @param path - The path of the property to set
433
 * @param updater - The function to produce the updated value
434
 * @param customizer - The function to customize assigned values
435
 * @returns Returns object
436
 */
437
function updateWith(object, path, updater, customizer);
438
```
439

440
#### unset
441
Removes the property at path of object.
442

443
```javascript { .api }
444
/**
445
 * Removes the property at path of object
446
 * @param object - The object to modify
447
 * @param path - The path of the property to unset
448
 * @returns Returns true if the property is deleted, else false
449
 */
450
function unset(object, path);
451
```
452

453
### Object Creation
454

455
#### create
456
Creates an object that inherits from the prototype object.
457

458
```javascript { .api }
459
/**
460
 * Creates an object that inherits from the prototype object
461
 * @param prototype - The object to inherit from
462
 * @param properties - The properties to assign to the object
463
 * @returns Returns the new object
464
 */
465
function create(prototype, properties);
466
```
467

468
### Value Resolution
469

470
#### result
471
Like get except that if the resolved value is a function it's invoked with the this binding of its parent object and its result is returned.
472

473
```javascript { .api }
474
/**
475
 * Like get except that if the resolved value is a function it's invoked with the this binding of its parent object and its result is returned
476
 * @param object - The object to query
477
 * @param path - The path of the property to resolve
478
 * @param defaultValue - The value returned for undefined resolved values
479
 * @returns Returns the resolved value
480
 */
481
function result(object, path, defaultValue);
482
```
483

484
## Property Path Formats
485

486
Lodash supports multiple formats for property paths:
487

488
```javascript { .api }
489
// String paths
490
get(object, 'a.b.c');          // → object.a.b.c
491
get(object, 'a[0].b.c');       // → object.a[0].b.c
492

493
// Array paths  
494
get(object, ['a', 'b', 'c']);   // → object.a.b.c
495
get(object, ['a', 0, 'b']);     // → object.a[0].b
496

497
// Mixed paths
498
get(object, 'users[0].name');   // → object.users[0].name
499
```
500

501
### Advanced Assignment Methods
502

503
#### assignInWith
504
Like assignIn but accepts customizer for specifying assigned values.
505

506
```javascript { .api }
507
/**
508
 * Like assignIn but accepts customizer for specifying assigned values
509
 * @param object - The destination object
510
 * @param sources - The source objects
511
 * @param customizer - The function to customize assigned values
512
 * @returns Returns object
513
 */
514
function assignInWith(object, ...sources, customizer);
515
```
516

517
### Method Aliases
518

519
#### extend & extendWith
520
Aliases for assignIn and assignInWith respectively.
521

522
```javascript { .api }
523
// Aliases
524
const extend = assignIn;
525
const extendWith = assignInWith;
526
```
527

528
#### first
529
Alias for head function from array methods.
530

531
```javascript { .api }
532
/**
533
 * Gets the first element of array (alias for head)
534
 * @param array - The array to query
535
 * @returns Returns the first element of array
536
 */
537
const first = head;
538
```
539

540
## Usage Examples
541

542
```javascript
543
import { 
544
  get, set, has, pick, omit, merge, assign,
545
  keys, values, mapValues, transform
546
} from "lodash";
547

548
const user = {
549
  id: 1,
550
  name: 'John Doe',
551
  profile: {
552
    age: 30,
553
    address: {
554
      city: 'New York',
555
      country: 'USA'
556
    }
557
  },
558
  roles: ['user', 'admin'],
559
  settings: {
560
    theme: 'dark',
561
    notifications: true
562
  }
563
};
564

565
// Property access
566
const name = get(user, 'name');                    // 'John Doe'
567
const city = get(user, 'profile.address.city');   // 'New York'
568
const role = get(user, 'roles[0]');               // 'user' 
569
const missing = get(user, 'profile.bio', 'N/A');  // 'N/A'
570

571
// Property modification
572
const updated = set({...user}, 'profile.age', 31);
573
const withEmail = set({...user}, 'profile.email', 'john@example.com');
574

575
// Property checking
576
const hasName = has(user, 'name');                 // true
577
const hasEmail = has(user, 'profile.email');      // false
578

579
// Property selection
580
const basic = pick(user, ['id', 'name']);
581
// Result: { id: 1, name: 'John Doe' }
582

583
const publicProfile = omit(user, ['settings', 'roles']);
584
// Result: user object without settings and roles
585

586
// Object merging
587
const defaults = { theme: 'light', language: 'en' };
588
const userSettings = merge({}, defaults, user.settings);
589
// Result: { theme: 'dark', language: 'en', notifications: true }
590

591
// Property extraction
592
const propertyNames = keys(user);
593
// Result: ['id', 'name', 'profile', 'roles', 'settings']
594

595
const propertyValues = values(user.settings);
596
// Result: ['dark', true]
597

598
// Object transformation
599
const normalized = mapValues(user.profile.address, val => 
600
  typeof val === 'string' ? val.toUpperCase() : val
601
);
602
// Result: { city: 'NEW YORK', country: 'USA' }
603

604
// Complex transformation
605
const flattened = transform(user, (result, value, key) => {
606
  if (typeof value === 'object' && !Array.isArray(value)) {
607
    Object.assign(result, mapKeys(value, (v, k) => `${key}.${k}`));
608
  } else {
609
    result[key] = value;
610
  }
611
}, {});
612

613
// Working with nested data
614
const posts = [
615
  { id: 1, author: { name: 'John' }, tags: ['js', 'web'] },
616
  { id: 2, author: { name: 'Jane' }, tags: ['react'] }
617
];
618

619
const authorNames = posts.map(post => get(post, 'author.name'));
620
// Result: ['John', 'Jane']
621

622
// Safe property updates
623
const safeUpdate = (obj, path, value) => {
624
  const copy = { ...obj };
625
  return set(copy, path, value);
626
};
627

628
const updatedUser = safeUpdate(user, 'profile.lastLogin', new Date());
629
```