{"id":12164,"library":"ts-api-utils","title":"TypeScript API Utilities","description":"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.","status":"active","version":"2.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/JoshuaKGoldberg/ts-api-utils","tags":["javascript","typescript"],"install":[{"cmd":"npm install ts-api-utils","lang":"bash","label":"npm"},{"cmd":"yarn add ts-api-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-api-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for accessing TypeScript's API types and runtime objects. Ensure a compatible version is installed alongside ts-api-utils.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"const { isTypeParameter } = require('ts-api-utils');","symbol":"isTypeParameter","correct":"import { isTypeParameter } from 'ts-api-utils';"},{"note":"Most utilities are named exports. There is no default export from this package.","wrong":"import getAccessKind from 'ts-api-utils';","symbol":"getAccessKind","correct":"import { getAccessKind } from 'ts-api-utils';"},{"note":"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.","wrong":"import { Identifier } from 'ts-api-utils';","symbol":"isIdentifier","correct":"import { isIdentifier } from 'ts-api-utils';"}],"quickstart":{"code":"import ts from 'typescript';\nimport { isIdentifier, isCallExpression } from 'ts-api-utils';\n\nfunction analyzeCode(code: string, fileName: string = 'test.ts') {\n  const sourceFile = ts.createSourceFile(\n    fileName,\n    code,\n    ts.ScriptTarget.ES2015,\n    /*setParentNodes*/ true\n  );\n\n  let identifiersFound: string[] = [];\n  let callExpressionsCount = 0;\n\n  ts.forEachChild(sourceFile, function visitor(node: ts.Node) {\n    if (isIdentifier(node)) {\n      identifiersFound.push(node.text);\n    } else if (isCallExpression(node)) {\n      callExpressionsCount++;\n    }\n    ts.forEachChild(node, visitor); // Continue recursion\n  });\n\n  console.log(`Analyzed file: ${fileName}`);\n  console.log(`Found identifiers: ${identifiersFound.join(', ')}`);\n  console.log(`Found call expressions: ${callExpressionsCount}`);\n}\n\nconst exampleCode = `\n  function greet(name: string) {\n    console.log(\"Hello, \" + name + \"!\");\n  }\n  greet(\"World\");\n  const myVar = 123;\n  const result = Math.max(myVar, 456);\n`;\n\nanalyzeCode(exampleCode, 'example.ts');\n","lang":"typescript","description":"Demonstrates parsing a TypeScript file and using `ts-api-utils` type guards (`isIdentifier`, `isCallExpression`) to analyze its Abstract Syntax Tree (AST)."},"warnings":[{"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.","message":"Minimum Node.js version was bumped to 18.12 and the TypeScript peer dependency to 4.8.4.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.4.3"},{"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.","message":"The package is primarily designed for consumption as an ES Module (ESM) in modern Node.js environments.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` to import `ts-api-utils` in a CommonJS context when Node.js is configured for strict ESM.","error":"ERR_REQUIRE_ESM: require() of ES Module ...ts-api-utils.js not supported."},{"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.","cause":"Missing or incompatible `typescript` peer dependency, meaning the `ts` object from the TypeScript API is not correctly resolved or available.","error":"TypeError: ts.createSourceFile is not a function"},{"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.","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.","error":"TS2345: Argument of type '...' is not assignable to parameter of type 'Node'."}],"ecosystem":"npm"}