0
# Parser Configuration
1

2
Configuration options and services for controlling parsing behavior and accessing TypeScript type information. These options allow fine-grained control over the parsing process and enable integration with TypeScript's type system.
3

4
## Capabilities
5

6
### TSESTree Options
7

8
Main configuration interface for parsing options, controlling output format, TypeScript integration, and performance settings.
9

10
```typescript { .api }
11
/**
12
 * Configuration options for TypeScript ESTree parsing
13
 */
14
interface TSESTreeOptions {
15
  /** Controls whether location information is included on AST nodes */
16
  loc?: boolean;
17
  /** Controls whether range information is included on AST nodes */
18
  range?: boolean;
19
  /** Set to true to create a top-level array containing all tokens */
20
  tokens?: boolean;
21
  /** Create a top-level comments array containing all comments */
22
  comment?: boolean;
23
  /** Enable parsing of JSX syntax */
24
  jsx?: boolean;
25
  /** Absolute path to the file being parsed */
26
  filePath?: string;
27
  /** Specify the source type (script or module) */
28
  sourceType?: SourceType;
29
  /** Allows invalid AST from TypeScript for error recovery */
30
  allowInvalidAST?: boolean;
31
  /** Error if unknown AST node type encountered */
32
  errorOnUnknownASTType?: boolean;
33
  /** Error on TypeScript syntax and semantic issues */
34
  errorOnTypeScriptSyntacticAndSemanticIssues?: boolean;
35
  /** Custom logging function or false to disable */
36
  loggerFn?: ((message: string) => void) | false;
37
  /** Suppress deprecated property warnings */
38
  suppressDeprecatedPropertyWarnings?: boolean;
39
  /** Debug level configuration */
40
  debugLevel?: DebugLevel;
41
  /** JSDoc parsing mode for TypeScript 5.3+ */
42
  jsDocParsingMode?: JSDocParsingMode;
43
}
44
```
45

46
### Project Configuration Options
47

48
Options for integrating with TypeScript projects and enabling type information services.
49

50
```typescript { .api }
51
/**
52
 * Additional options for parseAndGenerateServices with project integration
53
 */
54
interface ParseAndGenerateServicesOptions extends TSESTreeOptions {
55
  /** Path(s) to tsconfig.json or true to find nearest */
56
  project?: boolean | string | string[] | null;
57
  /** Root directory for resolving project paths */
58
  tsconfigRootDir?: string;
59
  /** Folders to ignore when resolving project globs */
60
  projectFolderIgnoreList?: string[];
61
  /** Whether to create a shared TypeScript project service */
62
  projectService?: boolean | ProjectServiceOptions;
63
  /** Non-standard file extensions to parse */
64
  extraFileExtensions?: string[];
65
  /** Array of TypeScript Program instances to use */
66
  programs?: ts.Program[] | null;
67
  /** Control AST node maps preservation */
68
  preserveNodeMaps?: boolean;
69
  /** Disable automatic single-run inference for performance */
70
  disallowAutomaticSingleRunInference?: boolean;
71
  /** Cache lifetime configuration */
72
  cacheLifetime?: {
73
    glob?: CacheDurationSeconds;
74
  };
75
}
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { parseAndGenerateServices, type TSESTreeOptions } from "@typescript-eslint/typescript-estree";
82

83
// Basic options
84
const basicOptions: TSESTreeOptions = {
85
  loc: true,
86
  range: true,
87
  tokens: true,
88
  comment: true,
89
  jsx: false
90
};
91

92
// Project-based options
93
const projectOptions = {
94
  ...basicOptions,
95
  project: './tsconfig.json',
96
  tsconfigRootDir: __dirname,
97
  extraFileExtensions: ['.vue']
98
};
99

100
// Project service options (recommended)
101
const serviceOptions = {
102
  ...basicOptions,
103
  projectService: {
104
    allowDefaultProject: ['*.js'],
105
    maximumDefaultProjectFileMatchCount: 8
106
  }
107
};
108
```
109

110
### Parser Services
111

112
Services provided by parseAndGenerateServices for accessing TypeScript type information and AST mappings.
113

114
```typescript { .api }
115
/**
116
 * Base parser services available in all parsing modes
117
 */
118
interface ParserServicesBase {
119
  emitDecoratorMetadata: boolean | undefined;
120
  experimentalDecorators: boolean | undefined;
121
  isolatedDeclarations: boolean | undefined;
122
}
123

124
/**
125
 * Node mapping services for converting between ESTree and TypeScript nodes
126
 */
127
interface ParserServicesNodeMaps {
128
  esTreeNodeToTSNodeMap: ParserWeakMapESTreeToTSNode;
129
  tsNodeToESTreeNodeMap: ParserWeakMap<TSNode | TSToken, TSESTree.Node>;
130
}
131

132
/**
133
 * Parser services with full TypeScript type information
134
 */
135
interface ParserServicesWithTypeInformation extends ParserServicesNodeMaps, ParserServicesBase {
136
  program: ts.Program;
137
  getSymbolAtLocation: (node: TSESTree.Node) => ts.Symbol | undefined;
138
  getTypeAtLocation: (node: TSESTree.Node) => ts.Type;
139
}
140

141
/**
142
 * Parser services without TypeScript type information
143
 */
144
interface ParserServicesWithoutTypeInformation extends ParserServicesNodeMaps, ParserServicesBase {
145
  program: null;
146
}
147

148
/**
149
 * Union type of all parser services
150
 */
151
type ParserServices = 
152
  | ParserServicesWithoutTypeInformation
153
  | ParserServicesWithTypeInformation;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { parseAndGenerateServices } from "@typescript-eslint/typescript-estree";
160

161
const result = parseAndGenerateServices(code, { project: './tsconfig.json' });
162

163
// Check if type information is available
164
if (result.services.program) {
165
  // TypeScript program is available
166
  const checker = result.services.program.getTypeChecker();
167
  const sourceFile = result.services.program.getSourceFile('file.ts');
168
  
169
  // Get type information for nodes
170
  const someNode = result.ast.body[0];
171
  const symbol = result.services.getSymbolAtLocation(someNode);
172
  const type = result.services.getTypeAtLocation(someNode);
173
}
174

175
// Access node mappings
176
const esTreeNode = result.ast.body[0];
177
const tsNode = result.services.esTreeNodeToTSNodeMap.get(esTreeNode);
178
```
179

180
### Utility Configuration Functions
181

182
Functions for managing parser configuration and project setup.
183

184
```typescript { .api }
185
/**
186
 * Removes project-related options for isolated parsing
187
 * @param opts - Options object to modify
188
 * @returns Options without project-related properties
189
 */
190
function withoutProjectParserOptions<Options extends object>(
191
  opts: Options
192
): Omit<Options, 'EXPERIMENTAL_useProjectService' | 'project' | 'projectService'>;
193

194
/**
195
 * Adds a candidate directory for TSConfig root detection
196
 * @param candidate - Directory path to add as candidate
197
 */
198
function addCandidateTSConfigRootDir(candidate: string): void;
199

200
/**
201
 * Clears all candidate TSConfig root directories
202
 */
203
function clearCandidateTSConfigRootDirs(): void;
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
import { 
210
  withoutProjectParserOptions,
211
  addCandidateTSConfigRootDir
212
} from "@typescript-eslint/typescript-estree";
213

214
// Remove project options for isolated parsing
215
const isolatedOptions = withoutProjectParserOptions({
216
  project: './tsconfig.json',
217
  projectService: true,
218
  loc: true,
219
  range: true
220
});
221
// Result: { loc: true, range: true }
222

223
// Add candidate TSConfig directories
224
addCandidateTSConfigRootDir('/path/to/project');
225
addCandidateTSConfigRootDir('/another/project');
226
```
227

228
## Type Definitions
229

230
```typescript { .api }
231
// Weak map interfaces for type safety
232
interface ParserWeakMap<Key, ValueBase> {
233
  get<Value extends ValueBase>(key: Key): Value;
234
  has(key: unknown): boolean;
235
}
236

237
interface ParserWeakMapESTreeToTSNode<Key extends TSESTree.Node = TSESTree.Node> {
238
  get<KeyBase extends Key>(key: KeyBase): TSESTreeToTSNode<KeyBase>;
239
  has(key: unknown): boolean;
240
}
241

242
// Source type enumeration
243
type SourceType = 'script' | 'module';
244

245
// Debug level configuration
246
type DebugLevel = boolean | ('typescript-eslint' | 'eslint' | 'typescript')[];
247

248
// JSDoc parsing modes for TypeScript 5.3+
249
type JSDocParsingMode = 'all' | 'none' | 'type-info';
250

251
// Cache duration configuration
252
type CacheDurationSeconds = number | 'Infinity';
253
```