Skip to content

README.md

Latest commit

 

History

History
234 lines (182 loc) · 5.71 KB

README.md

File metadata and controls

234 lines (182 loc) · 5.71 KB

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

Related Projects

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! ☕

Buy Me a Coffee