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 interperter 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 as 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 browser between frames of the same origin.

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 value to rust. Note that this trait does not automatic coercion but the Coerced can be used to convert the values with coercion.

For values which represent the name of variables or indecies the trait IntoAtom is available to convert values to the represention quickjs requires.

Optional features

Default

This crate can be customized via features. The following features is 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).
• exports adds an ability to read the module exports.

Advanced

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

• allocator adds support for custom allocators for Runtime. The allocators should implements 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).
• futures adds support for async Rust. When enabled the Rust futures can be passed to JS as ES6 Promises and ES6 Promises can be given back as Rust futures.
• tokio adds integration with tokio async runtime. The method Runtime::spawn_executor can be used with Tokio to spawn async executor.
• async-std adds integration with async_std runtime. The method Runtime::spawn_executor can be used with AsyncStd to spawn async executor.
• smol adds integrations with smol async runtime. The method Runtime::spawn_executor can be used with Smol to spawn async executor.
• 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.

Custom

To gets build faster the numbers of arguments which can be passed to and given by the functions is limited to 6. If you need more arguments you can enabled feature max-args-N where N is number from 7 to 16.

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 is pre-built for the following platforms:

• i686-unknown-linux-gnu, x86_64-unknown-linux-gnu
• x86_64-apple-darwin
• i686-pc-windows-gnu, x86_64-pc-windows-gnu, i686-pc-windows-msvc, x86_64-pc-windows-msvc

To build the crate for unsupported target you must enable 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 enables 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

intrinsic	A marker types for intrinsic
qjs	Native low-level bindings

Macros

class_def	classes The macro to simplify class definition.
generic_loader	loader The helper macro to impl Loader traits for generic module kind.
module_init	Helper macro to provide module init function

Structs

Accessor	properties The accessor descriptor of a readonly property
Array	Rust representation of a javascript object optimized as an array.
Async	futures The wrapper for async functons
AsyncStd	async-std The async_std runtime for spawning executors.
Atom	An atom is value representing the name of a variable of an objects and can be created from any javascript value.
BuiltinLoader	loader The builtin script module loader
BuiltinResolver	loader The builtin module resolver
Bundle	The resolver and loader for bundles of compiled modules
Class	classes The class object interface
ClassId	classes The type of identifier of class
Coerced	The wrapper for values to force coercion
Compile	loader Modules compiling data
Constructor	classes The wrapper for constructor function
Context	A single execution context with its own global variables and stack.
ContextBuilder	Used for building a Context with a specific set of intrinsics
Created	The marker for the module which is created but not loaded yet
Ctx	Context in use, passed to Context::with.
Evaluated	The marker for the module which is already loaded and evaluated
Executor	futures The async executor future
ExportEntriesIter	exports An iterator over the items exported out a module
ExportNamesIter	exports An iterator over the items exported out a module
FileResolver	loader The file module resolver
Filter	The property filter
Func	The wrapper for function to convert is into JS
Function	Rust representation of a javascript function.
Idle	The idle awaiting future
Loaded	The marker for the module which is loaded but not evaluated yet
MemoryUsage
Method	The wrapper for method functions
Module	Javascript module with certain exports and imports
ModuleLoader	loader The builtin native module loader
MutFn	The wrapper for mutable functions
Native	The marker for the module which is created using ModuleDef
NativeLoader	dyn-load The native module loader
Null	The placeholder which treated as null value
Object	Rust representation of a javascript object.
OnceFn	The wrapper for once functions
Opt	The wrapper to get optional argument from input
Persistent	The wrapper for JS values to keep it from GC
Promise	futures Future-aware promise
Promised	futures Wrapper for futures to convert to JS promises
Property	properties The data descriptor of a property
RefsMarker	classes The helper for QuickJS garbage collector which helps it find internal JS object references.
RegisteryKey	registery Key for a registery of a context.
Rest	The wrapper the rest arguments from input
Runtime	Quickjs runtime, entry point of the library.
RustAllocator	The allocator which uses Rust global allocator
Script	The marker for the module which is created from text source
ScriptLoader	loader The script module loader
Smol	smol and parallel The smol async runtime for spawning executors.
String	Rust representation of a javascript string.
Symbol	Rust representation of a javascript symbol.
This	The wrapper to get this from input
Tokio	tokio The tokio async runtime for spawning executors.
Undefined	The placeholder which treated as undefined value
Uninitialized	The placeholder which treated as uninitialized JS value
Value	Any javascript value
WithProto	classes The prototype setting wrapper

Enums

Error	Error type of the library.
Type	The type of value

Traits

Allocator	allocator The allocator interface
AsArguments	A helper trait to pass arguments on a function calls.
AsFunction	The trait to wrap rust function to JS directly
AsProperty	properties The property interface
ClassDef	classes The ES6 class definition trait
ExecutorSpawner	futures The trait to spawn execution of pending jobs on async runtime
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
HasByteCode	The module data which contains bytecode
HasRefs	classes The helper trait to mark internal JS value refs
IntoAtom	Trait for converting values to atoms.
IntoJs	For converting rust values to javascript values
Intrinsic	The internal trait to add JS builting
IteratorJs	The Rust's Iterator trait extension which works with Ctx
Loader	loader Module loader interface
ModuleDef	Module definition trait
MultiWith	A trait for using multiple contexts at the same time.
ObjectDef	The helper trait to define objects
Outlive	The trait to help break lifetime rules when JS objects leaves current context via Persistent wrapper.
ParallelSend
Resolver	loader Module resolver interface

Type Definitions

ModuleLoadFn	The raw module load function (js_module_init)
RawMemPtr	allocator Raw memory pointer
Result	Result type used throught the library.

Attribute Macros

bind	An attribute to generate bindings easy
embed	An attribute to convert scripts modules into builtins

Derive Macros

FromJs	A macro to derive FromJs for an arbitrary structured types
HasRefs	A macro to derive HasRefs
IntoJs	A macro to derive IntoJs for an arbitrary structured types
IntoJsByRef	A macro to derive IntoJs for an arbitrary structured types when it used by reference