Object-Scan
Find Keys using Wildcard matching and optional value function.
Install
Install with npm:
$ npm install --save object-scan
Usage
const objectScan = require('object-scan');
objectScan(["a.*.f"])({ a: { b: { c: 'd' }, e: { f: 'g' } } });
Features
- Object and array matching with e.g.
key.path
and [1]
- Key and index wildcard matching with
*
and [*]
- Partial key and index wildcard matching, e.g.
mark*
or [1*]
- Infinite nested matches with
**
- Simple or-clause for key and index with
{a,b}
and [{0,1}]
- Full support for escaping
- Lots of tests to ensure correctness
Options
Note on Functions:
Signature for all functions is Fn(key, value, { parents, isMatch, needle, needles })
, where:
key
is the key that the function is called for (respects joined
option).value
is the value of that key.parents
is an array containing all parents as [parent, grandparent, ...]
. Contains parents that are arrays only iff useArraySelector
is true.isMatch
is true if this is a valid (intermittent) result.needle
is the needle that matches if isMatch
is true, otherwise null
.needles
are all needles that triggered the function call.
excludeFn
Type: function
Default: undefined
Called for every intermittent result.
If function is defined and returns true, the entry is excluded from the final result.
breakFn
Type: function
Default: undefined
Called for every potential (partial) result at least once.
If function is defined and returns true, all nested entries under the current key are excluded from search and from the final result.
callbackFn
Type: function
Default: undefined
Called for every final result.
arrayCallbackFn
Type: function
Default: undefined
Called when useArraySelector
is false
for every array that contains top level matches.
joined
Type: boolean
Default: true
Can be set to false to return each key as a list. When dealing with special characters this can be useful.
Important: Setting this to false
improves performance.
escapePaths
Type: boolean
Default: `true
When set to false, joined paths for functions and the final result are not escaped.
useArraySelector
Type: boolean
Default: `true
When set to false no array selectors are used and arrays are automatically traversed.
Examples
More extensive examples can be found in the tests.
const objectScan = require('object-scan');
const obj = {
a: {
b: {
c: 'd'
},
e: {
f: 'g'
},
h: ["i", "j"]
},
k: "l"
};
objectScan(["*"])(obj);
objectScan(["a.*.f"])(obj);
objectScan(["*.*.*"])(obj);
objectScan(["a.*.{c,f}"])(obj);
objectScan(["a.*.{c,f}"], { joined: false })(obj);
objectScan(["*.*[*]"])(obj);
objectScan(["*[*]"])(obj);
objectScan(["**"])(obj);
objectScan(["**.f"])(obj);
objectScan(["**[*]"])(obj);
objectScan(["**"], { excludeFn: (key, value) => typeof value !== "string" })(obj);
objectScan(["**"], { breakFn: key => key === "a.b" })(obj);
Edge Cases
The empty needle ""
matches top level object(s). Useful for matching objects nested in arrays by setting useArraySelector
to false
. Note that the empty string does not work with _.get and _.set.
Special Characters
The following Characters are considered special and need to
be escaped if they should be matched in a key: [
, ]
, {
, }
, ,
, .
and *
.
When dealing with special characters the joined
option might be desirable to set to false
.