Package Exports

ast-monkey-traverse

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ast-monkey-traverse) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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 `1`st 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)