Jade: Experimental JavaScript Runtime Foundation

Jade is an educational JavaScript runtime implementation demonstrating core concepts used in production runtimes like Node.js and Bun. This project serves as a foundation for understanding low-level runtime construction using:

• JavaScriptCore (JSC) from WebKit for JS execution
• libuv for cross-platform asynchronous I/O
• C for native bindings and system integration

Current State: Basic prototype supporting core runtime features

📦 Installation

Prerequisites

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install \
  libwebkit2gtk-4.0-dev \
  libuv1-dev \
  cmake \
  build-essential

macOS

brew install cmake libuv
xcode-select --install # For Xcode command line tools

Build from Source

# Clone repository
git clone https://github.com/dexter-xD/jade.git
cd jade

# Configure build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug

# Compile
make

# Verify build
./jade --version

🏗️ Architecture Overview

Core Components

┌───────────────────────┐
│      JavaScript       │
│       (User Code)     │
└───────────┬───────────┘
            │
┌───────────▼───────────┐   ┌───────────────────┐
│  JavaScriptCore (JSC) │◄─▶│      System       │
│    JS Execution       │   │      APIs         │
└───────────┬───────────┘   └───────────────────┘
            │                     ▲
┌───────────▼───────────┐         │
│      libuv Event      │◄────────┘
│        Loop           │
└───────────────────────┘

Component Details

1. JSC Engine Layer

   • Creates/manages JS contexts
   • Handles JS code parsing/execution
   • Manages JS/C value conversions

2. libuv Event Loop

   • Timer management (setTimeout)
   • Filesystem operations (planned)
   • Network I/O (planned)
   • Thread pool integration

3. System API Bridge

   • Console I/O implementation
   • Future: File system access
   • Future: Network interfaces

🛠️ Current Features

Implemented

• Core event loop infrastructure
• Basic JS execution context
• console.log/console.error bindings
• setTimeout implementation
• Memory-safe value passing between JS/C
• Build system with CMake

In Progress

• Proper error propagation JS ↔ C
• File system API stubs
• Module resolution prototype

🚀 Usage

Basic Execution

./build/jade path/to/script.js

Example Script

// Basic functionality demo
console.log("Jade Runtime Initialized");

setTimeout(() => {
  console.error("Async operation completed");
}, 1000);

console.log("Main thread execution");

Expected Output:

LOG: Jade Runtime Initialized
LOG: Main thread execution
ERROR: Async operation completed

Current Limitations

• No Promise support
• Limited error handling
• Single-file execution only
• Basic memory management

🔬 Development Setup

Test Suite

# Run all tests
cd build && ctest --output-on-failure

# Specific test target
./test/runtime_tests

Test Coverage

# Generate coverage report
mkdir -p coverage
gcovr --exclude tests/ --html-details coverage/report.html

Debug Build

cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=1
make clean && make

📝 Project Roadmap

Phase 1: Core Foundation (Current)

• Basic JS execution context
• Event loop scaffolding
• Console API implementation
• File system API stubs

Phase 2: Production Patterns

• Error handling system
• Memory management audits
• Cross-platform testing
• Benchmarking suite

Phase 3: Advanced Features

• Promise integration
• HTTP server prototype
• WASM support exploration
• Debugger protocol

🤝 Contribution Guide

Ideal Contributions

• Core runtime improvements
• Additional system APIs
• Test coverage expansion
• Documentation improvements
• Cross-platform fixes

Workflow

1. Create issue for discussion
2. Fork repository
3. Use feature branch workflow:

   git checkout -b feat/features

4. Follow coding standards:
   • C11 standard
   • 4-space indentation
   • Doxygen-style comments
5. Submit PR with:
   • Implementation details
   • Test cases
   • Documentation updates

⚠️ Known Issues

Issue	Workaround	Priority
Memory leaks in timer callbacks	Manual cleanup in tests	High
No Windows support	Use WSL/Linux VM	Medium
Limited error messages	Check debug build output	Low

📚 Learning Resources

Core Technologies

• JavaScriptCore Internals
• libuv Design Overview
• Node.js Architecture Guide

Related Projects

• Bun Runtime
• Deno Core
• Node.js Bindings

---

Jade is maintained by dexter as an educational resource for understanding low-level runtime development. Not affiliated with Node.js, Bun, or WebKit projects.

---

Support

If you find this project helpful, consider buying me a coffee! ☕