CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-lodash-find

Knowledge Tile focused on Lodash's find method - comprehensive documentation for collection searching with multiple predicate formats and performance optimizations.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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:

  1. 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

  2. Object: { property: value, ... }

    • Matches elements that have all specified properties with matching values
    • Uses strict equality (===) for value comparison

  3. Array: [property, value]

    • Matches elements where the specified property equals the given value
    • Shorthand for property-value pair matching

  4. 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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lodash.find@4.6.x
Publish Source
CLI
Badge
tessl/npm-lodash-find badge