0
# Lodash Includes
1

2
Lodash Includes is a modular lodash package that exports the `_.includes` method for checking if a value is found in a collection. It provides a unified interface for searching arrays, objects, strings, and arguments objects using SameValueZero equality comparison.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
// ES modules (default export)
15
import includes from 'lodash.includes';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const includes = require('lodash.includes');
22
```
23

24
## Basic Usage
25

26
```javascript
27
import includes from 'lodash.includes';
28

29
// Search in arrays
30
includes([1, 2, 3], 2);
31
// => true
32

33
// Search in objects (searches values, not keys)
34
includes({ 'user': 'fred', 'age': 40 }, 'fred');
35
// => true
36

37
// Search in strings (substring search)
38
includes('pebbles', 'eb');
39
// => true
40

41
// Search with starting index
42
includes([1, 2, 3], 1, 2);
43
// => false (starts searching from index 2)
44
```
45

46
## Capabilities
47

48
### Collection Value Search
49

50
Checks if a value is found in a collection using SameValueZero equality comparison.
51

52
```javascript { .api }
53
/**
54
 * Checks if value is in collection. This method supports arrays, objects, 
55
 * strings, and arguments objects. Uses SameValueZero for equality comparisons.
56
 * 
57
 * @param {Array|Object|string} collection - The collection to inspect
58
 * @param {*} value - The value to search for
59
 * @param {number} [fromIndex=0] - The index to search from
60
 * @param {*} [guard] - Enables use as iteratee for methods like `_.reduce` (internal parameter)
61
 * @returns {boolean} Returns `true` if value is found, else `false`
62
 */
63
function includes(collection, value, fromIndex, guard);
64
```
65

66
**Supported Collection Types:**
67

68
- **Arrays**: Searches through array elements
69
- **Objects**: Searches through object values (not keys)
70
- **Strings**: Performs substring search
71
- **Arguments objects**: Treats as array-like objects
72

73
**Search Behavior:**
74

75
- Uses SameValueZero equality comparison ([ECMAScript specification](http://ecma-international.org/ecma-262/6.0/#sec-samevaluezero))
76
  - Matches `NaN` with `NaN` 
77
  - Matches `-0` with `0`
78
  - No type coercion (strict equality for most cases)
79
- For strings, performs substring search using native `indexOf`
80
- For objects, converts to values array and searches through values
81
- For array-like objects, searches through indexed elements
82

83
**fromIndex Parameter:**
84

85
- **Positive values**: Start searching from that index
86
- **Negative values**: Start searching from end of collection (calculated as `length + fromIndex`)
87
- **Out of bounds**: Values >= length return `false` (except empty string in strings)
88
- **Non-integer values**: Coerced to integers using floor operation
89
- **Falsy values**: Treated as `0`
90

91
**Usage Examples:**
92

93
```javascript
94
// Basic array search
95
includes([1, 2, 3], 1);
96
// => true
97

98
includes([1, 2, 3], 4);
99
// => false
100

101
// Search with fromIndex
102
includes([1, 2, 3, 1], 1, 2);
103
// => true (finds second occurrence)
104

105
includes([1, 2, 3], 1, 2);
106
// => false (starts from index 2)
107

108
// Negative fromIndex
109
includes([1, 2, 3], 3, -1);
110
// => true (starts from last element)
111

112
includes([1, 2, 3], 1, -2);
113
// => false (starts from second-to-last element)
114

115
// Object search (searches values)
116
includes({ 'a': 1, 'b': 2, 'c': 3 }, 2);
117
// => true
118

119
includes({ 'user': 'fred', 'age': 40 }, 'fred');
120
// => true
121

122
// String search (substring)
123
includes('hello world', 'world');
124
// => true
125

126
includes('hello', 'hi');
127
// => false
128

129
// String with fromIndex
130
includes('hello world', 'o', 5);
131
// => true (finds 'o' in 'world')
132

133
// Special equality cases
134
includes([1, NaN, 3], NaN);
135
// => true (matches NaN)
136

137
includes([-0], 0);
138
// => true (matches -0 with 0)
139

140
includes([0], -0);
141
// => true (matches 0 with -0)
142

143
// Empty collections
144
includes([], 1);
145
// => false
146

147
includes({}, 1);
148
// => false
149

150
includes('', 'a');
151
// => false
152

153
// Edge cases with fromIndex
154
includes([1, 2, 3], 1, 10);
155
// => false (fromIndex >= length)
156

157
includes([1, 2, 3], 1, -10);
158
// => true (negative fromIndex clamped to 0)
159

160
// As iteratee function
161
[1, 2, 3].every(x => includes([1, 2, 3, 4, 5], x));
162
// => true
163

164
// Method chaining (if using full lodash)
165
// _(collection).includes(value)
166
```
167

168
## Error Handling
169

170
The `includes` function is designed to handle edge cases gracefully:
171

172
- **Empty collections**: Always return `false`
173
- **Invalid fromIndex**: Non-integer values are coerced to integers
174
- **Out-of-bounds fromIndex**: Handled appropriately (returns `false` or starts from beginning/end)
175
- **Type coercion**: No automatic type coercion for values (uses SameValueZero equality)
176
- **Null/undefined collections**: Handled safely (converted to empty arrays for objects)
177

178
## Performance Characteristics
179

180
- **Arrays**: Uses optimized `baseIndexOf` for efficient searching
181
- **Strings**: Uses native `String.prototype.indexOf` for fast substring search
182
- **Objects**: Converts to values array first, then searches (less efficient for large objects)
183
- **fromIndex optimization**: Negative indices are calculated once and clamped appropriately
184

185
## Common Use Cases
186

187
1. **Array membership testing**: Check if an element exists in an array
188
2. **Object value searching**: Find if a value exists among object properties
189
3. **Substring detection**: Check if a string contains a substring
190
4. **Form validation**: Validate input against allowed values
191
5. **Data filtering**: Use as predicate function with other lodash methods
192
6. **Multi-type collection handling**: Unified API for different collection types