zuqe 0.3.3

Zuqe (pronounced /zuːk/, like "zook") is a lightweight JavaScript engine implemented in Rust. It is designed for embedded systems and general‑purpose use, balancing performance, memory safety, and a minimal footprint.

Zuqe is named after 朱雀 (Zhuque), the Vermilion Bird of Chinese mythology, which represents fire and renewal.

Zuqe is inspired by QuickJS.

🎯 Design Goals

Lightweight: Small binary footprint and low memory overhead for IoT devices, edge computing, and resource-constrained environments
Rust-Native: Leverages Rust's memory safety, zero-cost abstractions and modern toolchain to boost engineering process
Embedding-Friendly: Easy to embed in and integrate with host applications
Fast Bytecode Execution: Optimized interpreter with efficient garbage collection
Standards Compliance: Evolving implementation of modern JavaScript standards

🚀 ECMAScript Features

Zuqe implements a comprehensive set of ES2023+ features, making it suitable for modern JavaScript development:

Core Language Features

Modern Functions: Arrow functions, async functions, generator functions
Classes: Full ES6+ class implementation with inheritance, private fields, and static members
Modules: ES6 modules with import/export, dynamic imports, and top-level await
Destructuring: Array and object destructuring with rest parameters
Template Literals: String interpolation and tagged templates
Iterators and Generators: Full implementation of iterator protocol and generator functions

Built-in Objects and APIs

Arrays: Complete Array.prototype methods including map, filter, reduce
Collection Types: Map, Set, WeakMap, WeakSet
Promises: Full Promise implementation with async/await support
JSON: JSON.parse() and JSON.stringify() with proper error handling
Regular Expressions: PCRE2-based regex engine with modern features
Typed Arrays: Int8Array, Uint8Array, Float32Array, etc., plus DataView
Reflection APIs: Reflect object with comprehensive reflection capabilities

Advanced Features

Proxy: Complete proxy implementation for object interception
Symbols: Symbol primitives and well-known symbols
Date and Time: Date object with timezone support
Math: Comprehensive Math library implementation
Error Handling: Structured error types with stack traces

📋 Project Status

Zuqe is under active development. It currently passes a substantial portion of the Test262 test suite and is evolving toward production readiness.

🎪 Use Cases

IoT Devices: Resource-constrained environments requiring JavaScript scripting
Microcontrollers: 32-bit systems with limited memory (512KB - 2MB RAM)
Scripting Engine: Embeddable scripting for applications
Development Tools: IDEs, build tools, and development utilities
Serverless Functions: Lightweight function execution environments
Edge Runtime: Distributed computing at network edge

🏁 Getting Started

Setup `Cargo.toml`

Add zuqe to your dependencies in Cargo.toml:

[dependencies]
zuqe = "0.3.0"

Initialize Runtime and Context

The core of any zuqe application is the Runtime and Context. The Runtime manages the engine, while the Context provides an isolated environment for script execution.

use zuqe::{Runtime, Context};

let mut rt = Runtime::create().unwrap();
let mut ctx = rt.create_context_ecma().unwrap();

Run JavaScript

Use run_wait_with to execute JavaScript code within the context, wait till script exits.

use zuqe::{EvalFlags, EvalType};

let script = r#"
    let greet = (name) => `Hello, ${name}!`;
    greet("Zuqe");
"#;

let res = ctx.run_wait(
    script.as_bytes(), // script content
    "example.js", // filename
    EvalType::Global, // global eval mode
    EvalFlags::empty()
);

match res {
  Ok(val) => {
      println!("eval result: {val:?}");
  }
  Err(e) => {
      let mut err_msg = e.message;
      if let Some(tb) = e.traceback {
          err_msg = format!("{err_msg}\n{tb}");
      }
      println!("error: {err_msg}");
  }
}

Advanced Usage Examples

For more comprehensive examples, check the examples directory which includes:

Basic JavaScript execution
Module system usage
Promise and async/await
Custom native functions and classes
Error handling and debugging

📚 Documentation

User Guide:
Examples:
- ZJS

🤝 Contributing

Zuqe is an open-source project and welcomes contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

📄 License

Licensed under the Apache License 2.0.