@coderrob/typescript-ast

Policy-agnostic AST navigation helpers for TSESTree-compatible tooling.

@coderrob/typescript-ast is a focused utility library for inspecting, traversing, and interpreting AST nodes in ESLint rules, codemods, static analysis, and TypeScript-aware developer tooling. It helps you handle common AST tasks with small, composable helpers while keeping rule logic and policy decisions in your own code.

Highlights

• Focused on AST ergonomics rather than framework-specific policy.
• Split entry points for structural helpers and TypeScript-specific extensions.
• Designed around TSESTree-shaped nodes used by the @typescript-eslint ecosystem.
• Useful in lint rules, repository analysis, codemods, and internal code intelligence workflows.
• Published with ESM and CommonJS bundles plus matching declaration files.

Installation

npm install @coderrob/typescript-ast

If you also need to parse source code or supply visitor keys in your own tooling, install the relevant @typescript-eslint packages used by your stack.

Requirements

• Node.js >=18
• AST nodes compatible with @typescript-eslint/types / TSESTree
• A visitor key map for descendant-search helpers such as visitorKeys from @typescript-eslint/visitor-keys

Choose An Entry Point

| Entry point | Use when | Includes | | ------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | @coderrob/typescript-ast | You want the full public API surface. | Structural helpers, TypeScript-specific helpers, guards, and import-path utilities. | | @coderrob/typescript-ast/core | You only need structural AST utilities. | Calls, navigation, JSDoc helpers, descendant search, statements, import paths, and general-purpose guards. | | @coderrob/typescript-ast/typescript | You only need TypeScript ESTree extensions. | Parameter annotation helpers, type-reference helpers, TS expression unwrapping, and TS-specific guards. |

The root entry point is the compatibility surface. For the clearest dependency boundaries, prefer core for general AST work and add typescript only when you need TypeScript-specific node semantics.

Quick Start

This package operates on AST nodes you already have. It does not parse source code for you.

import { parse } from "@typescript-eslint/typescript-estree";
import { visitorKeys } from "@typescript-eslint/visitor-keys";
import {
  findDescendant,
  getStringLiteralCallArgument,
  isCallExpression,
  isNamedMemberCall,
} from "@coderrob/typescript-ast";

const ast = parse('console.error("boom")', { jsx: false });
const call = findDescendant(ast, visitorKeys, isCallExpression);

if (call && isNamedMemberCall(call, "console", "error")) {
  console.log(getStringLiteralCallArgument(call, 0));
}

Common Workflows

Match Call Shapes Without Manual Callee Inspection

Use the call helpers when you need to recognize direct calls, dotted member calls, or simple argument patterns.

import {
  getCalleeNamePath,
  getStringLiteralCallArgument,
  hasCallCalleeNamePath,
  isNamedCall,
  isNamedMemberCall,
} from "@coderrob/typescript-ast/core";

const calleePath = getCalleeNamePath(callExpression.callee);
const isConsoleError = isNamedMemberCall(callExpression, "console", "error");
const isReadFileSync = hasCallCalleeNamePath(callExpression, ["fs", "readFileSync"]);
const isDescribeCall = isNamedCall(callExpression, "describe");
const message = getStringLiteralCallArgument(callExpression, 0);

Traverse Descendants With Explicit Stop Conditions

The search helpers work well when you need predictable traversal and want to stop descending into boundaries such as nested functions or classes.

import { AST_NODE_TYPES } from "@typescript-eslint/types";
import { visitorKeys } from "@typescript-eslint/visitor-keys";
import { findDescendant, isCallExpression } from "@coderrob/typescript-ast/core";

const nestedCall = findDescendant(
  program,
  visitorKeys,
  isCallExpression,
  (node) => node.type === AST_NODE_TYPES.FunctionDeclaration,
);

Inspect TypeScript Parameters And Wrapped Expressions

Use the TypeScript entry point when you need parameter annotations, this parameter handling, or wrapper-expression unwrapping.

import {
  getFirstNonThisParameter,
  getParameterTypeNode,
  unwrapTsExpression,
} from "@coderrob/typescript-ast/typescript";

const param = getFirstNonThisParameter(functionNode.params);
const typeNode = param ? getParameterTypeNode(param) : null;
const runtimeExpression = unwrapTsExpression(expression);

Normalize Import-Path Checks

The import-path helpers cover a few recurring repository-analysis checks without bringing in a full path abstraction layer.

import { getFilename, isBarrelFile, isParentDirectoryImportPath } from "@coderrob/typescript-ast/core";

const filename = getFilename(importSource);
const isIndexFile = isBarrelFile(resolvedPath);
const walksUp = isParentDirectoryImportPath(importPath);

API Areas

The public API is organized by concern rather than by large utility classes.

| Area | Representative helpers | | --------------------- | --------------------------------------------------------------------------------------------------------- | | Call analysis | getCalleeNamePath, getCallArgument, hasCallCalleeNamePath, isNamedCall, isNamedMemberCall | | Structural navigation | findAncestor, findEnclosingFunction, getNodeParent, getParentBlockStatement, isInsideBoundary | | Descendant search | findDescendant, hasMatchingDescendant, hasMatchingDescendantUntil, hasSomeDescendant | | JSDoc ownership | getJsdocComment, getTargetNode, getParentOwnedTargetNode, isJsdocBlockComment | | Statement helpers | getBooleanLiteralReturnValue, getReturnStatement, getSingleReturnStatement | | TypeScript helpers | getParameterTypeAnnotation, getParameterTypeNode, getFirstTypeArgument, unwrapTsExpression | | Guards | isCallExpression, isIdentifier, isFunctionLike, isUncomputedMemberExpression, isTSTypeReference | | Import paths | getFilename, isBarrelFile, isParentDirectoryImportPath |

For the complete surface, inspect the exported declarations in dist or use editor IntelliSense from one of the supported entry points.

Design Principles

• Keep AST utilities small, explicit, and easy to test.
• Separate structural analysis from rule policy and reporting logic.
• Avoid coupling the package to a single lint engine or transform framework.
• Expose TypeScript-specific behavior through a distinct entry point instead of mixing it into every structural helper.

Repository Quality Standards

The repository is maintained with release gates intended for publishable library code:

• ESLint and Prettier for source consistency
• TypeScript validation for library and test projects
• Vitest coverage enforcement
• source-duplication checks with jscpd
• circular-dependency checks with madge
• package-quality linting with publint
• repeatable micro-benchmarks with tinybench

Useful commands:

• npm run build
• npm run test
• npm run test:coverage
• npm run lint
• npm run typecheck
• npm run quality
• npm run deps:circular
• npm run bench
• npm run ci

Benchmarks

Latest local benchmark snapshot:

• Date: April 7, 2026
• Command: npm run bench
• Runtime: Node.js v22.19.0
• OS: Microsoft Windows NT 10.0.26200.0
• Benchmark coverage plan: every exported function or function alias is benchmarked or explicitly skipped

These numbers are machine-dependent and should be treated as a point-in-time reference rather than a portability guarantee.

| Task | ops/sec | avg (ns) | Margin | | ------------------------------------------------ | ---------: | -------: | ------ | | getCalleeNamePath: member | 5,526,017 | 216 | ±0.71% | | getStringLiteralCallArgument: first | 13,449,858 | 57 | ±0.40% | | hasCallCalleeNamePath: member | 7,125,853 | 206 | ±2.56% | | hasMemberCallee: member | 14,309,821 | 53 | ±0.48% | | isNamedCall: simple | 10,416,387 | 83 | ±1.08% | | getCallMemberMethodName: member | 14,316,050 | 53 | ±0.89% | | getMemberPropertyName: member | 17,801,975 | 43 | ±0.94% | | getVisitorChildNodes: nested | 2,224,307 | 549 | ±5.15% | | resolveFunctionName: declaration | 12,171,612 | 64 | ±0.36% | | getJsdocComment: basic | 14,378,233 | 54 | ±4.28% | | isJsdocBlockComment: basic | 17,822,074 | 43 | ±0.61% | | findAncestor: function | 15,325,788 | 49 | ±0.45% | | getParentBlockStatement: return | 15,003,039 | 51 | ±4.15% | | isInsideBoundary: ancestors | 7,381,892 | 157 | ±0.10% | | getNamedParameterIdentifier: identifier | 14,808,104 | 51 | ±0.36% | | getObjectDestructuredParameterTypeNode: object | 9,918,208 | 94 | ±0.79% | | getParameterTypeAnnotation: identifier | 10,692,934 | 77 | ±0.24% | | findDescendant: call | 1,149,220 | 1055 | ±3.88% | | hasMatchingDescendant: call | 1,147,135 | 1047 | ±7.89% | | hasMatchingDescendantUntil: identifier | 705,477 | 1571 | ±3.02% | | getBooleanLiteralReturnValue: return | 12,703,016 | 60 | ±0.26% | | getReturnStatement: return | 14,658,744 | 52 | ±0.29% | | unwrapTsExpression: wrapped | 9,376,505 | 111 | ±0.47% | | isNamedTypeReference: promise | 12,910,823 | 59 | ±0.79% | | hasTypeArguments: promise | 18,079,021 | 42 | ±0.97% | | isCallExpression: simple | 14,820,742 | 51 | ±0.50% | | isIdentifier: callee | 14,730,622 | 52 | ±1.01% | | isTestFile: convention | 9,831,030 | 103 | ±1.27% | | isUncomputedMemberExpression: callee | 14,698,690 | 51 | ±0.28% | | getFilename: path | 9,924,890 | 94 | ±0.62% | | isBarrelFile: index | 9,692,900 | 104 | ±0.64% | | isParentDirectoryImportPath: relative | 16,641,774 | 46 | ±0.71% |

Run the suite again locally when you need numbers for a different machine, Node.js version, or code revision:

npm run bench

Documentation

• Contributing Guide
• Changelog
• Architecture Notes

License

Apache-2.0