{"id":11454,"library":"node-source-walk","title":"Node Source Walk AST Traversal","description":"node-source-walk is a JavaScript utility library designed for synchronously traversing Abstract Syntax Trees (ASTs) or raw source code strings. It allows developers to apply a callback function to every node within the AST, with the crucial capability to halt the traversal prematurely using `stopWalking()`. The current stable version is 7.0.1. Releases tend to align with Node.js LTS updates, primarily dropping support for older Node.js versions. A key differentiator is its flexibility in supporting both top-down (`walk`, `traverse`) and bottom-up (`moonwalk`) traversals, accepting either source code or a pre-parsed AST, and offering the option to replace its default `@babel/parser` with a custom parser.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/dependents/node-source-walk","tags":["javascript","ast","traversal","acorn","static analysis","source code","walker","jsx"],"install":[{"cmd":"npm install node-source-walk","lang":"bash","label":"npm"},{"cmd":"yarn add node-source-walk","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-source-walk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The Walker class is the default export for ESM modules. Avoid named import syntax.","wrong":"import { Walker } from 'node-source-walk';","symbol":"Walker","correct":"import Walker from 'node-source-walk';"},{"note":"For CommonJS, the Walker class is the default export. Destructuring will not work as expected.","wrong":"const { Walker } = require('node-source-walk');","symbol":"Walker","correct":"const Walker = require('node-source-walk');"},{"note":"For TypeScript projects, import the `WalkerOptions` interface to type the constructor options, if type definitions are available (e.g., via `@types/node-source-walk` or bundled).","symbol":"Walker (Type)","correct":"import type { WalkerOptions } from 'node-source-walk';"}],"quickstart":{"code":"import Walker from 'node-source-walk';\n\n// Example source code string\nconst src = `\n  const add = (a, b) => a + b;\n  function subtract(a, b) {\n    return a - b;\n  }\n  console.log(add(5, 3));\n  console.log(subtract(10, 4));\n`;\n\nconst walker = new Walker();\nlet foundFunctionDeclaration = false;\n\nconsole.log('Walking AST for function declarations...');\nwalker.walk(src, node => {\n  if (node.type === 'FunctionDeclaration') {\n    console.log(`Found function declaration: ${node.id.name}`);\n    foundFunctionDeclaration = true;\n    // Stop walking after finding the first one\n    walker.stopWalking();\n  }\n});\n\nif (!foundFunctionDeclaration) {\n  console.log('No function declarations found.');\n}\n\n// Example with custom parser options (for JSX)\nconst jsxSrc = `\n  import React from 'react';\n  function MyComponent() {\n    return <div>Hello, JSX!</div>;\n  }\n`;\n\nconst jsxWalker = new Walker({\n  plugins: ['jsx'] // Ensure JSX plugin is enabled for parsing\n});\n\nconsole.log('\\nWalking AST for JSX elements...');\nlet foundJsxElement = false;\njsxWalker.walk(jsxSrc, node => {\n  if (node.type === 'JSXElement') {\n    console.log('Found a JSXElement!');\n    foundJsxElement = true;\n    jsxWalker.stopWalking();\n  }\n});\n\nif (!foundJsxElement) {\n  console.log('No JSX elements found.');\n}\n","lang":"typescript","description":"This quickstart demonstrates how to instantiate the Walker class, traverse source code, identify specific AST node types (like 'FunctionDeclaration' or 'JSXElement'), and efficiently stop the traversal once a desired node is found. It also shows how to configure the internal parser with custom plugins like 'jsx'."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18 or newer. If an upgrade is not possible, pin `node-source-walk` to a version compatible with your Node.js environment (e.g., `<7.0.0` for Node.js 16).","message":"Version 7.0.0 and above drop support for Node.js versions older than 18. Projects running on Node.js 16 or earlier must upgrade their Node.js environment or remain on a previous major version of `node-source-walk`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Refactor code that directly called `shouldStop` or `reverseTraverse`. Instead, use the public `stopWalking()` method to halt traversal. The `moonwalk` method provides public access to reverse traversal functionality.","message":"In version 6.0.0, the `shouldStop` and `reverseTraverse` methods were made private. Direct access or usage of these methods in your application logic will now fail.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade your Node.js runtime to version 14 or newer, ideally to Node.js 18+ to be compatible with the latest major versions.","message":"Version 6.0.0 dropped support for Node.js 12. If you are migrating from a version below 6.0.0 and still using Node.js 12, an upgrade to Node.js 14 or higher (or eventually Node.js 18 for v7+) is required.","severity":"breaking","affected_versions":">=6.0.0 <7.0.0"},{"fix":"Verify that your custom parser adheres to the expected `.parse(sourceString)` signature and returns a compatible AST structure. Consult `@babel/parser`'s documentation for AST shape reference.","message":"When providing a custom parser to `Walker`, ensure it exposes a `.parse` method that accepts a string and returns a valid AST. The library passes all other options to this custom parser.","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":"Use default import for ESM (`import Walker from 'node-source-walk';`) or direct `require` assignment for CommonJS (`const Walker = require('node-source-walk');`).","cause":"Attempting to import `Walker` using named import syntax (`import { Walker } from '...'`) or destructuring (`const { Walker } = require('...')`) when it is exported as a default.","error":"TypeError: Walker is not a constructor"},{"fix":"Initialize the `Walker` with `plugins` option to enable required `@babel/parser` plugins, for example: `new Walker({ plugins: ['jsx', 'typescript'] })`.","cause":"The default `@babel/parser` might not have the necessary plugins enabled to parse specific syntax (e.g., JSX, Flow, TypeScript).","error":"SyntaxError: Unexpected token 'import' (or similar parsing errors for modern JS/TS features)"},{"fix":"Upgrade your Node.js runtime to version 18 or newer. Check your project's `engines` field in `package.json` for compatibility.","cause":"Running a version of `node-source-walk` (v7.0.0 or higher) on an unsupported Node.js runtime environment (e.g., Node.js 16).","error":"Error: node-source-walk requires Node.js version >= 18."}],"ecosystem":"npm"}