{"id":10520,"library":"ast-monkey-traverse","title":"AST Monkey Traverse","description":"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.","status":"active","version":"4.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/codsen/codsen","tags":["javascript","ast","by","delete","drop","from","helper","html","key","typescript"],"install":[{"cmd":"npm install ast-monkey-traverse","lang":"bash","label":"npm"},{"cmd":"yarn add ast-monkey-traverse","lang":"bash","label":"yarn"},{"cmd":"pnpm add ast-monkey-traverse","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is pure ESM since v3.0.0. Use `import` statements.","wrong":"const { traverse } = require('ast-monkey-traverse')","symbol":"traverse","correct":"import { traverse } from 'ast-monkey-traverse'"},{"note":"Type import for the `traverse` function's callback signature. Available when using TypeScript.","symbol":"Callback","correct":"import type { Callback } from 'ast-monkey-traverse'"},{"note":"Type import for the result value returned by the `traverse` function. Available when using TypeScript.","symbol":"TraverseResult","correct":"import type { TraverseResult } from 'ast-monkey-traverse'"}],"quickstart":{"code":"import { strict as assert } from \"assert\";\nimport { traverse } from \"ast-monkey-traverse\";\n\nconst paths = [];\nconst source = {\n  a: {\n    foo: {\n      bar: [\n        {\n          foo: \"c\"\n        }\n      ],\n      d: {\n        e: {\n          foo: \"f\"\n        }\n      }\n    }\n  }\n};\n\ntraverse(source, (key, val, innerObj) => {\n  // if currently an object is traversed, you get both \"key\" and \"val\"\n  // if it's array, only \"key\" is present, \"val\" is undefined\n  let current = val !== undefined ? val : key;\n  if (\n    // it's object (not array)\n    val !== undefined &&\n    // and has the key we need\n    key === \"foo\"\n  ) {\n    // push the path to array in the outer scope\n    paths.push(innerObj.path);\n  }\n  return current;\n});\n\n// notice object-path notation \"a.foo.bar.0.foo\" - array segments use dots too:\nassert.deepEqual(paths, [\"a.foo\", \"a.foo.bar.0.foo\", \"a.foo.d.e.foo\"]);","lang":"typescript","description":"Demonstrates how to use the `traverse` function to navigate a nested object, identify specific keys, and record their paths."},"warnings":[{"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`.","message":"ast-monkey-traverse transitioned to pure ECMAScript Modules (ESM) starting from version 3.0.0. This change removes CommonJS support.","severity":"breaking","affected_versions":">=3.0.0"},{"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;`.","message":"The `traverse` callback's `key` and `val` arguments behave differently when traversing array elements compared to object properties.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to use `require()` to import `ast-monkey-traverse` version 3.0.0 or later.","error":"ERR_REQUIRE_ESM"},{"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()`.","cause":"Using an `import` statement for `ast-monkey-traverse` in a JavaScript file that is treated as CommonJS.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}