0
# TypeScript Compilation
1

2
Advanced TypeScript compilation system with host augmentation for Angular-specific requirements including dependency collection, resource loading, and file replacements.
3

4
## Capabilities
5

6
### Host Augmentation for Resources
7

8
Augments TypeScript compiler host with resource loading capabilities for Angular templates and stylesheets.
9

10
```typescript { .api }
11
/**
12
 * Augments TypeScript compiler host with resource loading capabilities
13
 * Enables loading of Angular component templates and stylesheets
14
 * @param host - Base TypeScript compiler host
15
 * @param resourceLoader - Webpack resource loader instance
16
 * @param options - Resource loading options
17
 */
18
function augmentHostWithResources(
19
  host: ts.CompilerHost,
20
  resourceLoader: WebpackResourceLoader,
21
  options?: {
22
    directTemplateLoading?: boolean;
23
    inlineStyleFileExtension?: string;
24
  }
25
): void;
26
```
27

28
### Host Augmentation for Dependency Collection
29

30
Augments compiler host to collect and track file dependencies during compilation.
31

32
```typescript { .api }
33
/**
34
 * Augments host to collect dependencies during compilation
35
 * Tracks file dependencies for webpack's dependency graph
36
 * @param host - Base TypeScript compiler host
37
 * @param dependencies - Map storing file dependencies
38
 * @param moduleResolutionCache - Optional cache for resolved modules
39
 */
40
function augmentHostWithDependencyCollection(
41
  host: ts.CompilerHost,
42
  dependencies: Map<string, Set<string>>,
43
  moduleResolutionCache?: ts.ModuleResolutionCache
44
): void;
45
```
46

47
### Host Augmentation for File Replacements
48

49
Augments compiler host with file replacement capabilities for environment-specific builds.
50

51
```typescript { .api }
52
/**
53
 * Augments host with file replacement capabilities
54
 * Enables swapping files during compilation (e.g., environment configs)
55
 * @param host - Base TypeScript compiler host
56
 * @param replacements - Map of file paths to replacement paths
57
 * @param moduleResolutionCache - Optional cache for resolved modules
58
 */
59
function augmentHostWithReplacements(
60
  host: ts.CompilerHost,
61
  replacements: Record<string, string>,
62
  moduleResolutionCache?: ts.ModuleResolutionCache
63
): void;
64
```
65

66
### Host Augmentation for String Substitutions
67

68
Augments compiler host with string substitution capabilities for build-time constants.
69

70
```typescript { .api }
71
/**
72
 * Augments host with string substitution capabilities
73
 * Enables replacing string literals during compilation
74
 * @param host - Base TypeScript compiler host
75
 * @param substitutions - Map of strings to replacement values
76
 */
77
function augmentHostWithSubstitutions(
78
  host: ts.CompilerHost,
79
  substitutions: Record<string, string>
80
): void;
81
```
82

83
### Program Versioning Augmentation
84

85
Adds versioning support to TypeScript programs for incremental compilation.
86

87
```typescript { .api }
88
/**
89
 * Adds versioning support to TypeScript programs
90
 * Enables incremental compilation and change detection
91
 * @param program - TypeScript program to augment
92
 */
93
function augmentProgramWithVersioning(program: ts.Program): void;
94
```
95

96
### Host Augmentation for Caching
97

98
Augments compiler host with caching capabilities for improved build performance.
99

100
```typescript { .api }
101
/**
102
 * Augments host with caching capabilities
103
 * Improves compilation performance through source file caching
104
 * @param host - Base TypeScript compiler host
105
 * @param cache - Source file cache map
106
 */
107
function augmentHostWithCaching(
108
  host: ts.CompilerHost,
109
  cache: Map<string, ts.SourceFile>
110
): void;
111
```
112

113
### Source File Cache
114

115
Cache system for TypeScript source files to improve compilation performance.
116

117
```typescript { .api }
118
/**
119
 * Cache for TypeScript source files
120
 * Extends Map with additional caching functionality for Angular diagnostics
121
 */
122
class SourceFileCache extends Map<string, ts.SourceFile> {
123
  /**
124
   * Invalidates cached entries for a specific file
125
   * @param file - Path of file to invalidate
126
   */
127
  invalidate(file: string): void;
128
  
129
  /**
130
   * Updates Angular diagnostics for a source file
131
   * @param sourceFile - TypeScript source file
132
   * @param diagnostics - Array of diagnostics to store
133
   */
134
  updateAngularDiagnostics(sourceFile: ts.SourceFile, diagnostics: ts.Diagnostic[]): void;
135
  
136
  /**
137
   * Gets Angular diagnostics for a source file
138
   * @param sourceFile - TypeScript source file
139
   * @returns Array of diagnostics or undefined
140
   */
141
  getAngularDiagnostics(sourceFile: ts.SourceFile): ts.Diagnostic[] | undefined;
142
}
143
```
144

145
### Webpack System Integration
146

147
Creates TypeScript system from webpack's file system for seamless integration.
148

149
```typescript { .api }
150
/**
151
 * Type for webpack input file system
152
 * Represents webpack's file system interface
153
 */
154
type InputFileSystem = NonNullable<Compiler['inputFileSystem']>;
155

156
/**
157
 * Synchronous file system interface
158
 * Extends webpack's file system with synchronous operations
159
 */
160
interface InputFileSystemSync extends InputFileSystem {
161
  /** Synchronously get file statistics */
162
  statSync(path: string): { isFile(): boolean; isDirectory(): boolean };
163
  /** Synchronously read file content */
164
  readFileSync(path: string, encoding?: string): string | Buffer;
165
}
166

167
/**
168
 * Creates TypeScript system from webpack file system
169
 * Bridges webpack's file system with TypeScript compiler
170
 * @param inputFileSystem - Webpack input file system
171
 * @param currentDirectory - Current working directory
172
 * @returns TypeScript system interface
173
 */
174
function createWebpackSystem(
175
  inputFileSystem: InputFileSystemSync,
176
  currentDirectory: string
177
): ts.System;
178
```
179

180
### Diagnostics Integration
181

182
System for handling and reporting TypeScript and Angular compilation diagnostics.
183

184
```typescript { .api }
185
/**
186
 * Function type for reporting diagnostics
187
 * Handles TypeScript and Angular compilation diagnostics
188
 */
189
type DiagnosticsReporter = (diagnostics: readonly Diagnostic[]) => void;
190

191
/**
192
 * Creates a diagnostics reporter for webpack compilations
193
 * Integrates TypeScript diagnostics with webpack's error reporting
194
 * @param compilation - Webpack compilation instance
195
 * @param sourceFileToUrl - Function to convert file paths to URLs
196
 * @returns Diagnostics reporter function
197
 */
198
function createDiagnosticsReporter(
199
  compilation: Compilation,
200
  sourceFileToUrl?: (sourceFile: string) => string
201
): DiagnosticsReporter;
202

203
/**
204
 * Adds warning message to webpack compilation
205
 * @param compilation - Webpack compilation instance
206
 * @param message - Warning message to add
207
 */
208
function addWarning(compilation: Compilation, message: string): void;
209

210
/**
211
 * Adds error message to webpack compilation
212
 * @param compilation - Webpack compilation instance
213
 * @param message - Error message to add
214
 */
215
function addError(compilation: Compilation, message: string): void;
216
```
217

218
### Path Utilities
219

220
Cross-platform path normalization and externalization utilities.
221

222
```typescript { .api }
223
/**
224
 * Normalizes file paths for cross-platform compatibility
225
 * Converts paths to use forward slashes consistently
226
 * @param path - File path to normalize
227
 * @returns Normalized path string
228
 */
229
function normalizePath(path: string): string;
230

231
/**
232
 * Externalizes paths for different operating systems
233
 * Handles platform-specific path requirements
234
 */
235
const externalizePath: (path: string) => string;
236
```
237

238
### Complete Integration Example
239

240
Example showing how all host augmentations work together:
241

242
```typescript
243
import {
244
  augmentHostWithResources,
245
  augmentHostWithDependencyCollection,
246
  augmentHostWithReplacements,
247
  augmentHostWithSubstitutions,
248
  augmentHostWithCaching,
249
  SourceFileCache,
250
  WebpackResourceLoader
251
} from '@ngtools/webpack';
252

253
// Create base TypeScript compiler host
254
const baseHost = ts.createCompilerHost(compilerOptions);
255

256
// Create resource loader and cache
257
const resourceLoader = new WebpackResourceLoader();
258
const cache = new SourceFileCache();
259
const dependencies = new Map<string, Set<string>>();
260
const moduleResolutionCache = new Map<string, ts.ResolvedModule>();
261

262
// Apply all augmentations
263
let augmentedHost = augmentHostWithResources(baseHost, resourceLoader, options);
264
augmentedHost = augmentHostWithDependencyCollection(augmentedHost, dependencies, moduleResolutionCache);
265
augmentedHost = augmentHostWithReplacements(augmentedHost, fileReplacements, moduleResolutionCache);
266
augmentedHost = augmentHostWithSubstitutions(augmentedHost, substitutions);
267
augmentedHost = augmentHostWithCaching(augmentedHost, cache);
268

269
// Use augmented host for Angular compilation
270
const program = ts.createProgram(fileNames, compilerOptions, augmentedHost);
271
```