repository·master·Indexed 21 days ago
https://github.com/delskayn/rquickjsHigh-level, safe Rust bindings for the QuickJS-NG JavaScript engine (a fork of QuickJS). rquickjs provides ES2020 support, seamless async integration between Rust futures and ES6 Promises, and flexible data conversion. It allows Rust data types to be represented as JS classes via the JsClass trait, supporting static/instance members, getters, setters, and exotic property behavior. The library supports custom allocators, user-defined module loaders, and bytecode bundling via the embed macro.
rquickjs is a high-level, safe Rust binding for the QuickJS-NG JavaScript engine (a fork of QuickJS). It is designed to be an easy-to-use wrapper, similar in philosophy to the rlua library. It provides a way to embed a small, fast, and ES2020-compliant JavaScript engine into Rust applications.rquickjs-core provides high-level, safe Rust bindings for the QuickJS-NG JavaScript engine (a fork of QuickJS). It is designed to be an easy-to-use wrapper, similar in philosophy to the rlua library.
Key capabilities include:
You can represent Rust data types as JavaScript classes. This allows JS to interact with Rust data through object properties, including support for both static and instance members.
To ensure proper garbage collection when holding references to JS objects within Rust data types, the type must implement the Trace trait.
The rquickjs crate extends the core QuickJS engine with several Rust-centric features:
Runtime, including full support for Rust's global allocator.embed macro to bundle JavaScript modules as bytecode.Trace trait to ensure the garbage collector works correctly.The crate provides full integration with async Rust, allowing for seamless communication between the JavaScript engine and Rust's asynchronous ecosystem.
The library provides hooks for advanced memory and module management:
Runtime using a custom allocator or use Rust's global allocator.When executing JavaScript code via rquickjs, errors can be either native Rust errors or exceptions thrown from within the QuickJS engine. To handle both, use CaughtResult<'js, T> (an alias for StdResult<T, CaughtError<'js>>).
CaughtError can be one of three variants:
Error(Error): A native Rust error.Exception(Exception<'js>): A JavaScript exception that is an instance of the Error object.Value(Value<'js>): A JavaScript exception that is a primitive value (e.g., throw 3).You can use the catch extension trait to convert a standard Result<T> into a CaughtResult<'js, T>, which automatically retrieves the underlying JavaScript exception value from the context if an Error::Exception is encountered.
# use rquickjs::{Error, Context, Runtime, CaughtError};
# let rt = Runtime::new().unwrap();
# let ctx = Context::full(&rt).unwrap();
# ctx.with(|ctx|{
# use rquickjs::CatchResultExt;
if let Err(CaughtError::Value(err)) = ctx.eval::<(),_>("throw 3").catch(&ctx){
assert_eq!(err.as_int(), Some(3));
} else {
panic!("Expected a Value exception")
}If you need to hold a reference to a Runtime without preventing it from being dropped, use WeakRuntime. This is useful for long-lived handles that should not extend the lifetime of the engine.
Runtime::weak() -> WeakRuntime: Creates a weak handle from an existing Runtime.WeakRuntime::try_ref() -> Option<Runtime>: Attempts to upgrade the weak handle back into a strong Runtime handle. Returns None if the original Runtime has been dropped.let rt = Runtime::new().unwrap();
let weak_rt = rt.weak();
// Later...
if let Some(strong_rt) = weak_rt.try_ref() {
// Use strong_rt
}The #[qjs] macro automatically maps JavaScript arguments to Rust function parameters based on their type and mutability:
String or i32 will attempt to extract an owned value from the JavaScript argument.&T) will extract an OwnedBorrow<'js, T>.&mut T) will extract an OwnedBorrowMut<'js, T>.self (Methods): If the function is a method (using self), the macro handles the this context, allowing you to access the object instance as the first argument.When defining properties via Object::prop, you can use two main types to control how the property behaves in the JavaScript environment:
Property<T>Used for data descriptors. It stores a value and its associated flags.
writable(), configurable(), enumerable().Property::from(value).Accessor<G, S>Used for accessor descriptors. It defines logic for getting and setting a property.
get(closure), set(closure).Accessor::from(get_closure) or Accessor::new_get(get_closure) or Accessor::new_set(set_closure) or Accessor::new(get_closure, set_closure).Note: If you pass a raw value that implements IntoJs directly to prop, it is treated as a Property that is read-only by default.
// Property example
let p = Property::from("value").writable().enumerable();
// Accessor example
let a = Accessor::from(|| "get_val").set(|v| { /* set_val */ });The FromJs and IntoJs derives allow for seamless data transfer between Rust structs and JavaScript objects/arrays.
#[qjs(rename_all = ...)] or individual field attributes.undefined when converting to JS.FromJs or IntoJs derivation.// Unnamed struct (Tuple struct) mapping to a JS Array
#[derive(FromJs, IntoJs)]
struct Point(u32, u32);
// JS: [1, 2]
// Named struct mapping to a JS Object
#[derive(FromJs, IntoJs)]
struct User { id: u32, name: String }
// JS: { id: 1, name: "Alice" }