Security News
Combatting Alert Fatigue by Prioritizing Malicious Intent
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
object-scan
Advanced tools
Find keys in object hierarchies using wildcard and glob matching and callbacks.
Find keys in object hierarchies using wildcard and glob matching and callbacks.
Install with npm:
$ npm install --save object-scan
const objectScan = require('object-scan');
objectScan(['a.*.f'])({ a: { b: { c: 'd' }, e: { f: 'g' } } });
// => [ 'a.e.f' ]
key.path
and [1]
*
and [*]
mark*
, m?rk
, [*1]
or [?1]
**
{a,b}
and [{0,1}]
!key
A context can be passed into a search invocation as a second parameter. It is available in all callbacks and can be used to manage state across a search invocation without having to recompile the search.
By default all matched keys are returned from a search invocation. However, when it is not undefined, the context is returned instead.
Signature of all callbacks is
Fn({
key, value, parent, parents, isMatch, matchedBy, excludedBy, traversedBy, isCircular
getKey, getValue, getParent, getParents, getIsMatch, getMatchedBy, getExcludedBy, getTraversedBy, getIsCircular
context
})
where:
key
: key that callback is invoked for (respects joined
option).value
: value for key.parent
: current parent.parents
: array of form [parent, grandparent, ...]
.isMatch
: true iff last targeting needle exists and is non-excluding.matchedBy
: all non-excluding needles targeting key.excludedBy
: all excluding needles targeting key.traversedBy
: all needles involved in traversing key.isCircular
: true iff value
contained in parents
getKey
: function that returns key
getValue
: function that returns value
getParent
: function that returns parent
getParents
: function that returns parents
getIsMatch
: function that returns isMatch
getMatchedBy
: function that returns matchedBy
getExcludedBy
: function that returns excludedBy
getTraversedBy
: function that returns traversedBy
getIsCircular
: function that returns isCircular
context
: as passed into the searchNotes on Performance:
if (isMatch) { getParents() ... }
.Type: function
Default: undefined
If defined, this callback is invoked for every match. If false
is returned, the current key is excluded from the result.
The return value of this callback has no effect when a search context is provided.
Can be used to do processing as matching keys are traversed.
Invoked in same order as matches would appear in result.
This method is conceptually similar to Array.filter().
Type: function
Default: undefined
If defined, this callback is invoked for every key that is traversed by
the search. If true
is returned, all keys nested under the current key are
skipped in the search and from the final result.
Note that breakFn
is invoked before the corresponding filterFn
might be invoked.
Type: boolean
Default: false
Keys are returned as a string when set to true
instead of as a list.
Setting this option to true
will negatively impact performance.
Note that _.get and _.set fully support lists.
Type: boolean
Default: true
When set to false
, no array selectors should be used in any needles and arrays are automatically traversed.
Note that the results still include the array selectors.
Type: boolean
Default: true
When set to false
, no errors are thrown when:
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'
};
// top level keys
objectScan(['*'], { joined: true })(obj);
// => ["k", "a"]
// nested keys
objectScan(['a.*.f'], { joined: true })(obj);
// => ["a.e.f"]
objectScan(['*.*.*'], { joined: true })(obj);
// => ["a.e.f", "a.b.c"]
// or filter
objectScan(['a.*.{c,f}'], { joined: true })(obj);
// => ["a.e.f", "a.b.c"]
objectScan(['a.*.{c,f}'])(obj);
// => [["a", "e", "f"], ["a", "b", "c"]]
// list filter
objectScan(['*.*[*]'], { joined: true })(obj);
// => ["a.h[1]", "a.h[0]"]
objectScan(['*[*]'], { joined: true })(obj);
// => []
// deep star filter
objectScan(['**'], { joined: true })(obj);
// => ["k", "a.h[1]", "a.h[0]", "a.h", "a.e.f", "a.e", "a.b.c", "a.b", "a"]
objectScan(['**.f'], { joined: true })(obj);
// => ["a.e.f"]
objectScan(['**[*]'], { joined: true })(obj);
// => ["a.h[1]", "a.h[0]"]
// exclusion filter
objectScan(['a.*,!a.e'], { joined: true })(obj);
// => ["a.h", "a.b"]
// value function
objectScan(['**'], { filterFn: ({ value }) => typeof value === 'string', joined: true })(obj);
// => ["k", "a.h[1]", "a.h[0]", "a.e.f", "a.b.c"]
objectScan(['**'], { breakFn: ({ key }) => key === 'a.b', joined: true })(obj);
// => ["k", "a.h[1]", "a.h[0]", "a.h", "a.e.f", "a.e", "a.b", "a"]
The top level object(s) are matched by the empty needle ""
.
Useful for matching objects nested in arrays by setting useArraySelector
to false
.
Note that the empty string does not work with _.get and _.set.
The following characters are considered special and need to
be escaped if they should be matched in a key: [
, ]
, {
, }
, ,
, .
, !
, ?
, *
and \
.
Conceptually this package works as follows:
During initialization the needles are parsed and built into a search tree. Various information is pre-computed and stored for every node. Finally the search function is returned.
When the search function is invoked, the input is traversed simultaneously with the relevant nodes of the search tree. Processing multiple search tree branches in parallel allows for a single traversal of the input.
Having a separate initialization stage allows for a performant search and significant speed ups when applying the same search to different input.
FAQs
Traverse object hierarchies using matching and callbacks.
The npm package object-scan receives a total of 29,336 weekly downloads. As such, object-scan popularity was classified as popular.
We found that object-scan demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.