npm-lodash

1
# Function Utilities
2

3
Function composition, currying, debouncing, throttling, and other functional programming utilities. These methods help create more flexible and performant functions.
4

5
## Capabilities
6

7
### Function Control
8

9
Control when and how often functions execute.
10

11
```javascript { .api }
12
/**
13
 * Creates a debounced function that delays invoking `func` until after `wait`
14
 * milliseconds have elapsed since the last time the debounced function was invoked.
15
 * 
16
 * @param {Function} func The function to debounce
17
 * @param {number} [wait=0] The number of milliseconds to delay
18
 * @param {Object} [options] The options object
19
 * @returns {Function} Returns the new debounced function
20
 */
21
function debounce(func: Function, wait?: number, options?: Object): Function;
22

23
/**
24
 * Creates a throttled function that only invokes `func` at most once per
25
 * every `wait` milliseconds.
26
 * 
27
 * @param {Function} func The function to throttle
28
 * @param {number} [wait=0] The number of milliseconds to throttle invocations to
29
 * @param {Object} [options] The options object
30
 * @returns {Function} Returns the new throttled function
31
 */
32
function throttle(func: Function, wait?: number, options?: Object): Function;
33
```
34

35
**Usage Examples:**
36

37
```javascript
38
import { debounce, throttle } from "lodash";
39

40
// Debounce - waits for pause in calls
41
const debouncedSave = debounce(saveFunction, 1000);
42
// Will only call saveFunction 1 second after the last call
43

44
// Throttle - limits call frequency
45
const throttledScroll = throttle(onScroll, 100);
46
// Will call onScroll at most once every 100ms
47

48
// Debounce with options
49
const debouncedSearch = debounce(search, 300, {
50
  leading: true,  // invoke on leading edge
51
  trailing: false // don't invoke on trailing edge
52
});
53
```
54

55
### Function Caching
56

57
Cache function results for performance.
58

59
```javascript { .api }
60
/**
61
 * Creates a function that memoizes the result of `func`. If `resolver` is
62
 * provided, it determines the cache key for storing the result based on the
63
 * arguments provided to the memoized function.
64
 * 
65
 * @param {Function} func The function to have its output memoized
66
 * @param {Function} [resolver] The function to resolve the cache key
67
 * @returns {Function} Returns the new memoized function
68
 */
69
function memoize(func: Function, resolver?: Function): Function;
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
import { memoize } from "lodash";
76

77
// Basic memoization
78
const expensive = memoize(function(n) {
79
  console.log('Computing...');
80
  return n * n;
81
});
82

83
expensive(5); // logs "Computing...", returns 25
84
expensive(5); // returns 25 (cached, no log)
85

86
// Custom resolver
87
const memoizedGet = memoize(get, function(obj, path) {
88
  return obj.id + '.' + path;
89
});
90
```
91

92
### Function Currying
93

94
Transform functions to accept arguments partially.
95

96
```javascript { .api }
97
/**
98
 * Creates a function that accepts arguments of `func` and either invokes
99
 * `func` returning its result, if at least `arity` number of arguments have
100
 * been provided, or returns a function that accepts the remaining `func` arguments.
101
 * 
102
 * @param {Function} func The function to curry
103
 * @param {number} [arity=func.length] The arity of `func`
104
 * @returns {Function} Returns the new curried function
105
 */
106
function curry(func: Function, arity?: number): Function;
107

108
/**
109
 * This method is like `curry` except that arguments are applied to `func`
110
 * in the manner of `partialRight` instead of `partial`.
111
 * 
112
 * @param {Function} func The function to curry
113
 * @param {number} [arity=func.length] The arity of `func`
114
 * @returns {Function} Returns the new curried function
115
 */
116
function curryRight(func: Function, arity?: number): Function;
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
import { curry, curryRight } from "lodash";
123

124
// Basic currying
125
const add = (a, b, c) => a + b + c;
126
const curriedAdd = curry(add);
127

128
curriedAdd(1)(2)(3); // 6
129
curriedAdd(1, 2)(3); // 6
130
curriedAdd(1)(2, 3); // 6
131

132
// Curry right (arguments applied right-to-left)
133
const divide = (a, b) => a / b;
134
const curriedRightDivide = curryRight(divide);
135
curriedRightDivide(2)(10); // 10 / 2 = 5
136
```
137

138
### Partial Application
139

140
Create functions with pre-filled arguments.
141

142
```javascript { .api }
143
/**
144
 * Creates a function that invokes `func` with `partials` prepended to the
145
 * arguments it receives.
146
 * 
147
 * @param {Function} func The function to partially apply arguments to
148
 * @param {...*} [partials] The arguments to be partially applied
149
 * @returns {Function} Returns the new partially applied function
150
 */
151
function partial(func: Function, ...partials: any[]): Function;
152

153
/**
154
 * This method is like `partial` except that partially applied arguments
155
 * are appended to the arguments it receives.
156
 * 
157
 * @param {Function} func The function to partially apply arguments to
158
 * @param {...*} [partials] The arguments to be partially applied
159
 * @returns {Function} Returns the new partially applied function
160
 */
161
function partialRight(func: Function, ...partials: any[]): Function;
162
```
163

164
**Usage Examples:**
165

166
```javascript
167
import { partial, partialRight } from "lodash";
168

169
const greet = (greeting, name) => `${greeting} ${name}`;
170

171
// Partial application from left
172
const sayHello = partial(greet, 'Hello');
173
sayHello('World'); // "Hello World"
174

175
// Partial application from right
176
const greetJohn = partialRight(greet, 'John');
177
greetJohn('Hi'); // "Hi John"
178
```
179

180
### Function Binding
181

182
Bind functions to specific contexts.
183

184
```javascript { .api }
185
/**
186
 * Creates a function that invokes `func` with the `this` binding of `thisArg`
187
 * and `partials` prepended to the arguments it receives.
188
 * 
189
 * @param {Function} func The function to bind
190
 * @param {*} thisArg The `this` binding of `func`
191
 * @param {...*} [partials] The arguments to be partially applied
192
 * @returns {Function} Returns the new bound function
193
 */
194
function bind(func: Function, thisArg: any, ...partials: any[]): Function;
195

196
/**
197
 * Binds methods of an object to the object itself, overwriting the existing method.
198
 * 
199
 * @param {Object} object The object to bind and assign the bound methods to
200
 * @param {...(string|string[])} methodNames The object method names to bind
201
 * @returns {Object} Returns `object`
202
 */
203
function bindAll(object: Object, ...methodNames: (string|string[])[]): Object;
204

205
/**
206
 * Creates a function that invokes the method at `object[key]` with `partials`
207
 * prepended to the arguments it receives.
208
 * 
209
 * @param {Object} object The object to invoke the method on
210
 * @param {string} key The key of the method
211
 * @param {...*} [partials] The arguments to be partially applied
212
 * @returns {Function} Returns the new bound function
213
 */
214
function bindKey(object: Object, key: string, ...partials: any[]): Function;
215
```
216

217
### Function Composition
218

219
Combine multiple functions into single functions.
220

221
```javascript { .api }
222
/**
223
 * Creates a function that is the composition of the provided functions,
224
 * where each successive invocation is supplied the return value of the previous.
225
 * 
226
 * @param {...(Function|Function[])} [funcs] The functions to invoke
227
 * @returns {Function} Returns the new composite function
228
 */
229
function flow(...funcs: (Function|Function[])[]): Function;
230

231
/**
232
 * This method is like `flow` except that it creates a function that invokes
233
 * the given functions from right to left.
234
 * 
235
 * @param {...(Function|Function[])} [funcs] The functions to invoke
236
 * @returns {Function} Returns the new composite function
237
 */
238
function flowRight(...funcs: (Function|Function[])[]): Function;
239
```
240

241
**Usage Examples:**
242

243
```javascript
244
import { flow, flowRight } from "lodash";
245

246
const add = x => x + 1;
247
const multiply = x => x * 2;
248
const square = x => x * x;
249

250
// Left-to-right composition
251
const transform = flow(add, multiply, square);
252
transform(2); // ((2 + 1) * 2)² = 36
253

254
// Right-to-left composition  
255
const transform2 = flowRight(square, multiply, add);
256
transform2(2); // ((2 + 1) * 2)² = 36 (same result)
257
```
258

259
### Function Constraints
260

261
Limit how functions can be called.
262

263
```javascript { .api }
264
/**
265
 * Creates a function that is restricted to invoking `func` once. Repeat calls
266
 * to the function return the value of the first invocation.
267
 * 
268
 * @param {Function} func The function to restrict
269
 * @returns {Function} Returns the new restricted function
270
 */
271
function once(func: Function): Function;
272

273
/**
274
 * Creates a function that invokes `func`, with up to `n` arguments,
275
 * ignoring any additional arguments.
276
 * 
277
 * @param {Function} func The function to cap arguments for
278
 * @param {number} [n=func.length] The arity cap
279
 * @returns {Function} Returns the new capped function
280
 */
281
function ary(func: Function, n?: number): Function;
282

283
/**
284
 * Creates a function that accepts up to one argument, ignoring any
285
 * additional arguments.
286
 * 
287
 * @param {Function} func The function to cap arguments for
288
 * @returns {Function} Returns the new capped function
289
 */
290
function unary(func: Function): Function;
291
```
292

293
### Function Timing
294

295
Control the timing of function execution.
296

297
```javascript { .api }
298
/**
299
 * Creates a function that invokes `func` only after it's called more than
300
 * `n` times.
301
 * 
302
 * @param {number} n The number of calls before `func` is invoked
303
 * @param {Function} func The function to restrict
304
 * @returns {Function} Returns the new restricted function
305
 */
306
function after(n: number, func: Function): Function;
307

308
/**
309
 * Creates a function that invokes `func`, with the `this` binding and arguments
310
 * of the created function, while it's called less than `n` times.
311
 * 
312
 * @param {number} n The number of calls at which `func` is no longer invoked
313
 * @param {Function} func The function to restrict
314
 * @returns {Function} Returns the new restricted function
315
 */
316
function before(n: number, func: Function): Function;
317

318
/**
319
 * Defers invoking the `func` until the current call stack has cleared.
320
 * 
321
 * @param {Function} func The function to defer
322
 * @param {...*} [args] The arguments to invoke `func` with
323
 * @returns {number} Returns the timer id
324
 */
325
function defer(func: Function, ...args: any[]): number;
326

327
/**
328
 * Invokes `func` after `wait` milliseconds.
329
 * 
330
 * @param {Function} func The function to delay
331
 * @param {number} wait The number of milliseconds to delay invocation
332
 * @param {...*} [args] The arguments to invoke `func` with
333
 * @returns {number} Returns the timer id
334
 */
335
function delay(func: Function, wait: number, ...args: any[]): number;
336
```
337

338
### Function Transformation
339

340
Transform functions in various ways.
341

342
```javascript { .api }
343
/**
344
 * Creates a function that negates the result of the predicate `func`.
345
 * 
346
 * @param {Function} predicate The predicate to negate
347
 * @returns {Function} Returns the new negated function
348
 */
349
function negate(predicate: Function): Function;
350

351
/**
352
 * Creates a function that invokes `func` with arguments reversed.
353
 * 
354
 * @param {Function} func The function to flip arguments for
355
 * @returns {Function} Returns the new flipped function
356
 */
357
function flip(func: Function): Function;
358

359
/**
360
 * Creates a function that invokes `func` with its arguments transformed.
361
 * 
362
 * @param {Function} func The function to wrap
363
 * @param {...(Function|Function[])} [transforms] The argument transforms
364
 * @returns {Function} Returns the new function
365
 */
366
function overArgs(func: Function, ...transforms: (Function|Function[])[]): Function;
367

368
/**
369
 * Creates a function that invokes `func` with arguments arranged according
370
 * to the specified `indexes`.
371
 * 
372
 * @param {Function} func The function to rearrange arguments for
373
 * @param {...(number|number[])} indexes The arranged argument indexes
374
 * @returns {Function} Returns the new function
375
 */
376
function rearg(func: Function, ...indexes: (number|number[])[]): Function;
377
```
378

379
### Function Wrapping
380

381
Wrap functions with additional behavior.
382

383
```javascript { .api }
384
/**
385
 * Creates a function that provides `value` to `wrapper` as its first
386
 * argument. Any additional arguments provided to the function are appended
387
 * to those provided to the `wrapper`.
388
 * 
389
 * @param {*} value The value to wrap
390
 * @param {Function} [wrapper] The wrapper function
391
 * @returns {Function} Returns the new function
392
 */
393
function wrap(value: any, wrapper?: Function): Function;
394

395
/**
396
 * Creates a function that invokes `func` with the `this` binding of the
397
 * created function and an array of arguments much like `Function#apply`.
398
 * 
399
 * @param {Function} func The function to spread arguments over
400
 * @param {number} [start=0] The start position of the spread
401
 * @returns {Function} Returns the new function
402
 */
403
function spread(func: Function, start?: number): Function;
404

405
/**
406
 * Creates a function that invokes `func` with the `this` binding of the
407
 * created function and arguments from `start` and beyond provided as
408
 * an array.
409
 * 
410
 * @param {Function} func The function to apply a rest parameter to
411
 * @param {number} [start=func.length-1] The start position of the rest parameter
412
 * @returns {Function} Returns the new function
413
 */
414
function rest(func: Function, start?: number): Function;
415
```