ast-monkey-traverse

ast-monkey-traverse

Utility library to traverse parsed HTML (AST's) or anything nested (plain objects within arrays within plain objects)

• Check out the parent library which does even more: ast-monkey

Table of Contents

• Install
• Idea
• API
• Contributing
• Licence

Install

npm i ast-monkey-traverse

Then, consume either in CommonJS format (require) or as an ES Module (import):

// as CommonJS require:
const traverse = require("ast-monkey-traverse");
// or as ES Module:
import traverse from "ast-monkey-traverse";

Here's what you'll get:

Type	Key in package.json	Path	Size
Main export - CommonJS version, transpiled to ES5, contains require and module.exports	main	dist/ast-monkey-traverse.cjs.js	2 KB
ES module build that Webpack/Rollup understands. Untranspiled ES6 code with import/export.	module	dist/ast-monkey-traverse.esm.js	2 KB
UMD build for browsers, transpiled, minified, containing iife's and has all dependencies baked-in	browser	dist/ast-monkey-traverse.umd.js	10 KB

⬆ back to top

Idea

Walk through every single element of an array or key of an object or every string in the given input, use familiar callback function interface (just like Array.forEach or Array.map).

API

traverse() is an inner method meant to be used by other functions. It does the actual traversal of the AST tree (or whatever input you gave, from simplest string to most complex spaghetti of nested arrays and plain objects). This method function is used via a callback function, similarly to Array.forEach().

const traverse = require("ast-monkey-traverse");
var ast = [{ a: "a", b: "b" }];
ast = traverse(ast, function(key, val, innerObj) {
  let current = val !== undefined ? val : key;
  // if you are traversing and "stumbled" upon an object, it will have both "key" and "val"
  // if you are traversing and "stumbled" upon an array, it will have only "key"
  // you can detect either using the principle above.
  // you can also now change "current" - what you return will be overwritten.
  // return `NaN` to give instruction to delete currently traversed piece of AST.
  return current; // #1 <------ it's obligatory to return it, unless you want to assign it to "undefined"
});

It's very important to return the value of the callback function (point marked #1 above) because otherwise whatever you return will be written over the current AST piece being iterated.

If you want to delete, return NaN.

⬆ back to top

innerObj in the callback

When you call traverse() like this:

input = traverse(input, function (key, val, innerObj) {
  ...
})

you get three variables:

• key
• val
• innerObj

If traverse() is currently traversing a plain object, going each key/value pair, key will be the object's current key and val will be the value. If traverse() is currently traversing an array, going through all elements, a key will be the current element and val will be null.

innerObj object's key	Type	Description
{
depth	Integer number	Zero is root, topmost level. Every level deeper increments depth by 1.
path	String	The path to the current value. The path uses exactly the same notation as the popular object-path package. For example, a.1.b would be: input object's key a > value is array, take 1st index (second element in a row, since indexes start from zero) > value is object, take it's key b.
topmostKey	String	When you are very deep, this is the topmost parent's key.
parent	Type of the parent of current element being traversed	A whole parent (array or a plain object) which contains the current element. Its purpose is to allow you to query the siblings of the current element.
}

⬆ back to top

Contributing

• If you want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.

• If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.

• If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)

Copyright © 2018 Codsen Ltd, Roy Revelt