Asynkron.JsEngine

A lightweight JavaScript interpreter written in C# that parses and evaluates JavaScript code using an S-expression intermediate representation.

📚 Documentation

All documentation is organized in the docs/ folder. This is the main entry point for all documentation.

Getting Started

• Quick Start Guide - Installation, basic usage, and first steps
• API Reference - Complete API documentation

Feature Documentation

• Supported Features - Comprehensive list of all implemented JavaScript features with examples
• NPM Package Compatibility - Running npm packages with the engine

Architecture & Design

• Architecture Overview - System design, components, and design decisions
• Transformation Pipeline - How JavaScript code transforms through the pipeline (JS → S-Expr → CPS)
• Documentation Index - Complete documentation index with all implementation details

Implementation Details

• CPS Transformation Plan - Async/await implementation strategy
• ASI Implementation - Automatic Semicolon Insertion
• Signal Pattern - Control flow signal pattern
• Control Flow Alternatives - Alternative approaches for control flow

Investigations & Debugging

• Investigations - Investigation notes and debugging documentation
• Key investigations: Parser vs CPS analysis, promise rejection investigation, exception channel results

Status & Planning

• Feature Status - Current implementation status
• Completed Features - Catalog of implemented features
• Remaining Tasks - What's left to implement

---

Quick Overview

Asynkron.JsEngine implements a substantial subset of JavaScript features:

✅ Implemented Features (99% Coverage!)

• ✅ Variables, functions, classes, objects, arrays
• ✅ Async/await, Promises, generators
• ✅ ES6 modules (import/export) including dynamic imports
• ✅ Template literals, destructuring, spread/rest
• ✅ All operators and control flow
• ✅ Comprehensive standard library (Math, Date, JSON, RegExp, etc.)
• ✅ Symbol, Map, Set, WeakMap, WeakSet collections
• ✅ BigInt for arbitrary precision integers
• ✅ Typed Arrays and ArrayBuffer for binary data
• ✅ Async iteration (for await...of)

See Complete Feature List for detailed documentation with examples.

🚧 Not Implemented (2 Specialized Features)

Only 2 highly specialized features remain: Proxy/Reflect. See Large Features Not Implemented for analysis.

Note: BigInt, Typed Arrays, WeakMap/WeakSet, async iteration, and dynamic imports are now implemented!

---

Running the Demo

Console application demos are included in the examples folder:

Main Demo

cd examples/Demo
dotnet run

The main demo showcases basic features including variables, functions, closures, objects, arrays, control flow, operators, and standard library usage.

Promise and Timer Demo

cd examples/PromiseDemo
dotnet run

Demonstrates setTimeout, setInterval, Promise creation, chaining, error handling, and event queue processing.

NPM Package Compatibility Demo

cd examples/NpmPackageDemo
dotnet run

Shows that the engine can run pure JavaScript npm packages without Node.js dependencies.

S-Expression Demo

cd examples/SExpressionDemo
dotnet run

Displays the S-expression representation and CPS transformation of JavaScript code. See Transformation Pipeline for details.

---

Building and Testing

# Build the solution
dotnet build

# Run tests
cd tests/Asynkron.JsEngine.Tests
dotnet test

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

See LICENSE file for details.

Credits

Developed by Asynkron