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