# react-component/async-validator architecture

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

- Interactive diagram: https://gitdiagram.com/react-component/async-validator
- Repository: https://github.com/react-component/async-validator

## Overview

##### Project type and purpose
- This is an open-source npm library (“@rc-component/async-validator”) for declarative, asynchronous form or object validation in JavaScript/TypeScript. It provides a Schema API that takes a descriptor (a JSON-like specification of fields and rules) and validates arbitrary JS objects, returning results via callbacks or Promises.

##### File structure
- Top-level files:
- package.json, tsconfig.json, build config (fatherrc.js), lint and formatting configs, CI workflows.
- README.md documents installation, API, rule types, usage patterns.
- src/ – actual library source:
- index.ts: exports the Schema class and orchestrates validation.
- interface.ts, messages.ts: type definitions and default error messages.
- util.ts: shared utility functions (e.g. formatting, deep merging).
- rule/ – definitions of rule metadata/enums (type names, patterns, ranges, whitespace, URL, etc.).
- validator/ – implementations of each validation strategy (string, number, boolean, object, array, date, enum, pattern, required, asyncValidator, etc.).
- tests/ – unit tests for each validator, rule combinations, async behavior, deep rules, messages, promise use.

##### README for architectural insights
- The README emphasizes:
- A “Schema” entry point.
- Descriptor → schema → validate(source, options, callback) or Promise.
- Built-in rules (type, required, pattern, range, whitespace, enum, deep rules via fields/defaultField, transform).
- Custom synchronous validator vs. asyncValidator vs. promise.
- Message customization / i18n via options.messages.

a. Main components:
1. Consumer / Client Code – calls new Schema(descriptor) and invoke validate().
2. Schema (src/index.ts) – orchestrator.
3. Descriptor Model – JSON/object that describes fields + rules.
4. Rule Parser (src/rule/) – maps descriptor entries to internal Rule objects, normalizes arrays vs. single rule, deep rule expansion.
5. Validator Strategy Modules (src/validator/) – one module per rule type implementing synchronous or asynchronous checks.
6. Util & Messages (src/util.ts + src/messages.ts) – shared functions (e.g. message formatting, deep merge) and default error messages.
7. Build & Packaging – father build config, output to dist/, type declarations, dumi for docs.
8. CI/CD – GitHub Actions running lint, tests, coverage.
b. Relationships and interactions:
- Client invokes Schema.validate() → Schema uses Rule Parser to normalize the descriptor.
- For each field rule: Schema selects appropriate Validator module from the “validator” directory per rule.type or custom validator function.
- Validator modules use util functions and messages; may return synchronously or return a Promise or use callback.
- Schema collects all results, aggregates errors/fields, resolves or rejects the returned Promise (or invokes callback).
- Tests invoke the same Schema.validate() path with various descriptors to verify each rule module.
c. Architectural patterns & design principles:
- Strategy pattern: each validator type is encapsulated in its own module, pluggable via “type” name.
- Chain-of-Responsibility: multiple rules per field are processed in order, optionally stopping on first error.
- Extension points: custom validator() and asyncValidator() hooks.
- Separation of concerns: parsing vs. validation vs. messaging.
- Promise/Callback duality: supports both async models.
d. Key technologies and frameworks:
- TypeScript for source + types.
- Node.js module targeting CommonJS and ESModule via father (build tool).
- Jest or Mocha (implied by .spec.ts) for testing.
- Dumi for documentation.
- GitHub Actions for CI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef runtime fill:#ADD8E6,stroke:#000;
    classDef infra fill:#FFE4B5,stroke:#000;
    classDef extension fill:#90EE90,stroke:#000;

    subgraph "Runtime Components"
        Consumer["Consumer\n(Client Code)"]:::runtime
        Schema["Schema\n(Orchestrator)"]:::runtime
        DescriptorModel["Descriptor Model"]:::runtime
        Consumer -->|"validate(descriptor,options,callback/Promise)"| Schema
        Schema -->|"uses descriptor model"| DescriptorModel

        subgraph "Rule Parser"
            RPIndex["index.ts"]:::runtime
            RPType["type.ts"]:::runtime
            RPRequired["required.ts"]:::runtime
            RPRange["range.ts"]:::runtime
            RPPattern["pattern.ts"]:::runtime
            RPWhitespace["whitespace.ts"]:::runtime
            RPURL["url.ts"]:::runtime
            RPEnum["enum.ts"]:::runtime
        end
        Schema -->|"normalize descriptor"| RPIndex
        RPIndex -->|"parses to Rule Objects"| Schema

        subgraph "Validator Modules"
            ValidatorIndex["index.ts"]:::runtime
            Any["any.ts"]:::runtime
            Array["array.ts"]:::runtime
            Boolean["boolean.ts"]:::runtime
            DateV["date.ts"]:::runtime
            EnumV["enum.ts"]:::runtime
            Float["float.ts"]:::runtime
            Integer["integer.ts"]:::runtime
            Method["method.ts"]:::runtime
            NumberV["number.ts"]:::runtime
            ObjectV["object.ts"]:::runtime
            PatternV["pattern.ts"]:::runtime
            Regexp["regexp.ts"]:::runtime
            RequiredV["required.ts"]:::runtime
            StringV["string.ts"]:::runtime
            TypeV["type.ts"]:::runtime
        end
        Schema -->|"execute rules"| ValidatorIndex
        ValidatorIndex -->|"returns results (sync/Promise)"| Schema
        Schema -->|"aggregate & return results"| Consumer

        Util["Shared Utilities"]:::extension
        Messages["Default Messages"]:::extension
        RPIndex --> Util
        ValidatorIndex --> Util
        RPIndex --> Messages
        ValidatorIndex --> Messages
    end

    subgraph "Infrastructure & Docs"
        TestSuite["Test Suite (tests/)"]:::infra
        BuildPackaging["Build & Packaging\n(.fatherrc.js, .dumirc.ts)"]:::infra
        CICD["CI/CD\n(.github/workflows/ci.yml)"]:::infra
        Docs["Documentation & Metadata"]:::infra
        TestSuite --> Schema
    end

    click Schema "https://github.com/react-component/async-validator/blob/master/src/index.ts"
    click DescriptorModel "https://github.com/react-component/async-validator/blob/master/src/interface.ts"
    click RPIndex "https://github.com/react-component/async-validator/blob/master/src/rule/index.ts"
    click RPType "https://github.com/react-component/async-validator/blob/master/src/rule/type.ts"
    click RPRequired "https://github.com/react-component/async-validator/blob/master/src/rule/required.ts"
    click RPRange "https://github.com/react-component/async-validator/blob/master/src/rule/range.ts"
    click RPPattern "https://github.com/react-component/async-validator/blob/master/src/rule/pattern.ts"
    click RPWhitespace "https://github.com/react-component/async-validator/blob/master/src/rule/whitespace.ts"
    click RPURL "https://github.com/react-component/async-validator/blob/master/src/rule/url.ts"
    click RPEnum "https://github.com/react-component/async-validator/blob/master/src/rule/enum.ts"
    click ValidatorIndex "https://github.com/react-component/async-validator/blob/master/src/validator/index.ts"
    click Any "https://github.com/react-component/async-validator/blob/master/src/validator/any.ts"
    click Array "https://github.com/react-component/async-validator/blob/master/src/validator/array.ts"
    click Boolean "https://github.com/react-component/async-validator/blob/master/src/validator/boolean.ts"
    click DateV "https://github.com/react-component/async-validator/blob/master/src/validator/date.ts"
    click EnumV "https://github.com/react-component/async-validator/blob/master/src/validator/enum.ts"
    click Float "https://github.com/react-component/async-validator/blob/master/src/validator/float.ts"
    click Integer "https://github.com/react-component/async-validator/blob/master/src/validator/integer.ts"
    click Method "https://github.com/react-component/async-validator/blob/master/src/validator/method.ts"
    click NumberV "https://github.com/react-component/async-validator/blob/master/src/validator/number.ts"
    click ObjectV "https://github.com/react-component/async-validator/blob/master/src/validator/object.ts"
    click PatternV "https://github.com/react-component/async-validator/blob/master/src/validator/pattern.ts"
    click Regexp "https://github.com/react-component/async-validator/blob/master/src/validator/regexp.ts"
    click RequiredV "https://github.com/react-component/async-validator/blob/master/src/validator/required.ts"
    click StringV "https://github.com/react-component/async-validator/blob/master/src/validator/string.ts"
    click TypeV "https://github.com/react-component/async-validator/blob/master/src/validator/type.ts"
    click Util "https://github.com/react-component/async-validator/blob/master/src/util.ts"
    click Messages "https://github.com/react-component/async-validator/blob/master/src/messages.ts"
    click TestSuite "https://github.com/react-component/async-validator/tree/master/tests/"
    click BuildPackaging "https://github.com/react-component/async-validator/blob/master/.fatherrc.js"
    click BuildPackaging "https://github.com/react-component/async-validator/blob/master/.dumirc.ts"
    click CICD "https://github.com/react-component/async-validator/blob/master/.github/workflows/ci.yml"
    click Docs "https://github.com/react-component/async-validator/blob/master/README.md"
    click Docs "https://github.com/react-component/async-validator/blob/master/package.json"
    click Docs "https://github.com/react-component/async-validator/blob/master/tsconfig.json"
    click Docs "https://github.com/react-component/async-validator/blob/master/HISTORY.md"
    click Docs "https://github.com/react-component/async-validator/blob/master/LICENSE.md"
    click Docs "https://github.com/react-component/async-validator/blob/master/.eslintrc.js"
    click Docs "https://github.com/react-component/async-validator/blob/master/.prettierrc"
    class Consumer,Schema,DescriptorModel,RPIndex,RPType,RPRequired,RPRange,RPPattern,RPWhitespace,RPURL,RPEnum,ValidatorIndex,Any,Array,Boolean,DateV,EnumV,Float,Integer,Method,NumberV,ObjectV,PatternV,Regexp,RequiredV,StringV,TypeV runtime
    class Util,Messages extension
    class TestSuite,BuildPackaging,CICD,Docs infra
```
