Find Keys using Wildcard matching and optional value function.

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' ]

• Object and array matching with e.g. key.path and [1]
• Key and index wildcard matching with * and [*]
• Partial key and index wildcard matching, e.g. mark* or [1*]
• Infinite nested matches with **
• Simple or-clause for key and index with {a,b} and [{0,1}]
• Full support for escaping
• Lots of tests to ensure correctness

Note on Functions: Signature for all functions is Fn(key, value, { parents, isMatch, needle, needles }), where:

• key is the key that the function is called for (respects joined option).
• value is the value of that key.
• parents is an array containing all parents as [parent, grandparent, ...]. Contains parents that are arrays only iff useArraySelector is true.
• isMatch is true if this is a valid (intermittent) result.
• needle is the needle that matches if isMatch is true, otherwise null.
• needles are all needles that triggered the function call.

Type: function
Default: undefined

Called for every intermittent result. If function is defined and returns false, the entry is excluded from the final result.

This method is conceptually similar to Array.filter().

Type: function
Default: undefined

Called for every key (at least once) that could be (part of) a match. If function is defined and returns true, all nested entries under the current key are excluded from search and from the final result.

Type: function
Default: undefined

Called for every final result.

Type: function
Default: undefined

Called when useArraySelector is false for every array that contains top level matches.

Type: boolean
Default: true

Can be set to false to return each key as a list. When dealing with special characters this can be useful.

Important: Setting this to false improves performance.

Type: boolean
Default: `true

When set to false, joined paths for functions and the final result are not escaped.

Type: boolean
Default: `true

When set to false no array selectors are used and arrays are automatically traversed.

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(["*"])(obj);
// => ["a", "k"]

// nested keys
objectScan(["a.*.f"])(obj);
// => ["a.e.f"]
objectScan(["*.*.*"])(obj);
// => ["a.b.c", "a.e.f"]

// or filter
objectScan(["a.*.{c,f}"])(obj);
// => ["a.b.c", "a.e.f"]
objectScan(["a.*.{c,f}"], { joined: false })(obj);
// => [["a", "b", "c"], ["a", "e", "f"]]

// list filter
objectScan(["*.*[*]"])(obj);
// => ["a.h[0]", "a.h[1]"]
objectScan(["*[*]"])(obj);
// => []

// deep star filter
objectScan(["**"])(obj);
// => ["a", "a.b", "a.b.c", "a.e", "a.e.f", "a.h", "a.h[0]", "a.h[1]", "k"]
objectScan(["**.f"])(obj);
// => ["a.e.f"]
objectScan(["**[*]"])(obj);
// => ["a.h[0]", "a.h[1]"]

// value function
objectScan(["**"], { filterFn: (key, value) => typeof value === "string" })(obj);
// => ["a.b.c", "a.e.f", "a.h[0]", "a.h[1]", "k"]
objectScan(["**"], { breakFn: key => key === "a.b" })(obj);
// => ["a", "a.b", "a.e", "a.e.f", "a.h", "a.h[0]", "a.h[1]", "k"]

The empty needle "" matches top level object(s). 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 *.

When dealing with special characters the joined option might be desirable to set to false.