Crate rquickjs

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:

• either adds FromJs/IntoJs implementations for Either

• indexmap adds FromJs/IntoJs implementations for IndexSet and IndexMap

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

• allocatorallocator
  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.
• ArrayBufferarray-buffer
  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.
• 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.
• TypedArrayarray-buffer
  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.