ArchUnitTS Documentation

ArchUnitTS can interpret various PlantUML diagram types to enforce different architectural patterns:

• Component Diagrams: Validate relationships between high-level components.
• Package Diagrams: Enforce dependencies between layers (e.g., Presentation, Business, Data).
• Class Diagrams: Validate class relationships and inheritance hierarchies.
• Microservices: Validate boundaries and communication paths between services.
• Custom Patterns: Supports specialized architectures like Hexagonal (Ports and Adapters).

import { projectSlices } from 'archunit';

// Example: Layered Package Diagram validation
const diagram = `@startuml\npackage "Presentation" { [Controllers] }\npackage "Business" { [Services] }\n[Controllers] --> [Services]\n@enduml`;

const rule = projectSlices()
  .definedBy('src/**/(**)')
  .should()
  .adhereToDiagram(diagram);

await expect(rule).toPassAsync();

When using the metrics() module, you can target specific files or directories using three primary pattern matching methods. These methods support both string patterns (with glob support) and regular expressions.

• withName(pattern): Matches only the filename (e.g., 'Service.ts' from 'src/services/Service.ts').
• inPath(pattern): Matches against the full relative path (e.g., 'src/services/Service.ts').
• inFolder(pattern): Matches against the path without the filename (e.g., 'src/services' from 'src/services/Service.ts').

You can also use .forClassesMatching(regex) to filter by class names.

import { metrics } from 'archunit';

// Using glob strings
await metrics().withName('*.service.ts').check();
await metrics().inFolder('**/services').check();
await metrics().inPath('src/api/**/*.ts').check();

// Using regular expressions
await metrics().withName(/^.*Service\.ts$/).check();
await metrics().inFolder(/services$/).check();

// Using class name matching
await metrics().forClassesMatching(/.*Controller/).check();

ArchUnitTS provides three primary methods for targeting files across all modules using either string patterns (with glob support) or regular expressions.

• withName(pattern): Checks the pattern against the filename (e.g., Service.ts).
• inPath(pattern): Checks the pattern against the full relative path (e.g., src/services/Service.ts).
• inFolder(pattern): Checks the pattern against the path without the filename (e.g., src/services).

For the metrics module, you can also use:

• forClassesMatching(pattern): Checks the pattern against class names, regardless of file path.

// String patterns with glob support
.withName('*.service.ts')     // All files ending with .service.ts
.inFolder('**/services')      // All files in any services folder
.inPath('src/api/**/*.ts')    // All TypeScript files under src/api

// Regular expressions
.withName(/^.*Service\.ts$/)  // Case-sensitive regex
.inFolder(/services$/)        // Folders ending with 'services'

// Metrics module: Class name matching
.forClassesMatching(/.*Service$/)

ArchUnitTS is a comprehensive architecture testing library that goes beyond simple dependency linting.

Key differentiators from linters (like eslint-plugin-import):

• Code Metrics: Provides LCOM (cohesion), cyclomatic complexity, coupling, abstractness, instability, and distance from main sequence.
• Advanced Architecture: Supports UML diagram validation, architecture slices, and multi-layer validation.
• Nx Support: Built-in validation for Nx monorepo project graphs and boundaries.
• Empty Test Protection: Automatically fails tests if file patterns match zero files (preventing false positives due to typos).
• Deep Analysis: Performs class-level analysis (methods, fields) rather than just module-level imports.

Key differentiators from other TS architecture libraries:

• Empty Test Protection: Fails by default if no files are found.
• Universal Framework Support: Works with Jest, Vitest, Jasmine, Mocha, etc., with specialized async matchers.
• Code Metrics: The only library offering comprehensive code metrics.
• Rich Reporting: Generates HTML dashboards and multiple dependency graph formats (DOT, Mermaid, D2, CSV, JSON).