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 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).
  • array-buffer adds support for ArrayBuffer and TypedArray.
  • 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.
  • phf enables using Perfect Hash Function for builtin modules lookup

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:

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_defclasses

The macro to simplify class definition.

generic_loaderloader

The helper macro to impl Loader traits for generic module kind.

module_init

Helper macro to provide module init function

Structs

Accessorproperties

The accessor descriptor of a readonly property

Array

Rust representation of a javascript object optimized as an array.

ArrayBufferarray-buffer

Rust representation of a javascript object of class ArrayBuffer.

Asyncfutures

The wrapper for async functons

AsyncStdasync-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.

BuiltinLoaderloader

The builtin script module loader

BuiltinResolverloader

The builtin module resolver

Bundle

The resolver and loader for bundles of compiled modules

Classclasses

The class object interface

ClassIdclasses

The type of identifier of class

Coerced

The wrapper for values to force coercion

Compileloader

Modules compiling data

Constructorclasses

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

Executorfutures

The async executor future

ExportEntriesIterexports

An iterator over the items exported out a module

ExportNamesIterexports

An iterator over the items exported out a module

FileResolverloader

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

ModuleLoaderloader

The builtin native module loader

MutFn

The wrapper for mutable functions

Native

The marker for the module which is created using ModuleDef

NativeLoaderdyn-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

Promisefutures

Future-aware promise

Promisedfutures

Wrapper for futures to convert to JS promises

Propertyproperties

The data descriptor of a property

RefsMarkerclasses

The helper for QuickJS garbage collector which helps it find internal JS object references.

RegisteryKeyregistery

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

ScriptLoaderloader

The script module loader

Smolsmol 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

Tokiotokio

The tokio async runtime for spawning executors.

TypedArrayarray-buffer

Rust representation of a javascript objects of TypedArray classes.

Undefined

The placeholder which treated as undefined value

Uninitialized

The placeholder which treated as uninitialized JS value

Value

Any javascript value

WithProtoclasses

The prototype setting wrapper

Enums

Error

Error type of the library.

Type

The type of value

Traits

Allocatorallocator

The allocator interface

AsArguments

A helper trait to pass arguments on a function calls.

AsFunction

The trait to wrap rust function to JS directly

AsPropertyproperties

The property interface

ClassDefclasses

The ES6 class definition trait

ExecutorSpawnerfutures

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

HasRefsclasses

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

Loaderloader

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
Resolverloader

Module resolver interface

Type Definitions

ModuleLoadFn

The raw module load function (js_module_init)

RawMemPtrallocator

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