0
# Core Transformation
1

2
The core transformation functionality orchestrates the entire TypeScript to Closure Compiler conversion process, providing the main entry point and configuration system for all tsickle transformations.
3

4
## Capabilities
5

6
### Main Emit Function
7

8
The primary function that transforms a TypeScript program into Closure-compatible JavaScript with proper JSDoc annotations.
9

10
```typescript { .api }
11
/**
12
 * Main tsickle emit function that transforms TypeScript to Closure-compatible JavaScript
13
 * @param program - TypeScript program to transform
14
 * @param host - Configuration host with transformation options
15
 * @param writeFile - Callback for writing transformed files
16
 * @param targetSourceFile - Optional specific file to transform
17
 * @param cancellationToken - Optional cancellation token
18
 * @param emitOnlyDtsFiles - Whether to emit only declaration files
19
 * @param customTransformers - Optional custom transformer configuration
20
 * @returns EmitResult with diagnostics and generated content
21
 */
22
function emit(
23
  program: ts.Program,
24
  host: TsickleHost,
25
  writeFile: ts.WriteFileCallback,
26
  targetSourceFile?: ts.SourceFile,
27
  cancellationToken?: ts.CancellationToken,
28
  emitOnlyDtsFiles?: boolean,
29
  customTransformers?: EmitTransformers
30
): EmitResult;
31
```
32

33
**Usage Example:**
34

35
```typescript
36
import * as ts from "typescript";
37
import { emit, TsickleHost } from "tsickle";
38

39
const program = ts.createProgram(["src/app.ts"], {
40
  rootDir: "/project/src",
41
  outDir: "/project/dist",
42
  target: ts.ScriptTarget.ES2015,
43
  module: ts.ModuleKind.CommonJS,
44
});
45

46
const host: TsickleHost = {
47
  shouldSkipTsickleProcessing: (fileName) => fileName.includes("node_modules"),
48
  shouldIgnoreWarningsForPath: (filePath) => filePath.includes("third_party"),
49
  pathToModuleName: (context, importPath) => importPath.replace(/\.tsx?$/, ""),
50
  fileNameToModuleId: (fileName) => fileName,
51
  googmodule: true,
52
  transformTypesToClosure: true,
53
  generateExtraSuppressions: true,
54
};
55

56
const result = emit(program, host, (fileName, content) => {
57
  fs.writeFileSync(fileName, content);
58
});
59
```
60

61
### Legacy Emit Function (Deprecated)
62

63
Legacy emit function maintained for backward compatibility with Angular.
64

65
```typescript { .api }
66
/**
67
 * @deprecated Exposed for backward compat with Angular. Use emit() instead.
68
 */
69
function emitWithTsickle(
70
  program: ts.Program,
71
  host: TsickleHost,
72
  tsHost: ts.CompilerHost,
73
  tsOptions: ts.CompilerOptions,
74
  targetSourceFile?: ts.SourceFile,
75
  writeFile?: ts.WriteFileCallback,
76
  cancellationToken?: ts.CancellationToken,
77
  emitOnlyDtsFiles?: boolean,
78
  customTransformers?: EmitTransformers
79
): EmitResult;
80
```
81

82
### Result Merging
83

84
Utility function for combining multiple emit results into a single consolidated result.
85

86
```typescript { .api }
87
/**
88
 * Merges multiple EmitResult objects into a single consolidated result
89
 * @param emitResults - Array of EmitResult objects to merge
90
 * @returns Single merged EmitResult
91
 */
92
function mergeEmitResults(emitResults: EmitResult[]): EmitResult;
93
```
94

95
**Usage Example:**
96

97
```typescript
98
// Process multiple programs
99
const results = programs.map(program => emit(program, host, writeFile));
100
const mergedResult = mergeEmitResults(results);
101

102
console.log(`Total files emitted: ${mergedResult.emittedFiles?.length || 0}`);
103
console.log(`Total diagnostics: ${mergedResult.diagnostics.length}`);
104
```
105

106
## Configuration
107

108
### TsickleHost Interface
109

110
Main configuration interface that controls all aspects of the transformation process.
111

112
```typescript { .api }
113
interface TsickleHost extends GoogModuleProcessorHost, TsMigrationExportsShimProcessorHost, AnnotatorHost {
114
  /** Whether to downlevel decorators */
115
  transformDecorators?: boolean;
116
  /** Whether to convert types to closure */
117
  transformTypesToClosure?: boolean;
118
  /** Are tsMigrationExports calls allowed and should shim files be emitted? */
119
  generateTsMigrationExportsShim?: boolean;
120
  /** Whether to add aliases to the .d.ts files to add the exports to the ಠ_ಠ.clutz namespace */
121
  addDtsClutzAliases?: boolean;
122
  /** If true, tsickle and decorator downlevel processing will be skipped for that file */
123
  shouldSkipTsickleProcessing(fileName: string): boolean;
124
  /** Tsickle treats warnings as errors, if true, ignore warnings. This might be useful for e.g. third party code */
125
  shouldIgnoreWarningsForPath(filePath: string): boolean;
126
  /** Whether to convert CommonJS require() imports to goog.module() and goog.require() calls */
127
  googmodule: boolean;
128
  /** Whether to transform declaration merging namespaces */
129
  useDeclarationMergingTransformation?: boolean;
130
  /** Whether to add suppressions by default */
131
  generateExtraSuppressions: boolean;
132
}
133
```
134

135
### Custom Transformers
136

137
Configuration for additional custom transformers to run alongside tsickle transformations.
138

139
```typescript { .api }
140
interface EmitTransformers {
141
  /** Custom transformers to evaluate before built-in .js transformations */
142
  beforeTs?: ts.CustomTransformers['before'];
143
  /** Custom transformers to evaluate after built-in .js transformations */
144
  afterTs?: ts.CustomTransformers['after'];
145
  /** Custom transformers to evaluate after built-in .d.ts transformations */
146
  afterDeclarations?: ts.CustomTransformers['afterDeclarations'];
147
}
148
```
149

150
## Result Types
151

152
### EmitResult Interface
153

154
Extended emit result containing tsickle-specific outputs and metadata.
155

156
```typescript { .api }
157
interface EmitResult extends ts.EmitResult {
158
  /** The manifest of JS modules output by the compiler */
159
  modulesManifest: ModulesManifest;
160
  /** externs.js files produced by tsickle, if any. module IDs are relative paths from fileNameToModuleId */
161
  externs: { [moduleId: string]: string };
162
  /** Content for the generated files, keyed by their intended filename. Filenames are google3 relative */
163
  tsMigrationExportsShimFiles: Map<string, string>;
164
}
165
```
166

167
The `EmitResult` includes all standard TypeScript emit results plus:
168
- **modulesManifest**: Dependency graph of generated modules
169
- **externs**: Generated extern definitions for ambient declarations  
170
- **tsMigrationExportsShimFiles**: Generated shim files for migration support
171

172
## Utility Functions
173

174
### Path to Module Name
175

176
Converts import paths to googmodule module names (re-exported from cli_support).
177

178
```typescript { .api }
179
/**
180
 * Takes a context (ts.SourceFile.fileName of the current file) and the import URL of an ES6
181
 * import and generates a googmodule module name for the imported module
182
 */
183
function pathToModuleName(rootModulePath: string, context: string, fileName: string): string;
184
```