npm-lodash

Description
A comprehensive JavaScript utility library with 296+ functions for arrays, objects, strings, and functional programming
Author
tessl
Last updated

How to use

npx @tessl/cli registry install tessl/npm-lodash@4.9.0

object-methods.md docs/

1
# Object Methods
2
3
Deep object operations including property access, merging, transformation, and key/value manipulation for comprehensive object handling.
4
5
## Capabilities
6
7
### Assign
8
9
Assigns own enumerable string keyed properties of source objects to the destination object.
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
* Subsequent sources overwrite property assignments of previous sources.
16
* @param object - The destination object
17
* @param sources - The source objects
18
* @returns Returns `object`
19
*/
20
function assign<TObject, TSource>(object: TObject, source: TSource): TObject & TSource;
21
function assign<TObject, TSource1, TSource2>(object: TObject, source1: TSource1, source2: TSource2): TObject & TSource1 & TSource2;
22
function assign<TObject>(object: TObject, ...otherArgs: any[]): any;
23
```
24
25
### Assign In
26
27
Like assign except that it iterates over own and inherited source properties.
28
29
```javascript { .api }
30
/**
31
* This method is like `assign` except that it iterates over own and
32
* inherited source properties.
33
* @param object - The destination object
34
* @param sources - The source objects
35
* @returns Returns `object`
36
*/
37
function assignIn<TObject, TSource>(object: TObject, source: TSource): TObject & TSource;
38
function assignIn<TObject, TSource1, TSource2>(object: TObject, source1: TSource1, source2: TSource2): TObject & TSource1 & TSource2;
39
function assignIn<TObject>(object: TObject, ...otherArgs: any[]): any;
40
```
41
42
### Assign In With
43
44
Like assignIn except that it accepts customizer which is invoked to produce the assigned values.
45
46
```javascript { .api }
47
/**
48
* This method is like `assignIn` except that it accepts `customizer`
49
* which is invoked to produce the assigned values.
50
* @param object - The destination object
51
* @param sources - The source objects
52
* @param customizer - The function to customize assigned values
53
* @returns Returns `object`
54
*/
55
function assignInWith<TObject, TSource>(
56
object: TObject,
57
source: TSource,
58
customizer: (objValue: any, srcValue: any, key: string, object: TObject, source: TSource) => any
59
): TObject & TSource;
60
function assignInWith<TObject>(object: TObject, ...otherArgs: any[]): any;
61
```
62
63
### Assign With
64
65
Like assign except that it accepts customizer which is invoked to produce the assigned values.
66
67
```javascript { .api }
68
/**
69
* This method is like `assign` except that it accepts `customizer` which
70
* is invoked to produce the assigned values.
71
* @param object - The destination object
72
* @param sources - The source objects
73
* @param customizer - The function to customize assigned values
74
* @returns Returns `object`
75
*/
76
function assignWith<TObject, TSource>(
77
object: TObject,
78
source: TSource,
79
customizer: (objValue: any, srcValue: any, key: string, object: TObject, source: TSource) => any
80
): TObject & TSource;
81
function assignWith<TObject>(object: TObject, ...otherArgs: any[]): any;
82
```
83
84
### Create
85
86
Creates an object that inherits from the prototype object.
87
88
```javascript { .api }
89
/**
90
* Creates an object that inherits from the `prototype` object. If a
91
* `properties` object is given, its own enumerable string keyed properties
92
* are assigned to the created object.
93
* @param prototype - The object to inherit from
94
* @param properties - The properties to assign to the object
95
* @returns Returns the new object
96
*/
97
function create<T>(prototype: T, properties?: PropertyDescriptorMap): T;
98
```
99
100
### Defaults
101
102
Assigns own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to undefined.
103
104
```javascript { .api }
105
/**
106
* Assigns own and inherited enumerable string keyed properties of source
107
* objects to the destination object for all destination properties that
108
* resolve to `undefined`. Source objects are applied from left to right.
109
* Once a property is set, additional values of the same property are ignored.
110
* @param object - The destination object
111
* @param sources - The source objects
112
* @returns Returns `object`
113
*/
114
function defaults<TObject, TSource>(object: TObject, source: TSource): TSource & TObject;
115
function defaults<TObject, TSource1, TSource2>(object: TObject, source1: TSource1, source2: TSource2): TSource2 & TSource1 & TObject;
116
function defaults<TObject>(object: TObject, ...sources: any[]): any;
117
```
118
119
### Defaults Deep
120
121
Like defaults except that it recursively assigns default properties.
122
123
```javascript { .api }
124
/**
125
* This method is like `defaults` except that it recursively assigns
126
* default properties.
127
* @param object - The destination object
128
* @param sources - The source objects
129
* @returns Returns `object`
130
*/
131
function defaultsDeep<TObject, TSource>(object: TObject, source: TSource): TSource & TObject;
132
function defaultsDeep<TObject>(object: TObject, ...sources: any[]): any;
133
```
134
135
### Find Key
136
137
This method is like find except that it returns the key of the first element predicate returns truthy for instead of the element itself.
138
139
```javascript { .api }
140
/**
141
* This method is like `find` except that it returns the key of the first
142
* element `predicate` returns truthy for instead of the element itself.
143
* @param object - The object to inspect
144
* @param predicate - The function invoked per iteration
145
* @returns Returns the key of the matched element, else `undefined`
146
*/
147
function findKey<T>(
148
object: T,
149
predicate?: string | object | ((value: T[keyof T], key: string, object: T) => boolean)
150
): string | undefined;
151
```
152
153
### Find Last Key
154
155
Like findKey except that it iterates over elements in the opposite order.
156
157
```javascript { .api }
158
/**
159
* This method is like `findKey` except that it iterates over elements of
160
* a collection in the opposite order.
161
* @param object - The object to inspect
162
* @param predicate - The function invoked per iteration
163
* @returns Returns the key of the matched element, else `undefined`
164
*/
165
function findLastKey<T>(
166
object: T,
167
predicate?: string | object | ((value: T[keyof T], key: string, object: T) => boolean)
168
): string | undefined;
169
```
170
171
### For In
172
173
Iterates over own and inherited enumerable string keyed properties of an object and invokes iteratee for each property.
174
175
```javascript { .api }
176
/**
177
* Iterates over own and inherited enumerable string keyed properties of an
178
* object and invokes `iteratee` for each property. The iteratee is invoked
179
* with three arguments: (value, key, object). Iteratee functions may exit
180
* iteration early by explicitly returning `false`.
181
* @param object - The object to iterate over
182
* @param iteratee - The function invoked per iteration
183
* @returns Returns `object`
184
*/
185
function forIn<T>(
186
object: T,
187
iteratee?: (value: T[keyof T], key: string, object: T) => any
188
): T;
189
```
190
191
### For In Right
192
193
Like forIn except that it iterates over properties in the opposite order.
194
195
```javascript { .api }
196
/**
197
* This method is like `forIn` except that it iterates over properties of
198
* `object` in the opposite order.
199
* @param object - The object to iterate over
200
* @param iteratee - The function invoked per iteration
201
* @returns Returns `object`
202
*/
203
function forInRight<T>(
204
object: T,
205
iteratee?: (value: T[keyof T], key: string, object: T) => any
206
): T;
207
```
208
209
### For Own
210
211
Iterates over own enumerable string keyed properties of an object and invokes iteratee for each property.
212
213
```javascript { .api }
214
/**
215
* Iterates over own enumerable string keyed properties of an object and
216
* invokes `iteratee` for each property. The iteratee is invoked with three
217
* arguments: (value, key, object). Iteratee functions may exit iteration
218
* early by explicitly returning `false`.
219
* @param object - The object to iterate over
220
* @param iteratee - The function invoked per iteration
221
* @returns Returns `object`
222
*/
223
function forOwn<T>(
224
object: T,
225
iteratee?: (value: T[keyof T], key: string, object: T) => any
226
): T;
227
```
228
229
### For Own Right
230
231
Like forOwn except that it iterates over properties in the opposite order.
232
233
```javascript { .api }
234
/**
235
* This method is like `forOwn` except that it iterates over properties of
236
* `object` in the opposite order.
237
* @param object - The object to iterate over
238
* @param iteratee - The function invoked per iteration
239
* @returns Returns `object`
240
*/
241
function forOwnRight<T>(
242
object: T,
243
iteratee?: (value: T[keyof T], key: string, object: T) => any
244
): T;
245
```
246
247
### Functions
248
249
Creates an array of function property names from own enumerable properties of object.
250
251
```javascript { .api }
252
/**
253
* Creates an array of function property names from own enumerable properties
254
* of `object`.
255
* @param object - The object to inspect
256
* @returns Returns the function names
257
*/
258
function functions(object?: any): string[];
259
```
260
261
### Functions In
262
263
Creates an array of function property names from own and inherited enumerable properties of object.
264
265
```javascript { .api }
266
/**
267
* Creates an array of function property names from own and inherited
268
* enumerable properties of `object`.
269
* @param object - The object to inspect
270
* @returns Returns the function names
271
*/
272
function functionsIn(object?: any): string[];
273
```
274
275
### Get
276
277
Gets the value at path of object.
278
279
```javascript { .api }
280
/**
281
* Gets the value at `path` of `object`. If the resolved value is
282
* `undefined`, the `defaultValue` is returned in its place.
283
* @param object - The object to query
284
* @param path - The path of the property to get
285
* @param defaultValue - The value returned for `undefined` resolved values
286
* @returns Returns the resolved value
287
*/
288
function get<TObject extends object, TKey extends keyof TObject>(
289
object: TObject,
290
path: TKey | [TKey]
291
): TObject[TKey];
292
function get<TObject extends object, TKey extends keyof TObject, TDefault>(
293
object: TObject | null | undefined,
294
path: TKey | [TKey],
295
defaultValue: TDefault
296
): TObject[TKey] | TDefault;
297
function get<T>(
298
object: any,
299
path: PropertyPath,
300
defaultValue?: T
301
): T;
302
```
303
304
### Has
305
306
Checks if path is a direct property of object.
307
308
```javascript { .api }
309
/**
310
* Checks if `path` is a direct property of `object`.
311
* @param object - The object to query
312
* @param path - The path to check
313
* @returns Returns `true` if `path` exists, else `false`
314
*/
315
function has<T>(object: T, path: PropertyPath): boolean;
316
```
317
318
### Has In
319
320
Checks if path is a direct or inherited property of object.
321
322
```javascript { .api }
323
/**
324
* Checks if `path` is a direct or inherited property of `object`.
325
* @param object - The object to query
326
* @param path - The path to check
327
* @returns Returns `true` if `path` exists, else `false`
328
*/
329
function hasIn<T>(object: T, path: PropertyPath): boolean;
330
```
331
332
### Invert
333
334
Creates an object composed of the inverted keys and values of object.
335
336
```javascript { .api }
337
/**
338
* Creates an object composed of the inverted keys and values of `object`.
339
* If `object` contains duplicate values, subsequent values overwrite
340
* property assignments of previous values.
341
* @param object - The object to invert
342
* @returns Returns the new inverted object
343
*/
344
function invert(object: any): Record<string, string>;
345
```
346
347
### Invert By
348
349
Like invert except that the inverted object is generated from the results of running each element of object thru iteratee.
350
351
```javascript { .api }
352
/**
353
* This method is like `invert` except that the inverted object is generated
354
* from the results of running each element of `object` thru `iteratee`.
355
* The corresponding inverted value of each inverted key is an array of keys
356
* responsible for generating the inverted value.
357
* @param object - The object to invert
358
* @param iteratee - The iteratee invoked per element
359
* @returns Returns the new inverted object
360
*/
361
function invertBy<T>(
362
object: Record<PropertyKey, T>,
363
iteratee?: string | ((value: T) => PropertyKey)
364
): Record<string, string[]>;
365
```
366
367
### Invoke
368
369
Invokes the method at path of object.
370
371
```javascript { .api }
372
/**
373
* Invokes the method at `path` of `object`.
374
* @param object - The object to query
375
* @param path - The path of the method to invoke
376
* @param args - The arguments to invoke the method with
377
* @returns Returns the result of the invoked method
378
*/
379
function invoke(object: any, path: PropertyPath, ...args: any[]): any;
380
```
381
382
### Keys
383
384
Creates an array of the own enumerable property names of object.
385
386
```javascript { .api }
387
/**
388
* Creates an array of the own enumerable property names of `object`.
389
* @param object - The object to query
390
* @returns Returns the array of property names
391
*/
392
function keys(object?: any): string[];
393
```
394
395
### Keys In
396
397
Creates an array of the own and inherited enumerable property names of object.
398
399
```javascript { .api }
400
/**
401
* Creates an array of the own and inherited enumerable property names of `object`.
402
* @param object - The object to query
403
* @returns Returns the array of property names
404
*/
405
function keysIn(object?: any): string[];
406
```
407
408
### Map Keys
409
410
Creates an object with the same values as object and keys generated by running each own enumerable string keyed property of object thru iteratee.
411
412
```javascript { .api }
413
/**
414
* Creates an object with the same values as `object` and keys generated
415
* by running each own enumerable string keyed property of `object` thru
416
* `iteratee`. The iteratee is invoked with three arguments:
417
* (value, key, object).
418
* @param object - The object to iterate over
419
* @param iteratee - The function invoked per iteration
420
* @returns Returns the new mapped object
421
*/
422
function mapKeys<T>(
423
object: Record<string, T> | undefined,
424
iteratee?: string | ((value: T, key: string, object: Record<string, T>) => PropertyKey)
425
): Record<string, T>;
426
```
427
428
### Map Values
429
430
Creates an object with the same keys as object and values generated by running each own enumerable string keyed property of object thru iteratee.
431
432
```javascript { .api }
433
/**
434
* Creates an object with the same keys as `object` and values generated
435
* by running each own enumerable string keyed property of `object` thru
436
* `iteratee`. The iteratee is invoked with three arguments:
437
* (value, key, object).
438
* @param object - The object to iterate over
439
* @param iteratee - The function invoked per iteration
440
* @returns Returns the new mapped object
441
*/
442
function mapValues<T, R>(
443
object: Record<string, T> | undefined,
444
iteratee: string | ((value: T, key: string, object: Record<string, T>) => R)
445
): Record<string, R>;
446
function mapValues<T>(
447
object: Record<string, T> | undefined,
448
iteratee?: string
449
): Record<string, any>;
450
```
451
452
### Merge
453
454
Recursively merges own and inherited enumerable string keyed properties of source objects into the destination object.
455
456
```javascript { .api }
457
/**
458
* This method is like `assign` except that it recursively merges own and
459
* inherited enumerable string keyed properties of source objects into the
460
* destination object. Source properties that resolve to `undefined` are
461
* skipped if a destination value exists. Array and plain object properties
462
* are merged recursively.
463
* @param object - The destination object
464
* @param sources - The source objects
465
* @returns Returns `object`
466
*/
467
function merge<TObject, TSource>(object: TObject, source: TSource): TObject & TSource;
468
function merge<TObject, TSource1, TSource2>(object: TObject, source1: TSource1, source2: TSource2): TObject & TSource1 & TSource2;
469
function merge<TObject>(object: TObject, ...otherArgs: any[]): any;
470
```
471
472
### Merge With
473
474
Like merge except that it accepts customizer which is invoked to produce the merged values of the destination and source properties.
475
476
```javascript { .api }
477
/**
478
* This method is like `merge` except that it accepts `customizer` which
479
* is invoked to produce the merged values of the destination and source
480
* properties.
481
* @param object - The destination object
482
* @param sources - The source objects
483
* @param customizer - The function to customize assigned values
484
* @returns Returns `object`
485
*/
486
function mergeWith<TObject, TSource>(
487
object: TObject,
488
source: TSource,
489
customizer: (objValue: any, srcValue: any, key: string, object: TObject, source: TSource, stack: any) => any
490
): TObject & TSource;
491
function mergeWith<TObject>(object: TObject, ...otherArgs: any[]): any;
492
```
493
494
### Omit
495
496
Creates an object composed of the own and inherited enumerable property paths of object that are not omitted.
497
498
```javascript { .api }
499
/**
500
* The opposite of `pick`; this method creates an object composed of the
501
* own and inherited enumerable property paths of `object` that are not omitted.
502
* @param object - The source object
503
* @param paths - The property paths to omit
504
* @returns Returns the new object
505
*/
506
function omit<T, K extends keyof T>(object: T, ...paths: K[]): Omit<T, K>;
507
function omit<T>(object: T, ...paths: PropertyPath[]): Partial<T>;
508
```
509
510
### Omit By
511
512
The opposite of pickBy; this method creates an object composed of the own and inherited enumerable string keyed properties of object that predicate doesn't return truthy for.
513
514
```javascript { .api }
515
/**
516
* The opposite of `pickBy`; this method creates an object composed of
517
* the own and inherited enumerable string keyed properties of `object` that
518
* `predicate` doesn't return truthy for. The predicate is invoked with two
519
* arguments: (value, key).
520
* @param object - The source object
521
* @param predicate - The function invoked per property
522
* @returns Returns the new object
523
*/
524
function omitBy<T>(
525
object: Record<string, T> | undefined,
526
predicate?: string | ((value: T, key: string) => boolean)
527
): Record<string, T>;
528
```
529
530
### Pick
531
532
Creates an object composed of the picked object properties.
533
534
```javascript { .api }
535
/**
536
* Creates an object composed of the picked `object` properties.
537
* @param object - The source object
538
* @param paths - The property paths to pick
539
* @returns Returns the new object
540
*/
541
function pick<T, K extends keyof T>(object: T, ...paths: K[]): Pick<T, K>;
542
function pick<T>(object: T, ...paths: PropertyPath[]): Partial<T>;
543
```
544
545
### Pick By
546
547
Creates an object composed of the object properties predicate returns truthy for.
548
549
```javascript { .api }
550
/**
551
* Creates an object composed of the `object` properties `predicate` returns
552
* truthy for. The predicate is invoked with two arguments: (value, key).
553
* @param object - The source object
554
* @param predicate - The function invoked per property
555
* @returns Returns the new object
556
*/
557
function pickBy<T>(
558
object: Record<string, T> | undefined,
559
predicate?: string | ((value: T, key: string) => boolean)
560
): Record<string, T>;
561
```
562
563
### Result
564
565
Gets the value at path of object.
566
567
```javascript { .api }
568
/**
569
* This method is like `get` except that if the resolved value is a
570
* function it's invoked with the `this` binding of its parent object and
571
* its result is returned.
572
* @param object - The object to query
573
* @param path - The path of the property to resolve
574
* @param defaultValue - The value returned for `undefined` resolved values
575
* @returns Returns the resolved value
576
*/
577
function result<T>(object: any, path: PropertyPath, defaultValue?: T): T;
578
```
579
580
### Set
581
582
Sets the value at path of object.
583
584
```javascript { .api }
585
/**
586
* Sets the value at `path` of `object`. If a portion of `path` doesn't exist,
587
* it's created. Arrays are created for missing index properties while objects
588
* are created for all other missing properties.
589
* @param object - The object to modify
590
* @param path - The path of the property to set
591
* @param value - The value to set
592
* @returns Returns `object`
593
*/
594
function set<T>(object: T, path: PropertyPath, value: any): T;
595
```
596
597
### Set With
598
599
Like set except that it accepts customizer which is invoked to produce the objects of path.
600
601
```javascript { .api }
602
/**
603
* This method is like `set` except that it accepts `customizer` which is
604
* invoked to produce the objects of `path`.
605
* @param object - The object to modify
606
* @param path - The path of the property to set
607
* @param value - The value to set
608
* @param customizer - The function to customize assigned values
609
* @returns Returns `object`
610
*/
611
function setWith<T>(
612
object: T,
613
path: PropertyPath,
614
value: any,
615
customizer?: (nsValue: any, key: string, nsObject: T) => any
616
): T;
617
```
618
619
### To Pairs
620
621
Creates an array of own enumerable string keyed-value pairs for object.
622
623
```javascript { .api }
624
/**
625
* Creates an array of own enumerable string keyed-value pairs for `object`
626
* which can be consumed by `fromPairs`. If `object` is a map or set, its
627
* entries are returned.
628
* @param object - The object to query
629
* @returns Returns the key-value pairs
630
*/
631
function toPairs<T>(object?: Record<PropertyKey, T>): Array<[string, T]>;
632
```
633
634
### To Pairs In
635
636
Creates an array of own and inherited enumerable string keyed-value pairs for object.
637
638
```javascript { .api }
639
/**
640
* Creates an array of own and inherited enumerable string keyed-value
641
* pairs for `object` which can be consumed by `fromPairs`.
642
* @param object - The object to query
643
* @returns Returns the key-value pairs
644
*/
645
function toPairsIn<T>(object?: Record<PropertyKey, T>): Array<[string, T]>;
646
```
647
648
### To Path
649
650
Converts value to a property path array.
651
652
```javascript { .api }
653
/**
654
* Converts `value` to a property path array.
655
* @param value - The value to convert
656
* @returns Returns the new property path array
657
*/
658
function toPath(value: any): string[];
659
```
660
661
### Transform
662
663
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 thru iteratee.
664
665
```javascript { .api }
666
/**
667
* An alternative to `reduce`; this method transforms `object` to a new
668
* `accumulator` object which is the result of running each of its own
669
* enumerable string keyed properties thru `iteratee`, with each invocation
670
* potentially mutating the `accumulator` object.
671
* @param object - The object to iterate over
672
* @param iteratee - The function invoked per iteration
673
* @param accumulator - The custom accumulator value
674
* @returns Returns the accumulated value
675
*/
676
function transform<T, TResult>(
677
object: Record<string, T>,
678
iteratee: (accumulator: TResult, value: T, key: string, object: Record<string, T>) => void,
679
accumulator?: TResult
680
): TResult;
681
function transform<T, TResult>(
682
object: T[],
683
iteratee: (accumulator: TResult, value: T, index: number, array: T[]) => void,
684
accumulator?: TResult
685
): TResult;
686
```
687
688
### Unset
689
690
Removes the property at path of object.
691
692
```javascript { .api }
693
/**
694
* Removes the property at `path` of `object`.
695
* @param object - The object to modify
696
* @param path - The path of the property to unset
697
* @returns Returns `true` if the property is deleted, else `false`
698
*/
699
function unset<T>(object: T, path: PropertyPath): boolean;
700
```
701
702
### Update
703
704
This method is like set except that accepts updater to produce the value to set.
705
706
```javascript { .api }
707
/**
708
* This method is like `set` except that accepts `updater` to produce the
709
* value to set. Use `updateWith` to customize `path` creation.
710
* @param object - The object to modify
711
* @param path - The path of the property to set
712
* @param updater - The function to produce the updated value
713
* @returns Returns `object`
714
*/
715
function update<T>(object: T, path: PropertyPath, updater: (value: any) => any): T;
716
```
717
718
### Update With
719
720
This method is like update except that it accepts customizer which is invoked to produce the objects of path.
721
722
```javascript { .api }
723
/**
724
* This method is like `update` except that it accepts `customizer` which is
725
* invoked to produce the objects of `path`.
726
* @param object - The object to modify
727
* @param path - The path of the property to set
728
* @param updater - The function to produce the updated value
729
* @param customizer - The function to customize assigned values
730
* @returns Returns `object`
731
*/
732
function updateWith<T>(
733
object: T,
734
path: PropertyPath,
735
updater: (value: any) => any,
736
customizer?: (nsValue: any, key: string, nsObject: T) => any
737
): T;
738
```
739
740
### Values
741
742
Creates an array of the own enumerable string keyed property values of object.
743
744
```javascript { .api }
745
/**
746
* Creates an array of the own enumerable string keyed property values of `object`.
747
* @param object - The object to query
748
* @returns Returns the array of property values
749
*/
750
function values<T>(object?: Record<PropertyKey, T>): T[];
751
```
752
753
### Values In
754
755
Creates an array of the own and inherited enumerable string keyed property values of object.
756
757
```javascript { .api }
758
/**
759
* Creates an array of the own and inherited enumerable string keyed property
760
* values of `object`.
761
* @param object - The object to query
762
* @returns Returns the array of property values
763
*/
764
function valuesIn<T>(object?: Record<PropertyKey, T>): T[];
765
```
766
767
## Types
768
769
```javascript { .api }
770
type PropertyPath = string | number | symbol | Array<string | number | symbol>;
771
type PropertyKey = string | number | symbol;
772
```
773
774
## Aliases
775
776
- `entries``toPairs`
777
- `entriesIn``toPairsIn`
778
- `extend``assignIn`
779
- `extendWith``assignInWith`