or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Lodash Find

The find method from Lodash iterates over elements of a collection, returning the first element that a predicate function returns truthy for. It supports multiple predicate formats including functions, objects, arrays, and strings, providing flexible and powerful search capabilities for both arrays and objects.

Note: This Knowledge Tile provides comprehensive documentation specifically for Lodash's find method. It is a focused, single-method tile rather than complete Lodash package documentation.

Package Information

Package Name: lodash
Package Type: npm
Language: JavaScript
Installation: npm install lodash

Core Imports

import _ from "lodash";
// Use as _.find()

For CommonJS:

const _ = require("lodash");
// Use as _.find()

With modern bundlers and tree-shaking:

// Option 1: Use lodash-es for better tree-shaking
import { find } from "lodash-es";

// Option 2: Direct import from specific module (if available)
import find from "lodash/find";

// Note: Tree-shaking with lodash requires lodash-es or modular imports

Basic Usage

import _ from "lodash";

const users = [
  { user: 'barney', age: 36, active: true },
  { user: 'fred', age: 40, active: false },
  { user: 'pebbles', age: 1, active: true }
];

// Find using a function predicate
const youngUser = _.find(users, function(o) { return o.age < 40; });
// => { user: 'barney', age: 36, active: true }

// Find using object properties
const child = _.find(users, { age: 1, active: true });
// => { user: 'pebbles', age: 1, active: true }

// Find using property-value pair
const inactiveUser = _.find(users, ['active', false]);
// => { user: 'fred', age: 40, active: false }

// Find using property name
const activeUser = _.find(users, 'active');
// => { user: 'barney', age: 36, active: true }

Architecture

The find method is part of Lodash's collection iteration system with several key architectural features:

Shortcut Fusion: When used in method chains, find can terminate early without processing the entire collection, providing significant performance benefits
Lazy Evaluation: In chained operations, transformations are applied on-demand as find iterates, not to the entire collection upfront
Iteratee Integration: Uses Lodash's internal _.iteratee system for predicate normalization, allowing flexible predicate formats
Optimized Implementation: Different code paths for arrays vs objects to maximize performance

Capabilities

Find Function

Iterates over elements of collection, returning the first element predicate returns truthy for.

/**
 * Iterates over elements of collection, returning the first element
 * predicate returns truthy for. The predicate is invoked with three arguments:
 * (value, index|key, collection).
 * 
 * @param {Array|Object} collection - The collection to search
 * @param {Function|Object|Array|string} [predicate=_.identity] - The function invoked per iteration.
 *   - Function: Receives (value, index|key, collection) and returns boolean
 *   - Object: Uses _.matches for deep property matching
 *   - Array: Uses _.matchesProperty for [property, value] pair matching  
 *   - String: Uses _.property for truthy property checking
 * @returns {*} Returns the matched element, else undefined
 */
function find(collection, predicate);

Parameters:

collection (Array|Object): The collection to search
predicate (Function|Object|Array|string) [optional, defaults to _.identity]: The function invoked per iteration

Predicate Format Options:

Function: function(value, index|key, collection) => boolean
- Receives three arguments: the current value, its index/key, and the collection
- Returns true for elements that should be selected
Object: { property: value, ... }
- Matches elements that have all specified properties with matching values
- Uses strict equality (===) for value comparison
Array: [property, value]
- Matches elements where the specified property equals the given value
- Shorthand for property-value pair matching
String: "property"
- Matches elements where the specified property is truthy
- Equivalent to function(o) { return !!o[property]; }

Returns:

*: The first matched element, or undefined if no match is found

Behavior:

Stops iteration immediately when the first match is found
Works with both arrays and objects
For arrays, iterates by index in ascending order
For objects, iterates over own enumerable properties
Returns undefined if no element matches the predicate
Uses Lodash's internal iteratee system for predicate normalization

Usage Examples:

import _ from "lodash";

// Array of objects
const employees = [
  { name: 'Alice', department: 'Engineering', salary: 75000 },
  { name: 'Bob', department: 'Sales', salary: 60000 },
  { name: 'Charlie', department: 'Engineering', salary: 80000 }
];

// Function predicate with custom logic
const highEarner = _.find(employees, function(employee) {
  return employee.salary > 70000;
});
// => { name: 'Alice', department: 'Engineering', salary: 75000 }

// Object predicate for exact match
const salesPerson = _.find(employees, { department: 'Sales' });
// => { name: 'Bob', department: 'Sales', salary: 60000 }

// Array predicate for property-value pair
const charlie = _.find(employees, ['name', 'Charlie']);
// => { name: 'Charlie', department: 'Engineering', salary: 80000 }

// String predicate for truthy property
const products = [
  { name: 'Laptop', featured: false },
  { name: 'Phone', featured: true },
  { name: 'Tablet' }
];

const featuredProduct = _.find(products, 'featured');
// => { name: 'Phone', featured: true }

// Working with plain arrays
const numbers = [1, 2, 3, 4, 5];
const evenNumber = _.find(numbers, function(n) { return n % 2 === 0; });
// => 2

// Working with objects (not arrays)
const userRoles = {
  admin: { permissions: ['read', 'write', 'delete'] },
  editor: { permissions: ['read', 'write'] },
  viewer: { permissions: ['read'] }
};

const writeUser = _.find(userRoles, function(role) {
  return role.permissions.includes('write');
});
// => { permissions: ['read', 'write', 'delete'] }

// No match found
const notFound = _.find(employees, { department: 'Marketing' });
// => undefined

// Chaining with lazy evaluation and shortcut fusion
const largeDataset = _.range(1, 10000);
const result = _(largeDataset)
  .map(n => n * n)           // Only applied to elements until first match
  .filter(n => n > 100)      // Only applied to elements until first match  
  .find(n => n % 7 === 0);   // Stops at first match: 121 (11²)
// => 121
// Note: Only processes ~11 elements instead of all 10,000

Performance Characteristics:

Time complexity: O(n) in worst case, where n is the collection size
Space complexity: O(1)
Stops at first match for optimal performance
Array iteration is index-based for better performance than object iteration
Shortcut Fusion: In method chains, only processes elements until first match, potentially avoiding expensive transformations on the rest of the collection

Integration with Lodash Ecosystem:

Uses _.iteratee internally for predicate processing, enabling the flexible predicate formats
Supports lazy evaluation when used in _(collection).chain() sequences
Optimizes performance through early termination in chained operations

Error Handling:

Does not throw errors for invalid predicates
Returns undefined for non-collection inputs
Gracefully handles null/undefined collection parameters