jstime_core

The core JavaScript runtime library for jstime. This crate provides the fundamental functionality for executing JavaScript code using the V8 engine.

Overview

jstime_core is designed to be:

• Embeddable: Easy to integrate into Rust applications
• Minimal: Only essential APIs included
• Performant: Optimized for speed and low memory usage
• Standards-compliant: Follows web standards (WHATWG, W3C)

Usage

Add to your Cargo.toml:

[dependencies]
jstime_core = "0.64.0"

Basic Example

use jstime_core as jstime;

fn main() {
    // Initialize V8
    jstime::init(None);
    
    // Create runtime instance
    let options = jstime::Options::default();
    let mut runtime = jstime::JSTime::new(options);
    
    // Execute JavaScript
    match runtime.run_script("console.log('Hello from jstime!')", "script.js") {
        Ok(result) => println!("Result: {}", result),
        Err(error) => eprintln!("Error: {}", error),
    }
}

Module Import Example

use jstime_core as jstime;

fn main() {
    jstime::init(None);
    
    let options = jstime::Options::default();
    let mut runtime = jstime::JSTime::new(options);
    
    // Import and execute a module
    match runtime.import("./my-module.js") {
        Ok(_) => println!("Module executed successfully"),
        Err(error) => eprintln!("Error: {}", error),
    }
}

Performance: JIT Warmup

For performance-critical code or benchmarking, enable JIT warmup to allow V8's TurboFan compiler to optimize the code:

use jstime_core as jstime;

fn main() {
    jstime::init(None);
    
    // Create runtime with 10 warmup iterations
    let options = jstime::Options::default()
        .with_warmup(10);
    let mut runtime = jstime::JSTime::new(options);
    
    // Script will be executed 10 times for warmup, then once for actual execution
    match runtime.run_script("/* compute-intensive code */", "bench.js") {
        Ok(result) => println!("Result: {}", result),
        Err(error) => eprintln!("Error: {}", error),
    }
}

The warmup runs execute the script multiple times before the actual execution, allowing V8's JIT compiler to profile and optimize hot code paths. This is particularly useful for:

• Benchmarking JavaScript code
• Performance-critical scripts that will be executed multiple times
• Testing optimized execution paths

Note: Use warmup judiciously - it adds upfront cost. Default is 0 (no warmup) for optimal startup time.

Built-in APIs

jstime_core provides these JavaScript APIs:

Core APIs

• Console: console.log(), console.error(), etc.
• Timers: setTimeout(), setInterval()
• Performance: performance.now()
• Microtasks: queueMicrotask()

Web APIs

• Fetch: fetch(), Headers, Request, Response
• Streams: ReadableStream, WritableStream, TransformStream
• URL: URL, URLSearchParams
• Events: Event, EventTarget

Data APIs

• Base64: atob(), btoa()
• Structured Clone: structuredClone()
• Text Encoding: TextEncoder, TextDecoder

Cryptography

• Crypto: crypto.getRandomValues(), crypto.randomUUID(), crypto.subtle.digest()

System APIs

• File System: node:fs/promises module
• Process: process.env, process.argv, process.cwd(), process.exit()

Advanced Features

• ES Modules: import/export with top-level await
• WebAssembly: Full WebAssembly support via V8

See docs/README.md for overview and docs/apis/ for detailed API documentation.

Project Structure

core/
├── src/
│   ├── builtins/          # Built-in JavaScript APIs
│   │   ├── README.md      # Built-ins documentation
│   │   ├── *_impl.rs      # Rust implementations
│   │   └── *.js           # JavaScript polyfills
│   ├── event_loop.rs      # Event loop implementation
│   ├── isolate_state.rs   # V8 isolate state management
│   ├── js_loading.rs      # Script compilation
│   ├── module.rs          # ES module system
│   ├── script.rs          # Script execution
│   └── lib.rs             # Public API
├── tests/                 # Integration tests
│   ├── README.md          # Testing documentation
│   ├── common/            # Test utilities
│   ├── fixtures/          # Test fixtures
│   └── test_*.rs          # Test files
├── Cargo.toml             # Package configuration
└── README.md              # This file

Documentation

• README.md - Features overview
• Web APIs - Detailed web API documentation
• System APIs - Process and file system APIs
• Module System - ES Modules and WebAssembly
• Built-ins README - Built-in API implementation guide
• Tests README - Testing guide
• CONTRIBUTING.md - Development workflow
• ARCHITECTURE.md - Architecture overview

Development

Building

# Debug build
cargo build -p jstime_core

# Release build
cargo build -p jstime_core --release

Testing

# Run all tests
cargo test -p jstime_core

# Run with output
cargo test -p jstime_core -- --nocapture

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Contributing

See CONTRIBUTING.md for guidelines.