ast-monkey-traverse-with-lookahead^4.2.1

Installation

Quick Take

Examples

• Look ahead by zero nodes by default
• Inspect a node's metadata and its lookahead
• Look ahead two nodes at a time
• Signal a stop from the traversal callback

Idea

Original ast-monkey-traverse had means to edit the AST and couldn’t give you the next few values that are coming up. It only “saw” the current thing it traversed.

While working on codsen-parser, we found that: A) we don’t need AST editing functionality (perf win) and B) we need to see what nodes are coming next.

Instead of bloating ast-monkey-traverse and slowing it down, we decided to create alternative flavour of it, this program.

API — traverse()

The main function traverse() is imported like this:

It’s a function which takes three input arguments:

where the callback has the following API:

This function traverses AST tree given to it in the first input argument. You use it via a callback, similar way to Array.forEach().

The function returns undefined (because it’s operated via callbacks).

API — version

You can import version:

API — types

This package is written in TypeScript and exports the following types:

import type { Callback, InnerObj, NextToken, Obj } from "ast-monkey-traverse-with-lookahead";

A minimal example

import { traverse } from "ast-monkey-traverse-with-lookahead";
var ast = [{ a: "a", b: "b" }];
traverse(ast, (key, val, innerObj, stop) => {
  console.log(`key = ${JSON.stringify(key, null, 4)}`);
  console.log(`val = ${JSON.stringify(val, null, 4)}`);
  console.log(`innerObj = ${JSON.stringify(innerObj, null, 4)}`);
});

Unlike in ast-monkey-traverse, this program is read-only so you don’t need to return anything inside the callback.

The callback interface

When you call traverse() like this:

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

you get four variables:

• key
• val
• innerObj
• stop — set stop.now = true; to stop the traversal

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.

Looking into the future

The whole point of this program is being able to “see” the future. Otherwise, you could be using vanilla ast-monkey-traverse.

You can request how many sets from the future you want to have reported using the third argument, for example:

const gathered = [];
traverse(
  input,
  (key1, val1, innerObj) => {
    gathered.push([key1, val1, innerObj]);
  },
  2, // <---------------- ! lookahead
);

Now, the innerObj.next array will be populated with that many upcoming sets of values.

For example, consider this AST:

const ast = [
  {
    a: "b",
  },
  {
    c: "d",
  },
  {
    e: "f",
  },
];

If you didn’t request lookahead, if it’s default zero, and you traversed it simply pushing all inputs into an array:

const gathered = [];
traverse(
  input,
  (key1, val1, innerObj) => {
    gathered.push([key1, val1, innerObj]);
  },
  0, // <--- hardcoded lookahead, zero sets requested from the future, but it can be omitted
);

You’d get gathered populated with:

[
  // ===================
  [
    {
      a: "b",
    },
    null,
    {
      depth: 0,
      path: "0",
      parent: [
        {
          a: "b",
        },
        {
          c: "d",
        },
        {
          e: "f",
        },
      ],
      parentType: "array",
      next: [],
    },
  ],
  // ===================
  [
    "a",
    "b",
    {
      depth: 1,
      path: "0.a",
      parent: {
        a: "b",
      },
      parentType: "object",
      next: [],
    },
  ],
  // ===================
  ...

Notice above, next: [] is empty. No future sets are reported.

But, if you request the next set to be reported:

const gathered = [];
traverse(
  input,
  (key1, val1, innerObj) => {
    gathered.push([key1, val1, innerObj]);
  },
  1, // <---------------- ! lookahead
);

You’d get gathered populated with:

[
  // ===================
  [
    {
      a: "b",
    },
    null,
    {
      depth: 0,
      path: "0",
      parent: [
        {
          a: "b",
        },
        {
          c: "d",
        },
        {
          e: "f",
        },
      ],
      parentType: "array",
      next: [
        [
          "a",
          "b",
          {
            depth: 1,
            path: "0.a",
            parent: {
              a: "b",
            },
            parentType: "object",
          },
        ],
      ],
    },
  ],
  // ===================
  [
    "a",
    "b",
    {
      depth: 1,
      path: "0.a",
      parent: {
        a: "b",
      },
      parentType: "object",
      next: [
        [
          {
            c: "d",
          },
          null,
          {
            depth: 0,
            path: "1",
            parent: [
              {
                a: "b",
              },
              {
                c: "d",
              },
              {
                e: "f",
              },
            ],
            parentType: "array",
          },
        ],
      ],
    },
  ],
  // ===================
  ...

Notice how innerObj.next is reporting one set from the future, as you requested.

Stopping

Here’s how to stop the traversal. Let’s gather all the traversed paths first. By the way, paths are marked in object-path notation (arrays use dots too, a.1.b instead of a[1].b).

import { traverse } from "ast-monkey-traverse-with-lookahead";
const input = { a: "1", b: { c: "2" } };
const gathered = [];
traverse(input, (key1, val1, innerObj) => {
  const current = val1 !== undefined ? val1 : key1;
  gathered.push(innerObj.path);
  return current;
});
console.log(gathered);
// => ["a", "b", "b.c"]

All paths were gathered: ["a", "b", "b.c"].

Now let’s make the monkey to stop at the path “b”:

import { traverse } from "ast-monkey-traverse-with-lookahead";
const input = { a: "1", b: { c: "2" } };
const gathered = [];
traverse(input, (key1, val1, innerObj, stop) => {
  const current = val1 !== undefined ? val1 : key1;
  gathered.push(innerObj.path);
  if (innerObj.path === "b") {
    stop.now = true; // <---------------- !!!!!!!!!!
  }
  return current;
});
console.log(gathered);
// => ["a", "b"]

Notice how there were no more gathered paths after “b”, only ["a", "b"].

Stopping is not affected by lookahead, it does not matter how many sets from the future you request, a stopping will happen in the right place.

Why this program is read-only

This program is aimed at AST traversal, for example, to be used in codsen-parser, to enable the parser to patch up AST errors. When parser sees something wrong, it needs to see the next AST node to make a decision: is it something missing or is it something rogue what should be skipped?

Normally, people don’t mutate the AST — if you do need to delete something from it, note the path and perform the operation outside of the traversal.

On the other hand, the deletion feature impacts performance. That’s why we made this program read-only.

Changelog