traverse-object

Traverse a Javascript object tree (assuming it is not cyclic) and call a callback for each found node.

In addition, you can filter all property paths (e.g. 'user.0.firstName') by an Array of RegExp or Strings so that you only visit the nodes you care about.

Definition

traverse(object, callback, propertiesStrOrRegEx = undefined)

• object (required): any iterable (e.g. by in) Javascript Object.
• callback (required): a function to call on every matched property. Has signature (obj, path, value). obj will be the immediate parent object of the match. path will be an Array of the full path to the current match. value will be the value of the matched property. Return true from the callback if you want to stop traversing.
• propertiesOrStrOrRegEx (optional): a filter for which properties to visit. A String, RegExp, or an Array of mixed Strings or RegExps. If you do not pass this argument, then every descendent property is visited and the callback will be called for all of them.

Property paths and propertiesOrStrOrRegEx Wildcards

While traversing the tree of objects, the current path is considered to be a .-delimited String. This String is tested against the value(s) in propertiesOrStrOrRegEx, which can zero or more explicit RegExp instances or Strings.

Strings are converted to RegExp objects where the * character is considered a .*. For example the String '*firstName' will be converted into new RegExp(".*firstName"). Regular expressions are cached between calls but lastIndex=0 is explicitly set before each test to ensure that there is not state leaking between calls.

For example, if you want to visit the tree for any property with a path that ends in 'firstName' you could pass in '*firstName'. If you want to visit the tree for all properties that have 'firstName' anywhere in their path, you can pass in '*firstName*'.

Simple Example

var traverse = require('traverse-object');

let user = {
  firstName: 'Joshua',
  lastName: 'Jung',
  profession: {
    name: 'Software Engineer',
    contributions: ['trie-search', 'traverse-object']
  }
};

traverse(user, console.log); // Will output (obj, path, value) for each key in the tree

Advanced Example

Sanitize an object tree of all passwords and oauth tokens:

var traverse = require('../index');

let users = [
  { name: 'Josh', password: 'asdfasdf1234' },
  { name: 'Matej', token: 'testtest' },
  { name: 'Elisia', password: 'asdfasdf1234' },
  { name: 'Jonas' },
  { name: 'Lasse', password: 'asdfasdf1234' },
  { name: 'MyCorp LLC', oauth: { token: 'asdfasdf1234' } },
];

let sanitizeCallback = (obj, path, value) => {
  delete obj[path[path.length - 1]];
};

traverse(users, sanitizeCallback, [/password/, '*token']);

console.log(users);

// [ { name: 'Josh' },
//   { name: 'Matej' },
//   { name: 'Elisia' },
//   { name: 'Jonas' },
//   { name: 'Lasse' },
//   { name: 'MyCorp LLC', oauth: {} } ]

Testing

$ npm i -g mocha

$ npm test

...

16 passing (10ms)

License

The MIT License (MIT)

Copyright (c) 2019 Joshua Jung

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.