kget
v1.1.0
Published
Uses one or more keys to retrieve a value from a Map, Object, or other collection. Supports nesting, loose key matching, and more.
Downloads
10
Maintainers
Readme
kget
Uses one or more keys to retrieve a value from a Map, Object, or other collection. Supports nesting, loose key matching, and more.
Installation
Requires Node.js 8.3.0 or above.
npm i kget
API
The module exports a function (get()
) that has other functions attached to it as methods (e.g. get.any()
).
get()
Parameters
- Bindable:
collection
(Array, iterator, Map, Object, Set, string, Typed Array, or WeakMap): The key-value collection from which to retrieve a value. keychain
(any, or array of any): A key to retrieve, or an array of nested keys.- Optional: Object argument:
arrays
/maps
/sets
/weakMaps
(arrays of classes/strings): Arrays of classes and/or string names of classes that should be treated as equivalent toArray
/Map
/Set
/WeakMap
(respectively).elseReturn
(any): A value to return ifkeychain
is an invalid reference. Only takes effect if noelseThrow
is specified. Defaults toundefined
.elseThrow
(Error or string): An error to be thrown ifkeychain
is an invalid reference. A string will be wrapped in anError
object automatically.get
(function): A callback which, if provided, will override the built-in code that fetches an individual key from a collection. Use this if you need to support collections whose custom APIs preclude the use of parameters likemaps
. The callback will be called with five arguments: the collection, the key, the options object, the fallback to return if the key is not found, and a callback for the built-in get behavior (to which your customget
callback can defer if it determines that it doesn’t need to override the default behavior after all).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 evaluate keys 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 this option is omitted, then theequals
module is used. This module will, among other things, consider arrays/objects to be equal if they have the same entries.numerifyIndexes
(boolean): Set totrue
to convert number-containing key strings to numbers. This is most useful when thesplit
option is enabled: if you usesplit
to divide a'key.0'
keychain into'key'
and'0'
, enabling this option will result in the'0'
key being converted to a numeric0
index. Defaults tofalse
.preferStrict
(boolean): Only applies ifloose
istrue
. Iftrue
, then strictly-identical keys will be preferred over loosely-equivalent keys. Otherwise, the first loosely-equivalent key found will be used, even if a strictly-identical one comes later. Defaults tofalse
.reverse
(boolean): Set totrue
to use the last matching key instead of the first one. Only applies ifloose
istrue
. Defaults tofalse
.split
(boolean or object): Set totrue
to parse dot-separatedkeychain
strings (e.g.'key1.key2'
) as separate keys. You can also provide an object of options to be forwarded to thesplit-string
module. Defaults tofalse
.
Return Values
- Returns the value from
collection
referenced bykeychain
. - If no such value is found, returns
elseReturn
if set. - Otherwise returns
undefined
.
Example
In the following example, kget
fetches a map key, then an object key, then a string index:
const get = require('kget')
const map = new Map()
map.set('mapKey', {objKey: 'string'})
get(map, ['mapKey', 'objKey', 5]) // 'g'
get.any()
Has the same signature as the main function, except that the second parameter is called keychains
and expects an array of keys or keychain arrays to be tried one-by-one until one of them points to a value.
Example
const get = require('kget')
get.any({c: 3, d: 4}, [['a', 'subkey'], 'b', 'c']) // 3
The function tries the keys a.subkey
, b
, and c
in order. The first key found (c
) has its value returned.
get.in()
This method is an alias for calling the main get()
method with the inObj
option set to true
.
get.any.in()
This method is an alias for calling get.any()
with the inObj
option set to true
.
get.key()
This method allows you to determine the key that would be retrieved when loose equivalence is used.
Parameters
- Bindable:
collection
(Array, iterator, Map, Object, Set, string, or Typed Array): The key-value collection from which to retrieve a value. key
(any): A key which may or may not exist incollection
. (This can only be a single key, not a key chain.)- Optional: Object argument: The same options as in the base
get()
function.
Return Values
- If
key
exists incollection
:- If
loose
is set totrue
in the options argument, the first key incollection
that is loosely equal tokey
will be returned. - Otherwise,
key
is returned as-is.
- If
- If
key
does not exist incollection
, the return value isundefined
.
Example
const get = require('kget')
const a = ['key']
const b = ['key']
const map = new Map()
map.set(a, 'value a')
map.set(b, 'value b')
get(map, b) // 'value b'
get(map, b, {loose: true}) // 'value a'
get.key(map, b) === b // true
get.key(map, b, {loose: true}) === a // true
get.entry()
Parameters
- Bindable:
collection
(Array, iterator, Map, Object, Set, string, or Typed Array): The key-value collection from which to retrieve a value. key
(any): A key which may or may not exist incollection
. (This can only be a single key, not a key chain.)- Optional: Object argument: Any of (as defined above):
arrays
,maps
,sets
,weakMaps
,elseReturn
,elseThrow
,inObj
,loose
,looselyEquals
, andpreferStrict
.
Return Values
- If the
key
is found, returns a two-element array containing the matched key and the retrieved value. - If the
key
is not found, returnselseReturn
if provided, otherwiseundefined
.
Related
The “k” family of modules works on keyed/indexed collections.
The “v” family of modules works on any collection of values.