# Object-Scan
[](https://circleci.com/gh/blackflux/object-scan)
[](https://www.npmjs.com/package/object-scan)
[](https://www.npmjs.com/package/object-scan)
[](https://bundlephobia.com/package/object-scan)
[](./test/readme/replace-variables/ratio-badge.js)
Traverse object hierarchies using matching and callbacks.
## 1. Quickstart
### 1.1. Install
Using npm:
$ npm i object-scan
In a browser:
```html
```
### 1.2. Usage
```js
import objectScan from 'object-scan';
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' } } };
objectScan(['a.*.f'], { joined: true })(haystack);
// => [ 'a.e.f' ]
```
## 2. Table of Content
['[2]'] (exact in array)
```js
const haystack = [0, 1, 2, 3, 4];
objectScan(['[2]'], { joined: true })(haystack);
// => [ '[2]' ]
```
['[1]'] (no match in object)
```js
const haystack = { 0: 'a', 1: 'b', 2: 'c' };
objectScan(['[1]'], { joined: true })(haystack);
// => []
```
['foo'] (exact in object)
```js
const haystack = { foo: 0, bar: 1 };
objectScan(['foo'], { joined: true })(haystack);
// => [ 'foo' ]
```
['1'] (no match in array)
```js
const haystack = [0, 1, 2, 3, 4];
objectScan(['1'], { joined: true })(haystack);
// => []
```
['foo*'] (starting with `foo`)
```js
const haystack = { foo: 0, foobar: 1, bar: 2 };
objectScan(['foo*'], { joined: true })(haystack);
// => [ 'foobar', 'foo' ]
```
['*'] (top level)
```js
const haystack = { a: { b: 0, c: 1 }, d: 2 };
objectScan(['*'], { joined: true })(haystack);
// => [ 'd', 'a' ]
```
['[?5]'] (two digit ending in five)
```js
const haystack = [...Array(30).keys()];
objectScan(['[?5]'], { joined: true })(haystack);
// => [ '[25]', '[15]' ]
```
['a.+.c'] (nested)
```js
const haystack = { a: { b: { c: 0 }, d: { f: 0 } } };
objectScan(['a.+.c'], { joined: true })(haystack);
// => [ 'a.b.c' ]
```
['a.\\+.c'] (escaped)
```js
const haystack = { a: { b: { c: 0 }, '+': { c: 0 } } };
objectScan(['a.\\+.c'], { joined: true })(haystack);
// => [ 'a.\\+.c' ]
```
['(^foo)'] (starting with `foo`)
```js
const haystack = { foo: 0, foobar: 1, bar: 2 };
objectScan(['(^foo)'], { joined: true })(haystack);
// => [ 'foobar', 'foo' ]
```
['[(5)]'] (containing `5`)
```js
const haystack = [...Array(20).keys()];
objectScan(['[(5)]'], { joined: true })(haystack);
// => [ '[15]', '[5]' ]
```
['[(^[01]$)]'] (`[0]` and `[1]`)
```js
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[01]$)]'], { joined: true })(haystack);
// => [ '[1]', '[0]' ]
```
['[(^[^01]$)]'] (other than `[0]` and `[1]`)
```js
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[^01]$)]'], { joined: true })(haystack);
// => [ '[3]', '[2]' ]
```
['[{0,1}]'] (`[0]` and `[1]`)
```js
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`)
```js
const haystack = { a: { b: 0, c: 1 }, d: { e: 2, f: 3 } };
objectScan(['{a,d}.{b,f}'], { joined: true })(haystack);
// => [ 'd.f', 'a.b' ]
```
['a.**'] (zero or more nestings under `a`)
```js
const haystack = { a: { b: 0, c: 0 } };
objectScan(['a.**'], { joined: true })(haystack);
// => [ 'a.c', 'a.b', 'a' ]
```
['a.++'] (one or more nestings under `a`)
```js
const haystack = { a: { b: 0, c: 0 } };
objectScan(['a.++'], { joined: true })(haystack);
// => [ 'a.c', 'a.b' ]
```
['**(1)'] (all containing `1` at every level)
```js
const haystack = { 1: { 1: ['c', 'd'] }, 510: 'e', foo: { 1: 'f' } };
objectScan(['**(1)'], { joined: true })(haystack);
// => [ '510', '1.1[1]', '1.1', '1' ]
```
['++{[0][1]}'] (`cyclic path`)
```js
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`)
```js
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`)
```js
const haystack = [[[{ a: [1] }], [2]]];
objectScan(['**{[*]}'], { joined: true })(haystack);
// => [ '[0][1][0]', '[0][1]', '[0][0][0]', '[0][0]', '[0]' ]
```
['**{*}'] (`traverse only object`)
```js
const haystack = { a: [0, { b: 1 }], c: { d: 2 } };
objectScan(['**{*}'], { joined: true })(haystack);
// => [ 'c.d', 'c', 'a' ]
```
['a.**{b.c}'] (`zero or more times`)
```js
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`)
```js
const haystack = { a: { b: { c: { b: { c: 0 } } } } };
objectScan(['a.++{b.c}'], { joined: true })(haystack);
// => [ 'a.b.c.b.c', 'a.b.c' ]
```
['{a,b},!a'] (only `b`)
```js
const haystack = { a: 0, b: 1 };
objectScan(['{a,b},!a'], {
joined: true,
strict: false
})(haystack);
// => [ 'b' ]
```
['**,!**.a'] (all except ending in `a`)
```js
const haystack = { a: 0, b: { a: 1, c: 2 } };
objectScan(['**,!**.a'], { joined: true })(haystack);
// => [ 'b.c', 'b' ]
```
['[*]', '[!(^[01]$)]'] (exclude with regex)
```js
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[*]', '[!(^[01]$)]'], { joined: true })(haystack);
// => [ '[3]', '[2]' ]
```
`[`, `]`, `{`, `}`, `(`, `)`, `,`, `.`, `!`, `?`, `*`, `+` and `\`.
_Examples:_
['\\[1\\]'] (special object key)
```js
const haystack = { '[1]': 0 };
objectScan(['\\[1\\]'], { joined: true })(haystack);
// => [ '\\[1\\]' ]
```
[['a', 0, 'b']] (mixed path)
```js
const haystack = { a: [{ b: 0 }] };
objectScan([['a', 0, 'b']], { joined: true })(haystack);
// => [ 'a[0].b' ]
```
[['a.b', 0]] (implicit escape)
```js
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)
```js
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)
```js
const haystack = { a: [{ b: 0 }, { b: 0 }] };
objectScan([['a', 'b']], {
joined: true,
useArraySelector: false
})(haystack);
// => [ 'a[1].b', 'a[0].b' ]
```
['**.{c,d,e}'] (search context)
```js
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 }
```
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](#traversal_order).
This method is conceptually similar to
[Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter).
_Examples_:
['**'] (filter function)
```js
const haystack = { a: 0, b: 'bar' };
objectScan(['**'], {
joined: true,
filterFn: ({ value }) => typeof value === 'string'
})(haystack);
// => [ 'b' ]
```
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](#traversal_order).
_Examples_:
['**'] (break function)
```js
const haystack = { a: { b: { c: 0 } } };
objectScan(['**'], {
joined: true,
breakFn: ({ key }) => key === 'a.b'
})(haystack);
// => [ 'a.b', 'a' ]
```
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)
```js
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)
```js
const haystack = { a: 0, b: 1 };
objectScan(['**'], {
joined: true,
beforeFn: ({ haystack: h }) => Object.keys(h),
rtn: ['key', 'value']
})(haystack);
// => [ [ '[1]', 'b' ], [ '[0]', 'a' ] ]
```
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)
```js
const haystack = { a: 0 };
objectScan(['**'], {
afterFn: ({ result, context }) => result + context,
rtn: 'count'
})(haystack, 5);
// => 6
```
['**'] (post-processing result)
```js
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)
```js
const haystack = {};
objectScan(['**'], {
beforeFn: (state) => { /* eslint-disable no-param-reassign */ state.custom = 7; },
afterFn: (state) => state.custom
})(haystack);
// => 7
```
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](#traversal_order) for more information.
_Examples_:
['**'] (simple sort)
```js
const haystack = { a: 0, c: 1, b: 2 };
objectScan(['**'], {
joined: true,
compareFn: () => (k1, k2) => k1.localeCompare(k2),
reverse: false
})(haystack);
// => [ 'a', 'b', 'c' ]
```
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](#traversal_order) for more information.
_Examples_:
['**'] (breakFn, reverse true)
```js
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)
```js
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)
```js
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)
```js
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' ]
```
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)
```js
const haystack = { a: 0, b: 1, c: 1 };
objectScan(['c', 'a', 'b'], {
joined: true,
orderByNeedles: true
})(haystack);
// => [ 'c', 'a', 'b' ]
```
['b', '*'] (fallback reverse)
```js
const haystack = { a: 0, b: 1, c: 1 };
objectScan(['b', '*'], {
joined: true,
reverse: true,
orderByNeedles: true
})(haystack);
// => [ 'b', 'c', 'a' ]
```
['b', '*'] (fallback not reverse)
```js
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)
```js
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)
```js
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' ]
```
Default: `false`
When set to `true` the traversal immediately returns after the first match.
_Examples_:
['a', 'b'] (only return first property)
```js
const haystack = { a: 0, b: 1 };
objectScan(['a', 'b'], {
rtn: 'property',
abort: true
})(haystack);
// => 'b'
```
['[0]', '[1]'] (abort changes count)
```js
const haystack = ['a', 'b'];
objectScan(['[0]', '[1]'], {
rtn: 'count',
abort: true
})(haystack);
// => 1
```
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)
```js
const haystack = ['a', 'b', 'c'];
objectScan(['[*]'], { rtn: 'value' })(haystack);
// => [ 'c', 'b', 'a' ]
```
['foo[*]'] (return entries)
```js
const haystack = { foo: ['bar'] };
objectScan(['foo[*]'], { rtn: 'entry' })(haystack);
// => [ [ [ 'foo', 0 ], 'bar' ] ]
```
['a.b.c', 'a'] (return properties)
```js
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)
```js
const haystack = { a: { b: 0, c: 1 } };
objectScan(['a.b', 'a.c'], { rtn: 'bool' })(haystack);
// => true
```
['**'] (return not provided context)
```js
const haystack = { a: 0 };
objectScan(['**'], { rtn: 'context' })(haystack);
// => undefined
```
['a.b.{c,d}'] (return keys with context passed)
```js
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)
```js
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)
```js
const haystack = { a: { b: { c: 0, d: 1 } } };
objectScan(['**'], {
filterFn: ({ isLeaf }) => isLeaf,
rtn: ({ value }) => value + 1
})(haystack);
// => [ 2, 1 ]
```
['**'] (return sum)
```js
const haystack = { a: { b: { c: -2, d: 1 }, e: [3, 7] } };
objectScan(['**'], {
filterFn: ({ value }) => typeof value === 'number',
rtn: 'sum'
})(haystack);
// => 9
```
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](https://lodash.com/docs/#get) and [_.set](https://lodash.com/docs/#set) fully support lists.
_Examples_:
['[*]', '[*].foo'] (joined)
```js
const haystack = [0, 1, { foo: 'bar' }];
objectScan(['[*]', '[*].foo'], { joined: true })(haystack);
// => [ '[2].foo', '[2]', '[1]', '[0]' ]
```
['[*]', '[*].foo'] (not joined)
```js
const haystack = [0, 1, { foo: 'bar' }];
objectScan(['[*]', '[*].foo'])(haystack);
// => [ [ 2, 'foo' ], [ 2 ], [ 1 ], [ 0 ] ]
```
['**.c'] (joined, getKey)
```js
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)
```js
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 ] ] ]
```
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)
```js
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)
```js
const haystack = [{ a: 0 }, { b: 1 }];
objectScan([''], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]
```
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)
```js
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)
```js
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)
```js
const haystack = [];
objectScan(['a.b', 'a.**'], { joined: true })(haystack);
// => 'Error: Needle Target Invalidated: "a.b" by "a.**"'
```
['**.!**'] (consecutive recursion)
```js
const haystack = [];
objectScan(['**.!**'], { joined: true })(haystack);
// => 'Error: Redundant Recursion: "**.!**"'
```
[2]: _[Depth-first](https://en.wikipedia.org/wiki/Tree_traversal#Depth-first_search) traversal. See [here](#traversal_order) for details_
[3]: _[Depth-first](https://en.wikipedia.org/wiki/Tree_traversal#Depth-first_search) traversal in in Pre-order_
[4]: _[Custom depth-first](https://cs.stackexchange.com/questions/99440) traversal_
[5]: _[Reference](https://github.com/jmespath/jmespath.py/issues/110)_
[6]: _[Documentation](#callbacks)_
[7]: _Usefulness limited since context is lacking information_
[8]: _Path deduplication has to be done in custom code_
[9]: _[Reference](https://stackoverflow.com/questions/55497833/jsonpath-union-of-multiple-different-paths)_
## 7. Examples
### 7.1. Real World Uses
Noteworthy [dependents](https://github.com/blackflux/object-scan/network/dependents) are:
- [object-fields](https://github.com/blackflux/object-fields): Showcases how to retain only certain nested keys from object
- [object-lib](https://github.com/blackflux/object-lib): Good example of more advanced use cases
- [object-rewrite](https://github.com/blackflux/object-rewrite): The original reason for creating this library
Many other examples can be found on [Stack Overflow](https://stackoverflow.com/search?q=%5Bjavascript%5D+object-scan+user%3A1030413).
### 7.2. Other Examples
More extensive examples can be found in the tests.
['a.*.f'] (nested)
```js
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)
```js
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)
```js
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)
```js
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)
```js
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)
```js
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['*[*]'], { joined: true })(haystack);
// => []
```
['**'] (star recursion)
```js
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)
```js
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)
```js
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)
```js
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)
```js
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)
```js
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**.(^[bc]$)'], { joined: true })(haystack);
// => [ 'a.b.c', 'a.b' ]
```
['**'] (Reverse Pre-order)
```js
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)
```js
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)
```js
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)
```js
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' ]
```
['**'] (Deleting from Array)
```js
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 ]
```
['**'] (Deleting from Array Unexpected)
```js
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 ]
```
['c', 'b', 'a'] (orderByNeedles)
```js
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)
```js
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' ]
```
['c', '*'] (orderByNeedles and compareFn)
```js
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' ]
```
[''] (match top level objects in array)
```js
const haystack = [{}, {}];
objectScan([''], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]
```
[[]] (match top level objects in array)
```js
const haystack = [1, 2];
objectScan([[]], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]
```
[''] (match top level object)
```js
const haystack = {};
objectScan([''], { joined: true })(haystack);
// => [ '' ]
```
['**.(^$)'] (match empty string keys)
```js
const haystack = { '': 0, a: { '': 1 } };
objectScan(['**.(^$)'])(haystack);
// => [ [ 'a', '' ], [ '' ] ]
```
['**(^a$)'] (star recursion matches roots)
```js
const haystack = [0, [{ a: 1 }, 2]];
objectScan(['**(^a$)'], {
joined: true,
useArraySelector: false
})(haystack);
// => [ '[1][1]', '[1][0].a', '[1][0]', '[0]' ]
```
['**'] (str key skipped)
```js
const haystack = (() => { const r = ['a', 'b']; r.str = 'c'; return r; })();
objectScan(['**'], {
joined: true,
rtn: 'entry'
})(haystack);
// => [ [ '[1]', 'b' ], [ '[0]', 'a' ] ]
```
['**'] (empty entries skipped)
```js
const haystack = (() => { const r = []; r[1] = 'a'; return r; })();
objectScan(['**'], {
joined: true,
rtn: 'entry'
})(haystack);
// => [ [ '[1]', 'a' ] ]
```