How siubaak/sval works
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