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
  • innerObj in the callback
• 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 // it's obligatory to return it, unless you want to assign that
  // node to an "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.
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.
}

Allow me to show you how to practically tap the innerObj:

const traverse = require('ast-monkey-traverse')
let ast = {
            a: {
              b: 'b val'
            },
            c: 'c val'
          }
ast = traverse(ast, function (key, val, innerObj) {
  let current = (val !== undefined) ? val : key
  console.log('\nkey = ' + JSON.stringify(key, null, 4))
  console.log('val = ' + JSON.stringify(val, null, 4))
  console.log('innerObj = ' + JSON.stringify(innerObj, null, 4))
  return current
})
// ...

CONSOLE OUTPUT WILL BE:

key = "a"
val = {
    "b": "b val"
}
innerObj = {
    "depth": 0,
    "topmostKey": "a",
    "parent": {
        "a": {
            "b": "b val"
        },
        "c": "c val"
    }
}

key = "b"
val = "b val"
innerObj = {
    "depth": 1,
    "topmostKey": "a",
    "parent": {
        "b": "b val"
    }
}

key = "c"
val = "c val"
innerObj = {
    "depth": 0,
    "topmostKey": "c",
    "parent": {
        "a": {
            "b": "b val"
        },
        "c": "c val"
    }
}

⬆  back to top

Contributing

Hi! 99% of people in the society are passive - consumers. They wait for others to take action, they prefer to blend in. The remaining 1% are proactive citizens who will do something rather than wait. If you are one of that 1%, you're in luck because I am the same and together we can make something happen.

• If you want a new feature in this package or you would like to change some of its functionality, raise an issue on this repo. Also, you can email me. Just let it out.

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

• If you don't like the code in here and would like to give advice about how something could be done better, please do. Same drill - GitHub issues or email, your choice.

• If you would like to add or change some features, just fork it, hack away, and file a pull request. I'll do my best to merge it quickly. Code style is airbnb-base, only without semicolons. If you use a good code editor, it will pick up the established ESLint setup.

⬆  back to top

Licence

MIT License (MIT)

Copyright © 2017 Codsen Ltd, Roy Revelt