How Lodash minBy Finds the Smallest Object

Lodash’s _.minBy method allows developers to find the minimum element in an array of complex data types, such as objects, by applying a custom criterion known as an iteratee. This article explains how _.minBy works internally, how the iteratee function or shorthand transforms data for comparison, and how to effectively use it in JavaScript applications to extract the smallest object from a collection.

Understanding the Iteratee in Lodash

When working with primitive values like numbers, determining the minimum value requires a simple sequential comparison. However, when an array contains objects, JavaScript cannot compare them directly. This is where _.minBy comes in.

The method accepts two primary arguments:

  1. collection: The array of items to iterate over.
  2. iteratee: The criterion used to compute the value used for comparison.

The iteratee acts as a transformer. It is invoked for each element in the array to produce a criterion value. Lodash then compares these generated criterion values to determine which original object represents the minimum.

How _.minBy Processes Objects Step-by-Step

When _.minBy(array, iteratee) is executed, Lodash performs the following steps:

  1. Initialization: Lodash sets up internal references to store the lowest computed value (computed) and the corresponding object (result).
  2. Iteration: It loops through each element in the array sequentially.
  3. Value Extraction: Lodash invokes the iteratee with the current element. The returned value is the metric used for comparison.
  4. Comparison: The newly computed value is compared against the currently stored minimum using standard relational operators (<). Lodash also handles edge cases such as NaN, null, and undefined to prevent unexpected evaluation failures.
  5. Updating the Candidate: If the current computed value is strictly less than the stored minimum (or if it is the first valid value evaluated), Lodash updates its state: the current object becomes the new result, and the computed value becomes the new computed.
  6. Return: Once the loop finishes, _.minBy returns the original object associated with the lowest criterion value, rather than returning the computed criterion itself.

Common Types of Iteratees

Lodash provides flexibility in how iteratees are defined, supporting functions, property paths, and property name shorthands.

1. Function Iteratee

You can pass a custom function that computes and returns the value to be compared:

const items = [
  { name: 'Item A', dimensions: { weight: 25 } },
  { name: 'Item B', dimensions: { weight: 10 } },
  { name: 'Item C', dimensions: { weight: 15 } }
];

const lightest = _.minBy(items, (item) => item.dimensions.weight);
// Result: { name: 'Item B', dimensions: { weight: 10 } }

2. String Iteratee (Property Shorthand)

If you are comparing a top-level or nested property, you can pass a string representing the property name or deep path:

const users = [
  { user: 'Alex', age: 34 },
  { user: 'Sam', age: 22 },
  { user: 'Taylor', age: 29 }
];

const youngest = _.minBy(users, 'age');
// Result: { user: 'Sam', age: 22 }

Using a nested path string:

const nestedUsers = [
  { user: 'Alex', stats: { score: 85 } },
  { user: 'Sam', stats: { score: 42 } }
];

const lowestScore = _.minBy(nestedUsers, 'stats.score');
// Result: { user: 'Sam', stats: { score: 42 } }

Important Behaviors and Edge Cases