find-closest

This module provides functions equivalent to Array.prototype.find and Array.prototype.findIndex, but for finding the closest value where an exact match may not exist.

Installation

npm install find-closest

Usage

Basic usage

The default behaviour is to compare numbers in an array to the target number provided. The closest match is returned:

import { findClosest, findClosestIndex } from 'find-closest'

findClosest([0, 10, 20, 30], 12)
// => 10

findClosestIndex([0, 10, 20, 30], 12)
// => 1

Mapping and filtering with filterMapFn

Mapping

An optional filterMapFn function can be passed to compare non-number values to the target:

const pets = [
  { name: 'Fluffy', age: 10 },
  { name: 'Biscuit', age: 6 },
  { name: 'Wilbur', age: 12 },
]

findClosest(pets, 7, ({ age }) => age)
// => { name: 'Biscuit', age: 6 }

Filtering

Additionally, returning false from this function omits the value:

const isGreaterThan10 = (n) => n > 10

findClosest([0, 10, 20, 30], 12)
// => 10

findClosest([0, 10, 20, 30], 12, isGreaterThan10)
// => 20

Mapping and filtering

The mapping and filtering can be performed by the same function:

const pets = [
  { name: 'Fluffy', age: 10 },
  { name: 'Biscuit', age: 6 },
  { name: 'Wilbur', age: 12 },
]

findClosest(pets, 7, ({ age }) => {
  if (age < 7) {
    return false
  }
  return age
})
// => { name: 'Fluffy', age: 10 }

Note that, unless all the values in the array are numbers, the filterMapFn cannot return true - attempting to do so will cause an error to be thrown.

context argument

filterMapFn also receives a second argument with context information, allowing the last example to be rewritten like this:

findClosest(pets, 7, (pet, context) => {
  if (pet.age < context.target) {
    return false
  }
  return pet.age
})

The context argument also has context.index and context.array properties.

Performance

The filterMapFn argument has potential performance gains over manually calling .map().filter() on the input array:

• Mapping and filtering happens in a single pass.
• The mapping is executed lazily. If a perfect match is found before reaching the end of the array, unnecessary calculations are avoided.