0
# AST Parsing
1

2
Extensible parsing system that converts TypeScript AST nodes to internal type representations, supporting all TypeScript language features and custom parsing extensions.
3

4
## Capabilities
5

6
### Parser Factory Function
7

8
Creates a comprehensive node parser with all built-in parsers and optional custom extensions.
9

10
```typescript { .api }
11
/**
12
 * Create a node parser with all built-in parsers
13
 * @param program - TypeScript program instance
14
 * @param config - Configuration object
15
 * @param augmentor - Optional function to add custom parsers
16
 * @returns Configured NodeParser instance
17
 */
18
function createParser(
19
  program: ts.Program, 
20
  config: CompletedConfig, 
21
  augmentor?: ParserAugmentor
22
): NodeParser;
23

24
type ParserAugmentor = (parser: MutableParser) => void;
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { createParser, SubNodeParser, BaseType, Context } from "ts-json-schema-generator";
31

32
// Basic parser creation
33
const parser = createParser(program, config);
34

35
// Parser with custom extension
36
const customParser = createParser(program, config, (parser) => {
37
  parser.addNodeParser(new MyCustomParser());
38
});
39
```
40

41
### Core Parser Interface
42

43
Primary interface for converting TypeScript AST nodes to internal type representations.
44

45
```typescript { .api }
46
interface NodeParser {
47
  /**
48
   * Convert a TypeScript AST node to internal type representation
49
   * @param node - TypeScript AST node to parse
50
   * @param context - Parsing context with type arguments and parameters
51
   * @param reference - Optional reference type for resolution
52
   * @returns Internal type representation
53
   */
54
  createType(node: ts.Node, context: Context, reference?: ReferenceType): BaseType;
55
}
56
```
57

58
### Parser Context
59

60
Context object that maintains state during parsing including type arguments, parameters, and references.
61

62
```typescript { .api }
63
class Context {
64
  constructor(reference?: ts.Node);
65
  
66
  /** Add a type argument to the context */
67
  pushArgument(argumentType: BaseType): void;
68
  
69
  /** Add a type parameter name to the context */
70
  pushParameter(parameterName: string): void;
71
  
72
  /** Set default value for a type parameter */
73
  setDefault(parameterName: string, argumentType: BaseType): void;
74
  
75
  /** Get unique cache key for this context */
76
  getCacheKey(): string;
77
  
78
  /** Get type argument for a parameter name */
79
  getArgument(parameterName: string): BaseType;
80
  
81
  /** Get all parameter names */
82
  getParameters(): readonly string[];
83
  
84
  /** Get all type arguments */
85
  getArguments(): readonly BaseType[];
86
  
87
  /** Get the reference node */
88
  getReference(): ts.Node | undefined;
89
}
90
```
91

92
**Context Usage Examples:**
93

94
```typescript
95
// Creating context for generic type parsing
96
const context = new Context(referenceNode);
97
context.pushParameter("T");
98
context.pushParameter("U");
99
context.pushArgument(stringType);
100
context.pushArgument(numberType);
101

102
// T resolves to stringType, U resolves to numberType
103
const typeArgument = context.getArgument("T");
104
```
105

106
### Extensible Parser System
107

108
Custom parser interface for handling new TypeScript syntax or special constructs.
109

110
```typescript { .api }
111
interface SubNodeParser extends NodeParser {
112
  /**
113
   * Check if this parser can handle the given AST node
114
   * @param node - TypeScript AST node to check
115
   * @returns true if this parser supports the node type
116
   */
117
  supportsNode(node: ts.Node): boolean;
118
}
119

120
interface MutableParser {
121
  /**
122
   * Add a custom parser to the parsing chain
123
   * @param parser - Custom parser implementation
124
   */
125
  addNodeParser(parser: SubNodeParser): void;
126
}
127
```
128

129
**Custom Parser Example:**
130

131
```typescript
132
import { SubNodeParser, BaseType, Context, StringType } from "ts-json-schema-generator";
133
import ts from "ts-json-schema-generator";
134

135
class MyCustomParser implements SubNodeParser {
136
  supportsNode(node: ts.Node): boolean {
137
    return node.kind === ts.SyntaxKind.ConstructorType;
138
  }
139
  
140
  createType(node: ts.Node, context: Context, reference?: ReferenceType): BaseType {
141
    // Custom parsing logic
142
    return new StringType(); // Example: treat constructors as strings
143
  }
144
}
145
```
146

147
### Built-in Node Parsers
148

149
Comprehensive set of parsers for all TypeScript language constructs.
150

151
#### Type Declaration Parsers
152

153
```typescript { .api }
154
// Interface and class declarations
155
class InterfaceAndClassNodeParser implements SubNodeParser {}
156

157
// Type alias declarations  
158
class TypeAliasNodeParser implements SubNodeParser {}
159

160
// Enum declarations
161
class EnumNodeParser implements SubNodeParser {}
162
```
163

164
#### Literal Parsers
165

166
```typescript { .api }
167
// String literals and template literals
168
class StringLiteralNodeParser implements SubNodeParser {}
169
class StringTemplateLiteralNodeParser implements SubNodeParser {}
170

171
// Number literals
172
class NumberLiteralNodeParser implements SubNodeParser {}
173

174
// Boolean literals
175
class BooleanLiteralNodeParser implements SubNodeParser {}
176

177
// Null and undefined literals
178
class NullLiteralNodeParser implements SubNodeParser {}
179
class UndefinedLiteralNodeParser implements SubNodeParser {}
180
```
181

182
#### Type System Parsers
183

184
```typescript { .api }
185
// Primitive type keywords
186
class StringTypeNodeParser implements SubNodeParser {}
187
class NumberTypeNodeParser implements SubNodeParser {}
188
class BooleanTypeNodeParser implements SubNodeParser {}
189
class AnyTypeNodeParser implements SubNodeParser {}
190
class UnknownTypeNodeParser implements SubNodeParser {}
191
class VoidTypeNodeParser implements SubNodeParser {}
192
class NeverTypeNodeParser implements SubNodeParser {}
193
class UndefinedTypeNodeParser implements SubNodeParser {}
194
class SymbolTypeNodeParser implements SubNodeParser {}
195

196
// Complex type constructs
197
class ArrayNodeParser implements SubNodeParser {}
198
class TupleNodeParser implements SubNodeParser {}
199
class UnionNodeParser implements SubNodeParser {}
200
class IntersectionNodeParser implements SubNodeParser {}
201
class OptionalTypeNodeParser implements SubNodeParser {}
202
class RestTypeNodeParser implements SubNodeParser {}
203
```
204

205
#### Advanced Type Parsers
206

207
```typescript { .api }
208
// Generic and conditional types
209
class TypeReferenceNodeParser implements SubNodeParser {}
210
class ConditionalTypeNodeParser implements SubNodeParser {}
211
class MappedTypeNodeParser implements SubNodeParser {}
212
class IndexedAccessTypeNodeParser implements SubNodeParser {}
213

214
// Function and constructor types
215
class FunctionNodeParser implements SubNodeParser {}
216
class ConstructorNodeParser implements SubNodeParser {}
217
class ParameterParser implements SubNodeParser {}
218

219
// Type operators
220
class TypeofNodeParser implements SubNodeParser {}
221
class TypeOperatorNodeParser implements SubNodeParser {}
222
class InferTypeNodeParser implements SubNodeParser {}
223
```
224

225
#### Expression Parsers
226

227
```typescript { .api }
228
// Object and array expressions
229
class ObjectLiteralExpressionNodeParser implements SubNodeParser {}
230
class ArrayLiteralExpressionNodeParser implements SubNodeParser {}
231

232
// Other expressions
233
class AsExpressionNodeParser implements SubNodeParser {}
234
class CallExpressionParser implements SubNodeParser {}
235
class PropertyAccessExpressionParser implements SubNodeParser {}
236
class PrefixUnaryExpressionNodeParser implements SubNodeParser {}
237
class ParenthesizedNodeParser implements SubNodeParser {}
238
class ExpressionWithTypeArgumentsNodeParser implements SubNodeParser {}
239
```
240

241
### Parser Infrastructure
242

243
Chain and specialized parsers that manage the parsing process.
244

245
```typescript { .api }
246
/** Chains multiple parsers together */
247
class ChainNodeParser implements NodeParser {
248
  constructor(parsers: SubNodeParser[]);
249
  addNodeParser(parser: SubNodeParser): void;
250
}
251

252
/** Handles circular type references */
253
class CircularReferenceNodeParser implements NodeParser {}
254

255
/** Controls type exposure based on configuration */
256
class ExposeNodeParser implements NodeParser {}
257

258
/** Handles top-level reference generation */
259
class TopRefNodeParser implements NodeParser {}
260

261
/** Adds JSDoc annotations to types */
262
class AnnotatedNodeParser implements SubNodeParser {}
263

264
/** Handles hidden/internal types */
265
class HiddenNodeParser implements SubNodeParser {}
266
```
267

268
### Annotation Readers
269

270
Interfaces for reading JSDoc annotations and converting them to schema metadata.
271

272
```typescript { .api }
273
interface AnnotationsReader {
274
  /** Read annotations from a TypeScript node */
275
  getAnnotations(node: ts.Node): object;
276
}
277

278
/** Basic JSDoc tag reading */
279
class BasicAnnotationsReader implements AnnotationsReader {}
280

281
/** Extended JSDoc reading with validation keywords */
282
class ExtendedAnnotationsReader implements AnnotationsReader {}
283
```
284

285
**Annotation Examples:**
286

287
TypeScript with JSDoc:
288
```typescript
289
interface User {
290
  /** @format email */
291
  email: string;
292
  
293
  /** @minimum 0 @maximum 120 */
294
  age: number;
295
  
296
  /** @pattern ^[a-zA-Z]+$ */
297
  name: string;
298
}
299
```
300

301
Generated schema metadata:
302
```json
303
{
304
  "email": { "type": "string", "format": "email" },
305
  "age": { "type": "number", "minimum": 0, "maximum": 120 },
306
  "name": { "type": "string", "pattern": "^[a-zA-Z]+$" }
307
}
308
```