ts-api-utils

library2.5.0jsnpmunverified

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.

devops workflow

npm install ts-api-utils

github ↗package ↗

INSTALL

IMPORT

SIG · TS-API-UTILS

ts-api-utils

devopsjavascriptv2.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

isTypeParameter

✓ import { isTypeParameter } from 'ts-api-utils';

✗ const { isTypeParameter } = require('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

✓ import { getAccessKind } from 'ts-api-utils';

✗ import getAccessKind from 'ts-api-utils';

Most utilities are named exports. There is no default export from this package.

isIdentifier

✓ import { isIdentifier } from 'ts-api-utils';

✗ import { Identifier } 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.

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');

Debug

Known issues

breakingMinimum 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.

affects: >=2.0.0

gotchaThe `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.

affects: >=1.4.3

gotchaThe 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.

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ...ts-api-utils.js not supported.

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

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'.

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.

Upgrade

Version history

2.5.0latest on npm

Audit

Dependencies

typescriptrequiredRequired peer dependency for accessing TypeScript's API types and runtime objects. Ensure a compatible version is installed alongside ts-api-utils.

Agent activity

47 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/JoshuaKGoldberg/ts-api-utils ↗

packagehttps://www.npmjs.com/package/ts-api-utils ↗