TypeScript API Utilities

2.5.0 · active · verified Sun Apr 19

ts-api-utils is a utility library providing helper functions for interacting with the TypeScript Compiler API. It serves as a modern successor to the widely used tsutils library, offering improved maintainability and updated conventions. The current stable version is 2.5.0, with a v3.0.0 release candidate recently published, indicating an active development cadence with regular updates. This library is crucial for tooling developers, static analysis tools, and code transformers that need to navigate and analyze TypeScript's Abstract Syntax Tree (AST) and type system. It aims to simplify common operations, making it easier to work with `ts.Node`, `ts.Type`, and `ts.Symbol` objects without directly reimplementing frequently needed logic. Its focus on providing a robust set of utilities for advanced TypeScript usage differentiates it from general-purpose utility libraries.

Common errors

```
ERR_REQUIRE_ESM: require() of ES Module ...ts-api-utils.js not supported.
```
cause Attempting to use `require()` to import `ts-api-utils` in a CommonJS context when Node.js is configured for strict ESM.

fix Switch to `import { ... } from 'ts-api-utils'` syntax in an ES Module project, or configure Node.js to interpret your files as ESM (e.g., by setting `"type": "module"` in `package.json`).
```
TypeError: ts.createSourceFile is not a function
```
cause Missing or incompatible `typescript` peer dependency, meaning the `ts` object from the TypeScript API is not correctly resolved or available.

fix Install `typescript` as a dev dependency with a version compatible with `ts-api-utils` (e.g., `npm install typescript@^5 --save-dev`). Check `ts-api-utils` documentation for exact peer dependency ranges.
```
TS2345: Argument of type '...' is not assignable to parameter of type 'Node'.
```
cause Passing an incorrect type to a `ts-api-utils` function that expects a `ts.Node` or a specific derived type from the TypeScript AST.

fix Ensure the argument passed to utility functions like `isIdentifier` or `getAccessKind` is a valid `ts.Node` or compatible TypeScript API object. Review the function's signature for expected parameter types.

Warnings

breaking Minimum Node.js version was bumped to 18.12 and the TypeScript peer dependency to 4.8.4.
Fix: Upgrade your Node.js environment to 18.12 or higher and ensure `typescript` peer dependency is at least 4.8.4. For older environments, use `ts-api-utils` v1.x.
gotcha The `isTypeParameter` function was fixed in `v1.4.3` to no longer act as a type guard for scenarios where it incorrectly narrowed types, which might affect existing code relying on its previous type inference behavior.
Fix: Review usages of `isTypeParameter` and ensure explicit type checks or assertions are used if strict type narrowing is required. This was a corrective fix to align its behavior more accurately with TypeScript's type system.
gotcha The package is primarily designed for consumption as an ES Module (ESM) in modern Node.js environments.
Fix: Use `import ... from 'ts-api-utils'` syntax. If using CommonJS, ensure your build setup correctly transpiles or handles ESM imports, or upgrade to a modern Node.js version that supports ESM.

Install

npm install ts-api-utils npm
yarn add ts-api-utils yarn
pnpm add ts-api-utils pnpm

Imports

isTypeParameter
wrong:
```
const { isTypeParameter } = require('ts-api-utils');
```
correct:
```
import { isTypeParameter } from 'ts-api-utils';
```
Since v2.0.0, the package targets modern Node.js environments (>=18.12) and is primarily consumed as an ES Module. While CJS bundling might work, direct ESM imports are the standard.
getAccessKind
wrong:
```
import getAccessKind from 'ts-api-utils';
```
correct:
```
import { getAccessKind } from 'ts-api-utils';
```
Most utilities are named exports. There is no default export from this package.
isIdentifier
wrong:
```
import { Identifier } from 'ts-api-utils';
```
correct:
```
import { isIdentifier } from 'ts-api-utils';
```
Many functions are type guards for TypeScript AST nodes (e.g., `isNode`, `isExpression`). Pay attention to the exact export name, as importing a type as a value will fail.

Quickstart

Demonstrates parsing a TypeScript file and using `ts-api-utils` type guards (`isIdentifier`, `isCallExpression`) to analyze its Abstract Syntax Tree (AST).

import ts from 'typescript';
import { isIdentifier, isCallExpression } from 'ts-api-utils';

function analyzeCode(code: string, fileName: string = 'test.ts') {
  const sourceFile = ts.createSourceFile(
    fileName,
    code,
    ts.ScriptTarget.ES2015,
    /*setParentNodes*/ true
  );

  let identifiersFound: string[] = [];
  let callExpressionsCount = 0;

  ts.forEachChild(sourceFile, function visitor(node: ts.Node) {
    if (isIdentifier(node)) {
      identifiersFound.push(node.text);
    } else if (isCallExpression(node)) {
      callExpressionsCount++;
    }
    ts.forEachChild(node, visitor); // Continue recursion
  });

  console.log(`Analyzed file: ${fileName}`);
  console.log(`Found identifiers: ${identifiersFound.join(', ')}`);
  console.log(`Found call expressions: ${callExpressionsCount}`);
}

const exampleCode = `
  function greet(name: string) {
    console.log("Hello, " + name + "!");
  }
  greet("World");
  const myVar = 123;
  const result = Math.max(myVar, 456);
`;

analyzeCode(exampleCode, 'example.ts');

view raw JSON →