Find

Array find utility

Install

Install with npm directly from the github repository

npm install jeromedecoster/find

Install from a package.json file

{
  "dependencies": {
    "find": "jeromedecoster/find"
  }
}

API

find(array, fn, [options])

Find with a function

var users = [
  { name: 'Tobi', age: 2, species: 'ferret' },
  { name: 'Jane', age: 6, species: 'ferret' },
  { name: 'Luna', age: 2, species: 'cat' },
  { name: 'Jane', age: 4, species: 'dog' }
]

find(users, function(e) { return e.name == 'Jane' && e.age < 5 })
// => { name: 'Jane', age: 4, species: 'dog' }

find(array, obj, [options])

Find with object value matching

var users = [
  { name: 'Tobi', age: 2, species: 'ferret', admin: false },
  { name: 'Jane', age: 6, species: 'ferret', admin: true },
  { name: 'Luna', age: 2, species: 'cat',    awesome: { cat: false }},
  { name: 'Jane', age: 4, species: 'dog',    awesome: { cat: true } }
]

find(users, { name: 'Jane', age: 4 })
// => { name: 'Jane', age: 4, species: 'dog', awesome: { cat: true } }

find(users, { awesome: { cat: false } })
// => { name: 'Luna', age: 2, species: 'cat', awesome: { cat: false } }

find(users, { name: 'Jane', age: 1 })
// => undefined

Options

{all: true}

Return all matches instead of the first one

var users = [
  { name: 'Tobi', age: 2, species: 'ferret' },
  { name: 'Jane', age: 6, species: 'ferret' },
  { name: 'Luna', age: 2, species: 'cat' },
  { name: 'Jane', age: 4, species: 'dog' }
]

find(users, { name: 'Jane' }, { all: true })
// => [ { name: 'Jane', age: 6, species: 'ferret' },
//      { name: 'Jane', age: 4, species: 'dog' } ]

find(users, { name: 'John' }, { all: true })
// => undefined

{index: true}

Return the index instead of the value

var users = [
  { name: 'Tobi', age: 2, species: 'ferret' },
  { name: 'Jane', age: 6, species: 'ferret' },
  { name: 'Luna', age: 2, species: 'cat' },
  { name: 'Jane', age: 4, species: 'dog' }
]

find(users, { name: 'Luna' }, { index: true })
// => 2

find(users, { name: 'John' }, { index: true })
// => undefined

find(users, { name: 'Jane' }, { index: true, all: true })
// => [ 1, 3 ]

{last: true}

Return the last match instead of the first one

var users = [
  { name: 'Tobi', age: 2, species: 'ferret' },
  { name: 'Jane', age: 6, species: 'ferret' },
  { name: 'Luna', age: 2, species: 'cat' },
  { name: 'Jane', age: 4, species: 'dog' }
]

find(users, { name: 'Jane' }, { last: true })
// => { name: 'Jane', age: 4, species: 'dog' }

find(users, { name: 'Jane' }, { last: true, all: true, index: true })
// => [3]

{from: integer}

Start search from the specified index

var users = [
  { name: 'Tobi', age: 2, species: 'ferret' },
  { name: 'Jane', age: 6, species: 'ferret' },
  { name: 'Luna', age: 2, species: 'cat' },
  { name: 'Jane', age: 4, species: 'dog' }
]

find(users, { name: 'Jane' }, { from: 2 })
// => { name: 'Jane', age: 4, species: 'dog' }

{assign: obj}

Extend each match with obj

var users = [
  { name: 'Tobi', age: 2, species: 'ferret' },
  { name: 'Jane', age: 6, species: 'ferret' },
  { name: 'Luna', age: 2, species: 'cat' },
  { name: 'Jane', age: 4, species: 'dog' }
]

find(users, { name: 'Jane' }, { assign: { age: 7, ok: true } })
// => { name: 'Jane', age: 7, species: 'ferret', ok: true }

{map: fn}

Apply map function on each match

var users = [
  { name: 'Tobi', age: 2, species: 'ferret' },
  { name: 'Jane', age: 6, species: 'ferret' },
  { name: 'Luna', age: 2, species: 'cat' },
  { name: 'Jane', age: 4, species: 'dog' }
]

find(users, { name: 'Jane' }, { map: function(e, i) {
  e.age++
  e.index = i
  return e
}})
// => { name: 'Jane', age: 7, species: 'ferret', index: 1 }

Tests

Successfully tested on

Browser	Versions
IE	9 ... 11
Chrome	39 ... 45
Firefox	35 ... 41
Safari	5 ... 8
iPhone	6.0 ... 9.0
Android	4.0 ... 5.1

Thanks

Mainly forked / inspired by find and partial-compare