0
# lodash.find
1

2
lodash.find is a standalone module that provides the `_.find` utility function from the lodash library. It iterates over elements of a collection and returns the first element for which the predicate returns truthy, supporting multiple predicate styles including functions, property names, property-value pairs, and object matchers.
3

4
## Package Information
5

6
- **Package Name**: lodash.find
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.find`
10

11
## Core Imports
12

13
```javascript
14
var find = require('lodash.find');
15
```
16

17
For ES6/ESM environments:
18

19
```javascript
20
import find from 'lodash.find';
21
```
22

23
## Basic Usage
24

25
```javascript
26
var find = require('lodash.find');
27

28
var users = [
29
  { 'user': 'barney',  'age': 36, 'active': true },
30
  { 'user': 'fred',    'age': 40, 'active': false },
31
  { 'user': 'pebbles', 'age': 1,  'active': true }
32
];
33

34
// Using function predicate
35
var result = find(users, function(chr) {
36
  return chr.age < 40;
37
});
38
// => { 'user': 'barney', 'age': 36, 'active': true }
39

40
// Using object matcher (_.matches style)
41
var result = find(users, { 'age': 1, 'active': true });
42
// => { 'user': 'pebbles', 'age': 1, 'active': true }
43

44
// Using property-value matcher (_.matchesProperty style)
45
var result = find(users, 'active', false);
46
// => { 'user': 'fred', 'age': 40, 'active': false }
47

48
// Using property accessor (_.property style)
49
var result = find(users, 'active');
50
// => { 'user': 'barney', 'age': 36, 'active': true }
51
```
52

53
## Capabilities
54

55
### Find Function
56

57
Iterates over elements of a collection, returning the first element for which the predicate returns truthy. Also available as `detect` (alias).
58

59
```javascript { .api }
60
/**
61
 * Iterates over elements of collection, returning the first element
62
 * predicate returns truthy for. The predicate is bound to thisArg and
63
 * invoked with three arguments: (value, index|key, collection).
64
 *
65
 * @param {Array|Object|string} collection The collection to search.
66
 * @param {Function|Object|string} [predicate=_.identity] The function invoked per iteration.
67
 * @param {*} [thisArg] The this binding of predicate.
68
 * @returns {*} Returns the matched element, else undefined.
69
 */
70
function find(collection, predicate, thisArg);
71
```
72

73
### Predicate Types
74

75
The `find` function supports four different predicate styles:
76

77
#### Function Predicate
78
When `predicate` is a function, it's invoked with three arguments: `(value, index|key, collection)`.
79

80
```javascript
81
find(collection, function(value, index, collection) {
82
  // return true for the first matching element
83
  return someCondition;
84
});
85
```
86

87
#### Object Matcher (_.matches style)
88
When `predicate` is an object, it creates a `_.matches` style callback that returns `true` for elements that have the properties of the given object.
89

90
```javascript
91
find(users, { 'age': 36, 'active': true });
92
// Finds first user with age=36 AND active=true
93
```
94

95
#### Property-Value Matcher (_.matchesProperty style)
96
When both `predicate` and `thisArg` are provided as non-function values, it creates a `_.matchesProperty` style callback.
97

98
```javascript
99
find(users, 'active', false);
100
// Finds first user where active property equals false
101
```
102

103
#### Property Accessor (_.property style)
104
When `predicate` is a string, it creates a `_.property` style callback that returns the property value.
105

106
```javascript
107
find(users, 'active');
108
// Finds first user where active property is truthy
109
```
110

111
### Collection Types
112

113
The function works with multiple collection types:
114

115
- **Arrays**: Uses optimized array iteration with index-based searching
116
- **Objects**: Uses object property iteration 
117
- **Strings**: Iterates over string characters
118
- **Array-like objects**: Works with arguments objects, NodeLists, etc.
119

120
### Performance Characteristics
121

122
- For arrays: Uses `baseFindIndex` for optimized index-based searching
123
- For objects: Uses `baseFind` with `baseEach` for property iteration
124
- Returns immediately upon finding the first match (short-circuit evaluation)
125
- Returns `undefined` if no matching element is found
126

127
### Error Handling
128

129
The function is designed to handle edge cases gracefully:
130

131
- Returns `undefined` for empty collections
132
- Returns `undefined` if no element matches the predicate
133
- Handles `null` or `undefined` collection by returning `undefined`
134
- Supports sparse arrays and objects with missing properties
135

136
## Usage Examples
137

138
### Array Search
139

140
```javascript
141
var numbers = [1, 2, 3, 4, 5];
142

143
// Find first even number
144
var even = find(numbers, function(n) { return n % 2 === 0; });
145
// => 2
146

147
// Find number greater than 3
148
var large = find(numbers, function(n) { return n > 3; });
149
// => 4
150
```
151

152
### Object Search
153

154
```javascript
155
var inventory = {
156
  'apple': { price: 1.50, inStock: true },
157
  'banana': { price: 0.75, inStock: false },
158
  'orange': { price: 2.00, inStock: true }
159
};
160

161
// Find first in-stock item
162
var available = find(inventory, function(item) { 
163
  return item.inStock; 
164
});
165
// => { price: 1.50, inStock: true }
166
```
167

168
### Complex Object Matching
169

170
```javascript
171
var products = [
172
  { id: 1, name: 'Laptop', category: 'electronics', price: 999 },
173
  { id: 2, name: 'Book', category: 'books', price: 29 },
174
  { id: 3, name: 'Phone', category: 'electronics', price: 699 }
175
];
176

177
// Using object matcher
178
var electronics = find(products, { category: 'electronics' });
179
// => { id: 1, name: 'Laptop', category: 'electronics', price: 999 }
180

181
// Using property-value matcher
182
var book = find(products, 'category', 'books');
183
// => { id: 2, name: 'Book', category: 'books', price: 29 }
184
```
185

186
## Alternative Usage Patterns
187

188
### With thisArg Binding
189

190
```javascript
191
var context = { threshold: 100 };
192

193
var items = [50, 150, 75, 200];
194

195
var result = find(items, function(value) {
196
  return value > this.threshold;
197
}, context);
198
// => 150
199
```
200

201
### Nested Property Access
202

203
```javascript
204
var data = [
205
  { user: { profile: { active: false } } },
206
  { user: { profile: { active: true } } }
207
];
208

209
// Find using nested property path (requires custom function)
210
var active = find(data, function(item) {
211
  return item.user && item.user.profile && item.user.profile.active;
212
});
213
```