Traverse object hierarchies using matching and callbacks.
Using npm:
$ npm i object-scan
In a browser:
<script type="module">
import objectScan from 'https://cdn.jsdelivr.net/npm/object-scan@<VERSION>/lib/index.min.js';
// do logic here
</script>
import objectScan from 'object-scan';
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' } } };
objectScan(['a.*.f'], { joined: true })(haystack);
// => [ 'a.e.f' ]
- Input traversed at most once during search
- Dependency free and tiny bundle size
- Powerful matching syntax
- Very performant
- Extensive tests and lots of examples
A needle expression specifies one or more paths to an element (or a set of elements) in a JSON structure. Paths use the dot notation.
store.book[0].title
The matching syntax is fully validated and bad input will throw a syntax error. The following syntax is supported:
- Array and Object matching
- Wildcard and Regex matching
- Or Clause
- Arbitrary Depth and Nested Path Recursion
- Exclusion
- Escaping
- Array Needles
Rectangular brackets for array path matching.
Examples:
['[2]']
(exact in array)
const haystack = [0, 1, 2, 3, 4];
objectScan(['[2]'], { joined: true })(haystack);
// => [ '[2]' ]
['[1]']
(no match in object)
const haystack = { 0: 'a', 1: 'b', 2: 'c' };
objectScan(['[1]'], { joined: true })(haystack);
// => []
Property name for object property matching.
Examples:
['foo']
(exact in object)
const haystack = { foo: 0, bar: 1 };
objectScan(['foo'], { joined: true })(haystack);
// => [ 'foo' ]
['1']
(no match in array)
const haystack = [0, 1, 2, 3, 4];
objectScan(['1'], { joined: true })(haystack);
// => []
The following characters have special meaning when not escaped:
*
: Match zero or more character+
: Match one or more character?
: Match exactly one character\
: Escape the subsequent character
Can be used with Array and Object selector.
Examples:
['foo*']
(starting with `foo`)
const haystack = { foo: 0, foobar: 1, bar: 2 };
objectScan(['foo*'], { joined: true })(haystack);
// => [ 'foobar', 'foo' ]
['*']
(top level)
const haystack = { a: { b: 0, c: 1 }, d: 2 };
objectScan(['*'], { joined: true })(haystack);
// => [ 'd', 'a' ]
['[?5]']
(two digit ending in five)
const haystack = [...Array(30).keys()];
objectScan(['[?5]'], { joined: true })(haystack);
// => [ '[25]', '[15]' ]
['a.+.c']
(nested)
const haystack = { a: { b: { c: 0 }, d: { f: 0 } } };
objectScan(['a.+.c'], { joined: true })(haystack);
// => [ 'a.b.c' ]
['a.\\+.c']
(escaped)
const haystack = { a: { b: { c: 0 }, '+': { c: 0 } } };
objectScan(['a.\\+.c'], { joined: true })(haystack);
// => [ 'a.\\+.c' ]
Regex are defined by using parentheses.
Can be used with Array and Object selector.
Examples:
['(^foo)']
(starting with `foo`)
const haystack = { foo: 0, foobar: 1, bar: 2 };
objectScan(['(^foo)'], { joined: true })(haystack);
// => [ 'foobar', 'foo' ]
['[(5)]']
(containing `5`)
const haystack = [...Array(20).keys()];
objectScan(['[(5)]'], { joined: true })(haystack);
// => [ '[15]', '[5]' ]
['[(^[01]$)]']
(`[0]` and `[1]`)
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[01]$)]'], { joined: true })(haystack);
// => [ '[1]', '[0]' ]
['[(^[^01]$)]']
(other than `[0]` and `[1]`)
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[^01]$)]'], { joined: true })(haystack);
// => [ '[3]', '[2]' ]
Or Clauses are defined by using curley brackets.
Can be used with Array and Object selector and Arbitrary Depth matching.
Examples:
['[{0,1}]']
(`[0]` and `[1]`)
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[{0,1}]'], { joined: true })(haystack);
// => [ '[1]', '[0]' ]
['{a,d}.{b,f}']
(`a.b`, `a.f`, `d.b` and `d.f`)
const haystack = { a: { b: 0, c: 1 }, d: { e: 2, f: 3 } };
objectScan(['{a,d}.{b,f}'], { joined: true })(haystack);
// => [ 'd.f', 'a.b' ]
There are two types of arbitrary depth matching:
**
: Matches zero or more nestings++
: Matches one or more nestings
Can be combined with Regex and Or Clause by prepending.
Examples:
['a.**']
(zero or more nestings under `a`)
const haystack = { a: { b: 0, c: 0 } };
objectScan(['a.**'], { joined: true })(haystack);
// => [ 'a.c', 'a.b', 'a' ]
['a.++']
(one or more nestings under `a`)
const haystack = { a: { b: 0, c: 0 } };
objectScan(['a.++'], { joined: true })(haystack);
// => [ 'a.c', 'a.b' ]
['**(1)']
(all containing `1` at every level)
const haystack = { 1: { 1: ['c', 'd'] }, 510: 'e', foo: { 1: 'f' } };
objectScan(['**(1)'], { joined: true })(haystack);
// => [ '510', '1.1[1]', '1.1', '1' ]
To match a nested path recursively, combine Arbitrary Depth matching with an Or Clause.
There are two types of nested path matching:
**{...}
: Matches path(s) in Or Clause zero or more times++{...}
: Matches path(s) in Or Clause one or more times
Examples:
['++{[0][1]}']
(`cyclic path`)
const haystack = [[[[0, 1], [1, 2]], [[3, 4], [5, 6]]], [[[7, 8], [9, 10]], [[11, 12], [13, 14]]]];
objectScan(['++{[0][1]}'], { joined: true })(haystack);
// => [ '[0][1][0][1]', '[0][1]' ]
['++{[0],[1]}']
(`nested or`)
const haystack = [[0, 1, 2], [3, 4, 5], [6, 7, 8]];
objectScan(['++{[0],[1]}'], { joined: true })(haystack);
// => [ '[1][1]', '[1][0]', '[1]', '[0][1]', '[0][0]', '[0]' ]
['**{[*]}']
(`traverse only array`)
const haystack = [[[{ a: [1] }], [2]]];
objectScan(['**{[*]}'], { joined: true })(haystack);
// => [ '[0][1][0]', '[0][1]', '[0][0][0]', '[0][0]', '[0]' ]
['**{*}']
(`traverse only object`)
const haystack = { a: [0, { b: 1 }], c: { d: 2 } };
objectScan(['**{*}'], { joined: true })(haystack);
// => [ 'c.d', 'c', 'a' ]
['a.**{b.c}']
(`zero or more times`)
const haystack = { a: { b: { c: { b: { c: 0 } } } } };
objectScan(['a.**{b.c}'], { joined: true })(haystack);
// => [ 'a.b.c.b.c', 'a.b.c', 'a' ]
['a.++{b.c}']
(`one or more times`)
const haystack = { a: { b: { c: { b: { c: 0 } } } } };
objectScan(['a.++{b.c}'], { joined: true })(haystack);
// => [ 'a.b.c.b.c', 'a.b.c' ]
To exclude a path, use exclamation mark.
Examples:
['{a,b},!a']
(only `b`)
const haystack = { a: 0, b: 1 };
objectScan(['{a,b},!a'], {
joined: true,
strict: false
})(haystack);
// => [ 'b' ]
['**,!**.a']
(all except ending in `a`)
const haystack = { a: 0, b: { a: 1, c: 2 } };
objectScan(['**,!**.a'], { joined: true })(haystack);
// => [ 'b.c', 'b' ]
['[*]', '[!(^[01]$)]']
(exclude with regex)
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[*]', '[!(^[01]$)]'], { joined: true })(haystack);
// => [ '[3]', '[2]' ]
The following characters are considered special and need to
be escaped using \
, if they should be matched in a key:
[
, ]
, {
, }
, (
, )
, ,
, .
, !
, ?
, *
, +
and \
.
Examples:
['\\[1\\]']
(special object key)
const haystack = { '[1]': 0 };
objectScan(['\\[1\\]'], { joined: true })(haystack);
// => [ '\\[1\\]' ]
Needles can be passed as arrays, consisting of integers
and strings
.
When given as arrays, then needles:
- match array keys with
integers
and object keys withstrings
- do not support any other matching syntax
- do not require escaping
- parse faster than regular string needles
This syntax allows for key
result of object-scan to be passed back into itself.
Be advised that matchedBy
and similar contain the original needles and not copies.
Array needles work similarly to how they work in _.get.
Examples:
[['a', 0, 'b']]
(mixed path)
const haystack = { a: [{ b: 0 }] };
objectScan([['a', 0, 'b']], { joined: true })(haystack);
// => [ 'a[0].b' ]
[['a.b', 0]]
(implicit escape)
const haystack = { 'a.b': [0], a: { b: [1] } };
objectScan([['a.b', 0]], {
joined: true,
rtn: 'value'
})(haystack);
// => [ 0 ]
[['a', 0, 'b'], ['a', 1, 'b'], 'a[*].b']
(mixed needles)
const haystack = { a: [{ b: 0 }, { b: 0 }] };
objectScan([['a', 0, 'b'], ['a', 1, 'b'], 'a[*].b'], {
joined: true,
rtn: 'matchedBy'
})(haystack);
// => [ [ [ 'a', 1, 'b' ], 'a[*].b' ], [ [ 'a', 0, 'b' ], 'a[*].b' ] ]
[['a', 'b']]
(useArraySelector=false)
const haystack = { a: [{ b: 0 }, { b: 0 }] };
objectScan([['a', 'b']], {
joined: true,
useArraySelector: false
})(haystack);
// => [ 'a[1].b', 'a[0].b' ]
Fn({ key, value, ... })
where:
key
: key that callback is invoked for (respectsjoined
option).value
: value for key.entry
: entry consisting of [key
,value
].property
: current parent property.gproperty
: current grandparent property.parent
: current parent.gparent
: current grandparent.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 iffvalue
contained inparents
isLeaf
: true iffvalue
can not be traverseddepth
: length ofkey
result
: intermittent result as defined byrtn
getKey(joined?: boolean)
: function that returnskey
getValue
: function that returnsvalue
getEntry(joined?: boolean)
: function that returnsentry
getProperty
: function that returnsproperty
getGproperty
: function that returnsgproperty
getParent
: function that returnsparent
getGparent
: function that returnsgparent
getParents
: function that returnsparents
getIsMatch
: function that returnsisMatch
getMatchedBy
: function that returnsmatchedBy
getExcludedBy
: function that returnsexcludedBy
getTraversedBy
: function that returnstraversedBy
getIsCircular
: function that returnsisCircular
getIsLeaf
: function that returnsisLeaf
getDepth
: function that returnsdepth
getResult
: function that returnsresult
context
: as passed into the search
Notes on Performance
- Arguments backed by getters use Functions Getter and should be accessed via destructuring to prevent redundant computation.
- Getters should be used to improve performance for conditional access. E.g.
if (isMatch) { getParents() ... }
. - For performance reasons, the same object is passed to all callbacks.
Search Context
- 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.
Examples:
['**.{c,d,e}']
(search context)
const haystack = { a: { b: { c: 2, d: 11 }, e: 7 } };
objectScan(['**.{c,d,e}'], {
joined: true,
filterFn: ({ value, context }) => { context.sum += value; }
})(haystack, { sum: 0 });
// => { sum: 20 }
Type: function
Default: undefined
When 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.
For more information on invocation order, please refer to Section Traversal Order.
This method is conceptually similar to Array.filter().
Examples:
['**']
(filter function)
const haystack = { a: 0, b: 'bar' };
objectScan(['**'], {
joined: true,
filterFn: ({ value }) => typeof value === 'string'
})(haystack);
// => [ 'b' ]
Type: function
Default: undefined
When 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.
For more information on invocation order, please refer to Section Traversal Order.
Examples:
['**']
(break function)
const haystack = { a: { b: { c: 0 } } };
objectScan(['**'], {
joined: true,
breakFn: ({ key }) => key === 'a.b'
})(haystack);
// => [ 'a.b', 'a' ]
Type: function
Default: undefined
When defined, this function is called before traversal as beforeFn(state = { haystack, context })
.
If a value other than undefined
is returned from beforeFn
,
that value is written to state.haystack
before traversal.
The content of state
can be modified in the function.
After beforeFn
has executed, the traversal happens using state.haystack
and state.context
.
The content in state
can be accessed in afterFn
.
Note however that the key result
is being overwritten.
Examples:
['**']
(combining haystack and context)
const haystack = { a: 0 };
objectScan(['**'], {
joined: true,
beforeFn: ({ haystack: h, context: c }) => [h, c],
rtn: 'key'
})(haystack, { b: 0 });
// => [ '[1].b', '[1]', '[0].a', '[0]' ]
['**']
(pre-processing haystack)
const haystack = { a: 0, b: 1 };
objectScan(['**'], {
joined: true,
beforeFn: ({ haystack: h }) => Object.keys(h),
rtn: ['key', 'value']
})(haystack);
// => [ [ '[1]', 'b' ], [ '[0]', 'a' ] ]
Type: function
Default: undefined
When defined, this function is called after traversal as afterFn(state = { result, haystack, context })
.
Additional information written to state
in beforeFn
is available in afterFn
.
The content of state
can be modified in the function. In particular the key state.result
can be updated.
If a value other than undefined
is returned from afterFn
, that value is written to state.result
.
After beforeFn
has executed, the key state.result
is returned as the final result.
Examples:
['**']
(returning count plus context)
const haystack = { a: 0 };
objectScan(['**'], {
afterFn: ({ result, context }) => result + context,
rtn: 'count'
})(haystack, 5);
// => 6
['**']
(post-processing result)
const haystack = { a: 0, b: 3, c: 4 };
objectScan(['**'], {
afterFn: ({ result }) => result.filter((v) => v > 3),
rtn: 'value'
})(haystack);
// => [ 4 ]
['**']
(pass data from beforeFn to afterFn)
const haystack = {};
objectScan(['**'], {
beforeFn: (state) => { /* eslint-disable no-param-reassign */ state.custom = 7; },
afterFn: (state) => state.custom
})(haystack);
// => 7
Type: function
Default: undefined
This function has the same signature as the callback functions. When defined it is expected to return a function
or undefined
.
The returned value is used as a comparator to determine the traversal order of any object
keys.
This works together with the reverse
option.
Please refer to Section Traversal Order for more information.
Examples:
['**']
(simple sort)
const haystack = { a: 0, c: 1, b: 2 };
objectScan(['**'], {
joined: true,
compareFn: () => (k1, k2) => k1.localeCompare(k2),
reverse: false
})(haystack);
// => [ 'a', 'b', 'c' ]
Type: boolean
Default: true
When set to true
, the traversal is performed in reverse order. This means breakFn
is executed in reverse post-order and
filterFn
in reverse pre-order. Otherwise breakFn
is executed in pre-order and filterFn
in post-order.
When reverse
is true
the traversal is delete-safe. I.e. property
can be deleted / spliced from parent
object / array in filterFn
.
Please refer to Section Traversal Order for more information.
Examples:
['**']
(breakFn, reverse true)
const haystack = { f: { b: { a: {}, d: { c: {}, e: {} } }, g: { i: { h: {} } } } };
objectScan(['**'], {
breakFn: ({ isMatch, property, context }) => { if (isMatch) { context.push(property); } },
reverse: true
})(haystack, []);
// => [ 'f', 'g', 'i', 'h', 'b', 'd', 'e', 'c', 'a' ]
['**']
(filterFn, reverse true)
const haystack = { f: { b: { a: {}, d: { c: {}, e: {} } }, g: { i: { h: {} } } } };
objectScan(['**'], {
filterFn: ({ property, context }) => { context.push(property); },
reverse: true
})(haystack, []);
// => [ 'h', 'i', 'g', 'e', 'c', 'd', 'a', 'b', 'f' ]
['**']
(breakFn, reverse false)
const haystack = { f: { b: { a: {}, d: { c: {}, e: {} } }, g: { i: { h: {} } } } };
objectScan(['**'], {
breakFn: ({ isMatch, property, context }) => { if (isMatch) { context.push(property); } },
reverse: false
})(haystack, []);
// => [ 'f', 'b', 'a', 'd', 'c', 'e', 'g', 'i', 'h' ]
['**']
(filterFn, reverse false)
const haystack = { f: { b: { a: {}, d: { c: {}, e: {} } }, g: { i: { h: {} } } } };
objectScan(['**'], {
filterFn: ({ property, context }) => { context.push(property); },
reverse: false
})(haystack, []);
// => [ 'a', 'c', 'e', 'd', 'b', 'h', 'i', 'g', 'f' ]
Type: boolean
Default: false
When set to false
, all targeted keys are traversed and matched
in the order determined by the compareFn
and reverse
option.
When set to true
, all targeted keys are traversed and matched
in the order determined by the corresponding needles,
falling back to the above ordering.
Note that this option is constraint by the depth-first search approach.
Examples:
['c', 'a', 'b']
(order by needle)
const haystack = { a: 0, b: 1, c: 1 };
objectScan(['c', 'a', 'b'], {
joined: true,
orderByNeedles: true
})(haystack);
// => [ 'c', 'a', 'b' ]
['b', '*']
(fallback reverse)
const haystack = { a: 0, b: 1, c: 1 };
objectScan(['b', '*'], {
joined: true,
reverse: true,
orderByNeedles: true
})(haystack);
// => [ 'b', 'c', 'a' ]
['b', '*']
(fallback not reverse)
const haystack = { a: 0, b: 1, c: 1 };
objectScan(['b', '*'], {
joined: true,
reverse: false,
orderByNeedles: true
})(haystack);
// => [ 'b', 'a', 'c' ]
['a', 'b.c', 'd']
(nested match)
const haystack = { a: 0, b: { c: 1 }, d: 2 };
objectScan(['a', 'b.c', 'd'], {
joined: true,
orderByNeedles: true
})(haystack);
// => [ 'a', 'b.c', 'd' ]
['b', 'a', 'b.c', 'd']
(matches traverse first)
const haystack = { a: 0, b: { c: 1 }, d: 2 };
objectScan(['b', 'a', 'b.c', 'd'], {
joined: true,
orderByNeedles: true
})(haystack);
// => [ 'b.c', 'b', 'a', 'd' ]
Type: boolean
Default: false
When set to true
the traversal immediately returns after the first match.
Examples:
['a', 'b']
(only return first property)
const haystack = { a: 0, b: 1 };
objectScan(['a', 'b'], {
rtn: 'property',
abort: true
})(haystack);
// => 'b'
['[0]', '[1]']
(abort changes count)
const haystack = ['a', 'b'];
objectScan(['[0]', '[1]'], {
rtn: 'count',
abort: true
})(haystack);
// => 1
Type: string
or array
or function
Default: dynamic
Defaults to key
when search context is undefined and to context
otherwise.
Can be explicitly set as a string
:
context
: search context is returnedkey
: as passed intofilterFn
value
: as passed intofilterFn
entry
: as passed intofilterFn
property
: as passed intofilterFn
gproperty
: as passed intofilterFn
parent
: as passed intofilterFn
gparent
: as passed intofilterFn
parents
: as passed intofilterFn
isMatch
: as passed intofilterFn
matchedBy
: as passed intofilterFn
excludedBy
: as passed intofilterFn
traversedBy
: as passed intofilterFn
isCircular
: as passed intofilterFn
isLeaf
: as passed intofilterFn
depth
: as passed intofilterFn
bool
: returns true iff a match is foundcount
: returns the match countsum
: returns the match sum
When set to array
, can contain any of the above except context
, bool
, count
and sum
.
When set to function
, called with callback signature for every match. Returned value is added to the result.
When abort is set to true
and rtn is not context
, bool
, count
or sum
,
the first entry of the result or undefined is returned.
Examples:
['[*]']
(return values)
const haystack = ['a', 'b', 'c'];
objectScan(['[*]'], { rtn: 'value' })(haystack);
// => [ 'c', 'b', 'a' ]
['foo[*]']
(return entries)
const haystack = { foo: ['bar'] };
objectScan(['foo[*]'], { rtn: 'entry' })(haystack);
// => [ [ [ 'foo', 0 ], 'bar' ] ]
['a.b.c', 'a']
(return properties)
const haystack = { a: { b: { c: 0 } } };
objectScan(['a.b.c', 'a'], { rtn: 'property' })(haystack);
// => [ 'c', 'a' ]
['a.b', 'a.c']
(checks for any match, full traversal)
const haystack = { a: { b: 0, c: 1 } };
objectScan(['a.b', 'a.c'], { rtn: 'bool' })(haystack);
// => true
['**']
(return not provided context)
const haystack = { a: 0 };
objectScan(['**'], { rtn: 'context' })(haystack);
// => undefined
['a.b.{c,d}']
(return keys with context passed)
const haystack = { a: { b: { c: 0, d: 1 } } };
objectScan(['a.b.{c,d}'], { rtn: 'key' })(haystack, []);
// => [ [ 'a', 'b', 'd' ], [ 'a', 'b', 'c' ] ]
['a.b.{c,d}']
(return custom array)
const haystack = { a: { b: { c: 0, d: 1 } } };
objectScan(['a.b.{c,d}'], { rtn: ['property', 'value'] })(haystack, []);
// => [ [ 'd', 1 ], [ 'c', 0 ] ]
['**']
(return value plus one)
const haystack = { a: { b: { c: 0, d: 1 } } };
objectScan(['**'], {
filterFn: ({ isLeaf }) => isLeaf,
rtn: ({ value }) => value + 1
})(haystack);
// => [ 2, 1 ]
['**']
(return sum)
const haystack = { a: { b: { c: -2, d: 1 }, e: [3, 7] } };
objectScan(['**'], {
filterFn: ({ value }) => typeof value === 'number',
rtn: 'sum'
})(haystack);
// => 9
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.
This setting can be overwritten by using the getter method getKey()
or getEntry()
.
Note that _.get and _.set fully support lists.
Examples:
['[*]', '[*].foo']
(joined)
const haystack = [0, 1, { foo: 'bar' }];
objectScan(['[*]', '[*].foo'], { joined: true })(haystack);
// => [ '[2].foo', '[2]', '[1]', '[0]' ]
['[*]', '[*].foo']
(not joined)
const haystack = [0, 1, { foo: 'bar' }];
objectScan(['[*]', '[*].foo'])(haystack);
// => [ [ 2, 'foo' ], [ 2 ], [ 1 ], [ 0 ] ]
['**.c']
(joined, getKey)
const haystack = { a: { b: { c: 0 } } };
objectScan(['**.c'], {
joined: true,
rtn: ({ getKey }) => [getKey(true), getKey(false), getKey()]
})(haystack);
// => [ [ 'a.b.c', [ 'a', 'b', 'c' ], 'a.b.c' ] ]
['**.c']
(not joined, getEntry)
const haystack = { a: { b: { c: 0 } } };
objectScan(['**.c'], { rtn: ({ getEntry }) => [getEntry(true), getEntry(false), getEntry()] })(haystack);
// => [ [ [ 'a.b.c', 0 ], [ [ 'a', 'b', 'c' ], 0 ], [ [ 'a', 'b', 'c' ], 0 ] ] ]
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.
Examples:
['a', 'b.d']
(automatic array traversal)
const haystack = [{ a: 0 }, { b: [{ c: 1 }, { d: 2 }] }];
objectScan(['a', 'b.d'], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1].b[1].d', '[0].a' ]
['']
(top level array matching)
const haystack = [{ a: 0 }, { b: 1 }];
objectScan([''], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]
Type: boolean
Default: true
When set to true
, errors are thrown when:
- a path is identical to a previous path
- a path invalidates a previous path
- a path contains consecutive recursions
Examples:
['a.b', 'a.b']
(identical)
const haystack = [];
objectScan(['a.b', 'a.b'], { joined: true })(haystack);
// => 'Error: Redundant Needle Target: "a.b" vs "a.b"'
['a.{b,b}']
(identical, same needle)
const haystack = [];
objectScan(['a.{b,b}'], { joined: true })(haystack);
// => 'Error: Redundant Needle Target: "a.{b,b}" vs "a.{b,b}"'
['a.b', 'a.**']
(invalidates previous)
const haystack = [];
objectScan(['a.b', 'a.**'], { joined: true })(haystack);
// => 'Error: Needle Target Invalidated: "a.b" by "a.**"'
['**.!**']
(consecutive recursion)
const haystack = [];
objectScan(['**.!**'], { joined: true })(haystack);
// => 'Error: Redundant Recursion: "**.!**"'
This library has a similar syntax and can perform similar tasks to jsonpath or jmespath. But instead of querying an object hierarchy, it focuses on traversing it. Hence, it is designed around handling multiple paths in a single traversal. No other library doing this is currently available.
While nimma provides the ability to traverse multiple paths, it doesn't do it in a single traversal.
A one-to-one comparison with other libraries is difficult due to difference in functionality,
but it can be said that object-scan
is more versatile at similar performance.
objectScan (compiled) | objectScan | nimma (compiled) | nimma | jsonpath-plus | jsonpath | jmespath | |
---|---|---|---|---|---|---|---|
Get Key | - | ||||||
Get Value | |||||||
Conditional Path | [1] | [1] | |||||
Recursive Traversal | [2] | [2] | [3] | [3] | [4] | [4] | - [5] |
Partial Traversal | - | ||||||
Callback with Context | [6] | [6] | [7] | [7] | [7] | - | - |
Regex | - | - | |||||
Multiple Paths | [8] | [8] | - [9] | - [9] | - | ||
Get Parent | - | - | - | - | |||
Wildcard | - | - | - | - | - | ||
Exclusion | - | - | - | - | - | ||
Path Recursion | - | - | - | - | - | ||
Auto Traverse | - | - | - | - | - | ||
Break Circular | - | - | - | - | - |
[1]: Only in code logic
[2]: Depth-first traversal. See here for details
[3]: Depth-first traversal in in Pre-order
[4]: Custom depth-first traversal
[5]: Reference
[6]: Documentation
[7]: Usefulness limited since context is lacking information
[8]: Path deduplication has to be done in custom code
[9]: Reference
Noteworthy dependents are:
- object-fields: Showcases how to retain only certain nested keys from object
- object-lib: Good example of more advanced use cases
- object-rewrite: The original reason for creating this library
Many other examples can be found on Stack Overflow.
More extensive examples can be found in the tests.
['a.*.f']
(nested)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['a.*.f'], { joined: true })(haystack);
// => [ 'a.e.f' ]
['*.*.*']
(multiple nested)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['*.*.*'], { joined: true })(haystack);
// => [ 'a.e.f', 'a.b.c' ]
['a.*.{c,f}']
(or filter)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['a.*.{c,f}'], { joined: true })(haystack);
// => [ 'a.e.f', 'a.b.c' ]
['a.*.{c,f}']
(or filter, not joined)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['a.*.{c,f}'])(haystack);
// => [ [ 'a', 'e', 'f' ], [ 'a', 'b', 'c' ] ]
['*.*[*]']
(list filter)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['*.*[*]'], { joined: true })(haystack);
// => [ 'a.h[1]', 'a.h[0]' ]
['*[*]']
(list filter, unmatched)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['*[*]'], { joined: true })(haystack);
// => []
['**']
(star recursion)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**'], { joined: true })(haystack);
// => [ 'k', 'a.h[1]', 'a.h[0]', 'a.h', 'a.e.f', 'a.e', 'a.b.c', 'a.b', 'a' ]
['++.++']
(plus recursion)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['++.++'], { joined: true })(haystack);
// => [ 'a.h[1]', 'a.h[0]', 'a.h', 'a.e.f', 'a.e', 'a.b.c', 'a.b' ]
['**.f']
(star recursion ending in f)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**.f'], { joined: true })(haystack);
// => [ 'a.e.f' ]
['**[*]']
(star recursion ending in array)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**[*]'], { joined: true })(haystack);
// => [ 'a.h[1]', 'a.h[0]' ]
['a.*,!a.e']
(exclusion filter)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['a.*,!a.e'], { joined: true })(haystack);
// => [ 'a.h', 'a.b' ]
['**.(^[bc]$)']
(regex matching)
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**.(^[bc]$)'], { joined: true })(haystack);
// => [ 'a.b.c', 'a.b' ]
The traversal order is always depth first. However, the order the nodes are traversed in can be changed.
['**']
(Reverse Pre-order)
const haystack = { F: { B: { A: 0, D: { C: 1, E: 2 } }, G: { I: { H: 3 } } } };
objectScan(['**'], {
filterFn: ({ context, property }) => { context.push(property); }
})(haystack, []);
// => [ 'H', 'I', 'G', 'E', 'C', 'D', 'A', 'B', 'F' ]
['**']
(Reverse Post-order)
const haystack = { F: { B: { A: 0, D: { C: 1, E: 2 } }, G: { I: { H: 3 } } } };
objectScan(['**'], {
breakFn: ({ context, property }) => { context.push(property); }
})(haystack, []);
// => [ undefined, 'F', 'G', 'I', 'H', 'B', 'D', 'E', 'C', 'A' ]
['**']
(Post-order)
const haystack = { F: { B: { A: 0, D: { C: 1, E: 2 } }, G: { I: { H: 3 } } } };
objectScan(['**'], {
filterFn: ({ context, property }) => { context.push(property); },
reverse: false
})(haystack, []);
// => [ 'A', 'C', 'E', 'D', 'B', 'H', 'I', 'G', 'F' ]
['**']
(Pre-order)
const haystack = { F: { B: { A: 0, D: { C: 1, E: 2 } }, G: { I: { H: 3 } } } };
objectScan(['**'], {
breakFn: ({ context, property }) => { context.push(property); },
reverse: false
})(haystack, []);
// => [ undefined, 'F', 'B', 'A', 'D', 'C', 'E', 'G', 'I', 'H' ]
Note that the default traversal order is delete-safe. This means that elements from Arrays can be deleted without impacting the traversal.
['**']
(Deleting from Array)
const haystack = [0, 1, 2, 3, 4, 5];
objectScan(['**'], {
filterFn: ({ parent, property }) => { parent.splice(property, property % 2); },
afterFn: ({ haystack: h }) => h
})(haystack);
// => [ 0, 2, 4 ]
This is not true when the reverse
option is set to false
['**']
(Deleting from Array Unexpected)
const haystack = [0, 1, 2, 3, 4, 5];
objectScan(['**'], {
filterFn: ({ parent, property }) => { parent.splice(property, property % 2); },
afterFn: ({ haystack: h }) => h,
reverse: false
})(haystack);
// => [ 0, 2, 3, 5 ]
By default, the traversal order depends on the haystack input order and the reverse
option for the direction.
However, this input order can be altered by using compareFn
and orderByNeedles
.
['c', 'b', 'a']
(orderByNeedles)
const haystack = { b: 0, a: 1, c: 2 };
objectScan(['c', 'b', 'a'], {
filterFn: ({ context, property }) => { context.push(property); },
orderByNeedles: true
})(haystack, []);
// => [ 'c', 'b', 'a' ]
['**']
(compareFn)
const haystack = { b: 0, a: 1, c: 2 };
objectScan(['**'], {
filterFn: ({ context, property }) => { context.push(property); },
compareFn: () => (a, b) => b.localeCompare(a)
})(haystack, []);
// => [ 'a', 'b', 'c' ]
Note that compareFn
does not work on Arrays.
Both options can be combined, in which case orderByNeedles
supersedes compareFn
['c', '*']
(orderByNeedles and compareFn)
const haystack = { a: 0, b: 1, c: 2 };
objectScan(['c', '*'], {
filterFn: ({ context, property }) => { context.push(property); },
compareFn: () => (a, b) => b.localeCompare(a),
orderByNeedles: true
})(haystack, []);
// => [ 'c', 'a', 'b' ]
Top level object(s) are matched by the empty needle ''
or empty array []
.
This is useful for matching objects nested in arrays by setting useArraySelector
to false
.
To match the actual empty string as a key, use (^$)
.
Note that an empty string or empty array does not work to match top level objects with _.get or _.set.
Examples:
['']
(match top level objects in array)
const haystack = [{}, {}];
objectScan([''], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]
[[]]
(match top level objects in array)
const haystack = [1, 2];
objectScan([[]], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]
['']
(match top level object)
const haystack = {};
objectScan([''], { joined: true })(haystack);
// => [ '' ]
['**.(^$)']
(match empty string keys)
const haystack = { '': 0, a: { '': 1 } };
objectScan(['**.(^$)'])(haystack);
// => [ [ 'a', '' ], [ '' ] ]
['**(^a$)']
(star recursion matches roots)
const haystack = [0, [{ a: 1 }, 2]];
objectScan(['**(^a$)'], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1][1]', '[1][0].a', '[1][0]', '[0]' ]
String keys in an Array are not traversed.
['**']
(str key skipped)
const haystack = (() => { const r = ['a', 'b']; r.str = 'c'; return r; })();
objectScan(['**'], {
joined: true,
rtn: 'entry'
})(haystack);
// => [ [ '[1]', 'b' ], [ '[0]', 'a' ] ]
Only set keys are traversed for spare Arrays.
['**']
(empty entries skipped)
const haystack = (() => { const r = []; r[1] = 'a'; return r; })();
objectScan(['**'], {
joined: true,
rtn: 'entry'
})(haystack);
// => [ [ '[1]', 'a' ] ]
This library has been designed around performance as a core feature.
The implementation is completely recursion free. This allows
for traversal of deeply nested objects where a recursive approach
would fail with a Maximum call stack size exceeded
error.
Having a separate initialization stage allows for a performant search and significant speed-ups when applying the same search to different input.
Traversal happens depth-first, which allows for lower memory consumption.
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.