Crate rquickjs

Source
Expand description

§High-level bindings to QuickJS

The rquickjs crate provides safe high-level bindings to the QuickJS JavaScript engine. This crate is heavily inspired by the rlua crate.

§The Runtime and Context objects

The main entry point of this library is the Runtime struct. It represents the interpreter state and is used to create Context objects. As the QuickJS library does not support threading the runtime is locked behind a mutex. Multiple threads cannot run a script or create objects from the same runtime at the same time. The Context object represents a global environment. Contexts of the same runtime can share JavaScript objects like in the browser between frames of the same origin.

As both Runtime and Context use a lock it is discouraged to use them in a async environment. Instead, when the futures feature is enabled this library also exposes AsyncRuntime and AsyncContext which use a future aware lock.

§Converting Values

This library has multiple traits for converting to and from JavaScript. The IntoJs trait is used for taking Rust values and turning them into JavaScript values. The FromJs is for converting JavaScript values to Rust. Note that this trait does not perform automatic coercion but Coerced can be used to convert the values with coercion.

For values which represent the name of variables or indices, the trait IntoAtom is available to convert values to the representation QuickJS requires.

§Optional features

§Default

This crate can be customized via features. The following features are enabled by default but can be disabled when not needed:

  • classes enables support for ES6 classes. Any user-defined Rust type can be exported to JS as an ES6 class which can be derived and extended by JS.
  • properties enables support for object properties (Object.defineProperty).

§Advanced

The following features may be enabled to get an extra functionality:

  • allocator adds support for custom allocators for Runtime. The allocators should implements std::alloc::Allocator trait and can be plugged on Runtime creation via Runtime::new_with_alloc.

  • rust-alloc forces using Rust’s global allocator by default instead of libc’s one.

  • loader adds support for custom ES6 modules resolvers and loaders. The resolvers and loaders should implements Resolver and Loader traits respectively and can be plugged in already existing Runtime before loading modules via Runtime::set_loader. The resolvers and loaders can be easily combined via tuples. When the previous resolver or loader failed the next one will be applied.

  • dyn-load adds support for loadable native modules (so/dll/dylib).

  • array-buffer adds support for ArrayBuffer and TypedArray.

  • futures adds support for async Rust. When enabled the library exports AsyncRuntime and AsyncContext. These are the asynchronous variants of the normal runtime and context. In order to ensure that QuickJS is used properly the runtime is placed behind a lock. For the normal runtime this is a normal mutex. You should avoid blocking threads in asynchronous Rust so the async runtime uses a future aware mutex. In the async runtime Rust futures can be passed to JS as ES6 Promises and ES6 Promises can be given back as Rust futures.

  • macro enables some useful procedural macros which gets Rust/JS interop much easy. An attribute macros can be applied to functions, constants and modules. An derive macros can be used with structs and enums.

  • phf enables using Perfect Hash Function for builtin modules lookup

§Extra types

This crate has support for conversion of many Rust types like Option, Result, Vec and other collections. In addition an extra types support can be enabled via features:

§Bindings

The bindings are pre-generated for the following platforms:

  • Linux:
    • aarch64-unknown-linux-musl
    • i686-unknown-linux-gnu
    • x86_64-unknown-linux-gnu
    • x86_64-unknown-linux-musl
    • loongarch64-unknown-linux-gnu
    • loongarch64-unknown-linux-musl
  • macOS:
    • aarch64-apple-darwin
    • x86_64-apple-darwin
  • Windows:
    • i686-pc-windows-gnu
    • x86_64-pc-windows-gnu
    • i686-pc-windows-msvc
    • x86_64-pc-windows-msvc

To build the crate for any other target you must enable the bindgen feature.

§Experimental

  • parallel enables multithreading support.

Note that the experimental features which may not works as expected. Use it for your own risk.

§Debugging

QuickJS can be configured to output some info which can help debug. The following features enable that:

  • dump-bytecode
  • dump-gc
  • dump-gc-free
  • dump-free
  • dump-leaks
  • dump-mem
  • dump-objects
  • dump-atoms
  • dump-shapes
  • dump-module-resolve
  • dump-promise
  • dump-read-object

Modules§

allocator
Tools for using different allocators with QuickJS.
array
JavaScript array types.
atom
QuickJS atom functionality.
class
JavaScript classes defined from Rust.
context
JS Contexts related types.
convert
Utilities for converting to and from JavaScript values.
function
JavaScript function functionality
loaderloader
Loaders and resolvers for loading JS modules.
markers
Utility types and traits.
module
Types for loading and handling JS modules.
object
Module for types dealing with JS objects.
prelude
A group of often used types.
promise
Javascript promises and future integration.
qjs
Native low-level bindings
runtime
QuickJS runtime related types.

Macros§

async_withfutures
A macro for safely using an asynchronous context while capturing the environment.
embedmacro
A macro for embedding JavaScript code into a binary.
module_init
Helper macro to provide module init function. Use for exporting module definitions to be loaded as part of a dynamic library.

Structs§

Array
Rust representation of a JavaScript object optimized as an array.
ArrayBuffer
Rust representation of a JavaScript object of class ArrayBuffer.
AsyncContextfutures
An asynchronous single execution context with its own global variables and stack.
AsyncRuntimefutures
Asynchronous QuickJS runtime, entry point of the library.
Atom
A QuickJS Atom.
BigInt
Rust representation of a JavaScript big int.
CString
Rust representation of a JavaScript C string.
Class
A object which is instance of a Rust class.
Coerced
The wrapper for values to force coercion
Context
A single execution context with its own global variables and stack.
Ctx
Context in use, passed to Context::with.
Exception
A JavaScript instance of Error
Filter
The property filter
Function
A JavaScript function.
Module
A JavaScript module.
Null
The placeholder which treated as null value
Object
Rust representation of a JavaScript object.
Persistent
The wrapper for JS values to keep it from GC
Promise
A JavaScript promise.
Runtime
QuickJS runtime, entry point of the library.
String
Rust representation of a JavaScript string.
Symbol
Rust representation of a JavaScript symbol.
TypedArray
Rust representation of a JavaScript objects of TypedArray classes.
Undefined
The placeholder which treated as undefined value
Value
Any JavaScript value

Enums§

CaughtError
An error type containing possible thrown exception values.
Error
Error type of the library.
Type
The type of JavaScript value

Traits§

CatchResultExt
Extension trait to easily turn results with Error into results with CaughtError
FromAtom
Trait for converting values from atoms.
FromIteratorJs
The Rust’s FromIterator trait to use with Ctx
FromJs
For converting JavaScript values to Rust values
IntoAtom
Trait for converting values to atoms.
IntoJs
For converting Rust values to JavaScript values
IteratorJs
The Rust’s Iterator trait extension which works with Ctx
JsLifetime
The trait which signifies a type using the rquickjs 'js lifetime trick for maintaining safety around Javascript values.
ThrowResultExt
Extension trait to easily turn results with CaughtError into results with Error

Type Aliases§

CaughtResult
Result type containing an the JavaScript exception if there was one.
Result
Result type used throughout the library.

Attribute Macros§

classmacro
An attribute for implementing JsClass for a Rust type.
functionmacro
A attribute for implementing IntoJsFunc for a certain function.
methodsmacro
A attribute for implementing methods for a class.
modulemacro
An attribute which generates code for exporting a module to Rust.

Derive Macros§

JsLifetimemacro
A Macro for auto deriving the JsLifetime trait.