AST Monkey Utility

3.1.3 · active · verified Sun Apr 19

ast-monkey-util is a JavaScript utility library that provides a set of helper functions specifically designed for manipulating and navigating Abstract Syntax Trees (ASTs). It is currently at version 3.1.3 and is actively maintained within the Codsen monorepo, indicated by recent copyright updates and ongoing development. The library focuses on granular utilities for path manipulation within nested object structures that represent ASTs, offering functions to determine the next, previous, or parent path, and to identify a parent key. This makes it particularly useful for tasks requiring precise positional awareness without needing full AST traversal or transformation. A key differentiator is its pure ESM distribution, aligning with modern JavaScript module standards, which necessitates a Node.js environment of `v14.18.0` or higher for current versions.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import `ast-monkey-util` using `require()` in a CommonJS module, but the current version of the package is pure ESM.

fix Convert your module to ES modules by using `import { func } from 'ast-monkey-util'` and ensuring your `package.json` specifies `"type": "module"`, or install `ast-monkey-util@1.4.0` for CommonJS compatibility.
```
TypeError: Cannot read properties of undefined (reading 'split')
```
cause Passing `null`, `undefined`, or other non-string values as the path argument to functions like `pathNext`, `pathPrev`, `pathUp`, or `parent`.

fix Verify that all path arguments passed to `ast-monkey-util` functions are valid non-empty strings representing AST paths.

Warnings

breaking ast-monkey-util is a pure ESM package since version 2.0.0. Attempting to use CommonJS `require()` will result in an `ERR_REQUIRE_ESM` error.
Fix: Migrate your project to use ES modules (`import`) or install an older CommonJS-compatible version like `ast-monkey-util@1.4.0`.
gotcha The utility functions expect AST paths to be provided as dot-separated string representations (e.g., '9.children.3'). Incorrect formatting, such as passing array indices as pure numbers or non-string values, may lead to unexpected results or errors.
Fix: Ensure all AST path inputs conform to the '`root.key.index.key.index`' string format. Always pass valid non-empty strings.
gotcha The package requires Node.js version 14.18.0 or higher. Running in older Node.js environments might lead to compatibility issues or failures.
Fix: Upgrade your Node.js environment to version 14.18.0 or newer to ensure full compatibility and access to ESM features.

Install

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

Imports

pathNext
wrong:
```
const { pathNext } = require('ast-monkey-util')
```
correct:
```
import { pathNext } from 'ast-monkey-util'
```
The package is pure ESM since version 2.0.0. CommonJS `require()` is not supported for current versions. For CJS compatibility, install version 1.4.0.
pathUp
wrong:
```
const pathUp = require('ast-monkey-util').pathUp
```
correct:
```
import { pathUp } from 'ast-monkey-util'
```
As a pure ESM package, all functions are named exports. Attempting to use CommonJS `require()` will result in an error on current versions.
parent
wrong:
```
import parent from 'ast-monkey-util'
```
correct:
```
import { parent } from 'ast-monkey-util'
```
There is no default export; all utility functions are exposed as named exports.

Quickstart

This quickstart demonstrates how to use `ast-monkey-util` functions to navigate and query AST paths, including moving to next/previous siblings, ascending to a parent path, and identifying a parent key.

import { strict as assert } from "assert";
import { pathNext, pathPrev, pathUp, parent } from "ast-monkey-util";

// Example of navigating to the next sibling path
assert.equal(pathNext("9.children.3"), "9.children.4");

// Example of navigating to the previous sibling path
assert.equal(pathPrev("9.children.33"), "9.children.32");

// Example of navigating up to the parent path
assert.equal(pathUp("9.children.1.children.2"), "9.children.1");

// Example of identifying the direct parent key
assert.equal(parent("9.children.3"), "children");

console.log("All assertions passed!");

view raw JSON →