Package Health Score

51 / 100

security
No known security issues
popularity
Small
maintenance
Inactive
community
Limited

Explore Similar Packages

Security

No known security issues

All security vulnerabilities belong to production dependencies of direct and indirect packages.

Security and license risk for significant versions

Version				Vulnerabilities	License Risk
19.0.5	\|	10/2023		0 C 0 H 0 M 0 L	0 H 0 M 0 L
18.5.1	\|	09/2022		0 C 0 H 0 M 0 L	0 H 0 M 0 L
17.1.0	\|	10/2021	Popular	0 C 0 H 0 M 0 L	0 H 0 M 0 L
16.1.1	\|	08/2021		0 C 0 H 0 M 0 L	0 H 0 M 0 L
16.0.3	\|	07/2021		0 C 0 H 0 M 0 L	0 H 0 M 0 L

License

MIT

Security Policy

Is your project affected by vulnerabilities?

Scan your projects for vulnerabilities. Fix quickly with automated fixes. Get started with Snyk for free.

Get started free

Popularity

Small

Weekly Downloads (4,480)

GitHub Stars: 167
Forks: 16
Contributors: 9

Direct Usage Popularity

The npm package object-scan receives a total of 4,480 downloads a week. As such, we scored object-scan popularity level to be Small.

Based on project statistics from the GitHub repository for the npm package object-scan, we found that it has been starred 167 times.

Downloads are calculated as moving averages for a period of the last 12 months, excluding weekends and known missing data points.

Community

Limited

Readme.md: Yes
Contributing.md: No
Code of Conduct: No
Contributors: 9
Funding: No

This project has seen only 10 or less contributors.

We found a way for you to contribute to the project! Looks like object-scan is missing a Code of Conduct.

Embed Package Health Score Badge

Maintenance

Inactive

Commit Frequency

No Recent Commits

Open Issues: 13
Open PR: 2
Last Release: 1 year ago
Last Commit: 1 year ago

Further analysis of the maintenance status of object-scan based on released npm versions cadence, the repository activity, and other data points determined that its maintenance is Inactive.

An important project maintenance signal to consider for object-scan is that it hasn't seen any new versions released to npm in the past 12 months, and could be considered as a discontinued project, or that which receives low attention from its maintainers.

In the past month we didn't find any pull request activity or change in issues status has been detected for the GitHub repository.

Keep your project healthy

Check your package.json

Ensure all the packages you're using are healthy and well-maintained

Snyk Vulnerability Scanner

Get health score & security insights directly in your IDE

Package

Node.js Compatibility: >= 16

Age: 6 years
Dependencies: 0 Direct
Versions: 201
Install Size: 163 kB
Dist-tags: 1
# of Files: 20
Maintainers: 1
TS Typings: No

object-scan has more than a single and default latest tag published for the npm package. This means, there may be other tags available for this package, such as next to indicate future releases, or stable to indicate stable releases.

Readme

Object-Scan

Traverse object hierarchies using matching and callbacks.

1. Quickstart

1.1. Install

Using npm:

$ npm i object-scan

In a browser:

1.2. Usage

import objectScan from 'object-scan';

const haystack = { a: { b: { c: 'd' }, e: { f: 'g' } } };
objectScan(['a.*.f'], { joined: true })(haystack);
// =&gt; [ 'a.e.f' ]

2. Table of Content

3. Features

Input traversed at most once during search
Dependency free and tiny bundle size
Powerful matching syntax
Very performant
Extensive tests and lots of examples

4. Matching

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

4.1. Array

Rectangular brackets for array path matching.

Examples:

['[2]'] (exact in array)

const haystack = [0, 1, 2, 3, 4];
objectScan(['[2]'], { joined: true })(haystack);
// =&gt; [ '[2]' ]

['[1]'] (no match in object)

const haystack = { 0: 'a', 1: 'b', 2: 'c' };
objectScan(['[1]'], { joined: true })(haystack);
// =&gt; []

4.2. Object

Property name for object property matching.

Examples:

['foo'] (exact in object)

const haystack = { foo: 0, bar: 1 };
objectScan(['foo'], { joined: true })(haystack);
// =&gt; [ 'foo' ]

['1'] (no match in array)

const haystack = [0, 1, 2, 3, 4];
objectScan(['1'], { joined: true })(haystack);
// =&gt; []

4.3. Wildcard

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);
// =&gt; [ 'foobar', 'foo' ]

['*'] (top level)

const haystack = { a: { b: 0, c: 1 }, d: 2 };
objectScan(['*'], { joined: true })(haystack);
// =&gt; [ 'd', 'a' ]

['[?5]'] (two digit ending in five)

const haystack = [...Array(30).keys()];
objectScan(['[?5]'], { joined: true })(haystack);
// =&gt; [ '[25]', '[15]' ]

['a.+.c'] (nested)

const haystack = { a: { b: { c: 0 }, d: { f: 0 } } };
objectScan(['a.+.c'], { joined: true })(haystack);
// =&gt; [ 'a.b.c' ]

['a.\\+.c'] (escaped)

const haystack = { a: { b: { c: 0 }, '+': { c: 0 } } };
objectScan(['a.\\+.c'], { joined: true })(haystack);
// =&gt; [ 'a.\\+.c' ]

4.4. Regex

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);
// =&gt; [ 'foobar', 'foo' ]

['[(5)]'] (containing `5`)

const haystack = [...Array(20).keys()];
objectScan(['[(5)]'], { joined: true })(haystack);
// =&gt; [ '[15]', '[5]' ]

['[(^[01]$)]'] (`[0]` and `[1]`)

const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[01]$)]'], { joined: true })(haystack);
// =&gt; [ '[1]', '[0]' ]

['[(^[^01]$)]'] (other than `[0]` and `[1]`)

const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[^01]$)]'], { joined: true })(haystack);
// =&gt; [ '[3]', '[2]' ]

4.5. Or Clause

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);
// =&gt; [ '[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);
// =&gt; [ 'd.f', 'a.b' ]

4.6. Arbitrary Depth

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);
// =&gt; [ 'a.c', 'a.b', 'a' ]

['a.++'] (one or more nestings under `a`)

const haystack = { a: { b: 0, c: 0 } };
objectScan(['a.++'], { joined: true })(haystack);
// =&gt; [ '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);
// =&gt; [ '510', '1.1[1]', '1.1', '1' ]

4.7. Nested Path Recursion

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);
// =&gt; [ '[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);
// =&gt; [ '[1][1]', '[1][0]', '[1]', '[0][1]', '[0][0]', '[0]' ]

['**{[*]}'] (`traverse only array`)

const haystack = [[[{ a: [1] }], [2]]];
objectScan(['**{[*]}'], { joined: true })(haystack);
// =&gt; [ '[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);
// =&gt; [ '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);
// =&gt; [ '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);
// =&gt; [ 'a.b.c.b.c', 'a.b.c' ]

4.8. Exclusion

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);
// =&gt; [ 'b' ]

['**,!**.a'] (all except ending in `a`)

const haystack = { a: 0, b: { a: 1, c: 2 } };
objectScan(['**,!**.a'], { joined: true })(haystack);
// =&gt; [ 'b.c', 'b' ]

['[*]', '[!(^[01]$)]'] (exclude with regex)

const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[*]', '[!(^[01]$)]'], { joined: true })(haystack);
// =&gt; [ '[3]', '[2]' ]

4.9. Escaping

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);
// =&gt; [ '\\[1\\]' ]

4.10. Array Needles

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 with strings
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);
// =&gt; [ '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);
// =&gt; [ 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);
// =&gt; [ [ [ '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);
// =&gt; [ 'a[1].b', 'a[0].b' ]

5. Options

Signature of all callbacks is

Fn({ key, value, ... })

where:

key: key that callback is invoked for (respects joined 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 iff value contained in parents
isLeaf: true iff value can not be traversed
depth: length of key
result: intermittent result as defined by rtn
getKey(joined?: boolean): function that returns key
getValue: function that returns value
getEntry(joined?: boolean): function that returns entry
getProperty: function that returns property
getGproperty: function that returns gproperty
getParent: function that returns parent
getGparent: function that returns gparent
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
getIsLeaf: function that returns isLeaf
getDepth: function that returns depth
getResult: function that returns result
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 }) =&gt; { context.sum += value; }
})(haystack, { sum: 0 });
// =&gt; { sum: 20 }

5.1. filterFn

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 }) =&gt; typeof value === 'string'
})(haystack);
// =&gt; [ 'b' ]

5.2. breakFn

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 }) =&gt; key === 'a.b'
})(haystack);
// =&gt; [ 'a.b', 'a' ]

5.3. beforeFn

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 }) =&gt; [h, c],
  rtn: 'key'
})(haystack, { b: 0 });
// =&gt; [ '[1].b', '[1]', '[0].a', '[0]' ]

['**'] (pre-processing haystack)

const haystack = { a: 0, b: 1 };
objectScan(['**'], {
  joined: true,
  beforeFn: ({ haystack: h }) =&gt; Object.keys(h),
  rtn: ['key', 'value']
})(haystack);
// =&gt; [ [ '[1]', 'b' ], [ '[0]', 'a' ] ]

5.4. afterFn

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 }) =&gt; result + context,
  rtn: 'count'
})(haystack, 5);
// =&gt; 6

['**'] (post-processing result)

const haystack = { a: 0, b: 3, c: 4 };
objectScan(['**'], {
  afterFn: ({ result }) =&gt; result.filter((v) =&gt; v &gt; 3),
  rtn: 'value'
})(haystack);
// =&gt; [ 4 ]

['**'] (pass data from beforeFn to afterFn)

const haystack = {};
objectScan(['**'], {
  beforeFn: (state) =&gt; { /* eslint-disable no-param-reassign */ state.custom = 7; },
  afterFn: (state) =&gt; state.custom
})(haystack);
// =&gt; 7

5.5. compareFn

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: () =&gt; (k1, k2) =&gt; k1.localeCompare(k2),
  reverse: false
})(haystack);
// =&gt; [ 'a', 'b', 'c' ]

5.6. reverse

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 }) =&gt; { if (isMatch) { context.push(property); } },
  reverse: true
})(haystack, []);
// =&gt; [ '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 }) =&gt; { context.push(property); },
  reverse: true
})(haystack, []);
// =&gt; [ '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 }) =&gt; { if (isMatch) { context.push(property); } },
  reverse: false
})(haystack, []);
// =&gt; [ '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 }) =&gt; { context.push(property); },
  reverse: false
})(haystack, []);
// =&gt; [ 'a', 'c', 'e', 'd', 'b', 'h', 'i', 'g', 'f' ]

5.7. orderByNeedles

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);
// =&gt; [ 'c', 'a', 'b' ]

['b', '*'] (fallback reverse)

const haystack = { a: 0, b: 1, c: 1 };
objectScan(['b', '*'], {
  joined: true,
  reverse: true,
  orderByNeedles: true
})(haystack);
// =&gt; [ 'b', 'c', 'a' ]

['b', '*'] (fallback not reverse)

const haystack = { a: 0, b: 1, c: 1 };
objectScan(['b', '*'], {
  joined: true,
  reverse: false,
  orderByNeedles: true
})(haystack);
// =&gt; [ '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);
// =&gt; [ '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);
// =&gt; [ 'b.c', 'b', 'a', 'd' ]

5.8. abort

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);
// =&gt; 'b'

['[0]', '[1]'] (abort changes count)

const haystack = ['a', 'b'];
objectScan(['[0]', '[1]'], {
  rtn: 'count',
  abort: true
})(haystack);
// =&gt; 1

5.9. rtn

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 returned
key: as passed into filterFn
value: as passed into filterFn
entry: as passed into filterFn
property: as passed into filterFn
gproperty: as passed into filterFn
parent: as passed into filterFn
gparent: as passed into filterFn
parents: as passed into filterFn
isMatch: as passed into filterFn
matchedBy: as passed into filterFn
excludedBy: as passed into filterFn
traversedBy: as passed into filterFn
isCircular: as passed into filterFn
isLeaf: as passed into filterFn
depth: as passed into filterFn
bool: returns true iff a match is found
count: returns the match count
sum: 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);
// =&gt; [ 'c', 'b', 'a' ]

['foo[*]'] (return entries)

const haystack = { foo: ['bar'] };
objectScan(['foo[*]'], { rtn: 'entry' })(haystack);
// =&gt; [ [ [ 'foo', 0 ], 'bar' ] ]

['a.b.c', 'a'] (return properties)

const haystack = { a: { b: { c: 0 } } };
objectScan(['a.b.c', 'a'], { rtn: 'property' })(haystack);
// =&gt; [ '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);
// =&gt; true

['**'] (return not provided context)

const haystack = { a: 0 };
objectScan(['**'], { rtn: 'context' })(haystack);
// =&gt; 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, []);
// =&gt; [ [ '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, []);
// =&gt; [ [ 'd', 1 ], [ 'c', 0 ] ]

['**'] (return value plus one)

const haystack = { a: { b: { c: 0, d: 1 } } };
objectScan(['**'], {
  filterFn: ({ isLeaf }) =&gt; isLeaf,
  rtn: ({ value }) =&gt; value + 1
})(haystack);
// =&gt; [ 2, 1 ]

['**'] (return sum)

const haystack = { a: { b: { c: -2, d: 1 }, e: [3, 7] } };
objectScan(['**'], {
  filterFn: ({ value }) =&gt; typeof value === 'number',
  rtn: 'sum'
})(haystack);
// =&gt; 9

5.10. joined

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);
// =&gt; [ '[2].foo', '[2]', '[1]', '[0]' ]

['[*]', '[*].foo'] (not joined)

const haystack = [0, 1, { foo: 'bar' }];
objectScan(['[*]', '[*].foo'])(haystack);
// =&gt; [ [ 2, 'foo' ], [ 2 ], [ 1 ], [ 0 ] ]

['**.c'] (joined, getKey)

const haystack = { a: { b: { c: 0 } } };
objectScan(['**.c'], {
  joined: true,
  rtn: ({ getKey }) =&gt; [getKey(true), getKey(false), getKey()]
})(haystack);
// =&gt; [ [ 'a.b.c', [ 'a', 'b', 'c' ], 'a.b.c' ] ]

['**.c'] (not joined, getEntry)

const haystack = { a: { b: { c: 0 } } };
objectScan(['**.c'], { rtn: ({ getEntry }) =&gt; [getEntry(true), getEntry(false), getEntry()] })(haystack);
// =&gt; [ [ [ 'a.b.c', 0 ], [ [ 'a', 'b', 'c' ], 0 ], [ [ 'a', 'b', 'c' ], 0 ] ] ]

5.11. useArraySelector

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);
// =&gt; [ '[1].b[1].d', '[0].a' ]

[''] (top level array matching)

const haystack = [{ a: 0 }, { b: 1 }];
objectScan([''], {
  joined: true,
  useArraySelector: false
})(haystack);
// =&gt; [ '[1]', '[0]' ]

5.12. strict

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);
// =&gt; 'Error: Redundant Needle Target: "a.b" vs "a.b"'

['a.{b,b}'] (identical, same needle)

const haystack = [];
objectScan(['a.{b,b}'], { joined: true })(haystack);
// =&gt; '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);
// =&gt; 'Error: Needle Target Invalidated: "a.b" by "a.**"'

['**.!**'] (consecutive recursion)

const haystack = [];
objectScan(['**.!**'], { joined: true })(haystack);
// =&gt; 'Error: Redundant Recursion: "**.!**"'

6. Competitors

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	jmespath
Get Key						-
Get Value
Conditional Path	^[1]	^[1]
Recursive Traversal	^[2]	^[2]	^[3]	^[3]	![](https://img.shields.io/badge/2.63x-6c961c?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAAAXNSR0IArs4c6QAAAN5QTFRFAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAqTW0FQAAAEl0Uk5TAAECAwUKCwwQERQWFxkbHCInKDEzNTg5PkVHSEpRU1VXWV5fb3R1eHp7fn+AhIaLjZeboaaorK2ys7fW19jZ6ery8/f4+fv9/sHJynAAAAEzSU

FAQs

What is object-scan?

Traverse object hierarchies using matching and callbacks. Visit Snyk Advisor to see a full health score report for object-scan, including popularity, security, maintenance & community analysis.

Is object-scan popular?

The npm package object-scan receives a total of 4,480 weekly downloads. As such, object-scan popularity was classified as small. Visit the popularity section on Snyk Advisor to see the full health analysis.

Is object-scan well maintained?

We found indications that object-scan is an Inactive project. See the full package health analysis to learn more about the package maintenance status.

Is object-scan safe to use?

The npm package object-scan was scanned for known vulnerabilities and missing license, and no issues were found. Thus the package was deemed as safe to use. See the full health analysis review.

Last updated on 12 November-2024, at 13:05 (UTC).

Build a secure application checklist

Select a recommended open source package

Minimize your risk by selecting secure & well maintained open source packages

DONE

Scan your app for vulnerabilities

Scan your application to find vulnerabilities in your: source code, open source dependencies, containers and configuration files

SCAN NOW

Fix identified vulnerabilities

Easily fix your code by leveraging automatically generated PRs

AUTO FIX

Monitor for new issues

New vulnerabilities are discovered every day. Get notified if your application is affected

MONITOR APP

Package Health Score

Explore Similar Packages

Security and license risk for significant versions

Is your project affected by vulnerabilities?

Weekly Downloads (4,480)

Direct Usage Popularity

Embed Package Health Score Badge

Commit Frequency

Keep your project healthy

Check your package.json

Snyk Vulnerability Scanner

Readme

Object-Scan

1. Quickstart

1.1. Install

1.2. Usage

2. Table of Content

3. Features

4. Matching

4.1. Array

4.2. Object

4.3. Wildcard

4.4. Regex

4.5. Or Clause

4.6. Arbitrary Depth

4.7. Nested Path Recursion

4.8. Exclusion

4.9. Escaping

4.10. Array Needles

5. Options

5.1. filterFn

5.2. breakFn

5.3. beforeFn

5.4. afterFn

5.5. compareFn

5.6. reverse

5.7. orderByNeedles

5.8. abort

5.9. rtn

5.10. joined

5.11. useArraySelector

5.12. strict

6. Competitors

object-scan development dependencies

FAQs

What is object-scan?

Is object-scan popular?

Is object-scan well maintained?

Is object-scan safe to use?

Build a secure application checklist

Select a recommended open source package

Scan your app for vulnerabilities

Source Code

Open Source

Container

Config

Fix identified vulnerabilities

Monitor for new issues