0
# TypeScript ESLint Type Utils
1
2
TypeScript ESLint Type Utils provides essential type utilities for working with TypeScript within ESLint rules. This package offers a comprehensive set of functions for type analysis, type checking, and TypeScript compiler API interactions designed specifically for ESLint rule authors who need to build sophisticated type-aware rules.
3
4
## Package Information
5
6
- **Package Name**: @typescript-eslint/type-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @typescript-eslint/type-utils`
10
11
## Core Imports
12
13
```typescript
14
import {
15
isTypeReadonly,
16
getTypeName,
17
isUnsafeAssignment,
18
containsAllTypesByName,
19
isTypeAnyType,
20
getConstrainedTypeAtLocation
21
} from "@typescript-eslint/type-utils";
22
```
23
24
For CommonJS:
25
26
```javascript
27
const {
28
isTypeReadonly,
29
getTypeName,
30
isUnsafeAssignment,
31
containsAllTypesByName,
32
isTypeAnyType,
33
getConstrainedTypeAtLocation
34
} = require("@typescript-eslint/type-utils");
35
```
36
37
## Basic Usage
38
39
```typescript
40
import { RuleContext } from "@typescript-eslint/utils";
41
import { isTypeReadonly, getTypeName, isTypeAnyType } from "@typescript-eslint/type-utils";
42
43
export default {
44
create(context: RuleContext<string, unknown[]>) {
45
const services = context.parserServices;
46
const program = services.program;
47
const checker = program.getTypeChecker();
48
49
return {
50
VariableDeclaration(node) {
51
const tsNode = services.esTreeNodeToTSNodeMap.get(node);
52
const type = checker.getTypeAtLocation(tsNode);
53
54
// Check if type is readonly
55
if (isTypeReadonly(program, type)) {
56
console.log("Variable is readonly");
57
}
58
59
// Get type name
60
const typeName = getTypeName(checker, type);
61
console.log(`Type name: ${typeName}`);
62
63
// Check if type is any
64
if (isTypeAnyType(type)) {
65
context.report({
66
node,
67
messageId: "noAnyTypes"
68
});
69
}
70
}
71
};
72
}
73
};
74
```
75
76
## Architecture
77
78
TypeScript ESLint Type Utils is organized around several key functional areas:
79
80
- **Type Predicates**: Functions to test type characteristics (`isTypeAnyType`, `isNullableType`, etc.)
81
- **Type Analysis**: Tools for analyzing type structure and relationships (`getTypeName`, `containsAllTypesByName`)
82
- **Type Constraints**: Functions for working with type constraints and contextual types (`getConstrainedTypeAtLocation`, `getContextualType`)
83
- **Safety Checks**: Utilities for detecting unsafe type assignments and readonly violations (`isUnsafeAssignment`, `isTypeReadonly`)
84
- **Builtin Types**: Specialized checks for built-in TypeScript types (`isPromiseLike`, `isErrorLike`, etc.)
85
- **Symbol Analysis**: Functions for working with TypeScript symbols and declarations (`getDeclaration`, `isSymbolFromDefaultLibrary`)
86
87
## Capabilities
88
89
### Type Predicates
90
91
Essential type checking functions that determine characteristics of TypeScript types. These predicates help identify specific type categories and properties.
92
93
```typescript { .api }
94
function isTypeAnyType(type: ts.Type): boolean;
95
function isTypeUnknownType(type: ts.Type): boolean;
96
function isTypeNeverType(type: ts.Type): boolean;
97
function isNullableType(type: ts.Type): boolean;
98
function isTypeArrayTypeOrUnionOfArrayTypes(type: ts.Type, checker: ts.TypeChecker): boolean;
99
```
100
101
[Type Predicates](./type-predicates.md)
102
103
### Type Analysis
104
105
Functions for analyzing type names, structure, and relationships. Used to understand type composition and extract meaningful information from TypeScript types.
106
107
```typescript { .api }
108
function getTypeName(typeChecker: ts.TypeChecker, type: ts.Type): string;
109
function containsAllTypesByName(type: ts.Type, allowAny: boolean, allowedNames: Set<string>, matchAnyInstead?: boolean): boolean;
110
function getTypeFlags(type: ts.Type): ts.TypeFlags;
111
function isTypeFlagSet(type: ts.Type, flagsToCheck: ts.TypeFlags): boolean;
112
```
113
114
[Type Analysis](./type-analysis.md)
115
116
### Type Constraints and Context
117
118
Tools for working with TypeScript's type constraint system and contextual typing, essential for understanding generic types and inference.
119
120
```typescript { .api }
121
function getConstrainedTypeAtLocation(services: ParserServicesWithTypeInformation, node: TSESTree.Node): ts.Type;
122
function getContextualType(checker: ts.TypeChecker, node: ts.Expression): ts.Type | undefined;
123
```
124
125
[Type Constraints](./type-constraints.md)
126
127
### Type Safety Utilities
128
129
Functions for detecting potentially unsafe type operations, particularly around readonly properties and any type assignments.
130
131
```typescript { .api }
132
function isTypeReadonly(program: ts.Program, type: ts.Type, options?: ReadonlynessOptions): boolean;
133
function isUnsafeAssignment(type: ts.Type, receiver: ts.Type, checker: ts.TypeChecker, senderNode: TSESTree.Node | null): false | { receiver: ts.Type; sender: ts.Type };
134
135
interface ReadonlynessOptions {
136
readonly allow?: TypeOrValueSpecifier[];
137
readonly treatMethodsAsReadonly?: boolean;
138
}
139
```
140
141
[Type Safety](./type-safety.md)
142
143
### Builtin Type Checks
144
145
Specialized predicates for identifying built-in TypeScript types like Promise, Error, and readonly utility types.
146
147
```typescript { .api }
148
function isPromiseLike(program: ts.Program, type: ts.Type): boolean;
149
function isPromiseConstructorLike(program: ts.Program, type: ts.Type): boolean;
150
function isErrorLike(program: ts.Program, type: ts.Type): boolean;
151
function isReadonlyTypeLike(
152
program: ts.Program,
153
type: ts.Type,
154
predicate?: (subType: { aliasSymbol: ts.Symbol; aliasTypeArguments: readonly ts.Type[] } & ts.Type) => boolean
155
): boolean;
156
```
157
158
[Builtin Types](./builtin-types.md)
159
160
### Symbol and Declaration Analysis
161
162
Tools for working with TypeScript symbols, declarations, and their relationships to source files and libraries.
163
164
```typescript { .api }
165
function getDeclaration(services: ParserServicesWithTypeInformation, node: TSESTree.Node): ts.Declaration | null;
166
function isSymbolFromDefaultLibrary(program: ts.Program, symbol: ts.Symbol | undefined): boolean;
167
function getSourceFileOfNode(node: ts.Node): ts.SourceFile;
168
```
169
170
[Symbol Analysis](./symbol-analysis.md)
171
172
### Property Type Utilities
173
174
Functions for extracting and analyzing property types from complex type structures.
175
176
```typescript { .api }
177
function getTypeOfPropertyOfName(checker: ts.TypeChecker, type: ts.Type, name: string, escapedName?: ts.__String): ts.Type | undefined;
178
function getTypeOfPropertyOfType(checker: ts.TypeChecker, type: ts.Type, property: ts.Symbol): ts.Type | undefined;
179
```
180
181
[Property Types](./property-types.md)
182
183
### Type Specifiers
184
185
Advanced type matching system using specifiers to identify types from specific packages, files, or the TypeScript standard library.
186
187
```typescript { .api }
188
type TypeOrValueSpecifier = string | FileSpecifier | LibSpecifier | PackageSpecifier;
189
190
function typeMatchesSpecifier(type: ts.Type, specifier: TypeOrValueSpecifier, program: ts.Program): boolean;
191
function typeMatchesSomeSpecifier(type: ts.Type, specifiers: TypeOrValueSpecifier[], program: ts.Program): boolean;
192
function valueMatchesSpecifier(node: TSESTree.Node, specifier: TypeOrValueSpecifier, program: ts.Program, type: ts.Type): boolean;
193
function valueMatchesSomeSpecifier(node: TSESTree.Node, specifiers: TypeOrValueSpecifier[], program: ts.Program, type: ts.Type): boolean;
194
```
195
196
[Type Specifiers](./type-specifiers.md)
197
198
## Common Types
199
200
```typescript { .api }
201
interface FileSpecifier {
202
from: 'file';
203
name: string | string[];
204
path?: string;
205
}
206
207
interface LibSpecifier {
208
from: 'lib';
209
name: string | string[];
210
}
211
212
interface PackageSpecifier {
213
from: 'package';
214
name: string | string[];
215
package: string;
216
}
217
218
enum AnyType {
219
Any,
220
PromiseAny,
221
AnyArray,
222
Safe,
223
}
224
225
// Constants
226
const readonlynessOptionsDefaults: ReadonlynessOptions;
227
const readonlynessOptionsSchema: JSONSchema4;
228
const typeOrValueSpecifiersSchema: JSONSchema4;
229
```