# ealush/vest architecture

> Architecture diagram of the GitHub repository ealush/vest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ealush/vest
- Repository: https://github.com/ealush/vest
- Video tour (about a minute): https://gitdiagram.com/ealush/vest/video

## Overview

Vest is a stateful validation library for running field- and group-oriented test suites, retaining validation results, and coordinating asynchronous checks. The primary workflow is user-defined suite → suite runner → registered tests and runtime execution → queryable result. The README also documents schemas, Standard Schema interoperability, framework integrations, and workflow controls such as optional fields, warnings, and dynamic lists; these remain visible as product branches. The runner and result selectors are sampled, but several runtime and integration internals are not, so uncertain call wiring is omitted.

Main entry points: [`packages/vest/src/suite/useCreateSuiteRunner.ts`](https://github.com/ealush/vest/blob/latest/packages/vest/src/suite/useCreateSuiteRunner.ts) (Suite runner), [`packages/vest/src/vest.ts`](https://github.com/ealush/vest/blob/latest/packages/vest/src/vest.ts) (Suite API), [`packages/vest/src/core/isolate/IsolateSuite/IsolateSuite.ts`](https://github.com/ealush/vest/blob/latest/packages/vest/src/core/isolate/IsolateSuite/IsolateSuite.ts) (Suite isolation), [`packages/n4s/src/n4s.ts`](https://github.com/ealush/vest/blob/latest/packages/n4s/src/n4s.ts) (Enforce rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Suite authoring"]
  node_suite_api["Suite API<br/>[vest.ts]"]
  node_suite_factory["Suite creation<br/>[createSuite.ts]"]
  node_test_declaration["Test declarations"]
  node_workflow_hooks["Workflow controls"]
end

subgraph group_execution["Validation execution"]
  node_suite_runner["Suite runner"]
  node_suite_context["Suite context<br/>[SuiteContext.ts]"]
  node_suite_isolate["Suite isolation<br/>[IsolateSuite.ts]"]
  node_test_isolates["Test isolates<br/>[IsolateTest.ts]"]
  node_runtime["Isolate runtime<br/>[VestRuntime.ts]"]
  node_reconciliation["State reconciliation<br/>[Reconciler.ts]"]
  node_suite_events["Suite events<br/>[VestBus.ts]"]
end

subgraph group_results["State and results"]
  node_suite_result["Suite result<br/>[suiteResult.ts]"]
  node_result_queries["Result selectors<br/>[suiteSelectors.ts]"]
  node_validity["Field validity"]
end

subgraph group_rules["Rules and schemas"]
  node_rule_api["Enforce rules<br/>[n4s.ts]"]
  node_rule_chains["Rule chains<br/>[proxyHandlers.ts]"]
  node_schema_rules["Schema rules<br/>[schemaRules.ts]"]
end

subgraph group_interop["Interoperability"]
  node_schema_interop["Schema contract<br/>[standard-schema.ts]"]
  node_framework_integrations["Framework integrations"]
  node_server_integrations["Server integrations<br/>[app.ts]"]
end

node_user(("Form developer"))

node_user -->|"defines suite"| node_suite_api
node_suite_api -->|"creates suite"| node_suite_factory
node_suite_factory -->|"binds callback"| node_suite_runner
node_user -->|"runs suite"| node_suite_runner
node_suite_runner -->|"runs in context"| node_suite_context
node_suite_runner -->|"executes callback"| node_suite_isolate
node_suite_isolate -->|"registers tests"| node_test_declaration
node_test_declaration -->|"creates test state"| node_test_isolates
node_suite_isolate -->|"uses runtime"| node_runtime
node_runtime -->|"reconciles state"| node_reconciliation
node_suite_runner -->|"emits events"| node_suite_events
node_suite_runner -->|"builds result"| node_suite_result
node_suite_result -->|"exposes queries"| node_result_queries
node_result_queries -->|"checks validity"| node_validity
node_workflow_hooks -->|"modifies execution"| node_suite_runner
node_suite_runner -->|"applies schemas"| node_schema_rules
node_suite_runner -->|"uses schema rules"| node_rule_api
node_rule_api -->|"builds chains"| node_rule_chains
node_rule_api -->|"provides schemas"| node_schema_rules
node_suite_runner -.->|"supports schemas"| node_schema_interop
node_framework_integrations -.->|"adapts suites"| node_suite_api
node_server_integrations -.->|"validates requests"| node_suite_api

click node_suite_api "https://github.com/ealush/vest/blob/latest/packages/vest/src/vest.ts"
click node_suite_factory "https://github.com/ealush/vest/blob/latest/packages/vest/src/suite/createSuite.ts"
click node_workflow_hooks "https://github.com/ealush/vest/tree/latest/packages/vest/src/hooks"
click node_suite_runner "https://github.com/ealush/vest/blob/latest/packages/vest/src/suite/useCreateSuiteRunner.ts"
click node_suite_context "https://github.com/ealush/vest/blob/latest/packages/vest/src/core/context/SuiteContext.ts"
click node_suite_isolate "https://github.com/ealush/vest/blob/latest/packages/vest/src/core/isolate/IsolateSuite/IsolateSuite.ts"
click node_test_isolates "https://github.com/ealush/vest/blob/latest/packages/vest/src/core/isolate/IsolateTest/IsolateTest.ts"
click node_runtime "https://github.com/ealush/vest/blob/latest/packages/vestjs-runtime/src/VestRuntime.ts"
click node_reconciliation "https://github.com/ealush/vest/blob/latest/packages/vestjs-runtime/src/Reconciler.ts"
click node_suite_events "https://github.com/ealush/vest/blob/latest/packages/vest/src/core/VestBus/VestBus.ts"
click node_suite_result "https://github.com/ealush/vest/blob/latest/packages/vest/src/suiteResult/suiteResult.ts"
click node_result_queries "https://github.com/ealush/vest/blob/latest/packages/vest/src/suiteResult/selectors/suiteSelectors.ts"
click node_validity "https://github.com/ealush/vest/blob/latest/packages/vest/src/suiteResult/selectors/useSetValidProperty.ts"
click node_rule_api "https://github.com/ealush/vest/blob/latest/packages/n4s/src/n4s.ts"
click node_rule_chains "https://github.com/ealush/vest/blob/latest/packages/n4s/src/rules/chainBuilder/proxyHandlers.ts"
click node_schema_rules "https://github.com/ealush/vest/blob/latest/packages/n4s/src/rules/schemaRules/schemaRules.ts"
click node_schema_interop "https://github.com/ealush/vest/blob/latest/integrations/kit/src/contracts/standard-schema.ts"
click node_framework_integrations "https://github.com/ealush/vest/tree/latest/integrations"
click node_server_integrations "https://github.com/ealush/vest/blob/latest/integrations/hono/src/app.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_suite_api,node_suite_factory,node_test_declaration,node_workflow_hooks toneBlue
class node_suite_runner,node_suite_context,node_suite_isolate,node_test_isolates,node_runtime,node_reconciliation,node_suite_events toneAmber
class node_suite_result,node_result_queries,node_validity toneMint
class node_rule_api,node_rule_chains,node_schema_rules toneRose
class node_schema_interop,node_framework_integrations,node_server_integrations,node_user toneIndigo
```

## Components

### Suite authoring

- [Suite API](https://github.com/ealush/vest/blob/latest/packages/vest/src/vest.ts): `packages/vest/src/vest.ts`
- [Suite creation](https://github.com/ealush/vest/blob/latest/packages/vest/src/suite/createSuite.ts): `packages/vest/src/suite/createSuite.ts`
- **Test declarations**
- [Workflow controls](https://github.com/ealush/vest/tree/latest/packages/vest/src/hooks): `packages/vest/src/hooks`

### Validation execution

- [Suite runner](https://github.com/ealush/vest/blob/latest/packages/vest/src/suite/useCreateSuiteRunner.ts): `packages/vest/src/suite/useCreateSuiteRunner.ts`
- [Suite context](https://github.com/ealush/vest/blob/latest/packages/vest/src/core/context/SuiteContext.ts): `packages/vest/src/core/context/SuiteContext.ts`
- [Suite isolation](https://github.com/ealush/vest/blob/latest/packages/vest/src/core/isolate/IsolateSuite/IsolateSuite.ts): `packages/vest/src/core/isolate/IsolateSuite/IsolateSuite.ts`
- [Test isolates](https://github.com/ealush/vest/blob/latest/packages/vest/src/core/isolate/IsolateTest/IsolateTest.ts): `packages/vest/src/core/isolate/IsolateTest/IsolateTest.ts`
- [Isolate runtime](https://github.com/ealush/vest/blob/latest/packages/vestjs-runtime/src/VestRuntime.ts): `packages/vestjs-runtime/src/VestRuntime.ts`
- [State reconciliation](https://github.com/ealush/vest/blob/latest/packages/vestjs-runtime/src/Reconciler.ts): `packages/vestjs-runtime/src/Reconciler.ts`
- [Suite events](https://github.com/ealush/vest/blob/latest/packages/vest/src/core/VestBus/VestBus.ts): `packages/vest/src/core/VestBus/VestBus.ts`

### State and results

- [Suite result](https://github.com/ealush/vest/blob/latest/packages/vest/src/suiteResult/suiteResult.ts): `packages/vest/src/suiteResult/suiteResult.ts`
- [Result selectors](https://github.com/ealush/vest/blob/latest/packages/vest/src/suiteResult/selectors/suiteSelectors.ts): `packages/vest/src/suiteResult/selectors/suiteSelectors.ts`
- [Field validity](https://github.com/ealush/vest/blob/latest/packages/vest/src/suiteResult/selectors/useSetValidProperty.ts): `packages/vest/src/suiteResult/selectors/useSetValidProperty.ts`

### Rules and schemas

- [Enforce rules](https://github.com/ealush/vest/blob/latest/packages/n4s/src/n4s.ts): `packages/n4s/src/n4s.ts`
- [Rule chains](https://github.com/ealush/vest/blob/latest/packages/n4s/src/rules/chainBuilder/proxyHandlers.ts): `packages/n4s/src/rules/chainBuilder/proxyHandlers.ts`
- [Schema rules](https://github.com/ealush/vest/blob/latest/packages/n4s/src/rules/schemaRules/schemaRules.ts): `packages/n4s/src/rules/schemaRules/schemaRules.ts`

### Interoperability

- [Schema contract](https://github.com/ealush/vest/blob/latest/integrations/kit/src/contracts/standard-schema.ts): `integrations/kit/src/contracts/standard-schema.ts`
- [Framework integrations](https://github.com/ealush/vest/tree/latest/integrations): `integrations`
- [Server integrations](https://github.com/ealush/vest/blob/latest/integrations/hono/src/app.ts): `integrations/hono/src/app.ts`

### Other components

- **Form developer**

## Connections

- Form developer → Suite API: defines suite
- Suite API → Suite creation: creates suite
- Suite creation → Suite runner: binds callback
- Form developer → Suite runner: runs suite
- Suite runner → Suite context: runs in context
- Suite runner → Suite isolation: executes callback
- Suite isolation → Test declarations: registers tests
- Test declarations → Test isolates: creates test state
- Suite isolation → Isolate runtime: uses runtime
- Isolate runtime → State reconciliation: reconciles state
- Suite runner → Suite events: emits events
- Suite runner → Suite result: builds result
- Suite result → Result selectors: exposes queries
- Result selectors → Field validity: checks validity
- Workflow controls → Suite runner: modifies execution
- Suite runner → Schema rules: applies schemas
- Suite runner → Enforce rules: uses schema rules
- Enforce rules → Rule chains: builds chains
- Enforce rules → Schema rules: provides schemas
- Suite runner → Schema contract: supports schemas
- Framework integrations → Suite API: adapts suites
- Server integrations → Suite API: validates requests