0
# Program Management
1

2
Functions for creating and managing TypeScript programs with sophisticated caching. These utilities handle TypeScript program creation, file system operations, and cache management for optimal performance.
3

4
## Capabilities
5

6
### Program Creation
7

8
Functions for creating TypeScript programs from configuration files and managing program lifecycle.
9

10
```typescript { .api }
11
/**
12
 * Creates a TypeScript program from a config file
13
 * @param configFile - Path to tsconfig.json file
14
 * @returns TypeScript Program instance
15
 */
16
function createProgram(configFile: string): ts.Program;
17

18
/**
19
 * Gets the canonical file name for the current file system
20
 * @param fileName - File path to canonicalize
21
 * @returns Canonical file name respecting case sensitivity
22
 */
23
function getCanonicalFileName(fileName: string): string;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { createProgram, getCanonicalFileName } from "@typescript-eslint/typescript-estree";
30

31
// Create program from config
32
const program = createProgram('./tsconfig.json');
33
const checker = program.getTypeChecker();
34

35
// Get canonical file names
36
const canonical = getCanonicalFileName('/path/to/File.ts');
37
// On case-insensitive systems: '/path/to/file.ts'
38
// On case-sensitive systems: '/path/to/File.ts'
39
```
40

41
### Script Kind Utilities
42

43
Functions for determining TypeScript script kinds and language variants from file paths.
44

45
```typescript { .api }
46
/**
47
 * Determines TypeScript script kind from file path and JSX setting
48
 * @param filePath - Path to the file
49
 * @param jsx - Whether JSX is enabled for unknown extensions
50
 * @returns TypeScript ScriptKind enum value
51
 */
52
function getScriptKind(filePath: string, jsx: boolean): ts.ScriptKind;
53

54
/**
55
 * Gets language variant from script kind
56
 * @param scriptKind - TypeScript ScriptKind
57
 * @returns Language variant (JSX or Standard)
58
 */
59
function getLanguageVariant(scriptKind: ts.ScriptKind): ts.LanguageVariant;
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { getScriptKind, getLanguageVariant } from "@typescript-eslint/typescript-estree";
66

67
// Determine script kinds
68
const jsKind = getScriptKind('file.js', false);     // ScriptKind.JS
69
const tsKind = getScriptKind('file.ts', false);     // ScriptKind.TS
70
const jsxKind = getScriptKind('file.jsx', false);   // ScriptKind.JSX
71
const tsxKind = getScriptKind('file.tsx', false);   // ScriptKind.TSX
72
const unknownKind = getScriptKind('file.vue', true); // ScriptKind.TSX (jsx=true)
73

74
// Get language variants
75
const jsxVariant = getLanguageVariant(jsxKind);     // LanguageVariant.JSX
76
const standardVariant = getLanguageVariant(tsKind); // LanguageVariant.Standard
77
```
78

79
### Cache Management
80

81
Comprehensive cache clearing functions for managing internal parser state and memory usage.
82

83
```typescript { .api }
84
/**
85
 * Clears all internal caches including programs, configurations, and globs
86
 * Use in tests or iterative linting to prevent memory leaks
87
 */
88
function clearCaches(): void;
89

90
/**
91
 * @deprecated Use clearCaches() instead
92
 * Legacy alias for clearCaches function
93
 */
94
function clearProgramCache(): void;
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { clearCaches } from "@typescript-eslint/typescript-estree";
101

102
// Clear all caches (recommended)
103
clearCaches();
104

105
// In testing scenarios
106
afterEach(() => {
107
  clearCaches();
108
});
109

110
// In long-running processes between projects
111
function processProject(projectPath: string) {
112
  // ... process project
113
  clearCaches(); // Clean up for next project
114
}
115
```
116

117
### Internal Cache Functions
118

119
Internal cache management functions for specific cache types (primarily for testing).
120

121
```typescript { .api }
122
/**
123
 * Clears watch program caches
124
 * @internal
125
 */
126
function clearWatchCaches(): void;
127

128
/**
129
 * Clears default project matched files cache
130
 * @internal
131
 */
132
function clearDefaultProjectMatchedFiles(): void;
133

134
/**
135
 * Clears TSConfig match cache
136
 * @internal
137
 */
138
function clearTSConfigMatchCache(): void;
139

140
/**
141
 * Clears TypeScript server project service
142
 * @internal
143
 */
144
function clearTSServerProjectService(): void;
145

146
/**
147
 * Clears glob resolution cache
148
 * @internal
149
 */
150
function clearGlobCache(): void;
151
```
152

153
### Configuration Management
154

155
Functions for managing TypeScript configuration root directories and project detection.
156

157
```typescript { .api }
158
/**
159
 * Adds a candidate directory for TypeScript config root detection
160
 * @param candidate - Directory path to add as candidate
161
 */
162
function addCandidateTSConfigRootDir(candidate: string): void;
163

164
/**
165
 * Clears all candidate TypeScript config root directories
166
 */
167
function clearCandidateTSConfigRootDirs(): void;
168

169
/**
170
 * Gets the inferred TypeScript config root directory
171
 * @returns Inferred root directory path
172
 * @throws Error if multiple candidates exist without explicit setting
173
 * @internal
174
 */
175
function getInferredTSConfigRootDir(): string;
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import { 
182
  addCandidateTSConfigRootDir,
183
  clearCandidateTSConfigRootDirs
184
} from "@typescript-eslint/typescript-estree";
185

186
// Add candidate directories
187
addCandidateTSConfigRootDir('/project1');
188
addCandidateTSConfigRootDir('/project2');
189

190
// Clear candidates (typically in cleanup)
191
clearCandidateTSConfigRootDirs();
192
```
193

194
## Program and File System Types
195

196
```typescript { .api }
197
// Internal program result types
198
interface ASTAndNoProgram {
199
  ast: ts.SourceFile;
200
  program: null;
201
}
202

203
interface ASTAndDefiniteProgram {
204
  ast: ts.SourceFile;
205
  program: ts.Program;
206
}
207

208
type ASTAndProgram = ASTAndDefiniteProgram | ASTAndNoProgram;
209

210
// Canonical path type for file system operations
211
type CanonicalPath = string & { __brand: 'CanonicalPath' };
212

213
// Default file extensions supported
214
const DEFAULT_EXTRA_FILE_EXTENSIONS: Set<string>;
215

216
// Default compiler options for program creation
217
interface DefaultCompilerOptions extends ts.CompilerOptions {
218
  allowJs: true;
219
  allowNonTsExtensions: true;
220
  checkJs: true;
221
  // ... additional core options
222
}
223
```