0
# TSUtils
1
2
TSUtils provides comprehensive utility functions and type guard functions for working with TypeScript's Abstract Syntax Tree (AST) and type system. It offers backwards compatibility with TypeScript 2.8.0+ and includes modular imports for selective usage - users can import only type guards, only utilities, or both. The library features version-specific type guard functions to maintain compatibility across different TypeScript versions, with specialized functions for traversing AST nodes, analyzing types, working with comments and tokens, and performing type-safe operations on TypeScript compiler APIs.
3
4
## Package Information
5
6
- **Package Name**: tsutils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tsutils`
10
- **Peer Dependencies**: `typescript >=2.8.0`
11
12
## Core Imports
13
14
```typescript
15
import * as utils from "tsutils";
16
// Access both type guards and utilities
17
utils.isIdentifier(node);
18
utils.getLineRanges(sourceFile);
19
```
20
21
For selective imports:
22
23
```typescript
24
// Only type guards
25
import { isIdentifier, isCallExpression } from "tsutils/typeguard";
26
27
// Only utilities
28
import { forEachComment, forEachToken } from "tsutils/util";
29
30
// Version-specific type guards
31
import { isIdentifier } from "tsutils/typeguard/2.8";
32
```
33
34
CommonJS:
35
36
```javascript
37
const utils = require("tsutils");
38
const { isIdentifier, forEachToken } = require("tsutils");
39
```
40
41
## Basic Usage
42
43
```typescript
44
import * as ts from "typescript";
45
import { isIdentifier, isCallExpression, forEachToken, getLineRanges } from "tsutils";
46
47
// Type guard usage
48
function analyzeNode(node: ts.Node) {
49
if (isIdentifier(node)) {
50
// node is now typed as ts.Identifier
51
console.log("Identifier:", node.text);
52
}
53
54
if (isCallExpression(node)) {
55
// node is now typed as ts.CallExpression
56
console.log("Function call:", node.expression);
57
}
58
}
59
60
// Utility usage
61
function analyzeSourceFile(sourceFile: ts.SourceFile) {
62
// Iterate through all tokens
63
forEachToken(sourceFile, (token) => {
64
console.log("Token:", ts.SyntaxKind[token.kind]);
65
});
66
67
// Get line information
68
const lines = getLineRanges(sourceFile);
69
console.log("Total lines:", lines.length);
70
}
71
```
72
73
## Architecture
74
75
TSUtils is organized into two main functional areas:
76
77
- **Type Guards**: Functions that narrow TypeScript's union types for AST nodes and type system types, with version-specific compatibility layers (2.8, 2.9, 3.0, 3.2, next)
78
- **Utilities**: General-purpose functions for AST traversal, analysis, text processing, and compiler integration
79
- **Modular Design**: Selective imports allow users to load only the functionality they need
80
- **Version Compatibility**: Hierarchical export structure ensures compatibility across TypeScript versions
81
82
## Capabilities
83
84
### Node Type Guards
85
86
Type guard functions for TypeScript AST nodes using `ts.SyntaxKind` enumeration. Provides 181 functions covering all TypeScript syntax constructs including declarations, expressions, statements, literals, and JSX elements.
87
88
```typescript { .api }
89
function isIdentifier(node: ts.Node): node is ts.Identifier;
90
function isCallExpression(node: ts.Node): node is ts.CallExpression;
91
function isIfStatement(node: ts.Node): node is ts.IfStatement;
92
function isStringLiteral(node: ts.Node): node is ts.StringLiteral;
93
function isFunctionDeclaration(node: ts.Node): node is ts.FunctionDeclaration;
94
```
95
96
[Node Type Guards](./node-typeguards.md)
97
98
### Type System Guards
99
100
Type guard functions for TypeScript's type system using `ts.TypeFlags`. Provides 18 functions for checking union types, intersection types, literal types, object types, and other type system constructs.
101
102
```typescript { .api }
103
function isUnionType(type: ts.Type): type is ts.UnionType;
104
function isIntersectionType(type: ts.Type): type is ts.IntersectionType;
105
function isLiteralType(type: ts.Type): type is ts.LiteralType;
106
function isObjectType(type: ts.Type): type is ts.ObjectType;
107
function isTypeReference(type: ts.Type): type is ts.TypeReference;
108
```
109
110
[Type System Guards](./type-guards.md)
111
112
### AST Traversal and Analysis
113
114
Comprehensive utilities for navigating, analyzing, and manipulating TypeScript AST nodes. Includes token iteration, comment processing, position mapping, and node relationship traversal.
115
116
```typescript { .api }
117
function forEachToken(node: ts.Node, cb: (node: ts.Node) => void, sourceFile?: ts.SourceFile): void;
118
function forEachComment(node: ts.Node, cb: ForEachCommentCallback, sourceFile?: ts.SourceFile): void;
119
function getPreviousToken(node: ts.Node, sourceFile?: ts.SourceFile): ts.Node | undefined;
120
function getNextToken(node: ts.Node, sourceFile?: ts.SourceFile): ts.Node | undefined;
121
function getAstNodeAtPosition(node: ts.Node, pos: number): ts.Node | undefined;
122
```
123
124
[AST Traversal and Analysis](./ast-traversal.md)
125
126
### Code Analysis and Utilities
127
128
Advanced analysis utilities for scope boundaries, variable declarations, control flow, import/export analysis, and compiler option checking.
129
130
```typescript { .api }
131
function isScopeBoundary(node: ts.Node): ScopeBoundary;
132
function getVariableDeclarationKind(declarationList: ts.VariableDeclarationList): VariableDeclarationKind;
133
function hasModifier(modifiers: ts.ModifiersArray | undefined, ...kinds: Array<ts.Modifier['kind']>): boolean;
134
function isParameterProperty(node: ts.ParameterDeclaration): boolean;
135
function findImports(sourceFile: ts.SourceFile, kinds: ImportKind): Array<ts.StringLiteral | ts.NoSubstitutionTemplateLiteral>;
136
```
137
138
[Code Analysis and Utilities](./code-analysis.md)
139
140
### Text Processing and Validation
141
142
Text processing utilities for source code analysis including line range calculation, identifier validation, comment extraction, and position-based operations.
143
144
```typescript { .api }
145
function getLineRanges(sourceFile: ts.SourceFile): LineRange[];
146
function isValidIdentifier(text: string, languageVersion?: ts.ScriptTarget): boolean;
147
function commentText(sourceText: string, comment: ts.CommentRange): string;
148
function isPositionInComment(sourceFile: ts.SourceFile, pos: number, parent?: ts.Node): boolean;
149
function isSameLine(sourceFile: ts.SourceFile, pos1: number, pos2: number): boolean;
150
```
151
152
[Text Processing and Validation](./text-processing.md)
153
154
### Variable Usage Analysis
155
156
Specialized utilities for analyzing variable declarations, usage patterns, and scope analysis. Provides detailed information about variable domains, export status, and usage locations.
157
158
```typescript { .api }
159
function collectVariableUsage(sourceFile: ts.SourceFile): Map<ts.Identifier, VariableInfo>;
160
function getUsageDomain(node: ts.Identifier): UsageDomain | undefined;
161
function getDeclarationDomain(node: ts.Identifier): DeclarationDomain | undefined;
162
163
interface VariableInfo {
164
domain: DeclarationDomain;
165
exported: boolean;
166
uses: VariableUse[];
167
inGlobalScope: boolean;
168
declarations: ts.Identifier[];
169
}
170
```
171
172
[Variable Usage Analysis](./variable-usage.md)
173
174
### Type System Utilities
175
176
Advanced type system analysis including type assignability checking, property analysis, class type inspection, and type manipulation utilities.
177
178
```typescript { .api }
179
function isTypeAssignableToNumber(checker: ts.TypeChecker, type: ts.Type): boolean;
180
function isTypeAssignableToString(checker: ts.TypeChecker, type: ts.Type): boolean;
181
function unionTypeParts(type: ts.Type): ts.Type[];
182
function getPropertyOfType(type: ts.Type, name: ts.__String): ts.Symbol | undefined;
183
function getSymbolOfClassLikeDeclaration(node: ts.ClassLikeDeclaration, checker: ts.TypeChecker): ts.Symbol;
184
```
185
186
[Type System Utilities](./type-utilities.md)
187
188
### Control Flow Analysis
189
190
Control flow analysis utilities for determining statement reachability, analyzing function signatures, and identifying control flow termination points.
191
192
```typescript { .api }
193
function endsControlFlow(statement: ts.Statement | ts.BlockLike, checker?: ts.TypeChecker): boolean;
194
function getControlFlowEnd(statement: ts.Statement | ts.BlockLike, checker?: ts.TypeChecker): ControlFlowEnd;
195
function callExpressionAffectsControlFlow(node: ts.CallExpression, checker: ts.TypeChecker): SignatureEffect | undefined;
196
```
197
198
[Control Flow Analysis](./control-flow.md)
199
200
## Types
201
202
### Common Enums
203
204
```typescript { .api }
205
enum VariableDeclarationKind {
206
Var,
207
Let,
208
Const
209
}
210
211
enum ScopeBoundary {
212
None = 0,
213
Function = 1,
214
Block = 2,
215
Type = 4,
216
ConditionalType = 8
217
}
218
219
enum AccessKind {
220
None = 0,
221
Read = 1,
222
Write = 2,
223
Delete = 4,
224
ReadWrite = Read | Write,
225
Modification = Write | Delete
226
}
227
228
enum DeclarationDomain {
229
Namespace = 1,
230
Type = 2,
231
Value = 4,
232
Import = 8,
233
Any = Namespace | Type | Value
234
}
235
236
enum UsageDomain {
237
Namespace = 1,
238
Type = 2,
239
Value = 4,
240
ValueOrNamespace = Value | Namespace,
241
Any = Namespace | Type | Value,
242
TypeQuery = 8
243
}
244
```
245
246
### Callback Types
247
248
```typescript { .api }
249
type ForEachTokenCallback = (fullText: string, kind: ts.SyntaxKind, range: ts.TextRange, parent: ts.Node) => void;
250
type ForEachCommentCallback = (fullText: string, comment: ts.CommentRange) => void;
251
```
252
253
### Utility Interfaces
254
255
```typescript { .api }
256
interface LineRange extends ts.TextRange {
257
contentLength: number;
258
}
259
260
interface NodeWrap {
261
node: ts.Node;
262
kind: ts.SyntaxKind;
263
children: NodeWrap[];
264
next?: NodeWrap;
265
skip?: NodeWrap;
266
parent?: NodeWrap;
267
}
268
```