Lodash Includes

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.

Package Information

• Package Name: lodash.includes
• Package Type: npm
• Language: JavaScript
• Installation: npm install lodash.includes

Core Imports

// ES modules (default export)
import includes from 'lodash.includes';

For CommonJS:

const includes = require('lodash.includes');

Basic Usage

import includes from 'lodash.includes';

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

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

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

// Search with starting index
includes([1, 2, 3], 1, 2);
// => false (starts searching from index 2)

Capabilities

Collection Value Search

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

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

Supported Collection Types:

• Arrays: Searches through array elements
• Objects: Searches through object values (not keys)
• Strings: Performs substring search
• Arguments objects: Treats as array-like objects

Search Behavior:

• Uses SameValueZero equality comparison (ECMAScript specification)
  • Matches NaN with NaN
  • Matches -0 with 0
  • No type coercion (strict equality for most cases)
• For strings, performs substring search using native indexOf
• For objects, converts to values array and searches through values
• For array-like objects, searches through indexed elements

fromIndex Parameter:

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

Usage Examples:

// Basic array search
includes([1, 2, 3], 1);
// => true

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

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

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

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

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

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

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

// String search (substring)
includes('hello world', 'world');
// => true

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

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

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

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

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

// Empty collections
includes([], 1);
// => false

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

includes('', 'a');
// => false

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

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

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

// Method chaining (if using full lodash)
// _(collection).includes(value)

Error Handling

The includes function is designed to handle edge cases gracefully:

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

Performance Characteristics

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

Common Use Cases

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