Struct rustyscript::Runtime

pub struct Runtime { /* private fields */ }

A runtime instance that can be used to execute JavaScript code and interact with it Most runtime functions have 3 variants - blocking, async, and immediate For example:

• call_function will block until the function is resolved and the event loop is empty
• call_function_async will return a future that resolves when the function is resolved and the event loop is empty
• call_function_immediate will return the result immediately, without resolving promises or running the event loop (See crate::js_value::Promise)

Note: For multithreaded applications, you may need to call init_platform before creating a Runtime (See [crate::init_platform)

Implementations

impl Runtime

pub fn new(options: RuntimeOptions) -> Result<Self, Error>

Creates a new instance of the runtime with the provided options.

Arguments

• options - A RuntimeOptions struct that specifies the configuration options for the runtime.

Returns

A Result containing either the initialized runtime instance on success (Ok) or an error on failure (Err).

Example

use rustyscript::{ json_args, Runtime, RuntimeOptions, Module };
use std::time::Duration;

// Creates a runtime that will attempt to run function load() on start
// And which will time-out after 50ms
let mut runtime = Runtime::new(RuntimeOptions {
    default_entrypoint: Some("load".to_string()),
    timeout: Duration::from_millis(50),
    ..Default::default()
})?;

let module = Module::new("test.js", "
    export const load = () => {
        return 'Hello World!';
    }
");

let module_handle = runtime.load_module(&module)?;
let value: String = runtime.call_entrypoint(&module_handle, json_args!())?;
assert_eq!("Hello World!", value);

Errors

Can fail if the tokio runtime cannot be created, Or if the deno runtime initialization fails (usually issues with extensions)

pub fn with_tokio_runtime( options: RuntimeOptions, tokio: Rc<Runtime>, ) -> Result<Self, Error>

Creates a new instance of the runtime with the provided options and a pre-configured tokio runtime. See Runtime::new for more information.

Errors

Can fail if the deno runtime initialization fails (usually issues with extensions)

pub fn deno_runtime(&mut self) -> &mut JsRuntime

Access the underlying deno runtime instance directly

pub fn tokio_runtime(&self) -> Rc<Runtime>

Access the underlying tokio runtime used for blocking operations

pub fn options(&self) -> &RuntimeOptions

Access the options used to create this runtime

pub async fn await_event_loop( &mut self, options: PollEventLoopOptions, ) -> Result<(), Error>

Run the JS event loop to completion Required when using the _immediate variants of functions

Arguments

• options - Options for the event loop polling, see deno_core::PollEventLoopOptions

Errors

Can fail if a runtime error occurs during the event loop’s execution

pub fn block_on_event_loop( &mut self, options: PollEventLoopOptions, ) -> Result<(), Error>

Run the JS event loop to completion Required when using the _immediate variants of functions

This is the blocking variant of Runtime::await_event_loop

Arguments

• options - Options for the event loop polling, see deno_core::PollEventLoopOptions

Errors

Can fail if a runtime error occurs during the event loop’s execution

pub fn arg<A>(value: A) -> Result<Value, Error>

where A: Serialize,

👎Deprecated since 0.6.0: No longer needed, pass values and tuples directly, or with json_args!()

Encode an argument as a json value for use as a function argument

use rustyscript::{ Runtime, RuntimeOptions, Module };
use serde::Serialize;
use std::time::Duration;

let module = Module::new("test.js", "
    function load(obj) {
        console.log(`Hello world: a=${obj.a}, b=${obj.b}`);
    }
    export default load;
");

#[derive(Serialize)]
struct MyStruct {a: usize, b: usize}

Runtime::execute_module(
    &module, vec![],
    Default::default(),
    &[
        Runtime::arg(MyStruct{a: 1, b: 2})?,
    ]
)?;

Deprecated

This function is deprecated in favor of passing values and tuples directly Or using the json_args! macro

Errors

This conversion can fail if A’s implementation of Serialize decides to fail, or if A contains a map with non-string keys

pub fn into_arg<A>(value: A) -> Value

where Value: From<A>,

👎Deprecated since 0.6.0: No longer needed, pass values and tuples directly

Encode a primitive as a json value for use as a function argument Only for types with Into<Value>. For other types, use Runtime::arg

use rustyscript::{ Runtime, RuntimeOptions, Module };
use std::time::Duration;

let module = Module::new("test.js", "
    function load(a, b) {
        console.log(`Hello world: a=${a}, b=${b}`);
    }
    rustyscript.register_entrypoint(load);
");

Runtime::execute_module(
    &module, vec![],
    Default::default(),
    &[
        Runtime::into_arg("test"),
        Runtime::into_arg(5),
    ]
)?;

pub fn take<T>(&mut self) -> Option<T>

where T: 'static,

Remove and return a value from the state, if one exists

use rustyscript::{ Runtime };

let mut runtime = Runtime::new(Default::default())?;
runtime.put("test".to_string())?;
let value: String = runtime.take().unwrap();
assert_eq!(value, "test");

pub fn put<T>(&mut self, value: T) -> Result<(), Error>

where T: 'static,

Add a value to the state Only one value of each type is stored - additional calls to put overwrite the old value

Errors

Can fail if the inner state cannot be borrowed mutably

use rustyscript::{ Runtime };

let mut runtime = Runtime::new(Default::default())?;
runtime.put("test".to_string())?;
let value: String = runtime.take().unwrap();
assert_eq!(value, "test");

pub fn register_function<F>( &mut self, name: &str, callback: F, ) -> Result<(), Error>

where F: RsFunction,

Register a rust function to be callable from JS

• The crate::sync_callback macro can be used to simplify this process

Errors

Since this function borrows the state, it can fail if the state cannot be borrowed mutably

use rustyscript::{ Runtime, Module, serde_json::Value };

let module = Module::new("test.js", " rustyscript.functions.foo(); ");
let mut runtime = Runtime::new(Default::default())?;
runtime.register_function("foo", |args| {
    if let Some(value) = args.get(0) {
        println!("called with: {}", value);
    }
    Ok(Value::Null)
})?;

pub fn register_async_function<F>( &mut self, name: &str, callback: F, ) -> Result<(), Error>

where F: RsAsyncFunction,

Register a non-blocking rust function to be callable from JS

• The crate::async_callback macro can be used to simplify this process

Errors

Since this function borrows the state, it can fail if the state cannot be borrowed mutably

use rustyscript::{ Runtime, Module, serde_json::Value, async_callback, Error };

let module = Module::new("test.js", " rustyscript.async_functions.add(1, 2); ");
let mut runtime = Runtime::new(Default::default())?;
runtime.register_async_function("add", async_callback!(
    |a: i64, b: i64| async move {
        Ok::<i64, Error>(a + b)
    }
))?;

pub fn eval<T>(&mut self, expr: &str) -> Result<T, Error>

where T: DeserializeOwned,

Evaluate a piece of non-ECMAScript-module JavaScript code The expression is evaluated in the global context, so changes persist

Asynchronous code is supported, partially

• Top-level await is not supported
• The event loop will be run to completion after the expression is evaluated
• Eval must be run inside a tokio runtime for some async operations

For proper async support, use one of:

• call_function_async
• call_stored_function_async
• load_module_async
• load_modules_async

Or any of the _immmediate variants, paired with crate::js_value::Promise

Arguments

• expr - A string representing the JavaScript expression to evaluate

Returns

A Result containing the deserialized result of the expression (T) or an error (Error) if the expression cannot be evaluated or if the result cannot be deserialized.

Errors

Can fail if the expression cannot be evaluated, or if the result cannot be deserialized into the requested type

Example

use rustyscript::{ Runtime, Error };

let mut runtime = Runtime::new(Default::default())?;
let value:
   usize = runtime.eval("2 + 2")?;
assert_eq!(4, value);

pub async fn call_stored_function_async<T>( &mut self, module_context: Option<&ModuleHandle>, function: &Function, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Calls a stored javascript function and deserializes its return value. Returns a future that resolves when:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

See Runtime::call_function for an example

Note that synchronous functions are run synchronously. Returned promises will be run asynchronously, however.

Arguments

• module_context - Optional handle to a module providing global context for the function
• function - A The function object
• args - The arguments to pass to the function

Returns

A Result containing the deserialized result of the function call (T) or an error (Error) if there are issues with calling the function, or if the result cannot be deserialized.

Errors

Can fail if there are issues with calling the function, or if the result cannot be deserialized into the requested type

pub fn call_stored_function<T>( &mut self, module_context: Option<&ModuleHandle>, function: &Function, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Calls a stored javascript function and deserializes its return value. Blocks until:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

See Runtime::call_function for an example

Arguments

• module_context - Optional handle to a module providing global context for the function
• function - A The function object
• args - The arguments to pass to the function

Returns

A Result containing the deserialized result of the function call (T) or an error (Error) if there are issues with calling the function, or if the result cannot be deserialized.

Errors

Can fail if there are issues with calling the function, or if the result cannot be deserialized into the requested type

pub fn call_stored_function_immediate<T>( &mut self, module_context: Option<&ModuleHandle>, function: &Function, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Calls a stored javascript function and deserializes its return value. Will not attempt to resolve promises, or run the event loop Promises can be returned by specifying the return type as crate::js_value::Promise The event loop should be run using Runtime::await_event_loop

See Runtime::call_function for an example

Arguments

• module_context - Optional handle to a module providing global context for the function
• function - A The function object
• args - The arguments to pass to the function

Returns

A Result containing the deserialized result of the function call (T) or an error (Error) if there are issues with calling the function, or if the result cannot be deserialized.

Errors

Can fail if there are issues with calling the function, or if the result cannot be deserialized into the requested type

pub async fn call_function_async<T>( &mut self, module_context: Option<&ModuleHandle>, name: &str, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Calls a javascript function within the Deno runtime by its name and deserializes its return value. Returns a future that resolves when:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

Note that synchronous functions are run synchronously. Returned promises will be run asynchronously, however.

See Runtime::call_function for an example

Arguments

• module_context - Optional handle to a module to search - if None, or if the search fails, the global context is used
• name - A string representing the name of the javascript function to call.
• args - The arguments to pass to the function

Returns

A Result containing the deserialized result of the function call (T) or an error (Error) if the function cannot be found, if there are issues with calling the function, or if the result cannot be deserialized.

Errors

Fails if the function cannot be found, if there are issues with calling the function, Or if the result cannot be deserialized into the requested type

pub fn call_function<T>( &mut self, module_context: Option<&ModuleHandle>, name: &str, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Calls a javascript function within the Deno runtime by its name and deserializes its return value. Blocks until:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

Arguments

• module_context - Optional handle to a module to search - if None, or if the search fails, the global context is used
• name - A string representing the name of the javascript function to call.
• args - The arguments to pass to the function

Returns

A Result containing the deserialized result of the function call (T) or an error (Error) if the function cannot be found, if there are issues with calling the function, or if the result cannot be deserialized.

Errors

Fails if the function cannot be found, if there are issues with calling the function, Or if the result cannot be deserialized into the requested type

Example

use rustyscript::{ json_args, Runtime, Module, Error };

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("/path/to/module.js", "export function f() { return 2; };");
let module = runtime.load_module(&module)?;
let value: usize = runtime.call_function(Some(&module), "f", json_args!())?;

pub fn call_function_immediate<T>( &mut self, module_context: Option<&ModuleHandle>, name: &str, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Calls a javascript function within the Deno runtime by its name and deserializes its return value. Will not attempt to resolve promises, or run the event loop Promises can be returned by specifying the return type as crate::js_value::Promise The event loop should be run using Runtime::await_event_loop

Arguments

• module_context - Optional handle to a module to search - if None, or if the search fails, the global context is used
• name - A string representing the name of the javascript function to call.
• args - The arguments to pass to the function

Returns

A Result containing the deserialized result of the function call (T) or an error (Error) if the function cannot be found, if there are issues with calling the function, or if the result cannot be deserialized.

Errors

Fails if the function cannot be found, if there are issues with calling the function, Or if the result cannot be deserialized into the requested type

Example

use rustyscript::{ json_args, Runtime, Module, Error };

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("/path/to/module.js", "export function f() { return 2; };");
let module = runtime.load_module(&module)?;
let value: usize = runtime.call_function_immediate(Some(&module), "f", json_args!())?;

pub fn get_value<T>( &mut self, module_context: Option<&ModuleHandle>, name: &str, ) -> Result<T, Error>

where T: DeserializeOwned,

Get a value from a runtime instance Blocks until:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

Arguments

• module_context - Optional handle to a module to search - if None, or if the search fails, the global context is used
• name - A string representing the name of the value to find

Returns

A Result containing the deserialized result or an error (Error) if the value cannot be found, Or if the result cannot be deserialized into the requested type

Errors

Can fail if the value cannot be found, or if the result cannot be deserialized.

Example

use rustyscript::{ Runtime, Module, Error };

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("/path/to/module.js", "globalThis.my_value = 2;");
let module = runtime.load_module(&module)?;
let value: usize = runtime.get_value(Some(&module), "my_value")?;

pub async fn get_value_async<T>( &mut self, module_context: Option<&ModuleHandle>, name: &str, ) -> Result<T, Error>

where T: DeserializeOwned,

Get a value from a runtime instance Returns a future that resolves when:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

See Runtime::get_value for an example

Arguments

• module_context - Optional handle to a module to search - if None, or if the search fails, the global context is used
• name - A string representing the name of the value to find

Returns

A Result containing the deserialized result or an error (Error) if the value cannot be found, Or if the result cannot be deserialized into the requested type

Errors

Can fail if the value cannot be found, or if the result cannot be deserialized.

pub fn get_value_immediate<T>( &mut self, module_context: Option<&ModuleHandle>, name: &str, ) -> Result<T, Error>

where T: DeserializeOwned,

Get a value from a runtime instance Will not attempt to resolve promises, or run the event loop Promises can be returned by specifying the return type as crate::js_value::Promise The event loop should be run using Runtime::await_event_loop

Arguments

• module_context - Optional handle to a module to search - if None, or if the search fails, the global context is used
• name - A string representing the name of the value to find

Returns

A Result containing the deserialized result or an error (Error) if the value cannot be found, Or if the result cannot be deserialized into the requested type

Errors

Can fail if the value cannot be found, or if the result cannot be deserialized.

Example

use rustyscript::{ Runtime, Module, Error };

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("/path/to/module.js", "globalThis.my_value = 2;");
let module = runtime.load_module(&module)?;
let value: usize = runtime.get_value_immediate(Some(&module), "my_value")?;

pub fn load_module(&mut self, module: &Module) -> Result<ModuleHandle, Error>

Executes the given module, and returns a handle allowing you to extract values And call functions

Blocks until the module has been executed

Arguments

• module - A Module object containing the module’s filename and contents.

Returns

A Result containing a handle for the loaded module or an error (Error) if there are issues with loading or executing the module

Errors

Can fail if the module cannot be loaded, or execution fails

Example

// Create a module with filename and contents
use rustyscript::{Runtime, Module, Error};

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("test.js", "export default () => 'test'");
runtime.load_module(&module);

pub async fn load_module_async( &mut self, module: &Module, ) -> Result<ModuleHandle, Error>

Executes the given module, and returns a handle allowing you to extract values And call functions

Returns a future that resolves to the handle for the loaded module

Arguments

• module - A Module object containing the module’s filename and contents.

Returns

A Result containing a handle for the loaded module or an error (Error) if there are issues with loading or executing the module

Errors

Can fail if the module cannot be loaded, or execution fails

See Runtime::load_module for an example

pub fn load_modules( &mut self, module: &Module, side_modules: Vec<&Module>, ) -> Result<ModuleHandle, Error>

Executes the given module, and returns a handle allowing you to extract values And call functions.

Blocks until the module has been executed

This will load ‘module’ as the main module, and the others as side-modules. Only one main module can be loaded per runtime

Arguments

• module - A Module object containing the module’s filename and contents.
• side_modules - A set of additional modules to be loaded into memory for use

Returns

A Result containing a handle for the loaded module or an error (Error) if there are issues with loading or executing the module

Errors

Can fail if the module cannot be loaded, or execution fails

Example

// Create a module with filename and contents
use rustyscript::{Runtime, Module, Error};

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("test.js", "export default () => 'test'");
runtime.load_modules(&module, vec![]);

pub async fn load_modules_async( &mut self, module: &Module, side_modules: Vec<&Module>, ) -> Result<ModuleHandle, Error>

Executes the given module, and returns a handle allowing you to extract values And call functions.

Returns a future that resolves to the handle for the loaded module

This will load ‘module’ as the main module, and the others as side-modules. Only one main module can be loaded per runtime

See Runtime::load_modules for an example

Arguments

• module - A Module object containing the module’s filename and contents.
• side_modules - A set of additional modules to be loaded into memory for use

Returns

A Result containing a handle for the loaded main module, or the last side-module or an error (Error) if there are issues with loading or executing the modules

Errors

Can fail if the modules cannot be loaded, or execution fails

pub fn call_entrypoint<T>( &mut self, module_context: &ModuleHandle, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Executes the entrypoint function of a module within the Deno runtime. Blocks until:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

Arguments

• module_context - A handle returned by loading a module into the runtime

Returns

A Result containing the deserialized result of the entrypoint execution (T) if successful, or an error (Error) if the entrypoint is missing, the execution fails, or the result cannot be deserialized.

Errors

Can fail if the module cannot be loaded, if the entrypoint is missing, if the execution fails, Or if the result cannot be deserialized into the requested type

Example

use rustyscript::{json_args, Runtime, Module, Error};

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("test.js", "export default () => 'test'");
let module = runtime.load_module(&module)?;

// Run the entrypoint and handle the result
let value: String = runtime.call_entrypoint(&module, json_args!())?;

pub async fn call_entrypoint_async<T>( &mut self, module_context: &ModuleHandle, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Executes the entrypoint function of a module within the Deno runtime. Returns a future that resolves when:

• The event loop is resolved, and
• If the value is a promise, the promise is resolved

Note that synchronous functions are run synchronously. Returned promises will be run asynchronously, however.

See Runtime::call_entrypoint for an example

Arguments

• module_context - A handle returned by loading a module into the runtime

Returns

A Result containing the deserialized result of the entrypoint execution (T) if successful, or an error (Error) if the entrypoint is missing, the execution fails, or the result cannot be deserialized.

Errors

Can fail if the module cannot be loaded, if the entrypoint is missing, if the execution fails, Or if the result cannot be deserialized into the requested type

pub fn call_entrypoint_immediate<T>( &mut self, module_context: &ModuleHandle, args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Executes the entrypoint function of a module within the Deno runtime. Will not attempt to resolve promises, or run the event loop Promises can be returned by specifying the return type as crate::js_value::Promise The event loop should be run using Runtime::await_event_loop

Arguments

• module_context - A handle returned by loading a module into the runtime

Returns

A Result containing the deserialized result of the entrypoint execution (T) if successful, or an error (Error) if the entrypoint is missing, the execution fails, or the result cannot be deserialized.

Errors

Can fail if the module cannot be loaded, if the entrypoint is missing, if the execution fails, Or if the result cannot be deserialized into the requested type

Example

use rustyscript::{json_args, Runtime, Module, Error};

let mut runtime = Runtime::new(Default::default())?;
let module = Module::new("test.js", "export default () => 'test'");
let module = runtime.load_module(&module)?;

// Run the entrypoint and handle the result
let value: String = runtime.call_entrypoint_immediate(&module, json_args!())?;

pub fn execute_module<T>( module: &Module, side_modules: Vec<&Module>, runtime_options: RuntimeOptions, entrypoint_args: &impl Serialize, ) -> Result<T, Error>

where T: DeserializeOwned,

Loads a module into a new runtime, executes the entry function and returns the result of the module’s execution, deserialized into the specified Rust type (T).

Arguments

• module - A Module object containing the module’s filename and contents.
• side_modules - A set of additional modules to be loaded into memory for use
• runtime_options - Options for the creation of the runtime
• entrypoint_args - Arguments to pass to the entrypoint function

Returns

A Result containing the deserialized result of the entrypoint execution (T) if successful, or an error (Error) if the entrypoint is missing, the execution fails, or the result cannot be deserialized.

Errors

Can fail if the module cannot be loaded, if the entrypoint is missing, if the execution fails, Or if the result cannot be deserialized into the requested type

Example

// Create a module with filename and contents
use rustyscript::{json_args, Runtime, Module, Error};

let module = Module::new("test.js", "export default () => 2");
let value: usize = Runtime::execute_module(&module, vec![], Default::default(), json_args!())?;