API Reference Overview

​

Why Use These Utilities?

• Import/Require Analysis: Finding and analyzing import statements and require() calls for specific modules
• Binding Resolution: Determining how imported functions are accessed locally (destructured, aliased, etc.)
• Code Transformation: Safely removing unused imports and modifying code while preserving formatting
• Package.json Processing: Analyzing and transforming package.json scripts that use Node.js

​

API Categories

​

Import and Require Detection

• getModuleDependencies - Find all import/require statements for a module
• getNodeImportStatements - Find ES module import statements
• getNodeImportCalls - Find dynamic import calls
• getNodeRequireCalls - Find CommonJS require calls

​

Binding Resolution and Transformation

• resolveBindingPath - Resolve global API paths to local bindings
• removeBinding - Remove specific bindings from imports
• updateBinding - Update or replace bindings

​

AST-grep Helper Functions

• detectIndentUnit - Detect indentation style
• getLineIndent - Get indentation for a specific line
• getShebang - Find Node.js shebang lines
• getScope - Find enclosing scope for a node
• removeLines - Safely remove line ranges
• getDefaultImportIdentifier - Get default import identifier
• getRequireNamespaceIdentifier - Get namespace require identifier
• replaceNodeJsArgs (shebang) - Replace Node.js args in shebangs

​

Package.json Utilities

• removeDependencies - Remove dependencies from package.json
• getScriptsNode - Find the scripts section
• getNodeJsUsage - Find Node.js usage in scripts
• replaceNodeJsArgs - Replace Node.js arguments in scripts
• removeNodeJsArgs - Remove Node.js arguments from scripts

​

Type Definitions

• SgRoot<Js> - Root AST node for JavaScript/TypeScript
• SgNode<Js> - Individual AST node
• Edit - Represents a code edit operation
• Range - Represents a position range in source code

​

Getting Started

import { getModuleDependencies } from '@nodejs/codemod-utils/ast-grep/module-dependencies';
import { resolveBindingPath } from '@nodejs/codemod-utils/ast-grep/resolve-binding-path';
import removeDependencies from '@nodejs/codemod-utils/remove-dependencies';

​

Common Patterns

​

Finding Module Dependencies

const ast = context.getAST();
const fsImports = getModuleDependencies(ast, 'fs');
// Finds: import fs from 'fs'; import { readFile } from 'node:fs';
// Finds: const fs = require('fs')
// Finds: const fs = await import('fs')

​

Resolving Bindings

// Given: const { types } = require('node:util');
const path = resolveBindingPath(node, '$.types.isNativeError');
// Returns: 'types.isNativeError'

// Given: const util = require('node:util');
const path = resolveBindingPath(node, '$.types.isNativeError');
// Returns: 'util.types.isNativeError'

​

Removing Bindings

// Given: const { types, isNativeError } = require('node:util');
const result = removeBinding(node, 'isNativeError');
// Edit to: const { types } = require('node:util');

// Given: const { isNativeError } = require('node:util');
const result = removeBinding(node, 'isNativeError');
// Returns: lineToRemove range to remove entire statement