# typestack/class-validator architecture

> Architecture diagram of the GitHub repository typestack/class-validator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/typestack/class-validator
- Repository: https://github.com/typestack/class-validator

## Overview

##### Overall Project Type and Purpose
- This is not a full-stack application but a utility library focused on validation.
- Its purpose is to provide a rich set of validation decorators and functions that developers apply to model classes in TypeScript/JavaScript.
- The library supports custom validations, conditional validations, inheritance of decorators, and even integration with a service container.

##### Main Architectural Components and Their Locations
a. Public API and Entry Points
– Files: src/index.ts, register-decorator.ts, and the container (src/container.ts)
– These expose the core functions like validate, validateOrReject, and the custom decorator registration.
– Represent this as the “Public API Layer” which client code calls.

b. Decorators and Custom Validation Definitions
– Located in src/decorator (and its subfolders: common, array, date, number, string, typechecker, etc.)
– Each set of decorators encapsulates specific validation logic (e.g., IsEmail, MinLength, Contains, etc.).
– Also note the custom validators in the sample directory (e.g., sample4-custom-validator, sample6-custom-decorator) serve as examples for extending this mechanism.

c. Metadata Storage and Transformation
– Located in src/metadata and src/validation-schema.
– These modules are responsible for collecting and storing validation metadata that is registered through decorators.
– The “Metadata Storage” component holds information such as the constraints, target class details, and validation arguments.

d. Validation Engine
– Located in src/validation (which includes files like ValidationExecutor.ts, ValidationError.ts, and Validator.ts).
– This component is responsible for executing the validation rules, processing the metadata, and returning structured errors.
– Represent this as the “Validation Engine” that receives a class instance (populated with constraints from decorators) and then iterates through the metadata.

e. Utility Modules
– Located in src/utils.
– These components provide helper functions such as converting values to arrays, checking promises, and other generic utilities.

f. Test and Sample Modules
– The sample directory (sample/sample1-simple-validation, sample/sample2-using-groups, etc.) contains concrete usage examples.
– The test folder contains automated tests for various functionalities.

##### Relationships and Data Flow
- The validation engine then consults the “Metadata Storage” that was populated by the decorator modules.
- If a service container is used (via src/container.ts and the integration with typedi), illustrate this dependency injection feeding into the Validation Engine and custom validators.
- Interactions from custom decorators (and custom validators) that plug into the Validation Engine via the public API.

##### Important Architectural Patterns & Design Principles
- Emphasis on metadata registration via decorators.
- Separation of concerns: the validation logic is separated from metadata management and actual execution.
- Extensibility: separated modules to allow developers to define custom decorators and constraints without altering core logic.
- Reusability: utility modules and a clearly defined API allow the library to be integrated into various ecosystems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User/Client Code"):::client

    subgraph "Public API Layer"
        P1("Index"):::api
        P2("Register Decorator"):::api
        P3("Container"):::api
    end

    subgraph "Decorators Module"
        D1("Core Decorators"):::decorators
        D2("Common Decorators"):::decorators
        D3("Array Decorators"):::decorators
        D4("Date Decorators"):::decorators
        D5("Number Decorators"):::decorators
        D6("String Decorators"):::decorators
        D7("Typechecker Decorators"):::decorators
        D8("Object Decorators"):::decorators
    end

    subgraph "Metadata Storage"
        M1("Metadata Storage"):::metadata
        M2("Validation Schema"):::metadata
    end

    subgraph "Validation Engine"
        V1("Validation Executor"):::engine
        V2("Validation Error"):::engine
        V3("Validator"):::engine
    end

    subgraph "Utilities"
        U("Utilities"):::utilities
    end

    subgraph "Examples & Tests"
        E1("Samples"):::examples
        E2("Automated Tests"):::examples
    end

    %% Data Flow Connections
    A -->|"calls"| P1
    A -->|"applies"| D1

    P1 -->|"executes"| V1
    P3 -->|"injects"| V1

    D1 -->|"registersMetadata"| M1
    D2 -->|"registersMetadata"| M1
    D3 -->|"registersMetadata"| M1
    D4 -->|"registersMetadata"| M1
    D5 -->|"registersMetadata"| M1
    D6 -->|"registersMetadata"| M1
    D7 -->|"registersMetadata"| M1
    D8 -->|"registersMetadata"| M1

    %% Custom validations integration
    D1 -->|"integrates"| V1

    M1 -->|"providesMetadata"| V1
    M2 -->|"transformsSchema"| M1

    V1 -->|"uses"| U

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef api fill:#bbf,stroke:#333,stroke-width:2px;
    classDef decorators fill:#bfb,stroke:#333,stroke-width:2px;
    classDef metadata fill:#ffb,stroke:#333,stroke-width:2px;
    classDef engine fill:#fbb,stroke:#333,stroke-width:2px;
    classDef utilities fill:#fbf,stroke:#333,stroke-width:2px;
    classDef examples fill:#bbf,stroke:#333,stroke-dasharray: 5,5,stroke-width:2px;

    %% Click Events for Public API Layer
    click P1 "https://github.com/typestack/class-validator/blob/develop/src/index.ts"
    click P2 "https://github.com/typestack/class-validator/blob/develop/src/register-decorator.ts"
    click P3 "https://github.com/typestack/class-validator/blob/develop/src/container.ts"

    %% Click Events for Decorators Module
    click D1 "https://github.com/typestack/class-validator/blob/develop/src/decorator/decorators.ts"
    click D2 "https://github.com/typestack/class-validator/tree/develop/src/decorator/common"
    click D3 "https://github.com/typestack/class-validator/tree/develop/src/decorator/array"
    click D4 "https://github.com/typestack/class-validator/tree/develop/src/decorator/date"
    click D5 "https://github.com/typestack/class-validator/tree/develop/src/decorator/number"
    click D6 "https://github.com/typestack/class-validator/tree/develop/src/decorator/string"
    click D7 "https://github.com/typestack/class-validator/tree/develop/src/decorator/typechecker"
    click D8 "https://github.com/typestack/class-validator/tree/develop/src/decorator/object"

    %% Click Events for Metadata Storage
    click M1 "https://github.com/typestack/class-validator/blob/develop/src/metadata/MetadataStorage.ts"
    click M2 "https://github.com/typestack/class-validator/tree/develop/src/validation-schema"

    %% Click Events for Validation Engine
    click V1 "https://github.com/typestack/class-validator/blob/develop/src/validation/ValidationExecutor.ts"
    click V2 "https://github.com/typestack/class-validator/blob/develop/src/validation/ValidationError.ts"
    click V3 "https://github.com/typestack/class-validator/blob/develop/src/validation/Validator.ts"

    %% Click Event for Utilities
    click U "https://github.com/typestack/class-validator/tree/develop/src/utils"

    %% Click Events for Examples & Tests
    click E1 "https://github.com/typestack/class-validator/tree/develop/sample"
    click E2 "https://github.com/typestack/class-validator/tree/develop/test"
```
