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, 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 [..., grandparent, parent]
(includes arrays iff useArraySelector
is true).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.
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);
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
.