Skip to main content

findBest()

findBest<T, Criterion>(array, iteratee, compareFn): T | undefined

Finds the element that produces the extreme value according to a comparator.

💎 Why is this a Hidden Gem?

Finds the best item without sorting. Instead of sort()[0] (O(n log n)) or complex reduces, get the min/max/best item in O(n). Perfect for finding cheapest products, nearest locations, or highest-rated items with custom comparison logic.

Type Parameters​

T: T​

The type of elements in the array.

Criterion: Criterion​

The type of the comparison criterion.

Parameters​

array: readonly T[]​

The array to search.

iteratee: (value) => Criterion​

A function that returns the comparison value for each element.

compareFn: (a, b) => boolean​

Returns true if the first criterion should replace the current extreme.

Returns: T | undefined​

The element with the extreme value, or undefined if array is empty.

Since​

2.0.0

Performance​

O(n) time, O(1) space, uses for loop with early return for empty arrays.

Also known as​

boil (Radashi) · ❌ (Lodash, es-toolkit, Remeda, Ramda, Effect, Modern Dash, Antfu)

Example​

findBest(
  [{ name: 'John', age: 25 }, { name: 'Bob', age: 20 }],
  (u) => u.age,
  (a, b) => a < b
);
// => { name: 'Bob', age: 20 }

findBest(['hi', 'hello', 'hey'], (s) => s.length, (a, b) => a > b);
// => 'hello'

How it works?​

Generic extremum finder — finds the element that produces the best value according to a custom comparator.

How comparator works​

ComparatorFindsExample
(a, b) => a < bMinimumYoungest user
(a, b) => a > bMaximumOldest user

Use Cases​

Find best match with custom criteria 📌​

Select the optimal item from a collection based on any comparable property. Perfect for finding the cheapest product, nearest location, or highest-rated item.

const products = [
  { name: "Laptop", price: 999, rating: 4.5 },
  { name: "Phone", price: 699, rating: 4.8 },
  { name: "Tablet", price: 449, rating: 4.2 },
];

const cheapest = findBest(
  products,
  (p) => p.price,
  (a, b) => a < b
);
// => { name: "Tablet", price: 449, rating: 4.2 }

const bestRated = findBest(
  products,
  (p) => p.rating,
  (a, b) => a > b
);
// => { name: "Phone", price: 699, rating: 4.8 }

Find nearest or furthest element​

Locate items closest to or furthest from a reference point. Essential for geolocation, scheduling, or any proximity-based searches.

const events = [
  { name: "Meeting", date: new Date("2025-01-15") },
  { name: "Conference", date: new Date("2025-01-05") },
  { name: "Workshop", date: new Date("2025-01-22") },
];

const now = new Date("2025-01-10");

const nextEvent = findBest(
  events.filter((e) => e.date > now),
  (e) => e.date.getTime(),
  (a, b) => a < b
);
// => { name: "Meeting", date: 2025-01-15 }

Priority-based selection with complex rules​

Select items using multi-factor comparisons or business-specific logic. Ideal for task scheduling, resource allocation, or weighted scoring systems.

const tasks = [
  { name: "Bug fix", priority: 2, deadline: 1 },
  { name: "Feature", priority: 1, deadline: 3 },
  { name: "Refactor", priority: 3, deadline: 2 },
];

// Custom logic: lower priority number wins, then earlier deadline
const mostUrgent = findBest(
  tasks,
  (t) => t,
  (a, b) =>
    a.priority < b.priority ||
    (a.priority === b.priority && a.deadline < b.deadline)
);
// => { name: "Feature", priority: 1, deadline: 3 }

Find best matching organ donor for transplant​

Find the most compatible organ donor from a pool of candidates. Critical for transplant coordination systems optimizing patient outcomes.

type DonorMatch = {
  donorId: string;
  bloodType: string;
  hlaMatch: number;      // 0-6 antigens matched
  distance: number;       // km from recipient hospital
  organQuality: number;   // 1-10 scale
  waitTime: number;       // days recipient has waited
};

const potentialDonors: DonorMatch[] = [
  { donorId: "D001", bloodType: "O-", hlaMatch: 5, distance: 120, organQuality: 9, waitTime: 450 },
  { donorId: "D002", bloodType: "O-", hlaMatch: 6, distance: 350, organQuality: 8, waitTime: 450 },
  { donorId: "D003", bloodType: "O-", hlaMatch: 4, distance: 80, organQuality: 10, waitTime: 450 },
];

// Complex matching: prioritize HLA match, then quality, then proximity
const bestMatch = findBest(
  potentialDonors,
  (d) => d,
  (a, b) => {
    // Higher HLA match wins
    if (a.hlaMatch !== b.hlaMatch) return a.hlaMatch > b.hlaMatch;
    // Then higher organ quality
    if (a.organQuality !== b.organQuality) return a.organQuality > b.organQuality;
    // Then shorter distance
    return a.distance < b.distance;
  }
);

console.log(`Best match: ${bestMatch?.donorId} (HLA: ${bestMatch?.hlaMatch}/6)`);
// => Best match: D002 (HLA: 6/6)