0
# Angular Transformer
1

2
Custom Jest transformer that handles Angular-specific compilation including component templates, styles, decorators, and TypeScript compilation with Angular compiler integration.
3

4
## Capabilities
5

6
### NgJestTransformer Class
7

8
Main transformer class that extends ts-jest's TsJestTransformer to provide Angular-specific file processing and compilation.
9

10
```typescript { .api }
11
/**
12
 * Angular-specific Jest transformer extending ts-jest functionality
13
 */
14
class NgJestTransformer extends TsJestTransformer {
15
  /**
16
   * Creates a new NgJestTransformer instance
17
   * @param tsJestConfig - Optional ts-jest configuration options
18
   */
19
  constructor(tsJestConfig?: TsJestTransformerOptions);
20

21
  /**
22
   * Processes source files for Jest transformation
23
   * @param fileContent - The content of the file to transform
24
   * @param filePath - The path to the file being transformed
25
   * @param transformOptions - Jest transformation options
26
   * @returns Transformed source code with source maps
27
   */
28
  process(
29
    fileContent: string,
30
    filePath: string,
31
    transformOptions: TsJestTransformOptions
32
  ): TransformedSource;
33

34
  /**
35
   * Gets the current package version
36
   * @returns The version string from package.json
37
   */
38
  readonly version: string;
39
}
40

41
interface TransformedSource {
42
  code: string;
43
  map?: string | object;
44
}
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { NgJestTransformer } from 'jest-preset-angular';
51

52
// Create transformer instance
53
const transformer = new NgJestTransformer();
54

55
// With custom ts-jest configuration
56
const transformer = new NgJestTransformer({
57
  tsconfig: '<rootDir>/tsconfig.spec.json',
58
  isolatedModules: true
59
});
60

61
// Use in Jest configuration
62
module.exports = {
63
  transform: {
64
    '^.+\\.(ts|js|html|svg)$': ['jest-preset-angular', {
65
      tsconfig: '<rootDir>/tsconfig.spec.json',
66
      stringifyContentPathRegex: '\\.(html|svg)$'
67
    }]
68
  }
69
};
70
```
71

72
### createTransformer Factory Function
73

74
Factory function for creating NgJestTransformer instances, providing the main export of the package.
75

76
```typescript { .api }
77
/**
78
 * Factory function to create NgJestTransformer instances
79
 * @param tsJestConfig - Optional ts-jest configuration options
80
 * @returns New NgJestTransformer instance
81
 */
82
function createTransformer(tsJestConfig?: TsJestTransformerOptions): NgJestTransformer;
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
import jestPresetAngular from 'jest-preset-angular';
89

90
// Create transformer using factory
91
const transformer = jestPresetAngular.createTransformer();
92

93
// With configuration
94
const transformer = jestPresetAngular.createTransformer({
95
  tsconfig: '<rootDir>/tsconfig.spec.json'
96
});
97
```
98

99
### NgJestCompiler Class
100

101
Angular-specific compiler that handles TypeScript compilation with Angular transformations.
102

103
```typescript { .api }
104
/**
105
 * Angular-specific Jest compiler extending ts-jest's TsCompiler
106
 */
107
class NgJestCompiler extends TsCompiler {
108
  /**
109
   * Creates a new NgJestCompiler instance
110
   * @param configSet - Configuration set for the compiler
111
   * @param jestCacheFS - Jest cache file system map
112
   */
113
  constructor(
114
    readonly configSet: ConfigSet,
115
    readonly jestCacheFS: Map<string, string>
116
  );
117
}
118
```
119

120
### NgJestConfig Class
121

122
Angular-specific configuration management extending ts-jest's ConfigSet.
123

124
```typescript { .api }
125
/**
126
 * Angular-specific Jest configuration extending ts-jest ConfigSet
127
 */
128
class NgJestConfig extends ConfigSet {
129
  /** Matcher for determining which files to process with esbuild */
130
  readonly processWithEsbuild: ReturnType<typeof globsToMatcher>;
131

132
  /**
133
   * Creates a new NgJestConfig instance
134
   * @param jestConfig - Jest configuration object
135
   * @param parentLogger - Optional parent logger instance
136
   */
137
  constructor(
138
    jestConfig: TsJestTransformOptions['config'] | undefined,
139
    parentLogger?: Logger | undefined
140
  );
141
}
142

143
interface Logger {
144
  debug(message: string, ...args: any[]): void;
145
  info(message: string, ...args: any[]): void;
146
  warn(message: string, ...args: any[]): void;
147
  error(message: string, ...args: any[]): void;
148
}
149

150
type globsToMatcher = (patterns: string[]) => (filePath: string) => boolean;
151
```
152

153
### Transformation Process
154

155
The NgJestTransformer handles different file types with optimized processing:
156

157
**esbuild Processing:**
158
- Used for certain file patterns (e.g., `.mjs` files)
159
- Faster compilation for JavaScript files
160
- Configurable through `processWithEsbuild` patterns
161

162
**TypeScript API Processing:**
163
- Used for Angular components and services
164
- Applies Angular-specific AST transformations
165
- Handles decorators, templates, and dependency injection
166

167
**File Type Support:**
168
- TypeScript files (`.ts`)
169
- JavaScript files (`.js`)
170
- ECMAScript modules (`.mjs`)
171
- HTML templates (`.html`)
172
- SVG files (`.svg`)
173

174
### Angular-Specific Features
175

176
**Template and Style Processing:**
177
- Inlines external templates and styles
178
- Processes `templateUrl` and `styleUrls` properties
179
- Handles Angular component resource transformation
180

181
**Decorator Processing:**
182
- Transforms Angular decorators (@Component, @Injectable, etc.)
183
- Maintains metadata for dependency injection
184
- Preserves type information for Angular compiler
185

186
**JIT Compilation Support:**
187
- Supports Angular's Just-In-Time compilation
188
- Handles dynamic component creation
189
- Processes Angular application transforms via `angularJitApplicationTransform`
190
- Applies `replaceResources` transformer for template and style inlining
191

192
**Custom AST Transformers:**
193
- `replaceResources`: Processes `templateUrl` and `styleUrls` to inline content
194
- `angularJitApplicationTransform`: Handles Angular-specific JIT transformations
195
- Supports additional custom transformers via configuration
196

197
**Performance Optimizations:**
198
- esbuild processing for JavaScript files in node_modules
199
- Selective TypeScript API usage for Angular-specific files
200
- Optimized caching with SHA1 hash generation
201
- Isolated modules support for faster compilation
202

203
### getCacheKey Method
204

205
Generates cache keys for transformed files to optimize Jest's caching mechanism.
206

207
```typescript { .api }
208
/**
209
 * Generates a cache key for the transformed file
210
 * @param fileContent - The content of the file
211
 * @param filePath - The path to the file
212
 * @param transformOptions - Jest transformation options
213
 * @returns SHA1 hash for cache identification
214
 */
215
getCacheKey(
216
  fileContent: string,
217
  filePath: string,
218
  transformOptions: TsJestTransformOptions
219
): string;
220
```
221

222
**Usage Examples:**
223

224
```typescript
225
// Automatically used by Jest for caching
226
const transformer = new NgJestTransformer();
227
const cacheKey = transformer.getCacheKey(content, filePath, options);
228

229
// Cache key includes:
230
// - File content hash
231
// - Transformer version
232
// - Configuration options
233
// - TypeScript compiler options
234
```
235

236
### Version Property
237

238
Provides the current version of jest-preset-angular for debugging and cache invalidation.
239

240
```typescript { .api }
241
/**
242
 * Gets the current package version
243
 * @returns The version string from package.json
244
 */
245
readonly version: string;
246
```
247

248
### Configuration Options
249

250
The transformer accepts all standard ts-jest options plus Angular-specific configurations:
251

252
```typescript { .api }
253
interface TsJestTransformerOptions {
254
  /** TypeScript configuration file path or inline options */
255
  tsconfig?: string | object;
256
  /** Custom AST transformers */
257
  astTransformers?: object;
258
  /** Babel configuration for additional processing */
259
  babelConfig?: object;
260
  /** TypeScript diagnostic options */
261
  diagnostics?: object;
262
  /** Enable isolated modules compilation */
263
  isolatedModules?: boolean;
264
  /** String content path regex for inlining */
265
  stringifyContentPathRegex?: string;
266
  /** Enable ESM support */
267
  useESM?: boolean;
268
}
269

270
interface TsJestAstTransformer {
271
  before?: ts.TransformerFactory<ts.SourceFile>[];
272
  after?: ts.TransformerFactory<ts.SourceFile>[];
273
  afterDeclarations?: ts.TransformerFactory<ts.SourceFile>[];
274
}
275

276
interface ConfigSet {
277
  compilerModule: typeof ts;
278
  parsedTsConfig: ts.ParsedCommandLine;
279
  useESM: boolean;
280
  resolvedTransformers: TsJestAstTransformer;
281
}
282

283
interface TsJestTransformer {
284
  constructor(tsJestConfig?: TsJestTransformerOptions);
285
  process(fileContent: string, filePath: string, transformOptions: TsJestTransformOptions): TransformedSource;
286
  getCacheKey(fileContent: string, filePath: string, transformOptions: TsJestTransformOptions): string;
287
}
288

289
interface TsCompiler {
290
  constructor(configSet: ConfigSet, jestCacheFS: Map<string, string>);
291
  program?: ts.Program;
292
}
293
```