0
# Module System Transformation
1

2
Converts CommonJS require() imports to goog.module() and goog.require() calls, with comprehensive support for ES6 module syntax transformation to Closure Compiler's module system.
3

4
## Capabilities
5

6
### CommonJS to goog.module Transformer
7

8
Main transformer that converts CommonJS and ES6 modules to Closure's goog.module format.
9

10
```typescript { .api }
11
/**
12
 * Main transformer factory for CommonJS to goog.module conversion
13
 */
14
function commonJsToGoogmoduleTransformer(
15
  host: GoogModuleProcessorHost,
16
  modulesManifest: ModulesManifest,
17
  typeChecker: ts.TypeChecker
18
): ts.TransformerFactory<ts.SourceFile>;
19
```
20

21
**Usage Example:**
22

23
```typescript
24
import { commonJsToGoogmoduleTransformer, ModulesManifest } from "tsickle";
25

26
const manifest = new ModulesManifest();
27
const host: GoogModuleProcessorHost = {
28
  pathToModuleName: (context, importPath) => importPath.replace(/\.tsx?$/, ''),
29
  fileNameToModuleId: (fileName) => fileName,
30
  isJsTranspilation: false
31
};
32

33
const transformer = commonJsToGoogmoduleTransformer(host, manifest, typeChecker);
34
```
35

36
### Module Resolution
37

38
Functions for resolving and managing module names in the goog.module system.
39

40
```typescript { .api }
41
/**
42
 * Resolves module names for goog.module
43
 */
44
function resolveModuleName(
45
  typechecker: ts.TypeChecker,
46
  node: ts.Node,
47
  pathToModuleName: (context: string, importPath: string) => string,
48
  host: ts.ModuleResolutionHost
49
): string | undefined;
50

51
/**
52
 * Gets namespace for import URL
53
 */
54
function namespaceForImportUrl(
55
  host: GoogModuleProcessorHost,
56
  context: string,
57
  importUrl: string
58
): string;
59

60
/**
61
 * Gets ambient module symbol
62
 */
63
function getAmbientModuleSymbol(
64
  typeChecker: ts.TypeChecker,
65
  moduleName: string
66
): ts.Symbol | undefined;
67
```
68

69
### Module Marker Extraction
70

71
Utility for extracting module marker symbols from TypeScript library options.
72

73
```typescript { .api }
74
/**
75
 * Extracts module marker symbols
76
 */
77
function extractModuleMarker(tsOptionsLib: readonly string[]): ts.Symbol[];
78
```
79

80
### Module Comment Processing
81

82
Functions for handling existing goog.module comments and markers.
83

84
```typescript { .api }
85
/**
86
 * Gets original goog.module name from comment
87
 */
88
function getOriginalGoogModuleFromComment(sourceFile: ts.SourceFile): string | undefined;
89
```
90

91
## Configuration
92

93
### GoogModuleProcessorHost Interface
94

95
Configuration interface for goog.module processing behavior.
96

97
```typescript { .api }
98
interface GoogModuleProcessorHost {
99
  /** Converts import paths to module names */
100
  pathToModuleName(context: string, importPath: string): string;
101
  /** Converts file names to module IDs */
102
  fileNameToModuleId(fileName: string): string;
103
  /** Whether this is a JS transpilation (optional) */
104
  isJsTranspilation?: boolean;
105
}
106
```
107

108
**Configuration Example:**
109

110
```typescript
111
const host: GoogModuleProcessorHost = {
112
  pathToModuleName: (context, importPath) => {
113
    // Convert relative imports to module names
114
    if (importPath.startsWith('./')) {
115
      return path.resolve(path.dirname(context), importPath).replace(/\.tsx?$/, '');
116
    }
117
    return importPath;
118
  },
119
  fileNameToModuleId: (fileName) => {
120
    // Convert file paths to module IDs
121
    return fileName.replace(/^\/project\/src\//, '').replace(/\.tsx?$/, '');
122
  },
123
  isJsTranspilation: false
124
};
125
```
126

127
## Module Dependencies
128

129
### ModulesManifest Class
130

131
Manages the module dependency graph of output JavaScript files.
132

133
```typescript { .api }
134
/**
135
 * A class that maintains the module dependency graph of output JS files
136
 */
137
class ModulesManifest {
138
  /** Merges another manifest */
139
  addManifest(other: ModulesManifest): void;
140
  /** Registers a module */
141
  addModule(fileName: string, module: string): void;
142
  /** Adds module reference */
143
  addReferencedModule(fileName: string, resolvedModule: string): void;
144
  /** Gets filename from module name */
145
  getFileNameFromModule(module: string): string;
146
  /** Gets referenced modules */
147
  getReferencedModules(fileName: string): string[];
148
  /** All registered modules */
149
  get modules(): string[];
150
  /** All registered file names */
151
  get fileNames(): string[];
152
}
153
```
154

155
**Usage Example:**
156

157
```typescript
158
const manifest = new ModulesManifest();
159

160
// Register modules
161
manifest.addModule('src/utils.js', 'app.utils');
162
manifest.addModule('src/main.js', 'app.main');
163

164
// Track dependencies
165
manifest.addReferencedModule('src/main.js', 'app.utils');
166

167
// Query dependencies
168
const dependencies = manifest.getReferencedModules('src/main.js');
169
console.log(dependencies); // ['app.utils']
170
```
171

172
### FileMap Interface
173

174
Generic interface for file-based mappings.
175

176
```typescript { .api }
177
interface FileMap<T> {
178
  [fileName: string]: T;
179
}
180
```
181

182
## Transformation Examples
183

184
### Import Statements
185

186
```typescript
187
// Before transformation (TypeScript/ES6)
188
import { Component } from '@angular/core';
189
import * as utils from './utils';
190
import defaultExport from './default-export';
191

192
// After transformation (goog.module)
193
goog.module('app.component');
194

195
const Component = goog.require('angular.core.Component');
196
const utils = goog.require('app.utils');
197
const defaultExport = goog.require('app.default_export');
198
```
199

200
### Export Statements
201

202
```typescript
203
// Before transformation
204
export class MyClass {}
205
export const MY_CONSTANT = 'value';
206
export default function defaultFunction() {}
207

208
// After transformation
209
goog.module('app.my_module');
210

211
class MyClass {}
212
const MY_CONSTANT = 'value';
213
function defaultFunction() {}
214

215
exports.MyClass = MyClass;
216
exports.MY_CONSTANT = MY_CONSTANT;
217
exports = defaultFunction;
218
```
219

220
### Dynamic Imports
221

222
```typescript
223
// Before transformation
224
const module = await import('./dynamic-module');
225

226
// After transformation
227
const module = await goog.module.get('app.dynamic_module');
228
```
229

230
### Module Namespace Handling
231

232
```typescript
233
// Before transformation
234
import * as fs from 'fs';
235
fs.readFileSync('file.txt');
236

237
// After transformation
238
const fs = goog.require('node.fs');
239
fs.readFileSync('file.txt');
240
```
241

242
## Error Handling
243

244
The module system transformation includes comprehensive error handling and diagnostics for common issues:
245

246
- **Circular dependencies**: Detected and reported with helpful error messages
247
- **Missing modules**: Import resolution failures are clearly reported
248
- **Invalid module names**: Module name validation with suggestions
249
- **Namespace conflicts**: Detection of conflicting module names
250

251
## Integration with Other Systems
252

253
The module system transformation integrates with:
254

255
- **Type Translation**: Ensures proper type imports in generated JSDoc
256
- **Decorator Processing**: Handles decorator imports and dependencies  
257
- **Externs Generation**: Coordinates with extern generation for ambient modules
258
- **JSDoc Processing**: Maintains JSDoc comments through module transformations