# siubaak/sval architecture

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

- Interactive diagram: https://gitdiagram.com/siubaak/sval
- Repository: https://github.com/siubaak/sval

## Overview

##### Project Type and Purpose
- This is an open-source JavaScript interpreter library (named **Sval**), written in TypeScript/JavaScript.
- It embeds the Acorn parser to parse JS code into an ESTree AST, then evaluates it in either a sandboxed or “invasive” (global) environment.
- Primary use cases: safely evaluate arbitrary ES code in Node or browser, support newer ECMAScript versions without using native `eval` or `new Function`.

##### File Structure Analysis
- Top-level directories:
- **src/** – core interpreter logic (evaluate, scope, shared utilities, public API)
- **dist/** – compiled outputs (JavaScript bundles, UMD, CommonJS, and type declarations)
- **scripts/** – auxiliary CLI scripts and plugin management tools
- **tests/** – unit tests covering every language feature (declaration, expression, pattern, etc.)
- Config & metadata: `package.json`, `tsconfig.json`, `vite.config.ts`, CI workflow in `.github/workflows/coverage.yml`.
- Build pipeline: TS compiler + Vite for bundling, producing multiple module formats and type definitions.

##### Key Insights from README
- Core class **Sval** with options: `ecmaVer`, `sourceType`, `sandBox`.
- Main methods:
- `parse(code)` → returns AST
- `run(code|AST)` → executes code within managed scope
- `import(...)` & `exports` → module interop in both script and module modes
- Supported targets: ES5 runtime, latest JS features, sandbox vs global execution contexts.

a. Main Components
1. **API Layer (Sval Class)**
- Exposed to users: constructor, parse, run, import, exports.
2. **Parser Integration**
- Acorn or custom parser hook
- Takes source code → ESTree AST
3. **Evaluator Engine**
- **evaluate/** modules subdivided by AST node types: declaration, expression, statement, literal, pattern, program, identifier, helper
- Two flavors: normal (`evaluate`) and “n-” optimized (`evaluate_n`)
4. **Scope Manager**
- env record, variable resolution (`scope/variable.ts`)
5. **Shared Utilities**
- async handling, constants, general helpers (`share/*.ts`)
6. **Sandbox / Global Environment**
- isolates or merges with host global scope
7. **Module Loader**
- handles script vs module semantics, dynamic imports, export collection
8. **Build & Packaging**
- TypeScript compiler → `dist/`
- Vite bundler outputs: `sval.js`, `sval.umd.cjs`
9. **Testing Harness**
- Mocha/Jest tests under `tests/`, bootstrapping environment

b. Relationships & Data Flows
- User code (string or AST) → **API Layer** → **Parser** → AST
- AST → **Evaluator Engine** ↔ **Scope Manager**
- Evaluator invokes **Shared Utilities** for runtime behaviors
- Results and exported values accumulate in **Module Loader** → `exports` object
- **Sandbox** wrapper enforces environment isolation if enabled
- CI/Tests → validate each stage; Build pipeline compiles & bundles for distribution

c. Architectural Patterns & Principles
- Interpreter Pattern: separate parsing, evaluation, and environment
- Modularization by AST node type for single-responsibility
- Extension points: two evaluator modes, plugin CLI scripts, custom parser injection
- Layered design: public API → parsing layer → evaluation layer → environment

d. Key Technologies & Frameworks
- TypeScript for source code & type definitions
- Vite for build and bundling
- Acorn (AST parsing)
- ESTree spec for node definitions
- Node.js and browser environments (UMD, ESM, CJS)
- GitHub Actions for CI coverage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        SvalClass["Sval Class<br/>(Constructor, parse, run, import, exports)"]:::api
    end
    click SvalClass "https://github.com/siubaak/sval/blob/master/src/index.ts"

    %% Parser Integration
    subgraph "Parser Integration"
        Parser["Parser (Acorn)<br/>ESTree AST"]:::parser
    end
    click Parser "https://github.com/siubaak/sval/blob/master/src/index.ts"

    AST["AST"]:::io

    %% Evaluator Engine - Standard Mode
    subgraph "Evaluator Engine - Standard Mode"
        EvalDecl["declaration.ts"]:::evaluator
        EvalExpr["expression.ts"]:::evaluator
        EvalHelper["helper.ts"]:::evaluator
        EvalIdent["identifier.ts"]:::evaluator
        EvalLit["literal.ts"]:::evaluator
        EvalPattern["pattern.ts"]:::evaluator
        EvalProgram["program.ts"]:::evaluator
        EvalStmt["statement.ts"]:::evaluator
    end
    click EvalDecl "https://github.com/siubaak/sval/blob/master/src/evaluate/declaration.ts"
    click EvalExpr "https://github.com/siubaak/sval/blob/master/src/evaluate/expression.ts"
    click EvalHelper "https://github.com/siubaak/sval/blob/master/src/evaluate/helper.ts"
    click EvalIdent "https://github.com/siubaak/sval/blob/master/src/evaluate/identifier.ts"
    click EvalLit "https://github.com/siubaak/sval/blob/master/src/evaluate/literal.ts"
    click EvalPattern "https://github.com/siubaak/sval/blob/master/src/evaluate/pattern.ts"
    click EvalProgram "https://github.com/siubaak/sval/blob/master/src/evaluate/program.ts"
    click EvalStmt "https://github.com/siubaak/sval/blob/master/src/evaluate/statement.ts"

    %% Evaluator Engine - Optimized Mode
    subgraph "Evaluator Engine - Optimized Mode (n-flavor)"
        EvalNDecl["declaration.d.ts"]:::evaluator
        EvalNExpr["expression.d.ts"]:::evaluator
        EvalNHelper["helper.d.ts"]:::evaluator
        EvalNIdent["identifier.d.ts"]:::evaluator
        EvalNLit["literal.d.ts"]:::evaluator
        EvalNPattern["pattern.d.ts"]:::evaluator
        EvalNProgram["program.d.ts"]:::evaluator
        EvalNStmt["statement.d.ts"]:::evaluator
    end
    click EvalNDecl "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/declaration.d.ts"
    click EvalNExpr "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/expression.d.ts"
    click EvalNHelper "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/helper.d.ts"
    click EvalNIdent "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/identifier.d.ts"
    click EvalNLit "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/literal.d.ts"
    click EvalNPattern "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/pattern.d.ts"
    click EvalNProgram "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/program.d.ts"
    click EvalNStmt "https://github.com/siubaak/sval/blob/master/dist/src/evaluate_n/statement.d.ts"

    %% Scope Manager
    subgraph "Scope Manager"
        ScopeIndex["index.ts"]:::scope
        ScopeVar["variable.ts"]:::scope
    end
    click ScopeIndex "https://github.com/siubaak/sval/blob/master/src/scope/index.ts"
    click ScopeVar "https://github.com/siubaak/sval/blob/master/src/scope/variable.ts"

    %% Shared Utilities
    subgraph "Shared Utilities"
        ShareAsync["async.ts"]:::util
        ShareConst["const.ts"]:::util
        ShareUtil["util.ts"]:::util
    end
    click ShareAsync "https://github.com/siubaak/sval/blob/master/src/share/async.ts"
    click ShareConst "https://github.com/siubaak/sval/blob/master/src/share/const.ts"
    click ShareUtil "https://github.com/siubaak/sval/blob/master/src/share/util.ts"

    %% Module Loader
    ModuleLoader["Module Loader<br/>(import/exports)"]:::module
    click ModuleLoader "https://github.com/siubaak/sval/blob/master/src/index.ts"

    Exports["Exports Object"]:::io

    %% Environment Wrapper
    Sandbox["Sandbox / Global Environment"]:::env
    click Sandbox "https://github.com/siubaak/sval/blob/master/src/index.ts"

    %% Build & Packaging
    subgraph "Build & Packaging"
        ViteConfig["vite.config.ts"]:::build
        TSConfig["tsconfig.json"]:::build
        PackageJSON["package.json"]:::build
        Scripts["scripts/"]:::build
    end
    click ViteConfig "https://github.com/siubaak/sval/blob/master/vite.config.ts"
    click TSConfig "https://github.com/siubaak/sval/blob/master/tsconfig.json"
    click PackageJSON "https://github.com/siubaak/sval/blob/master/package.json"
    click Scripts "https://github.com/siubaak/sval/tree/master/scripts/"

    %% Distribution Artifacts
    subgraph "Distribution Artifacts"
        DistBundle1["dist/sval.js"]:::build
        DistBundle2["dist/sval.umd.cjs"]:::build
        DistTypesIndex["dist/src/index.d.ts"]:::build
        DistTypesEval["dist/src/evaluate/**/*.d.ts"]:::build
        DistTypesScope["dist/src/scope/**/*.d.ts"]:::build
        DistTypesShare["dist/src/share/**/*.d.ts"]:::build
    end
    click DistBundle1 "https://github.com/siubaak/sval/blob/master/dist/sval.js"
    click DistBundle2 "https://github.com/siubaak/sval/blob/master/dist/sval.umd.cjs"
    click DistTypesIndex "https://github.com/siubaak/sval/blob/master/dist/src/index.d.ts"
    click DistTypesEval "https://github.com/siubaak/sval/blob/master/dist/src/evaluate/declaration.d.ts"
    click DistTypesScope "https://github.com/siubaak/sval/blob/master/dist/src/scope/index.d.ts"
    click DistTypesShare "https://github.com/siubaak/sval/blob/master/dist/src/share/util.d.ts"

    %% Testing Harness
    subgraph "Testing Harness"
        TestsDir["tests/"]:::test
    end
    click TestsDir "https://github.com/siubaak/sval/tree/master/tests/"

    %% Connections
    SvalClass -->|"invokes"| Parser
    Parser -->|"produces"| AST
    AST -->|"evaluated by"| EvalDecl
    AST --> EvalExpr
    AST --> EvalHelper
    AST --> EvalIdent
    AST --> EvalLit
    AST --> EvalPattern
    AST --> EvalProgram
    AST --> EvalStmt

    EvalDecl -->|"optimized"| EvalNDecl
    EvalExpr --> EvalNExpr
    EvalHelper --> EvalNHelper
    EvalIdent --> EvalNIdent
    EvalLit --> EvalNLit
    EvalPattern --> EvalNPattern
    EvalProgram --> EvalNProgram
    EvalStmt --> EvalNStmt

    %% Evaluator uses scope and utilities
    EvalDecl --> ScopeIndex
    EvalExpr --> ScopeVar
    EvalHelper --> ShareUtil
    EvalIdent --> ScopeIndex
    EvalLit --> ShareConst
    EvalPattern --> ScopeVar
    EvalProgram --> ModuleLoader
    EvalStmt --> ShareAsync

    %% Module loader and environment
    SvalClass --> Sandbox
    Sandbox --> EvalDecl
    ModuleLoader --> Exports
    Sandbox --> ModuleLoader

    %% Build & test flows
    PackageJSON -->|configures| ViteConfig
    ViteConfig -->|bundles| DistBundle1
    ViteConfig --> DistBundle2
    TSConfig -->|types| DistTypesIndex
    TSConfig --> DistTypesEval
    TSConfig --> DistTypesScope
    TSConfig --> DistTypesShare

    TestsDir -->|runs against| EvalDecl
    TestsDir --> EvalExpr
    TestsDir --> ScopeIndex

    %% Styles
    classDef api fill:#f9f,stroke:#333,stroke-width:1px
    classDef parser fill:#ff9,stroke:#333,stroke-width:1px
    classDef evaluator fill:#9f9,stroke:#333,stroke-width:1px
    classDef scope fill:#9ff,stroke:#333,stroke-width:1px
    classDef util fill:#fc9,stroke:#333,stroke-width:1px
    classDef module fill:#ccf,stroke:#333,stroke-width:1px
    classDef env fill:#cfc,stroke:#333,stroke-width:1px
    classDef build fill:#eee,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef test fill:#ffc,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef io fill:#fff,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
