npm-lodash

1
# General Utilities
2

3
Miscellaneous utilities including iteration, constants, method chaining, and utility functions that don't fit into other categories.
4

5
## Capabilities
6

7
### Iteration Utilities
8

9
Create arrays and iterate specific numbers of times.
10

11
```javascript { .api }
12
/**
13
 * Invokes the iteratee `n` times, returning an array of the results of
14
 * each invocation.
15
 * 
16
 * @param {number} n The number of times to invoke `iteratee`
17
 * @param {Function} [iteratee] The function invoked per iteration
18
 * @returns {Array} Returns the array of results
19
 */
20
function times(n: number, iteratee?: Function): Array;
21

22
/**
23
 * Creates an array of numbers (positive and/or negative) progressing from
24
 * `start` up to, but not including, `end`. A step of `-1` is used if a negative
25
 * `start` is specified without an `end` or `step`.
26
 * 
27
 * @param {number} [start=0] The start of the range
28
 * @param {number} end The end of the range
29
 * @param {number} [step=1] The value to increment or decrement by
30
 * @returns {Array} Returns the range of numbers
31
 */
32
function range(start?: number, end?: number, step?: number): Array;
33

34
/**
35
 * This method is like `range` except that it populates values in
36
 * descending order.
37
 * 
38
 * @param {number} [start=0] The start of the range
39
 * @param {number} end The end of the range
40
 * @param {number} [step=1] The value to increment or decrement by
41
 * @returns {Array} Returns the range of numbers
42
 */
43
function rangeRight(start?: number, end?: number, step?: number): Array;
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
import { times, range, rangeRight } from "lodash";
50

51
times(3, String); // ['0', '1', '2']
52
times(4, () => 'a'); // ['a', 'a', 'a', 'a']
53
times(3); // [0, 1, 2]
54

55
range(4); // [0, 1, 2, 3]
56
range(-4); // [0, -1, -2, -3]
57
range(1, 5); // [1, 2, 3, 4]
58
range(0, 20, 5); // [0, 5, 10, 15]
59
range(0, -4, -1); // [0, -1, -2, -3]
60

61
rangeRight(4); // [3, 2, 1, 0]
62
rangeRight(-4); // [-3, -2, -1, 0]
63
rangeRight(1, 5); // [4, 3, 2, 1]
64
rangeRight(0, 20, 5); // [15, 10, 5, 0]
65
```
66

67
### Identity and Constants
68

69
Basic utility functions for common operations.
70

71
```javascript { .api }
72
/**
73
 * This method returns the first argument it receives.
74
 * 
75
 * @param {*} value Any value
76
 * @returns {*} Returns `value`
77
 */
78
function identity(value: any): any;
79

80
/**
81
 * Creates a function that returns `value`.
82
 * 
83
 * @param {*} value The value to return from the new function
84
 * @returns {Function} Returns the new constant function
85
 */
86
function constant(value: any): Function;
87

88
/**
89
 * This method returns `undefined`.
90
 * 
91
 * @returns {undefined} Returns `undefined`
92
 */
93
function noop(): undefined;
94
```
95

96
**Usage Examples:**
97

98
```javascript
99
import { identity, constant, noop } from "lodash";
100

101
identity(1); // 1
102
identity({ a: 1 }); // { a: 1 }
103

104
const object = { 'a': 1 };
105
const getObject = constant(object);
106
getObject() === object; // true
107

108
noop(); // undefined
109
[1, 2, 3].forEach(noop); // does nothing
110
```
111

112
### Function Creation
113

114
Create functions that return specific values or perform specific tasks.
115

116
```javascript { .api }
117
/**
118
 * Creates a function that invokes `iteratees` with the arguments it receives
119
 * and returns their results.
120
 * 
121
 * @param {...(Function|Function[])} [iteratees] The iteratees to invoke
122
 * @returns {Function} Returns the new function
123
 */
124
function over(...iteratees: (Function|Function[])[]): Function;
125

126
/**
127
 * Creates a function that checks if **all** of the `predicates` return
128
 * truthy when invoked with the arguments it receives.
129
 * 
130
 * @param {...(Function|Function[])} [predicates] The predicates to check
131
 * @returns {Function} Returns the new function
132
 */
133
function overEvery(...predicates: (Function|Function[])[]): Function;
134

135
/**
136
 * Creates a function that checks if **any** of the `predicates` return
137
 * truthy when invoked with the arguments it receives.
138
 * 
139
 * @param {...(Function|Function[])} [predicates] The predicates to check
140
 * @returns {Function} Returns the new function
141
 */
142
function overSome(...predicates: (Function|Function[])[]): Function;
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
import { over, overEvery, overSome } from "lodash";
149

150
const func = over([Math.max, Math.min]);
151
func(1, 2, 3, 4); // [4, 1]
152

153
const func2 = overEvery([Boolean, isFinite]);
154
func2('1'); // true
155
func2(null); // false
156
func2(NaN); // false
157

158
const func3 = overSome([Boolean, isFinite]);
159
func3('1'); // true
160
func3(null); // false
161
func3(NaN); // true (isFinite returns false, but Boolean returns false which is falsy, so isFinite's false is converted to true)
162
```
163

164
### Property Accessors
165

166
Create functions for accessing object properties.
167

168
```javascript { .api }
169
/**
170
 * Creates a function that returns the value at `path` of a given object.
171
 * 
172
 * @param {Array|string} path The path of the property to get
173
 * @returns {Function} Returns the new accessor function
174
 */
175
function property(path: Array|string): Function;
176

177
/**
178
 * The opposite of `property`; this method creates a function that returns
179
 * the value at a given path of `object`.
180
 * 
181
 * @param {Object} object The object to query
182
 * @returns {Function} Returns the new accessor function
183
 */
184
function propertyOf(object: Object): Function;
185
```
186

187
**Usage Examples:**
188

189
```javascript
190
import { property, propertyOf } from "lodash";
191

192
const objects = [
193
  { 'a': { 'b': 2 } },
194
  { 'a': { 'b': 1 } }
195
];
196

197
map(objects, property('a.b')); // [2, 1]
198
map(objects, property(['a', 'b'])); // [2, 1]
199

200
const array = [0, 1, 2];
201
const object = { 'a': array, 'b': array, 'c': array };
202

203
map(['a[2]', 'c[0]'], propertyOf(object)); // [2, 0]
204
```
205

206
### Matching Functions
207

208
Create functions for matching values and properties.
209

210
```javascript { .api }
211
/**
212
 * Creates a function that performs a partial deep comparison between a given
213
 * object and `source`, returning `true` if the given object has equivalent
214
 * property values, else `false`.
215
 * 
216
 * @param {Object} source The object of property values to match
217
 * @returns {Function} Returns the new spec function
218
 */
219
function matches(source: Object): Function;
220

221
/**
222
 * Creates a function that performs a partial deep comparison between the
223
 * value at `path` of a given object to `srcValue`, returning `true` if the
224
 * object value is equivalent, else `false`.
225
 * 
226
 * @param {Array|string} path The path of the property to get
227
 * @param {*} srcValue The value to match
228
 * @returns {Function} Returns the new spec function
229
 */
230
function matchesProperty(path: Array|string, srcValue: any): Function;
231
```
232

233
**Usage Examples:**
234

235
```javascript
236
import { matches, matchesProperty, filter } from "lodash";
237

238
const objects = [
239
  { 'a': 1, 'b': 2, 'c': 3 },
240
  { 'a': 4, 'b': 5, 'c': 6 }
241
];
242

243
filter(objects, matches({ 'a': 4, 'c': 6 })); // [{ 'a': 4, 'b': 5, 'c': 6 }]
244

245
filter(objects, matchesProperty('a', 4)); // [{ 'a': 4, 'b': 5, 'c': 6 }]
246
filter(objects, matchesProperty(['a'], 4)); // [{ 'a': 4, 'b': 5, 'c': 6 }]
247
```
248

249
### Method Creation
250

251
Create functions that invoke methods on objects.
252

253
```javascript { .api }
254
/**
255
 * Creates a function that invokes the method at `path` of a given object.
256
 * Any additional arguments are provided to the invoked method.
257
 * 
258
 * @param {Array|string} path The path of the method to invoke
259
 * @param {...*} [args] The arguments to invoke the method with
260
 * @returns {Function} Returns the new invoker function
261
 */
262
function method(path: Array|string, ...args: any[]): Function;
263

264
/**
265
 * The opposite of `method`; this method creates a function that invokes
266
 * the method at a given path of `object`. Any additional arguments are
267
 * provided to the invoked method.
268
 * 
269
 * @param {Object} object The object to query
270
 * @param {...*} [args] The arguments to invoke the method with
271
 * @returns {Function} Returns the new invoker function
272
 */
273
function methodOf(object: Object, ...args: any[]): Function;
274
```
275

276
### Argument Functions
277

278
Create functions that work with function arguments.
279

280
```javascript { .api }
281
/**
282
 * Creates a function that gets the argument at index `n`. If `n` is negative,
283
 * the nth argument from the end is returned.
284
 * 
285
 * @param {number} [n=0] The index of the argument to return
286
 * @returns {Function} Returns the new pass-thru function
287
 */
288
function nthArg(n?: number): Function;
289
```
290

291
**Usage Examples:**
292

293
```javascript
294
import { nthArg } from "lodash";
295

296
const func = nthArg(1);
297
func('a', 'b', 'c', 'd'); // 'b'
298

299
const func2 = nthArg(-2);
300
func2('a', 'b', 'c', 'd'); // 'c'
301
```
302

303
### Unique ID Generation
304

305
Generate unique identifiers.
306

307
```javascript { .api }
308
/**
309
 * Generates a unique ID. If `prefix` is given, the ID is appended to it.
310
 * 
311
 * @param {string} [prefix=''] The value to prefix the ID with
312
 * @returns {string} Returns the unique ID
313
 */
314
function uniqueId(prefix?: string): string;
315
```
316

317
**Usage Examples:**
318

319
```javascript
320
import { uniqueId } from "lodash";
321

322
uniqueId('contact_'); // 'contact_104'
323
uniqueId(); // '105'
324
```
325

326
### Path Conversion
327

328
Convert values to property paths.
329

330
```javascript { .api }
331
/**
332
 * Converts `value` to a property path array.
333
 * 
334
 * @param {*} value The value to convert
335
 * @returns {Array} Returns the new property path array
336
 */
337
function toPath(value: any): Array;
338
```
339

340
**Usage Examples:**
341

342
```javascript
343
import { toPath } from "lodash";
344

345
toPath('a.b.c'); // ['a', 'b', 'c']
346
toPath('a[0].b.c'); // ['a', '0', 'b', 'c']
347
toPath(['a', 'b', 'c']); // ['a', 'b', 'c']
348
```
349

350
### Library Management
351

352
Manage the lodash library itself.
353

354
```javascript { .api }
355
/**
356
 * Reverts the `_` variable to its previous value and returns a reference to
357
 * the `lodash` function.
358
 * 
359
 * @returns {Function} Returns the `lodash` function
360
 */
361
function noConflict(): Function;
362

363
/**
364
 * Adds all own enumerable string keyed function properties of a source
365
 * object to the destination object. If `object` is a function, then methods
366
 * are added to its prototype as well.
367
 * 
368
 * @param {Function|Object} [object=lodash] The destination object
369
 * @param {Object} source The object of functions to add
370
 * @param {Object} [options] The options object
371
 * @returns {Function|Object} Returns `object`
372
 */
373
function mixin(object?: Function|Object, source?: Object, options?: Object): Function|Object;
374

375
/**
376
 * Creates a pristine `lodash` function using the `context` object.
377
 * 
378
 * @param {Object} [context=root] The context object
379
 * @returns {Function} Returns a new `lodash` function
380
 */
381
function runInContext(context?: Object): Function;
382
```
383

384
### Iteratee Creation
385

386
Create iteratee functions for use with collection methods.
387

388
```javascript { .api }
389
/**
390
 * Creates a function that invokes `func` with the arguments of the created
391
 * function. If `func` is a property name, the created function returns the
392
 * property value for a given element. If `func` is an array or object, the
393
 * created function returns `true` for elements that contain the equivalent
394
 * source properties, otherwise it returns `false`.
395
 * 
396
 * @param {*} [func=_.identity] The value to convert to a callback
397
 * @returns {Function} Returns the callback
398
 */
399
function iteratee(func?: any): Function;
400
```
401

402
### Conformance Testing
403

404
Create functions that test if values conform to schemas.
405

406
```javascript { .api }
407
/**
408
 * Creates a function that iterates over `pairs` and invokes the corresponding
409
 * function of the first predicate to return truthy. The predicate-function
410
 * pairs are invoked with the `this` binding and arguments of the created function.
411
 * 
412
 * @param {Array} pairs The predicate-function pairs
413
 * @returns {Function} Returns the new composite function
414
 */
415
function cond(pairs: Array): Function;
416

417
/**
418
 * Creates a function that invokes the predicate properties of `source` with
419
 * the corresponding property values of a given object, returning `true` if
420
 * all predicates return truthy, else `false`.
421
 * 
422
 * @param {Object} source The object of property predicates to conform to
423
 * @returns {Function} Returns the new spec function
424
 */
425
function conforms(source: Object): Function;
426
```
427

428
### Error Handling
429

430
Safely attempt function execution.
431

432
```javascript { .api }
433
/**
434
 * Attempts to invoke `func`, returning either the result or the caught error
435
 * object. Any additional arguments are provided to `func` when it's invoked.
436
 * 
437
 * @param {Function} func The function to attempt
438
 * @param {...*} [args] The arguments to invoke `func` with
439
 * @returns {*} Returns the `func` result or error object
440
 */
441
function attempt(func: Function, ...args: any[]): any;
442
```
443

444
**Usage Examples:**
445

446
```javascript
447
import { attempt } from "lodash";
448

449
// Successful execution
450
attempt(function(x) {
451
  return x / 2;
452
}, 6); // 3
453

454
// Error handling
455
attempt(function() {
456
  throw new Error('Something went wrong');
457
}); // Error: Something went wrong
458

459
// Useful for safely parsing JSON
460
attempt(JSON.parse, '{"a": 1}'); // { a: 1 }
461
attempt(JSON.parse, '{invalid json}'); // SyntaxError: Unexpected token...
462
```
463

464
### Method Chaining
465

466
Core utility for creating method chains.
467

468
```javascript { .api }
469
/**
470
 * Creates a lodash wrapper instance that wraps `value` with explicit method chain sequences enabled.
471
 * 
472
 * @param {*} value The value to wrap
473
 * @returns {Object} Returns the new lodash wrapper instance
474
 */
475
function chain(value: any): Object;
476
```
477

478
### Time Utilities
479

480
Utilities for working with time.
481

482
```javascript { .api }
483
/**
484
 * Gets the timestamp of the number of milliseconds that have elapsed since
485
 * the Unix epoch (1 January 1970 00:00:00 UTC).
486
 * 
487
 * @returns {number} Returns the timestamp
488
 */
489
function now(): number;
490
```