npm-lodash

1
# Utility Methods
2

3
General-purpose utilities including function creation, control flow, miscellaneous helpers, and core Lodash functionality.
4

5
## Capabilities
6

7
### Attempt
8

9
Attempts to invoke func, returning either the result or the caught error object.
10

11
```javascript { .api }
12
/**
13
 * Attempts to invoke `func`, returning either the result or the caught error object.
14
 * Any additional arguments are provided to `func` when it's invoked.
15
 * @param func - The function to attempt
16
 * @param args - The arguments to invoke `func` with
17
 * @returns Returns the `func` result or error object
18
 */
19
function attempt<T>(func: (...args: any[]) => T, ...args: any[]): T | Error;
20
```
21

22
### Bind All
23

24
Binds methods of an object to the object itself, overwriting the existing methods.
25

26
```javascript { .api }
27
/**
28
 * Binds methods of an object to the object itself, overwriting the existing
29
 * methods.
30
 * @param object - The object to bind and assign the bound methods to
31
 * @param methodNames - The object method names to bind
32
 * @returns Returns `object`
33
 */
34
function bindAll<T>(object: T, ...methodNames: string[]): T;
35
```
36

37
### Cond
38

39
Creates a function that iterates over pairs and invokes the corresponding function of the first predicate to return truthy.
40

41
```javascript { .api }
42
/**
43
 * Creates a function that iterates over `pairs` and invokes the corresponding
44
 * function of the first predicate to return truthy. The predicate-function
45
 * pairs are invoked with the `this` binding and arguments of the created function.
46
 * @param pairs - The predicate-function pairs
47
 * @returns Returns the new composite function
48
 */
49
function cond<T, R>(pairs: Array<[(args: T) => boolean, (args: T) => R]>): (args: T) => R;
50
function cond<R>(pairs: Array<[(...args: any[]) => boolean, (...args: any[]) => R]>): (...args: any[]) => R;
51
```
52

53
### Conforms
54

55
Creates a function that invokes the predicate properties of source with the corresponding property values of a given object, returning true if all predicates return truthy, else false.
56

57
```javascript { .api }
58
/**
59
 * Creates a function that invokes the predicate properties of `source` with
60
 * the corresponding property values of a given object, returning `true` if
61
 * all predicates return truthy, else `false`.
62
 * @param source - The object of property predicates to conform to
63
 * @returns Returns the new spec function
64
 */
65
function conforms<T>(source: Record<keyof T, (value: any) => boolean>): (object: T) => boolean;
66
```
67

68
### Constant
69

70
Creates a function that returns value.
71

72
```javascript { .api }
73
/**
74
 * Creates a function that returns `value`.
75
 * @param value - The value to return from the new function
76
 * @returns Returns the new constant function
77
 */
78
function constant<T>(value: T): () => T;
79
```
80

81
### Default To
82

83
Checks value to determine whether a default value should be returned in its place.
84

85
```javascript { .api }
86
/**
87
 * Checks `value` to determine whether a default value should be returned in
88
 * its place. The `defaultValue` is returned if `value` is `NaN`, `null`,
89
 * or `undefined`.
90
 * @param value - The value to check
91
 * @param defaultValue - The default value
92
 * @returns Returns the resolved value
93
 */
94
function defaultTo<T>(value: T | null | undefined, defaultValue: T): T;
95
function defaultTo<T, TDefault>(value: T | null | undefined, defaultValue: TDefault): T | TDefault;
96
```
97

98
### Flow
99

100
Creates a function that is the composition of the provided functions, where each successive invocation is supplied the return value of the previous.
101

102
```javascript { .api }
103
/**
104
 * Creates a function that is the composition of the provided functions,
105
 * where each successive invocation is supplied the return value of the previous.
106
 * @param funcs - The functions to invoke
107
 * @returns Returns the new composite function
108
 */
109
function flow<A extends any[], R1, R2, R3, R4, R5, R6, R7>(
110
  f1: (...args: A) => R1,
111
  f2: (a: R1) => R2,
112
  f3?: (a: R2) => R3,  
113
  f4?: (a: R3) => R4,
114
  f5?: (a: R4) => R5,
115
  f6?: (a: R5) => R6,
116
  f7?: (a: R6) => R7
117
): (...args: A) => R7;
118

119
function flow(...funcs: Array<(...args: any[]) => any>): (...args: any[]) => any;
120
```
121

122
### Flow Right
123

124
Like flow except that it creates a function that invokes the given functions from right to left.
125

126
```javascript { .api }
127
/**
128
 * This method is like `flow` except that it creates a function that invokes
129
 * the given functions from right to left.
130
 * @param funcs - The functions to invoke
131
 * @returns Returns the new composite function
132
 */
133
function flowRight<A extends any[], R1, R2, R3, R4, R5, R6, R7>(
134
  f7: (a: R6) => R7,
135
  f6?: (a: R5) => R6,
136
  f5?: (a: R4) => R5,
137
  f4?: (a: R3) => R4,
138
  f3?: (a: R2) => R3,
139
  f2?: (a: R1) => R2,
140
  f1?: (...args: A) => R1
141
): (...args: A) => R7;
142

143
function flowRight(...funcs: Array<(...args: any[]) => any>): (...args: any[]) => any;
144
```
145

146
### Identity
147

148
This method returns the first argument it receives.
149

150
```javascript { .api }
151
/**
152
 * This method returns the first argument it receives.
153
 * @param value - Any value
154
 * @returns Returns `value`
155
 */
156
function identity<T>(value: T): T;
157
```
158

159
### Iteratee
160

161
Creates a function that invokes func with the arguments of the created function.
162

163
```javascript { .api }
164
/**
165
 * Creates a function that invokes `func` with the arguments of the created
166
 * function. If `func` is a property name, the created function returns the
167
 * property value for a given element. If `func` is an array or object, the
168
 * created function returns `true` for elements that contain the equivalent
169
 * source properties, otherwise it returns `false`.
170
 * @param func - The value to convert to a callback
171
 * @returns Returns the callback
172
 */
173
function iteratee<T>(func?: T): T extends string 
174
  ? (object: any) => any
175
  : T extends object
176
  ? (object: any) => boolean  
177
  : T extends (...args: any[]) => any
178
  ? T
179
  : (value: any) => any;
180
```
181

182
### Matches
183

184
Creates a function that performs a partial deep comparison between a given object and source, returning true if the given object has equivalent property values, else false.
185

186
```javascript { .api }
187
/**
188
 * Creates a function that performs a partial deep comparison between a given
189
 * object and `source`, returning `true` if the given object has equivalent
190
 * property values, else `false`.
191
 * @param source - The object of property values to match
192
 * @returns Returns the new spec function
193
 */
194
function matches<T>(source: T): (object: any) => boolean;
195
```
196

197
### Matches Property
198

199
Creates a function that performs a partial deep comparison between the value at path of a given object to srcValue, returning true if the object value is equivalent, else false.
200

201
```javascript { .api }
202
/**
203
 * Creates a function that performs a partial deep comparison between the
204
 * value at `path` of a given object to `srcValue`, returning `true` if the
205
 * object value is equivalent, else `false`.
206
 * @param path - The path of the property to get
207
 * @param srcValue - The value to match
208
 * @returns Returns the new spec function
209
 */
210
function matchesProperty(path: PropertyPath, srcValue: any): (object: any) => boolean;
211
```
212

213
### Method
214

215
Creates a function that invokes the method at path of a given object.
216

217
```javascript { .api }
218
/**
219
 * Creates a function that invokes the method at `path` of a given object.
220
 * Any additional arguments are provided to the invoked method.
221
 * @param path - The path of the method to invoke
222
 * @param args - The arguments to invoke the method with
223
 * @returns Returns the new invoker function
224
 */
225
function method(path: PropertyPath, ...args: any[]): (object: any) => any;
226
```
227

228
### Method Of
229

230
The opposite of method; this method creates a function that invokes the method at a given path of object.
231

232
```javascript { .api }
233
/**
234
 * The opposite of `method`; this method creates a function that invokes
235
 * the method at a given path of `object`. Any additional arguments are
236
 * provided to the invoked method.
237
 * @param object - The object to query
238
 * @param args - The arguments to invoke the method with
239
 * @returns Returns the new invoker function
240
 */
241
function methodOf(object: any, ...args: any[]): (path: PropertyPath) => any;
242
```
243

244
### Mixin
245

246
Adds all own enumerable string keyed function properties of a source object to the destination object.
247

248
```javascript { .api }
249
/**
250
 * Adds all own enumerable string keyed function properties of a source
251
 * object to the destination object. If `object` is a function, then methods
252
 * are added to its prototype as well.
253
 * @param object - The destination object
254
 * @param source - The object of functions to add
255
 * @param options - The options object
256
 * @returns Returns `object`
257
 */
258
function mixin<T>(object: T, source: any, options?: { chain?: boolean }): T;
259
function mixin(source: any, options?: { chain?: boolean }): typeof _;
260
```
261

262
### No Conflict
263

264
Reverts the _ variable to its previous value and returns a reference to the lodash function.
265

266
```javascript { .api }
267
/**
268
 * Reverts the `_` variable to its previous value and returns a reference to
269
 * the `lodash` function.
270
 * @returns Returns the `lodash` function
271
 */
272
function noConflict(): typeof _;
273
```
274

275
### Noop
276

277
This method returns undefined.
278

279
```javascript { .api }
280
/**
281
 * This method returns `undefined`.
282
 * @returns Returns `undefined`
283
 */
284
function noop(): void;
285
```
286

287
### Nth Arg
288

289
Creates a function that gets the argument at index n.
290

291
```javascript { .api }
292
/**
293
 * Creates a function that gets the argument at index `n`. If `n` is negative,
294
 * the nth argument from the end is returned.
295
 * @param n - The index of the argument to return
296
 * @returns Returns the new pass-thru function
297
 */
298
function nthArg(n?: number): (...args: any[]) => any;
299
```
300

301
### Over
302

303
Creates a function that invokes iteratees with the arguments it receives and returns their results.
304

305
```javascript { .api }
306
/**
307
 * Creates a function that invokes `iteratees` with the arguments it receives
308
 * and returns their results.
309
 * @param iteratees - The iteratees to invoke
310
 * @returns Returns the new function
311
 */
312
function over<T extends ReadonlyArray<(...args: any[]) => any>>(
313
  ...iteratees: T
314
): (...args: any[]) => { [K in keyof T]: T[K] extends (...args: any[]) => infer R ? R : never };
315
```
316

317
### Over Every
318

319
Creates a function that checks if all of the provided predicates return truthy when invoked with the arguments it receives.
320

321
```javascript { .api }
322
/**
323
 * Creates a function that checks if **all** of the provided predicates return
324
 * truthy when invoked with the arguments it receives.
325
 * @param predicates - The predicates to check
326
 * @returns Returns the new function
327
 */
328
function overEvery<T extends ReadonlyArray<(...args: any[]) => boolean>>(
329
  ...predicates: T
330
): (...args: any[]) => boolean;
331
```
332

333
### Over Some
334

335
Creates a function that checks if any of the provided predicates return truthy when invoked with the arguments it receives.
336

337
```javascript { .api }
338
/**
339
 * Creates a function that checks if **any** of the provided predicates return
340
 * truthy when invoked with the arguments it receives.
341
 * @param predicates - The predicates to check
342
 * @returns Returns the new function
343
 */
344
function overSome<T extends ReadonlyArray<(...args: any[]) => boolean>>(
345
  ...predicates: T
346
): (...args: any[]) => boolean;
347
```
348

349
### Property
350

351
Creates a function that returns the value at path of a given object.
352

353
```javascript { .api }
354
/**
355
 * Creates a function that returns the value at `path` of a given object.
356
 * @param path - The path of the property to get
357
 * @returns Returns the new accessor function
358
 */
359
function property<T>(path: PropertyPath): (obj: any) => T;
360
```
361

362
### Property Of
363

364
The opposite of property; this method creates a function that returns the value at a given path of object.
365

366
```javascript { .api }
367
/**
368
 * The opposite of `property`; this method creates a function that returns
369
 * the value at a given path of `object`.
370
 * @param object - The object to query
371
 * @returns Returns the new accessor function
372
 */
373
function propertyOf<T>(object: T): (path: PropertyPath) => any;
374
```
375

376
### Run In Context
377

378
Create a pristine lodash function to avoid conflicts caused by modifying the original.
379

380
```javascript { .api }
381
/**
382
 * Create a pristine `lodash` function to avoid conflicts caused by modifying
383
 * the original.
384
 * @param context - The context object
385
 * @returns Returns a new `lodash` function
386
 */
387
function runInContext(context?: any): typeof _;
388
```
389

390
### Times
391

392
Invokes the iteratee n times, returning an array of the results of each invocation.
393

394
```javascript { .api }
395
/**
396
 * Invokes the iteratee `n` times, returning an array of the results of
397
 * each invocation. The iteratee is invoked with one argument; (index).
398
 * @param n - The number of times to invoke `iteratee`
399
 * @param iteratee - The function invoked per iteration
400
 * @returns Returns the array of results
401
 */
402
function times<T>(n: number, iteratee: (index: number) => T): T[];
403
function times(n: number): number[];
404
```
405

406
### Unique Id
407

408
Generates a unique ID.
409

410
```javascript { .api }
411
/**
412
 * Generates a unique ID. If `prefix` is given, the ID is appended to it.
413
 * @param prefix - The value to prefix the ID with
414
 * @returns Returns the unique ID
415
 */
416
function uniqueId(prefix?: string): string;
417
```
418

419
## Date Methods
420

421
### Now
422

423
Gets the timestamp of the number of milliseconds that have elapsed since the Unix epoch.
424

425
```javascript { .api }
426
/**
427
 * Gets the timestamp of the number of milliseconds that have elapsed since
428
 * the Unix epoch (1 January 1970 00:00:00 UTC).
429
 * @returns Returns the timestamp
430
 */
431
function now(): number;
432
```
433

434
## Number Methods
435

436
### Clamp
437

438
Clamps number within the inclusive lower and upper bounds.
439

440
```javascript { .api }
441
/**
442
 * Clamps `number` within the inclusive `lower` and `upper` bounds.
443
 * @param number - The number to clamp
444
 * @param lower - The lower bound
445
 * @param upper - The upper bound
446
 * @returns Returns the clamped number
447
 */
448
function clamp(number: number, lower: number, upper?: number): number;
449
```
450

451
### Random
452

453
Produces a random number between the inclusive lower and upper bounds.
454

455
```javascript { .api }
456
/**
457
 * Produces a random number between the inclusive `lower` and `upper` bounds.
458
 * If only one argument is provided a number between `0` and the given number
459
 * is returned. If `floating` is `true`, or either `lower` or `upper` are
460
 * floats, a floating-point number is returned instead of an integer.
461
 * @param lower - The lower bound
462
 * @param upper - The upper bound
463
 * @param floating - Specify returning a floating-point number
464
 * @returns Returns the random number
465
 */
466
function random(lower?: number, upper?: number, floating?: boolean): number;
467
function random(floating?: boolean): number;
468
```
469

470
## Sequence Methods
471

472
### Chain
473

474
Creates a lodash wrapper instance that wraps value with explicit method chain sequences enabled.
475

476
```javascript { .api }
477
/**
478
 * Creates a `lodash` wrapper instance that wraps `value` with explicit method
479
 * chain sequences enabled. The result of such sequences must be unwrapped
480
 * with `_#value`.
481
 * @param value - The value to wrap
482
 * @returns Returns the new `lodash` wrapper instance
483
 */
484
function chain<T>(value: T): LodashExplicitWrapper<T>;
485
```
486

487
### Tap
488

489
This method invokes interceptor and returns value.
490

491
```javascript { .api }
492
/**
493
 * This method invokes `interceptor` and returns `value`. The interceptor
494
 * is invoked with one argument; (value). The purpose of this method is to
495
 * "tap into" a method chain sequence in order to modify intermediate results.
496
 * @param value - The value to provide to `interceptor`
497
 * @param interceptor - The function to invoke
498
 * @returns Returns `value`
499
 */
500
function tap<T>(value: T, interceptor: (value: T) => void): T;
501
```
502

503
### Thru
504

505
This method is like tap except that it returns the result of interceptor.
506

507
```javascript { .api }
508
/**
509
 * This method is like `tap` except that it returns the result of `interceptor`.
510
 * The purpose of this method is to "pass thru" values replacing intermediate
511
 * results in a method chain sequence.
512
 * @param value - The value to provide to `interceptor`
513
 * @param interceptor - The function to invoke
514
 * @returns Returns the result of `interceptor`
515
 */
516
function thru<T, R>(value: T, interceptor: (value: T) => R): R;
517
```
518

519
## Method Aliases
520

521
### Each
522

523
Alias for forEach. Iterates over elements of collection and invokes iteratee for each element.
524

525
```javascript { .api }
526
/**
527
 * Iterates over elements of `collection` and invokes `iteratee` for each element.
528
 * The iteratee is invoked with three arguments: (value, index|key, collection).
529
 * Iteratee functions may exit iteration early by explicitly returning `false`.
530
 * @param collection - The collection to iterate over
531
 * @param iteratee - The function invoked per iteration
532
 * @returns Returns `collection`
533
 */
534
function each<T>(collection: T[], iteratee?: (value: T, index: number, collection: T[]) => any): T[];
535
function each<T>(collection: Record<string, T>, iteratee?: (value: T, key: string, collection: Record<string, T>) => any): Record<string, T>;
536
```
537

538
### Each Right
539

540
Alias for forEachRight. Like each except that it iterates over elements of collection from right to left.
541

542
```javascript { .api }
543
/**
544
 * This method is like `each` except that it iterates over elements of
545
 * `collection` from right to left.
546
 * @param collection - The collection to iterate over
547
 * @param iteratee - The function invoked per iteration
548
 * @returns Returns `collection`
549
 */
550
function eachRight<T>(collection: T[], iteratee?: (value: T, index: number, collection: T[]) => any): T[];
551
function eachRight<T>(collection: Record<string, T>, iteratee?: (value: T, key: string, collection: Record<string, T>) => any): Record<string, T>;
552
```
553

554
### Entries
555

556
Alias for toPairs. Creates an array of own enumerable string keyed-value pairs for object.
557

558
```javascript { .api }
559
/**
560
 * Creates an array of own enumerable string keyed-value pairs for `object`
561
 * which can be consumed by `fromPairs`. If `object` is a map or set, its
562
 * entries are returned.
563
 * @param object - The object to query
564
 * @returns Returns the key-value pairs
565
 */
566
function entries<T>(object?: Record<string, T>): Array<[string, T]>;
567
function entries(object?: any): Array<[string, any]>;
568
```
569

570
### Entries In
571

572
Alias for toPairsIn. Creates an array of own and inherited enumerable string keyed-value pairs for object.
573

574
```javascript { .api }
575
/**
576
 * Creates an array of own and inherited enumerable string keyed-value pairs
577
 * for `object` which can be consumed by `fromPairs`. If `object` is a map
578
 * or set, its entries are returned.
579
 * @param object - The object to query
580
 * @returns Returns the key-value pairs
581
 */
582
function entriesIn<T>(object?: Record<string, T>): Array<[string, T]>;
583
function entriesIn(object?: any): Array<[string, any]>;
584
```
585

586
### Extend
587

588
Alias for assign. Assigns own enumerable string keyed properties of source objects to the destination object.
589

590
```javascript { .api }
591
/**
592
 * Assigns own enumerable string keyed properties of source objects to the
593
 * destination object. Source objects are applied from left to right.
594
 * Subsequent sources overwrite property assignments of previous sources.
595
 * @param object - The destination object
596
 * @param sources - The source objects
597
 * @returns Returns `object`
598
 */
599
function extend<TObject, TSource>(object: TObject, source: TSource): TObject & TSource;
600
function extend<TObject, TSource1, TSource2>(object: TObject, source1: TSource1, source2: TSource2): TObject & TSource1 & TSource2;
601
function extend<TObject>(object: TObject, ...sources: any[]): any;
602
```
603

604
### Extend With
605

606
Alias for assignWith. Like extend except that it accepts customizer which is invoked to produce the assigned values.
607

608
```javascript { .api }
609
/**
610
 * This method is like `extend` except that it accepts `customizer` which
611
 * is invoked to produce the assigned values. If `customizer` returns `undefined`,
612
 * assignment is handled by the method instead. The `customizer` is invoked
613
 * with five arguments: (objValue, srcValue, key, object, source).
614
 * @param object - The destination object
615
 * @param sources - The source objects
616
 * @param customizer - The function to customize assigned values
617
 * @returns Returns `object`
618
 */
619
function extendWith<TObject, TSource>(
620
  object: TObject,
621
  source: TSource,
622
  customizer: (objValue: any, srcValue: any, key: string, object: TObject, source: TSource) => any
623
): TObject & TSource;
624
function extendWith<TObject>(object: TObject, ...otherArgs: any[]): any;
625
```
626

627
### First
628

629
Alias for head. Gets the first element of array.
630

631
```javascript { .api }
632
/**
633
 * Gets the first element of `array`.
634
 * @param array - The array to query
635
 * @returns Returns the first element of `array`
636
 */
637
function first<T>(array: T[] | null | undefined): T | undefined;
638
```
639

640
## Types
641

642
```javascript { .api }
643
type PropertyPath = string | number | symbol | Array<string | number | symbol>;
644

645
interface LodashExplicitWrapper<TValue> {
646
  chain(): LodashExplicitWrapper<TValue>;
647
  value(): TValue;
648
  valueOf(): TValue;
649
}
650

651
declare const _: LoDashStatic;
652

653
interface LoDashStatic {
654
  VERSION: string;
655
  templateSettings: TemplateSettings;
656
  
657
  // All lodash methods
658
  [key: string]: any;
659
}
660

661
interface TemplateSettings {
662
  escape?: RegExp;
663
  evaluate?: RegExp;
664
  interpolate?: RegExp;
665
  variable?: string;
666
}
667
```