key-of
Returns the first key/index at which the specified value is located in a collection.
It’s like Array.prototype.indexOf()
except it works on Maps/Objects/etc.
Installation
Requires Node.js 8.3.0 or above.
npm i key-of
API
The module exports a keyOf()
function that has one other function attached to it as a method: keyOf.any()
.
keyOf()
Parameters
- Bindable:
collection
(Array, Iterator, Object, Map, Set, string, or Typed Array) valueToFind
(any): The value whose corresponding key or index you want to locate.- Optional: Object argument:
arrays
/maps
/sets
(arrays of classes/strings): Arrays of classes and/or string names of classes that should be treated as equivalent toArray
/Map
/Set
(respectively).elseReturn
(any): A value to return in lieu of the key/index ifvalueToFind
is not found. Only takes effect if noelseThrow
is specified. Defaults toundefined
.elseThrow
(Error or string): An error to be thrown ifvalueToFind
is not found. A string will be wrapped in anError
object automatically.inObj
(boolean): Whether or not to search inherited properties ifcollection
is an Object (i.e. not another recognized type). Defaults tofalse
.loose
(boolean): Whether or not to identify values loosely (as defined bylooselyEquals
). Defaults tofalse
.looselyEquals
(function): A callback that accepts two values and returnstrue
if they are to be considered equivalent orfalse
otherwise. This argument is only used ifloose
istrue
. If omitted, the default behavior will, among other things, consider arrays/objects to be equal if they have the same entries.preferStrict
(boolean): Only applies ifloose
istrue
. Iftrue
, then strictly-identical values will be preferred over loosely-equivalent values. Otherwise, the first loosely-equivalent value found will have its key returned, even if a strictly-identical value comes later. Defaults tofalse
.reflectObj
(boolean): Whether or not to use reflection to include non-enumerable Object property values. Only takes effect ifcollection
is an Object (i.e. not another recognized type). Defaults tofalse
.reverse
(boolean): Set totrue
to emulate the behavior ofArray.prototype.lastIndexOf()
. Defaults tofalse
.
Return Value
- Returns the first key or numeric index (depending on the collection type) at which
valueToFind
(or its loose equivalent, if so configured) was found incollection
. - If
valueToFind
is not found incollection
, returnselseReturn
if set; otherwiseundefined
.
Example
const keyOf = const obj = a: 1 b: 2 c: 2 d: {} e: {} // 'a' // 'b' // undefined // 'd'
keyOf.any()
Use this function to find the first key (in iteration order) that corresponds to any of the given values. The signature is the same as the main function except that the second parameter is called valuesToFind
and takes an iterable (such as an array or string).
Example
const keyOf = const obj = a: 1 b: 2 c: 2 d: {} e: {} keyOf // 'a'keyOf // 'a'
Related
- keys-of: Same as this module, except it returns all keys/indexes, not just the first.