API Reference Overview

Comprehensive API reference for Node.js Userland Migrations codemod utilities

The @nodejs/codemod-utils package provides a comprehensive set of utilities for building Node.js codemods with ast-grep. These utilities handle complex patterns for import/require analysis, binding resolution, code transformation, and package.json processing.

Why Use These Utilities?

Building Node.js codemods requires handling complex patterns for:

• 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

These utilities provide battle-tested solutions for common codemod operations, reducing boilerplate and ensuring consistent behavior across all migration recipes.

API Categories

Import and Require Detection

Utilities for finding and analyzing module dependencies:

• 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

Utilities for resolving and manipulating import bindings:

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

AST-grep Helper Functions

Core utilities for working with AST nodes:

• 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

Utilities for processing package.json files:

• 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

All utilities use types from @codemod.com/jssg-types:

• 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 utilities directly from their respective modules:

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