npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2021 – Pkg Stats / Ryan Hefner

object-scan

v17.0.1

Published

Traverse object hierarchies using matching and callbacks.

Downloads

42,604

Readme

Object-Scan

Build Status Test Coverage Dependabot Status Dependencies NPM Downloads Semantic-Release Gardener

Traverse object hierarchies using matching and callbacks.

Install

Install with npm:

$ npm install --save object-scan

Usage

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

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

Features

  • Input traversed exactly once during search
  • Dependency free, small in size and very performant
  • Separate Object and Array matching
  • Wildcard and Regex matching
  • Arbitrary depth matching
  • Or-clause Syntax
  • Exclusion Matching
  • Full support for escaping
  • Traversal in "delete-safe" order
  • Recursion free implementation
  • Search syntax validated
  • Lots of tests and examples

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

Array

Rectangular brackets for array path matching.

Examples:

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

Object

Property name for object property matching.

Examples:

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

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

Wildcards can be used with Array and Object selector.

Examples:

const haystack = { a: { b: 0, c: 1 }, d: 2 };
objectScan(['*'], { joined: true })(haystack);
// => [ 'd', 'a' ]
const haystack = [...Array(30).keys()];
objectScan(['[?5]'], { joined: true })(haystack);
// => [ '[25]', '[15]' ]
const haystack = { a: { b: { c: 0 }, d: { f: 0 } } };
objectScan(['a.+.c'], { joined: true })(haystack);
// => [ 'a.b.c' ]
const haystack = { a: { b: { c: 0 }, '+': { c: 0 } } };
objectScan(['a.\\+.c'], { joined: true })(haystack);
// => [ 'a.\\+.c' ]

Regex

Regex are defined by using parentheses.

Can be used with Array and Object selector.

Examples:

const haystack = { foo: 0, foobar: 1, bar: 2 };
objectScan(['(^foo)'], { joined: true })(haystack);
// => [ 'foobar', 'foo' ]
const haystack = [...Array(20).keys()];
objectScan(['[(5)]'], { joined: true })(haystack);
// => [ '[15]', '[5]' ]
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[01]$)]'], { joined: true })(haystack);
// => [ '[1]', '[0]' ]
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[(^[^01]$)]'], { joined: true })(haystack);
// => [ '[3]', '[2]' ]
const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[*]', '[!(^[01]$)]'], { joined: true })(haystack);
// => [ '[3]', '[2]' ]

Arbitrary Depth

There are two types of arbitrary depth matching:

  • **: Matches zero or more nestings
  • ++: Matches one or more nestings

Recursions can be combined with a regex by appending the regex.

Examples:

const haystack = { a: { b: 0, c: 0 } };
objectScan(['a.**'], { joined: true })(haystack);
// => [ 'a.c', 'a.b', 'a' ]
const haystack = { a: { b: 0, c: 0 } };
objectScan(['a.++'], { joined: true })(haystack);
// => [ 'a.c', 'a.b' ]
const haystack = { 1: { 1: ['c', 'd'] }, 510: 'e', foo: { 1: 'f' } };
objectScan(['**(1)'], { joined: true })(haystack);
// => [ '510', '1.1[1]', '1.1', '1' ]

Or Clause

Or Clauses are defined by using curley brackets.

Can be used with Array and Object selector.

Examples:

const haystack = ['a', 'b', 'c', 'd'];
objectScan(['[{0,1}]'], { joined: true })(haystack);
// => [ '[1]', '[0]' ]
const haystack = { a: { b: 0, c: 1 }, d: { e: 2, f: 3 } };
objectScan(['{a,d}.{b,f}'], { joined: true })(haystack);
// => [ 'd.f', 'a.b' ]

Exclusion

To exclude a path, use exclamation mark.

Examples:

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

Escaping

The following characters are considered special and need to be escaped using \, if they should be matched in a key: [, ], {, }, (, ), ,, ., !, ?, *, + and \.

Examples:

const haystack = { '[1]': 0 };
objectScan(['\\[1\\]'], { joined: true })(haystack);
// => [ '\\[1\\]' ]

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: function that returns key
  • getValue: function that returns value
  • getEntry: 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.

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.

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

Examples:

const haystack = { a: 0, b: 'bar' };
objectScan(['**'], {
  joined: true,
  filterFn: ({ value }) => typeof value === 'string'
})(haystack);
// => [ 'b' ]

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.

Examples:

const haystack = { a: { b: { c: 0 } } };
objectScan(['**'], {
  joined: true,
  breakFn: ({ key }) => key === 'a.b'
})(haystack);
// => [ 'a.b', 'a' ]

beforeFn

Type: function Default: undefined

When defined, this function is called before traversal as beforeFn(state = { haystack, context }) and state.haystack is then traversed using state.context.

Examples:

const haystack = { a: 0 };
objectScan(['**'], {
  joined: true,
  beforeFn: (state) => { /* eslint-disable no-param-reassign */ state.haystack = [state.haystack, state.context]; },
  rtn: 'key'
})(haystack, { b: 0 });
// => [ '[1].b', '[1]', '[0].a', '[0]' ]

afterFn

Type: function Default: undefined

When defined, this function is called after traversal as afterFn(state = { result, haystack, context }) and state.result is then returned from the search invocation.

Examples:

const haystack = { a: 0 };
objectScan(['**'], {
  afterFn: (state) => { /* eslint-disable no-param-reassign */ state.result += state.context; },
  rtn: 'count'
})(haystack, 5);
// => 6

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.

Examples:

const haystack = { a: 0, c: 1, b: 2 };
objectScan(['**'], {
  joined: true,
  compareFn: () => (k1, k2) => k1.localeCompare(k2),
  reverse: false
})(haystack);
// => [ 'a', 'b', 'c' ]

reverse

Type: boolean Default: true

When set to true, the scan 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 scan is delete-safe. I.e. property can be deleted / spliced from parent object / array in filterFn.

Examples:

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

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:

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

abort

Type: boolean Default: false

When set to true the scan immediately returns after the first match.

Examples:

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

rtn

Type: string or array 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

Or, when set as an array, can contain any of the above except context, bool and count.

When abort is set to true and the result would be a list, the first match or undefined is returned.

Examples:

const haystack = ['a', 'b', 'c'];
objectScan(['[*]'], { rtn: 'value' })(haystack);
// => [ 'c', 'b', 'a' ]
const haystack = { foo: ['bar'] };
objectScan(['foo[*]'], { rtn: 'entry' })(haystack);
// => [ [ [ 'foo', 0 ], 'bar' ] ]
const haystack = { a: { b: { c: 0 } } };
objectScan(['a.b.c', 'a'], { rtn: 'property' })(haystack);
// => [ 'c', 'a' ]
const haystack = { a: { b: 0, c: 1 } };
objectScan(['a.b', 'a.c'], { rtn: 'bool' })(haystack);
// => true
const haystack = { a: 0 };
objectScan(['**'], { rtn: 'context' })(haystack);
// => undefined
const haystack = { a: { b: { c: 0, d: 1 } } };
objectScan(['a.b.{c,d}'], { rtn: 'key' })(haystack, []);
// => [ [ 'a', 'b', 'd' ], [ 'a', 'b', 'c' ] ]
const haystack = { a: { b: { c: 0, d: 1 } } };
objectScan(['a.b.{c,d}'], { rtn: ['property', 'value'] })(haystack, []);
// => [ [ 'd', 1 ], [ 'c', 0 ] ]

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.

Note that _.get and _.set fully support lists.

Examples:

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

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:

const haystack = [{ a: 0 }, { b: [{ c: 1 }, { d: 2 }] }];
objectScan(['a', 'b.d'], {
  joined: true,
  useArraySelector: false
})(haystack);
// => [ '[1].b[1].d', '[0].a' ]
const haystack = [{ a: 0 }, { b: 1 }];
objectScan([''], {
  joined: true,
  useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]

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:

const haystack = [];
objectScan(['a.b', 'a.b'], { joined: true })(haystack);
// => 'Error: Redundant Needle Target: "a.b" vs "a.b"'
const haystack = [];
objectScan(['a.{b,b}'], { joined: true })(haystack);
// => 'Error: Redundant Needle Target: "a.{b,b}" vs "a.{b,b}"'
const haystack = [];
objectScan(['a.b', 'a.**'], { joined: true })(haystack);
// => 'Error: Needle Target Invalidated: "a.b" by "a.**"'
const haystack = [];
objectScan(['**.!**'], { joined: true })(haystack);
// => 'Error: Redundant Recursion: "**.!**"'

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:

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 }

Examples

More extensive examples can be found in the tests.

const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['a.*.f'], { joined: true })(haystack);
// => [ 'a.e.f' ]
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['*.*.*'], { joined: true })(haystack);
// => [ 'a.e.f', 'a.b.c' ]
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' ]
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' ] ]
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['*.*[*]'], { joined: true })(haystack);
// => [ 'a.h[1]', 'a.h[0]' ]
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['*[*]'], { joined: true })(haystack);
// => []
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' ]
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' ]
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**.f'], { joined: true })(haystack);
// => [ 'a.e.f' ]
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**[*]'], { joined: true })(haystack);
// => [ 'a.h[1]', 'a.h[0]' ]
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' ]
const haystack = { a: { b: { c: 'd' }, e: { f: 'g' }, h: ['i', 'j'] }, k: 'l' };
objectScan(['**.(^[bc]$)'], { joined: true })(haystack);
// => [ 'a.b.c', 'a.b' ]

Edge Cases

Top level object(s) are matched by the empty needle ''. This is useful for matching objects nested in arrays by setting useArraySelector to false. To match the actual empty string as a key, use (^$).

Note that the empty string does not work to match top level objects with _.get or _.set.

Examples:

const haystack = [{}, {}];
objectScan([''], {
  joined: true,
  useArraySelector: false
})(haystack);
// => [ '[1]', '[0]' ]
const haystack = {};
objectScan([''], { joined: true })(haystack);
// => [ '' ]
const haystack = { '': 0, a: { '': 1 } };
objectScan(['**.(^$)'])(haystack);
// => [ [ 'a', '' ], [ '' ] ]
const haystack = [0, [{ a: 1 }, 2]];
objectScan(['**(^a$)'], {
  joined: true,
  useArraySelector: false
})(haystack);
// => [ '[1][1]', '[1][0].a', '[1][0]', '[0]' ]

Internals

Conceptually this package works as follows:

  1. During initialization the needles are parsed and built into a search tree. Various information is pre-computed and stored for every node. Finally the search function is returned.

  2. When the search function is invoked, the input is traversed simultaneously with the relevant nodes of the search tree. Processing multiple search tree branches in parallel allows for a single traversal of the input.

Having a separate initialization stage allows for a performant search and significant speed ups when applying the same search to different input.