object-scan

Object-Scan

Find Keys using Wildcard matching and optional value function.

Install

Install with npm:

$ npm install --save object-scan

Usage

const objectScan = require('object-scan');

objectScan(['a.*.f'])({ a: { b: { c: 'd' }, e: { f: 'g' } } });
// => [ 'a.e.f' ]

Features

• 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 matching with **
• Matches ordered so that they can safely be deleted from the input in order
• Simple or-clause for key and index with {a,b} and [{0,1}]
• Input is traversed exactly once and only unique results are returned.
• Full support for escaping
• Lots of tests to ensure correctness

Options

Note on Functions: Signature for all functions is Fn(key, value, { parents, isMatch, matchedBy, traversedBy }), 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 exactly matched by at least one key. Indicates valid (intermittent) result.
• matchedBy are all needles matching the key exactly.
• traversedBy are all needles involved in traversing the key

filterFn

Type: function
Default: undefined

Called for every exact match. Iff function is defined and returns false, the entry is excluded from the final result.

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

breakFn

Type: function
Default: undefined

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

callbackFn

Type: function
Default: undefined

Called for every final result.

arrayCallbackFn

Type: function
Default: undefined

Called when useArraySelector is false for every array where the direct non-array parent is matched.

joined

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.

escapePaths

Type: boolean
Default: true

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

useArraySelector

Type: boolean
Default: true

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

Examples

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

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

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

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

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

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

Edge Cases

The top level object(s) are matched by the empty needle "". Useful for matching objects nested in arrays by setting useArraySelector to false. Note that the empty string does not work with _.get and _.set.

Special Characters

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.