tessl/npm-jest-preset-angular

Jest preset configuration for Angular projects

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Angular Transformer

Name: tessl/npm-jest-preset-angular
Author: tessl

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

Capabilities

NgJestTransformer Class

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

/**
 * Angular-specific Jest transformer extending ts-jest functionality
 */
class NgJestTransformer extends TsJestTransformer {
  /**
   * Creates a new NgJestTransformer instance
   * @param tsJestConfig - Optional ts-jest configuration options
   */
  constructor(tsJestConfig?: TsJestTransformerOptions);

  /**
   * Processes source files for Jest transformation
   * @param fileContent - The content of the file to transform
   * @param filePath - The path to the file being transformed
   * @param transformOptions - Jest transformation options
   * @returns Transformed source code with source maps
   */
  process(
    fileContent: string,
    filePath: string,
    transformOptions: TsJestTransformOptions
  ): TransformedSource;

  /**
   * Gets the current package version
   * @returns The version string from package.json
   */
  readonly version: string;
}

interface TransformedSource {
  code: string;
  map?: string | object;
}

Usage Examples:

import { NgJestTransformer } from 'jest-preset-angular';

// Create transformer instance
const transformer = new NgJestTransformer();

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

// Use in Jest configuration
module.exports = {
  transform: {
    '^.+\\.(ts|js|html|svg)$': ['jest-preset-angular', {
      tsconfig: '<rootDir>/tsconfig.spec.json',
      stringifyContentPathRegex: '\\.(html|svg)$'
    }]
  }
};

createTransformer Factory Function

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

/**
 * Factory function to create NgJestTransformer instances
 * @param tsJestConfig - Optional ts-jest configuration options
 * @returns New NgJestTransformer instance
 */
function createTransformer(tsJestConfig?: TsJestTransformerOptions): NgJestTransformer;

Usage Examples:

import jestPresetAngular from 'jest-preset-angular';

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

// With configuration
const transformer = jestPresetAngular.createTransformer({
  tsconfig: '<rootDir>/tsconfig.spec.json'
});

NgJestCompiler Class

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

/**
 * Angular-specific Jest compiler extending ts-jest's TsCompiler
 */
class NgJestCompiler extends TsCompiler {
  /**
   * Creates a new NgJestCompiler instance
   * @param configSet - Configuration set for the compiler
   * @param jestCacheFS - Jest cache file system map
   */
  constructor(
    readonly configSet: ConfigSet,
    readonly jestCacheFS: Map<string, string>
  );
}

NgJestConfig Class

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

/**
 * Angular-specific Jest configuration extending ts-jest ConfigSet
 */
class NgJestConfig extends ConfigSet {
  /** Matcher for determining which files to process with esbuild */
  readonly processWithEsbuild: ReturnType<typeof globsToMatcher>;

  /**
   * Creates a new NgJestConfig instance
   * @param jestConfig - Jest configuration object
   * @param parentLogger - Optional parent logger instance
   */
  constructor(
    jestConfig: TsJestTransformOptions['config'] | undefined,
    parentLogger?: Logger | undefined
  );
}

interface Logger {
  debug(message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
}

type globsToMatcher = (patterns: string[]) => (filePath: string) => boolean;

Transformation Process

The NgJestTransformer handles different file types with optimized processing:

esbuild Processing:

Used for certain file patterns (e.g., .mjs files)
Faster compilation for JavaScript files
Configurable through processWithEsbuild patterns

TypeScript API Processing:

Used for Angular components and services
Applies Angular-specific AST transformations
Handles decorators, templates, and dependency injection

File Type Support:

TypeScript files (.ts)
JavaScript files (.js)
ECMAScript modules (.mjs)
HTML templates (.html)
SVG files (.svg)

Angular-Specific Features

Template and Style Processing:

Inlines external templates and styles
Processes templateUrl and styleUrls properties
Handles Angular component resource transformation

Decorator Processing:

Transforms Angular decorators (@Component, @Injectable, etc.)
Maintains metadata for dependency injection
Preserves type information for Angular compiler

JIT Compilation Support:

Supports Angular's Just-In-Time compilation
Handles dynamic component creation
Processes Angular application transforms via angularJitApplicationTransform
Applies replaceResources transformer for template and style inlining

Custom AST Transformers:

replaceResources: Processes templateUrl and styleUrls to inline content
angularJitApplicationTransform: Handles Angular-specific JIT transformations
Supports additional custom transformers via configuration

Performance Optimizations:

esbuild processing for JavaScript files in node_modules
Selective TypeScript API usage for Angular-specific files
Optimized caching with SHA1 hash generation
Isolated modules support for faster compilation

getCacheKey Method

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

/**
 * Generates a cache key for the transformed file
 * @param fileContent - The content of the file
 * @param filePath - The path to the file
 * @param transformOptions - Jest transformation options
 * @returns SHA1 hash for cache identification
 */
getCacheKey(
  fileContent: string,
  filePath: string,
  transformOptions: TsJestTransformOptions
): string;

Usage Examples:

// Automatically used by Jest for caching
const transformer = new NgJestTransformer();
const cacheKey = transformer.getCacheKey(content, filePath, options);

// Cache key includes:
// - File content hash
// - Transformer version
// - Configuration options
// - TypeScript compiler options

Version Property

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

/**
 * Gets the current package version
 * @returns The version string from package.json
 */
readonly version: string;

Configuration Options

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

interface TsJestTransformerOptions {
  /** TypeScript configuration file path or inline options */
  tsconfig?: string | object;
  /** Custom AST transformers */
  astTransformers?: object;
  /** Babel configuration for additional processing */
  babelConfig?: object;
  /** TypeScript diagnostic options */
  diagnostics?: object;
  /** Enable isolated modules compilation */
  isolatedModules?: boolean;
  /** String content path regex for inlining */
  stringifyContentPathRegex?: string;
  /** Enable ESM support */
  useESM?: boolean;
}

interface TsJestAstTransformer {
  before?: ts.TransformerFactory<ts.SourceFile>[];
  after?: ts.TransformerFactory<ts.SourceFile>[];
  afterDeclarations?: ts.TransformerFactory<ts.SourceFile>[];
}

interface ConfigSet {
  compilerModule: typeof ts;
  parsedTsConfig: ts.ParsedCommandLine;
  useESM: boolean;
  resolvedTransformers: TsJestAstTransformer;
}

interface TsJestTransformer {
  constructor(tsJestConfig?: TsJestTransformerOptions);
  process(fileContent: string, filePath: string, transformOptions: TsJestTransformOptions): TransformedSource;
  getCacheKey(fileContent: string, filePath: string, transformOptions: TsJestTransformOptions): string;
}

interface TsCompiler {
  constructor(configSet: ConfigSet, jestCacheFS: Map<string, string>);
  program?: ts.Program;
}