AST Monkey Traverse

4.1.3 · active · verified Sun Apr 19

ast-monkey-traverse is a utility library designed for traversing Abstract Syntax Trees (ASTs) and general JavaScript object/array structures recursively. The current stable version is 4.1.3. As part of the Codsen monorepo, it receives regular updates and maintenance. Its core functionality offers a simple API, `traverse`, which allows users to visit each node in a data structure, providing access to the current key, value, and an internal object containing contextual information like the current path in object-path notation. A key differentiator is its clear distinction in the callback for object keys/values versus array indices, and its explicit focus on pure ESM since version 3.0.0, which streamlined its module architecture. It also provides built-in TypeScript types, enhancing developer experience for type-safe applications.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import `ast-monkey-traverse` version 3.0.0 or later.

fix For versions `>=3.0.0`, ensure your project uses ESM and change `require('ast-monkey-traverse')` to `import { traverse } from 'ast-monkey-traverse'`. If CommonJS is required, install `ast-monkey-traverse@2.1.0`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Using an `import` statement for `ast-monkey-traverse` in a JavaScript file that is treated as CommonJS.

fix Ensure your `package.json` contains `"type": "module"` for your project, or rename the file to have a `.mjs` extension to signal it as an ESM module. Alternatively, for CommonJS environments, install `ast-monkey-traverse@2.1.0` and use `require()`.

Warnings

breaking ast-monkey-traverse transitioned to pure ECMAScript Modules (ESM) starting from version 3.0.0. This change removes CommonJS support.
Fix: Migrate from CommonJS `require()` to ESM `import` statements. Ensure your project is configured for ESM (e.g., by adding `"type": "module"` to your `package.json` or using `.mjs` file extensions). If migrating to ESM is not feasible, install an older CommonJS-compatible version, such as `ast-monkey-traverse@2.1.0`.
gotcha The `traverse` callback's `key` and `val` arguments behave differently when traversing array elements compared to object properties.
Fix: When an array element is being processed, `val` will be `undefined`, and the array element's value will be passed as `key`. For object properties, `key` is the property name, and `val` is its value. Always check `val !== undefined` to correctly differentiate and access the current node's value, for example: `let current = val !== undefined ? val : key;`.

Install

npm install ast-monkey-traverse npm
yarn add ast-monkey-traverse yarn
pnpm add ast-monkey-traverse pnpm

Imports

traverse

wrong:

const { traverse } = require('ast-monkey-traverse')

correct:

import { traverse } from 'ast-monkey-traverse'

Package is pure ESM since v3.0.0. Use `import` statements.

Callback
```
import type { Callback } from 'ast-monkey-traverse'
```
Type import for the `traverse` function's callback signature. Available when using TypeScript.
TraverseResult
```
import type { TraverseResult } from 'ast-monkey-traverse'
```
Type import for the result value returned by the `traverse` function. Available when using TypeScript.

Quickstart

Demonstrates how to use the `traverse` function to navigate a nested object, identify specific keys, and record their paths.

import { strict as assert } from "assert";
import { traverse } from "ast-monkey-traverse";

const paths = [];
const source = {
  a: {
    foo: {
      bar: [
        {
          foo: "c"
        }
      ],
      d: {
        e: {
          foo: "f"
        }
      }
    }
  }
};

traverse(source, (key, val, innerObj) => {
  // if currently an object is traversed, you get both "key" and "val"
  // if it's array, only "key" is present, "val" is undefined
  let current = val !== undefined ? val : key;
  if (
    // it's object (not array)
    val !== undefined &&
    // and has the key we need
    key === "foo"
  ) {
    // push the path to array in the outer scope
    paths.push(innerObj.path);
  }
  return current;
});

// notice object-path notation "a.foo.bar.0.foo" - array segments use dots too:
assert.deepEqual(paths, ["a.foo", "a.foo.bar.0.foo", "a.foo.d.e.foo"]);

view raw JSON →