0
# Module Graph Management
1

2
System for tracking and managing dependencies between TypeScript modules, enabling efficient tree-shaking and symbol resolution across the entire module graph.
3

4
## Capabilities
5

6
### TSModuleGraph
7

8
Manages the dependency graph between TypeScript modules for tree-shaking and symbol resolution.
9

10
```javascript { .api }
11
/**
12
 * Manages dependency relationships between TypeScript modules
13
 */
14
class TSModuleGraph {
15
  /**
16
   * Creates a new module graph with a main module
17
   * @param mainModuleName - Name of the entry point module
18
   */
19
  constructor(mainModuleName: string);
20
  
21
  /**
22
   * Adds a module to the graph
23
   * @param name - Module name
24
   * @param module - TSModule instance
25
   */
26
  addModule(name: string, module: TSModule): void;
27
  
28
  /**
29
   * Retrieves a module by name
30
   * @param name - Module name
31
   * @returns TSModule instance or null if not found
32
   */
33
  getModule(name: string): TSModule | null;
34
  
35
  /**
36
   * Marks a symbol as used and propagates usage to dependencies
37
   * @param module - Module containing the symbol
38
   * @param name - Symbol name
39
   * @param context - TypeScript transform context
40
   */
41
  markUsed(module: TSModule, name: string, context: any): void;
42
  
43
  /**
44
   * Resolves export information for a module export
45
   * @param module - Module containing the export
46
   * @param exportObj - Export definition
47
   * @returns Resolved export information or null
48
   */
49
  getExport(module: TSModule, exportObj: Export): ResolvedExport | null;
50
  
51
  /**
52
   * Resolves import to its original export
53
   * @param module - Module containing the import
54
   * @param local - Local import name
55
   * @param imported - Imported symbol name (optional)
56
   * @returns Resolved import information or null
57
   */
58
  resolveImport(module: TSModule, local: string, imported?: string): ResolvedImport | null;
59
  
60
  /**
61
   * Resolves export by name in a module
62
   * @param module - Module to search
63
   * @param name - Export name
64
   * @returns Resolved export information or null
65
   */
66
  resolveExport(module: TSModule, name: string): ResolvedExport | null;
67
  
68
  /**
69
   * Gets all exports from a module
70
   * @param module - Module to get exports from (defaults to main module)
71
   * @param excludeDefault - Whether to exclude default exports
72
   * @returns Array of resolved exports
73
   */
74
  getAllExports(module?: TSModule, excludeDefault?: boolean): ResolvedExport[];
75
  
76
  /**
77
   * Gets all external imports across all modules
78
   * @returns Map of specifier to import mappings
79
   */
80
  getAllImports(): Map<string, Map<string, string>>;
81
  
82
  /**
83
   * Propagates usage information and assigns unique names
84
   * @param context - TypeScript transform context
85
   * @returns Map of exported names to their modules
86
   */
87
  propagate(context: any): Map<string, TSModule>;
88
}
89
```
90

91
### TSModule
92

93
Represents a single TypeScript module with its imports, exports, and local bindings.
94

95
```javascript { .api }
96
/**
97
 * Represents a TypeScript module with imports, exports, and bindings
98
 */
99
class TSModule {
100
  /**
101
   * Map of local names to import information
102
   */
103
  imports: Map<string, Import>;
104
  
105
  /**
106
   * Array of export definitions
107
   */
108
  exports: Export[];
109
  
110
  /**
111
   * Map of binding names to AST node sets
112
   */
113
  bindings: Map<string, Set<any>>;
114
  
115
  /**
116
   * Map of original names to renamed names
117
   */
118
  names: Map<string, string>;
119
  
120
  /**
121
   * Set of used symbol names
122
   */
123
  used: Set<string>;
124
  
125
  /**
126
   * Creates a new empty module
127
   */
128
  constructor();
129
  
130
  /**
131
   * Adds an import to the module
132
   * @param local - Local binding name
133
   * @param specifier - Module specifier (e.g., './other-module')
134
   * @param imported - Imported symbol name ('default', '*', or named export)
135
   */
136
  addImport(local: string, specifier: string, imported: string): void;
137
  
138
  /**
139
   * Adds an export to the module
140
   * @param name - Export name
141
   * @param imported - Local symbol being exported
142
   * @param specifier - Re-export specifier (optional)
143
   */
144
  addExport(name: string, imported: string, specifier?: string): void;
145
  
146
  /**
147
   * Adds a wildcard export (export * from 'module')
148
   * @param specifier - Module specifier
149
   */
150
  addWildcardExport(specifier: string): void;
151
  
152
  /**
153
   * Adds a local binding to the module
154
   * @param name - Binding name
155
   * @param node - TypeScript AST node
156
   */
157
  addLocal(name: string, node: any): void;
158
  
159
  /**
160
   * Gets the renamed version of a symbol
161
   * @param name - Original symbol name
162
   * @returns Renamed symbol name or original if not renamed
163
   */
164
  getName(name: string): string;
165
  
166
  /**
167
   * Checks if a binding exists in the module
168
   * @param name - Binding name
169
   * @returns True if binding exists
170
   */
171
  hasBinding(name: string): boolean;
172
}
173
```
174

175
## Type Definitions
176

177
```javascript { .api }
178
/**
179
 * Import definition for a symbol
180
 */
181
type Import = {
182
  specifier: string;  // Module path
183
  imported: string;   // Symbol name in source module
184
};
185

186
/**
187
 * Export definition - either named export or wildcard
188
 */
189
type Export = 
190
  | {
191
      name: string;           // Export name
192
      imported: string;       // Local symbol name
193
      specifier?: string;     // Re-export source (optional)
194
    }
195
  | {
196
      specifier: string;      // Wildcard export source
197
    };
198

199
/**
200
 * Resolved export information
201
 */
202
type ResolvedExport = {
203
  imported: string;     // Symbol name in source module
204
  module: TSModule;     // Source module
205
  name: string;         // Export name
206
};
207

208
/**
209
 * Resolved import information
210
 */
211
type ResolvedImport = {
212
  imported: string;     // Symbol name
213
  module: TSModule;     // Source module
214
  name: string;         // Local name
215
};
216
```
217

218
**Usage Examples:**
219

220
```javascript
221
import { TSModuleGraph, TSModule } from '@parcel/transformer-typescript-types';
222

223
// Create module graph for project with entry point 'index'
224
const graph = new TSModuleGraph('index');
225

226
// Create and configure the main module
227
const mainModule = new TSModule();
228
mainModule.addImport('Button', './button', 'default');    // import Button from './button'
229
mainModule.addImport('utils', './utils', '*');            // import * as utils from './utils'
230
mainModule.addImport('React', 'react', 'default');        // import React from 'react'
231
mainModule.addExport('Button', 'Button');                 // export { Button }
232
mainModule.addLocal('config', configNode);                // const config = { ... }
233
graph.addModule('index', mainModule);
234

235
// Create button module with re-exports
236
const buttonModule = new TSModule();
237
buttonModule.addImport('Component', 'react', 'Component'); // import { Component } from 'react'
238
buttonModule.addLocal('Button', buttonClassNode);          // class Button extends Component
239
buttonModule.addExport('default', 'Button');              // export default Button
240
graph.addModule('./button', buttonModule);
241

242
// Track usage starting from exports
243
graph.markUsed(mainModule, 'Button', context);
244

245
// Propagate usage and get final exported names
246
const exportedNames = graph.propagate(context);
247
console.log(exportedNames.get('Button')); // mainModule
248

249
// Get all external imports needed in final output
250
const externalImports = graph.getAllImports();
251
// Map { 'react' => Map { 'React' => 'default', 'Component' => 'Component' } }
252

253
// Resolve specific imports
254
const resolved = graph.resolveImport(mainModule, 'Button');
255
console.log(resolved); // { imported: 'Button', module: mainModule, name: 'Button' }
256
```
257

258
## Graph Operations
259

260
### Symbol Resolution
261

262
The module graph provides sophisticated symbol resolution that:
263

264
- Follows import chains across multiple modules
265
- Resolves re-exports to their original sources
266
- Handles namespace imports and qualified name references
267
- Tracks external module dependencies
268

269
### Usage Propagation
270

271
When a symbol is marked as used:
272

273
1. If it's an import, marks the symbol as used in the source module
274
2. Recursively marks dependencies in the original binding
275
3. Visits all AST nodes associated with the binding
276
4. Marks any referenced types as used
277

278
### Name Collision Resolution
279

280
The propagation phase assigns unique names to avoid conflicts:
281

282
- Preserves exported names for public API
283
- Renames internal symbols that would conflict
284
- Handles namespace collisions across modules
285
- Updates import statements for external dependencies