Clean Architecture Filtering Layer: Design Patterns and Implementation

Overview

This code sample demonstrates a complete filtering layer implementation that adheres to clean architecture principles. The system provides type-safe, configurable filtering for business entities while maintaining strict separation of concerns and dependency inversion.

Architecture Layers

Domain Layer (Innermost)

The domain layer contains pure business entities and value types with no external dependencies:

export interface User {
  id: string;
  email: string;
  // ... other fields
}

const userRole = ['admin', 'user', 'moderator'] as const;
export type UserRole = (typeof userRole)[number];

Key Characteristics:

• Entities represent core business concepts
• Value types use as const assertions for compile-time type safety
• No framework dependencies or infrastructure concerns

Application Layer (Use Cases)

The application layer orchestrates business logic through service interfaces:

export interface ApiFilterService<T> {
  findEntities(query: FilterQuery<T>): Promise<ApiResponse<T[]>>;
  countEntities(filters: Filter<T>[]): Promise<ApiResponse<number>>;
  // ... CRUD operations
}

Design Decisions:

• Generic interfaces enable reuse across entity types
• All operations return wrapped responses with error handling
• Services depend on abstractions, not concrete implementations

Interface Adapters Layer

This layer contains validation logic and field registry management:

export function createFilterValidationService<T>(
  fieldRegistry: FieldEvaluatorRegistry<T>
): FilterValidationService<T>

Responsibilities:

• Validate filter operations against field types
• Convert between external API formats and internal representations
• Enforce business rules for filter construction

Infrastructure Layer (Outermost)

The repository interface defines the contract for data persistence:

export interface Repository<T> {
  findByFilters(query: FilterQuery<T>): Promise<T[]>;
  // ... other persistence operations
}

Design Patterns Applied

1. Revealing Module Pattern

Implementation:

export function createFieldEvaluatorRegistry<T>(): {
  register: (field: keyof T, metadata: FieldMetadata) => void;
  registry: FieldEvaluatorRegistry<T>;
} {
  const fieldMappings = new Map<keyof T, FieldMetadata>(); // Private state
  
  // Private functions...
  
  return { register, registry }; // Public interface
}

Benefits:

• Encapsulates internal state within closures
• Exposes only necessary public methods
• Eliminates need for class-based inheritance hierarchies
• Provides clear separation between public API and implementation

Tradeoffs:

• Slightly more verbose than class-based approach
• Each instance creates new function references (minor memory overhead)
• Less familiar to developers coming from OOP backgrounds

2. Type-Level Configuration

Implementation:

const fieldType = ['string', 'number', 'boolean'] as const;
export type FieldType = (typeof fieldType)[number];

export const FIELD_TYPE_OPERATORS: Record<FieldType, FieldTypeConfig> = {
  string: { allowedOperators: stringOperators },
  number: { allowedOperators: numberOperators },
  // ...
};

Benefits:

• Compile-time validation of field types and operators
• Eliminates runtime string literal errors
• Enables IDE autocomplete and refactoring support
• Self-documenting code through type constraints

Tradeoffs:

• Requires TypeScript for full benefits
• Can make types more complex for beginners
• Build-time overhead for type checking

3. Strategy Pattern via Type System

Implementation:

switch (metadata.type) {
  case 'literal_union':
    return validateLiteralUnionValue(filter, metadata);
  case 'number':
    return validateNumberValue(filter);
  // ... other strategies
}

Benefits:

• Validation strategies determined by field type
• Easy to extend with new field types
• Type-safe dispatch based on discriminated unions
• Avoids complex inheritance hierarchies

Tradeoffs:

• Validation logic spread across multiple functions
• Requires careful coordination between type definitions and implementations

4. Dependency Injection via Factory Functions

Implementation:

export function createUserService(userRepository: Repository<User>): ApiFilterService<User> {
  const validationService = createFilterValidationService(userFieldRegistry);
  return createApiFilterService(userRepository, validationService);
}

Benefits:

• Clear dependency relationships
• Easy to test with mock implementations
• Supports multiple configurations
• No global state or service locators

Tradeoffs:

• Manual wiring of dependencies
• Can become verbose for complex dependency graphs
• No automatic lifecycle management

Clean Architecture Conformance

Dependency Rule

Dependencies point inward toward higher-level policies:

• Domain entities have no dependencies
• Application services depend on domain abstractions
• Infrastructure implementations depend on application interfaces
• External frameworks interact only through interface adapters

Stable Dependencies Principle

Core business logic depends on stable abstractions:

• FilterQuery<T> interface remains stable regardless of storage implementation
• Field type system provides stable operator mappings
• Validation rules are independent of external API formats

Interface Segregation

Interfaces are focused and cohesive:

• Repository<T> contains only data access operations
• FilterValidationService<T> handles only validation concerns
• ApiFilterService<T> manages only API-level operations

Extensibility Points

Adding New Field Types

1. Extend the fieldType const array
2. Define operator mappings in FIELD_TYPE_OPERATORS
3. Add validation logic in createFilterValidationService

Adding New Operators

1. Extend the filterOperator const array
2. Update relevant operator arrays (e.g., stringOperators)
3. Implement validation logic for the new operator

Supporting New Entities

1. Define entity interface in domain layer
2. Create field registry configuration
3. Use factory function to create typed service

Testing Strategy

The architecture supports comprehensive testing at each layer:

Unit Tests:

• Domain entities (pure functions, no dependencies)
• Validation logic (isolated business rules)
• Field registry operations (type safety verification)

Integration Tests:

• API service with mock repository
• End-to-end filter query processing
• Cross-layer contract verification

Property-Based Testing:

• Generate random valid filter queries
• Verify validation rules against type constraints
• Test operator behavior across field types

Performance Considerations

Compile-Time Optimizations:

• Type-level computations reduce runtime checks
• Const assertions enable dead code elimination
• Generic specialization allows for optimized implementations

Runtime Characteristics:

• Field registries use Map for O(1) metadata lookup
• Validation short-circuits on first error
• Operator mappings are pre-computed constants

Memory Management:

• Revealing module pattern creates closures (minor overhead)
• Field registries share operator arrays via references
• No class inheritance chains or prototype pollution

Conclusion

This filtering layer demonstrates how functional programming patterns can be effectively combined with TypeScript's type system to create clean, maintainable architecture. The design prioritizes type safety, testability, and extensibility while maintaining clear separation between business logic and infrastructure concerns.

The patterns shown here scale well to complex domain models and provide a solid foundation for building robust query systems that can evolve with changing business requirements.