npm-lodash

1
# Function Methods
2

3
Function composition, currying, debouncing, throttling, and other function manipulation utilities for enhancing and controlling function behavior.
4

5
## Capabilities
6

7
### After
8

9
Creates a function that invokes func once it's called n or more times.
10

11
```javascript { .api }
12
/**
13
 * Creates a function that invokes `func` once it's called `n` or more times.
14
 * @param n - The number of calls before `func` is invoked
15
 * @param func - The function to restrict
16
 * @returns Returns the new restricted function
17
 */
18
function after<T extends (...args: any[]) => any>(n: number, func: T): T;
19
```
20

21
### Ary
22

23
Creates a function that invokes func, with up to n arguments, ignoring any additional arguments.
24

25
```javascript { .api }
26
/**
27
 * Creates a function that invokes `func`, with up to `n` arguments,
28
 * ignoring any additional arguments.
29
 * @param func - The function to cap arguments for
30
 * @param n - The arity cap (defaults to func.length)
31
 * @returns Returns the new capped function
32
 */
33
function ary<T extends (...args: any[]) => any>(func: T, n?: number): T;
34
```
35

36
### Before
37

38
Creates a function that invokes func, with the this binding and arguments of the created function, while it's called less than n times.
39

40
```javascript { .api }
41
/**
42
 * Creates a function that invokes `func`, with the `this` binding and arguments
43
 * of the created function, while it's called less than `n` times. Subsequent
44
 * calls to the created function return the result of the last `func` invocation.
45
 * @param n - The number of calls at which `func` is no longer invoked
46
 * @param func - The function to restrict
47
 * @returns Returns the new restricted function
48
 */
49
function before<T extends (...args: any[]) => any>(n: number, func: T): T;
50
```
51

52
### Bind
53

54
Creates a function that invokes func with the this binding of thisArg and prepends any additional bind arguments to those provided to the bound function.
55

56
```javascript { .api }
57
/**
58
 * Creates a function that invokes `func` with the `this` binding of `thisArg`
59
 * and `partials` prepended to the arguments it receives.
60
 * @param func - The function to bind
61
 * @param thisArg - The `this` binding of `func`
62
 * @param partials - The arguments to be partially applied
63
 * @returns Returns the new bound function
64
 */
65
function bind<T extends (...args: any[]) => any>(
66
  func: T,
67
  thisArg: any,
68
  ...partials: any[]
69
): T;
70
```
71

72
### Bind All
73

74
Binds methods of an object to the object itself, overwriting the existing methods.
75

76
```javascript { .api }
77
/**
78
 * Binds methods of an object to the object itself, overwriting the existing
79
 * methods.
80
 * @param object - The object to bind and assign the bound methods to
81
 * @param methodNames - The object method names to bind
82
 * @returns Returns `object`
83
 */
84
function bindAll<T>(object: T, ...methodNames: string[]): T;
85
```
86

87
### Bind Key
88

89
Creates a function that invokes the method at object[key] with partials prepended to the arguments it receives.
90

91
```javascript { .api }
92
/**
93
 * Creates a function that invokes the method at `object[key]` with `partials`
94
 * prepended to the arguments it receives.
95
 * @param object - The object to invoke the method on
96
 * @param key - The key of the method
97
 * @param partials - The arguments to be partially applied
98
 * @returns Returns the new bound function
99
 */
100
function bindKey(
101
  object: any,
102
  key: string,
103
  ...partials: any[]
104
): (...args: any[]) => any;
105
```
106

107
### Curry
108

109
Creates a function that accepts arguments of func and either invokes func returning its result, if at least arity number of arguments have been provided, or returns a function that accepts the remaining func arguments, and so on.
110

111
```javascript { .api }
112
/**
113
 * Creates a function that accepts arguments of `func` and either invokes
114
 * `func` returning its result, if at least `arity` number of arguments have
115
 * been provided, or returns a function that accepts the remaining `func`
116
 * arguments, and so on.
117
 * @param func - The function to curry
118
 * @param arity - The arity of `func` (defaults to func.length)
119
 * @returns Returns the new curried function
120
 */
121
function curry<T extends (...args: any[]) => any>(func: T, arity?: number): CurriedFunction<T>;
122

123
interface CurriedFunction<T> {
124
  (): CurriedFunction<T>;
125
  <A>(a: A): T extends (a: A, ...rest: any[]) => any ? CurriedFunction<T> : never;
126
  <A, B>(a: A, b: B): T extends (a: A, b: B, ...rest: any[]) => any ? CurriedFunction<T> : never;
127
  <A, B, C>(a: A, b: B, c: C): T extends (a: A, b: B, c: C, ...rest: any[]) => any ? CurriedFunction<T> : never;
128
  (...args: any[]): any;
129
}
130
```
131

132
### Curry Right
133

134
Like curry except that arguments are applied to func in the manner of partialRight instead of partial.
135

136
```javascript { .api }
137
/**
138
 * This method is like `curry` except that arguments are applied to `func`
139
 * in the manner of `partialRight` instead of `partial`.
140
 * @param func - The function to curry
141
 * @param arity - The arity of `func` (defaults to func.length)
142
 * @returns Returns the new curried function
143
 */
144
function curryRight<T extends (...args: any[]) => any>(
145
  func: T,
146
  arity?: number
147
): CurriedFunction<T>;
148
```
149

150
### Debounce
151

152
Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked.
153

154
```javascript { .api }
155
/**
156
 * Creates a debounced function that delays invoking `func` until after `wait`
157
 * milliseconds have elapsed since the last time the debounced function was
158
 * invoked.
159
 * @param func - The function to debounce
160
 * @param wait - The number of milliseconds to delay (defaults to 0)
161
 * @param options - The options object
162
 * @returns Returns the new debounced function
163
 */
164
function debounce<T extends (...args: any[]) => any>(
165
  func: T,
166
  wait?: number,
167
  options?: DebounceOptions
168
): DebouncedFunc<T>;
169

170
interface DebounceOptions {
171
  /** Specify invoking on the leading edge of the timeout */
172
  leading?: boolean;
173
  /** The maximum time `func` is allowed to be delayed before it's invoked */
174
  maxWait?: number;
175
  /** Specify invoking on the trailing edge of the timeout */
176
  trailing?: boolean;
177
}
178

179
interface DebouncedFunc<T extends (...args: any[]) => any> {
180
  (...args: Parameters<T>): ReturnType<T> | undefined;
181
  /** Cancels any pending invocation */
182
  cancel(): void;
183
  /** Immediately invokes the function */
184
  flush(): ReturnType<T> | undefined;
185
}
186
```
187

188
### Defer
189

190
Defers invoking the func until the current call stack has cleared.
191

192
```javascript { .api }
193
/**
194
 * Defers invoking the `func` until the current call stack has cleared.
195
 * Any additional arguments are provided to `func` when it's invoked.
196
 * @param func - The function to defer
197
 * @param args - The arguments to invoke `func` with
198
 * @returns Returns the timer id
199
 */
200
function defer<T extends (...args: any[]) => any>(func: T, ...args: Parameters<T>): number;
201
```
202

203
### Delay
204

205
Invokes func after wait milliseconds.
206

207
```javascript { .api }
208
/**
209
 * Invokes `func` after `wait` milliseconds. Any additional arguments are
210
 * provided to `func` when it's invoked.
211
 * @param func - The function to delay
212
 * @param wait - The number of milliseconds to delay invocation
213
 * @param args - The arguments to invoke `func` with
214
 * @returns Returns the timer id
215
 */
216
function delay<T extends (...args: any[]) => any>(
217
  func: T,
218
  wait: number,
219
  ...args: Parameters<T>
220
): number;
221
```
222

223
### Flip
224

225
Creates a function that invokes func with arguments flipped.
226

227
```javascript { .api }
228
/**
229
 * Creates a function that invokes `func` with arguments flipped.
230
 * @param func - The function to flip arguments for
231
 * @returns Returns the new flipped function
232
 */
233
function flip<T extends (...args: any[]) => any>(func: T): T;
234
```
235

236
### Memoize
237

238
Creates a function that memoizes the result of func.
239

240
```javascript { .api }
241
/**
242
 * Creates a function that memoizes the result of `func`. If `resolver` is
243
 * provided, it determines the cache key for storing the result based on the
244
 * arguments provided to the memoized function.
245
 * @param func - The function to have its output memoized
246
 * @param resolver - The function to resolve the cache key
247
 * @returns Returns the new memoized function
248
 */
249
function memoize<T extends (...args: any[]) => any>(
250
  func: T,
251
  resolver?: (...args: Parameters<T>) => any
252
): MemoizedFunction<T>;
253

254
interface MemoizedFunction<T extends (...args: any[]) => any> extends T {
255
  /** The cache object for the memoized function */
256
  cache: Map<any, ReturnType<T>>;
257
}
258
```
259

260
### Negate
261

262
Creates a function that negates the result of the predicate func.
263

264
```javascript { .api }
265
/**
266
 * Creates a function that negates the result of the predicate `func`. The
267
 * `func` predicate is invoked with the `this` binding and arguments of the
268
 * created function.
269
 * @param predicate - The predicate to negate
270
 * @returns Returns the new negated function
271
 */
272
function negate<T extends (...args: any[]) => boolean>(predicate: T): T;
273
```
274

275
### Once
276

277
Creates a function that is restricted to invoking func once.
278

279
```javascript { .api }
280
/**
281
 * Creates a function that is restricted to invoking `func` once. Repeat calls
282
 * to the function return the value of the first invocation.
283
 * @param func - The function to restrict
284
 * @returns Returns the new restricted function
285
 */
286
function once<T extends (...args: any[]) => any>(func: T): T;
287
```
288

289
### Over Args
290

291
Creates a function that invokes func with its arguments transformed.
292

293
```javascript { .api }
294
/**
295
 * Creates a function that invokes `func` with its arguments transformed.
296
 * @param func - The function to wrap
297
 * @param transforms - The argument transforms
298
 * @returns Returns the new function
299
 */
300
function overArgs<T extends (...args: any[]) => any>(
301
  func: T,
302
  ...transforms: Array<(arg: any) => any>
303
): T;
304
```
305

306
### Partial
307

308
Creates a function that invokes func with partials prepended to the arguments it receives.
309

310
```javascript { .api }
311
/**
312
 * Creates a function that invokes `func` with `partials` prepended to the
313
 * arguments it receives. This method is like `bind` except it does **not**
314
 * alter the `this` binding.
315
 * @param func - The function to partially apply arguments to
316
 * @param partials - The arguments to be partially applied
317
 * @returns Returns the new partially applied function
318
 */
319
function partial<T extends (...args: any[]) => any>(
320
  func: T,
321
  ...partials: any[]
322
): T;
323
```
324

325
### Partial Right
326

327
Like partial except that partially applied arguments are appended to the arguments it receives.
328

329
```javascript { .api }
330
/**
331
 * This method is like `partial` except that partially applied arguments
332
 * are appended to the arguments it receives.
333
 * @param func - The function to partially apply arguments to
334
 * @param partials - The arguments to be partially applied
335
 * @returns Returns the new partially applied function
336
 */
337
function partialRight<T extends (...args: any[]) => any>(
338
  func: T,
339
  ...partials: any[]
340
): T;
341
```
342

343
### Rearg
344

345
Creates a function that invokes func with arguments arranged according to the specified indexes.
346

347
```javascript { .api }
348
/**
349
 * Creates a function that invokes `func` with arguments arranged according
350
 * to the specified `indexes` where the argument value at the first index is
351
 * provided as the first argument, the argument value at the second index is
352
 * provided as the second argument, and so on.
353
 * @param func - The function to rearrange arguments for
354
 * @param indexes - The arranged argument indexes
355
 * @returns Returns the new function
356
 */
357
function rearg<T extends (...args: any[]) => any>(
358
  func: T,
359
  ...indexes: number[]
360
): T;
361
```
362

363
### Rest
364

365
Creates a function that invokes func with the this binding of the created function and arguments from start and beyond provided as an array.
366

367
```javascript { .api }
368
/**
369
 * Creates a function that invokes `func` with the `this` binding of the
370
 * created function and arguments from `start` and beyond provided as
371
 * an array.
372
 * @param func - The function to apply a rest parameter to
373
 * @param start - The start position of the rest parameter (defaults to func.length - 1)
374
 * @returns Returns the new function
375
 */
376
function rest<T extends (...args: any[]) => any>(
377
  func: T,
378
  start?: number
379
): (...args: any[]) => ReturnType<T>;
380
```
381

382
### Spread
383

384
Creates a function that invokes func with the this binding of the created function and an array of arguments much like Function#apply.
385

386
```javascript { .api }
387
/**
388
 * Creates a function that invokes `func` with the `this` binding of the
389
 * created function and an array of arguments much like
390
 * [`Function#apply`](http://www.ecma-international.org/ecma-262/7.0/#sec-function.prototype.apply).
391
 * @param func - The function to spread arguments over
392
 * @param start - The start position of the spread (defaults to 0)
393
 * @returns Returns the new function
394
 */
395
function spread<T extends (args: any[]) => any>(
396
  func: T,
397
  start?: number
398
): (...args: any[]) => ReturnType<T>;
399
```
400

401
### Throttle
402

403
Creates a throttled function that only invokes func at most once per every wait milliseconds.
404

405
```javascript { .api }
406
/**
407
 * Creates a throttled function that only invokes `func` at most once per
408
 * every `wait` milliseconds. The throttled function comes with a `cancel`
409
 * method to cancel delayed `func` invocations and a `flush` method to
410
 * immediately invoke them.
411
 * @param func - The function to throttle
412
 * @param wait - The number of milliseconds to throttle invocations to (defaults to 0)
413
 * @param options - The options object
414
 * @returns Returns the new throttled function
415
 */
416
function throttle<T extends (...args: any[]) => any>(
417
  func: T,
418
  wait?: number,
419
  options?: ThrottleOptions
420
): ThrottledFunc<T>;
421

422
interface ThrottleOptions {
423
  /** Specify invoking on the leading edge of the timeout */
424
  leading?: boolean;
425
  /** Specify invoking on the trailing edge of the timeout */
426
  trailing?: boolean;
427
}
428

429
interface ThrottledFunc<T extends (...args: any[]) => any> {
430
  (...args: Parameters<T>): ReturnType<T> | undefined;
431
  /** Cancels any pending invocation */
432
  cancel(): void;
433
  /** Immediately invokes the function */
434
  flush(): ReturnType<T> | undefined;
435
}
436
```
437

438
### Unary
439

440
Creates a function that accepts up to one argument, ignoring any additional arguments.
441

442
```javascript { .api }
443
/**
444
 * Creates a function that accepts up to one argument, ignoring any
445
 * additional arguments.
446
 * @param func - The function to cap arguments for
447
 * @returns Returns the new capped function
448
 */
449
function unary<T extends (arg: any, ...rest: any[]) => any>(func: T): (arg: Parameters<T>[0]) => ReturnType<T>;
450
```
451

452
### Wrap
453

454
Creates a function that provides value to wrapper as its first argument.
455

456
```javascript { .api }
457
/**
458
 * Creates a function that provides `value` to `wrapper` as its first
459
 * argument. Any additional arguments provided to the function are appended
460
 * to those provided to the `wrapper`.
461
 * @param value - The value to wrap
462
 * @param wrapper - The wrapper function
463
 * @returns Returns the new function
464
 */
465
function wrap<T, R>(
466
  value: T,
467
  wrapper: (value: T, ...args: any[]) => R
468
): (...args: any[]) => R;
469
```
470

471
## Flow Control
472

473
### Flow
474

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

477
```javascript { .api }
478
/**
479
 * Creates a function that is the composition of the provided functions,
480
 * where each successive invocation is supplied the return value of the previous.
481
 * @param funcs - The functions to invoke
482
 * @returns Returns the new composite function
483
 */
484
function flow<A extends any[], R1, R2, R3, R4, R5, R6, R7>(
485
  f1: (...args: A) => R1,
486
  f2: (a: R1) => R2,
487
  f3?: (a: R2) => R3,
488
  f4?: (a: R3) => R4,
489
  f5?: (a: R4) => R5,
490
  f6?: (a: R5) => R6,
491
  f7?: (a: R6) => R7
492
): (...args: A) => R7;
493

494
function flow(...funcs: Array<(...args: any[]) => any>): (...args: any[]) => any;
495
```
496

497
### Flow Right
498

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

501
```javascript { .api }
502
/**
503
 * This method is like `flow` except that it creates a function that invokes
504
 * the given functions from right to left.
505
 * @param funcs - The functions to invoke
506
 * @returns Returns the new composite function
507
 */
508
function flowRight<A extends any[], R1, R2, R3, R4, R5, R6, R7>(
509
  f7: (a: R6) => R7,
510
  f6?: (a: R5) => R6,
511
  f5?: (a: R4) => R5,
512
  f4?: (a: R3) => R4,
513
  f3?: (a: R2) => R3,
514
  f2?: (a: R1) => R2,
515
  f1?: (...args: A) => R1
516
): (...args: A) => R7;
517

518
function flowRight(...funcs: Array<(...args: any[]) => any>): (...args: any[]) => any;
519
```