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

Options

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.

filterFn

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().

breakFn

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.

callbackFn

Type: function
Default: undefined

Called for every final result.

arrayCallbackFn

Type: function
Default: undefined

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

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

Edge Cases

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.

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.