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)
, where key
is the key that the function is called for,
value
is the value of that key and parents
is an array containing all parents as [..., grandparent, parent]
.
The key
argument respects the joined
option and the parents
only includes arrays if useArraySelector
is true.
filterFn
Type: function
Default: undefined
Called for every intermittent result.
If function is defined and returns false, the entry is filtered from the final result.
breakFn
Type: function
Default: undefined
Called for every intermittent result.
If function is defined and returns true, all nested entries under the current key are excluded from the 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(["**"], { filterFn: (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
.