0
# Utility Functions
1

2
General utility functions for common programming patterns including identity, constant functions, flow control, and stub functions.
3

4
## Capabilities
5

6
### Basic Utilities
7

8
```javascript { .api }
9
/**
10
 * Returns the first argument it receives
11
 * @param {*} value - Any value
12
 * @returns {*} Returns value
13
 */
14
function identity(value);
15

16
/**
17
 * Creates a function that returns value
18
 * @param {*} value - The value to return from the new function
19
 * @returns {Function} Returns the new constant function
20
 */
21
function constant(value);
22

23
/**
24
 * A method that returns undefined
25
 * @returns {undefined} Returns undefined
26
 */
27
function noop();
28

29
/**
30
 * Generates a unique ID
31
 * @param {string} prefix - The value to prefix the ID with
32
 * @returns {string} Returns the unique ID
33
 */
34
function uniqueId(prefix);
35
```
36

37
### Range Generation
38

39
```javascript { .api }
40
/**
41
 * Creates an array of numbers progressing from start up to, but not including, end
42
 * @param {number} start - The start of the range
43
 * @param {number} end - The end of the range
44
 * @param {number} step - The value to increment or decrement by
45
 * @returns {Array} Returns the range of numbers
46
 */
47
function range(start, end, step);
48

49
/**
50
 * Like range but populates the array in descending order
51
 * @param {number} start - The start of the range
52
 * @param {number} end - The end of the range
53
 * @param {number} step - The value to increment or decrement by
54
 * @returns {Array} Returns the range of numbers
55
 */
56
function rangeRight(start, end, step);
57
```
58

59
### Iteration Utilities
60

61
```javascript { .api }
62
/**
63
 * Invokes the iteratee n times, returning an array of the results
64
 * @param {number} n - The number of times to invoke iteratee
65
 * @param {Function} iteratee - The function invoked per iteration
66
 * @returns {Array} Returns the array of results
67
 */
68
function times(n, iteratee);
69
```
70

71
### Stub Functions
72

73
```javascript { .api }
74
/**
75
 * A method that returns a new empty array
76
 * @returns {Array} Returns the new empty array
77
 */
78
function stubArray();
79

80
/**
81
 * A method that returns false
82
 * @returns {boolean} Returns false
83
 */
84
function stubFalse();
85

86
/**
87
 * A method that returns a new empty object
88
 * @returns {Object} Returns the new empty object
89
 */
90
function stubObject();
91

92
/**
93
 * A method that returns an empty string
94
 * @returns {string} Returns the empty string
95
 */
96
function stubString();
97

98
/**
99
 * A method that returns true
100
 * @returns {boolean} Returns true
101
 */
102
function stubTrue();
103
```
104

105
### Error Handling and Defaults
106

107
```javascript { .api }
108
/**
109
 * Attempts to invoke func, returning either the result or the caught error object
110
 * @param {Function} func - The function to attempt
111
 * @param {...*} args - The arguments to invoke func with
112
 * @returns {*} Returns the func result or error object
113
 */
114
function attempt(func, ...args);
115

116
/**
117
 * Returns defaultValue if value is NaN, null, or undefined
118
 * @param {*} value - The value to check
119
 * @param {*} defaultValue - The default value
120
 * @returns {*} Returns the resolved value
121
 */
122
function defaultTo(value, defaultValue);
123
```
124

125
### Function Creation Utilities
126

127
```javascript { .api }
128
/**
129
 * Creates a function that invokes func with arguments converted to iteratee
130
 * @param {*} func - The value to convert to a callback
131
 * @returns {Function} Returns the callback
132
 */
133
function iteratee(func);
134

135
/**
136
 * Creates a function that performs a partial deep comparison between a source object
137
 * @param {Object} source - The object of property values to match
138
 * @returns {Function} Returns the new spec function
139
 */
140
function matches(source);
141

142
/**
143
 * Creates a function that performs a partial deep comparison between the value at path and srcValue
144
 * @param {Array|string} path - The path of the property to get
145
 * @param {*} srcValue - The value to match
146
 * @returns {Function} Returns the new spec function
147
 */
148
function matchesProperty(path, srcValue);
149

150
/**
151
 * Creates a function that returns the argument at index n
152
 * @param {number} n - The index of the argument to return
153
 * @returns {Function} Returns the new pass-thru function
154
 */
155
function nthArg(n);
156

157
/**
158
 * Creates a function that returns the value at path of a given object
159
 * @param {Array|string} path - The path of the property to get
160
 * @returns {Function} Returns the new accessor function
161
 */
162
function property(path);
163

164
/**
165
 * Creates a function that returns the value at path of object
166
 * @param {Object} object - The object to query
167
 * @returns {Function} Returns the new accessor function
168
 */
169
function propertyOf(object);
170
```
171

172
## Usage Examples
173

174
```javascript
175
import { 
176
  identity, constant, range, times, uniqueId,
177
  attempt, defaultTo, matches, property, nthArg
178
} from "lodash-es";
179

180
// Identity function (useful as default iteratee)
181
console.log([1, 2, 3].map(identity)); // [1, 2, 3]
182

183
// Constant function
184
const getTrue = constant(true);
185
console.log(getTrue()); // true
186
console.log([1, 2, 3].map(getTrue)); // [true, true, true]
187

188
// Generate ranges
189
console.log(range(4)); // [0, 1, 2, 3]
190
console.log(range(1, 5)); // [1, 2, 3, 4]
191
console.log(range(0, 20, 5)); // [0, 5, 10, 15]
192

193
// Generate arrays with times
194
const squares = times(5, n => n * n); // [0, 1, 4, 9, 16]
195

196
// Generate unique IDs
197
console.log(uniqueId()); // '1'
198
console.log(uniqueId('contact_')); // 'contact_2'
199
console.log(uniqueId('user_')); // 'user_3'
200

201
// Safe function execution
202
const result = attempt(JSON.parse, '{"valid": true}');
203
console.log(result); // { valid: true }
204

205
const errorResult = attempt(JSON.parse, 'invalid json');
206
console.log(errorResult); // Error object
207

208
// Default values
209
console.log(defaultTo(undefined, 'default')); // 'default'
210
console.log(defaultTo(null, 'default')); // 'default'
211
console.log(defaultTo('value', 'default')); // 'value'
212

213
// Create predicate functions
214
const users = [
215
  { name: 'Alice', age: 25, active: true },
216
  { name: 'Bob', age: 30, active: false }
217
];
218

219
const isActive = matches({ active: true });
220
console.log(users.filter(isActive)); // [{ name: 'Alice', age: 25, active: true }]
221

222
// Property accessor functions
223
const getName = property('name');
224
console.log(users.map(getName)); // ['Alice', 'Bob']
225

226
// Get nth argument
227
const getSecond = nthArg(1);
228
console.log(getSecond('a', 'b', 'c')); // 'b'
229
```