Struct rustyscript::Runtime

pub struct Runtime(/* private fields */);

Represents a configured runtime ready to run modules

Implementations

impl Runtime

pub const EMPTY_ARGS: &'static FunctionArguments = _

The lack of any arguments - used to simplify calling functions Prevents you from needing to specify the type using ::<serde_json::Value>

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);

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

Access the underlying deno runtime instance directly

pub fn options(&self) -> &RuntimeOptions

Access the options used to create this runtime

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

where A: Serialize,

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}`);
    }
    rustyscript.register_entrypoint(load);
");

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

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

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

where Value: From<A>,

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

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( &mut self, name: &str, callback: RsFunction, ) -> Result<(), Error>

Register a rust function to be callable from JS

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, _state| {
    if let Some(value) = args.get(0) {
        println!("called with: {}", value);
    }
    Ok(Value::Null)
})?;

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

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.

Example

use rustyscript::{ Runtime, Error };

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

pub fn call_stored_function<T>( &mut self, module_context: &ModuleHandle, function: &JsFunction<'_>, args: &FunctionArguments, ) -> Result<T, Error>

where T: DeserializeOwned,

Calls a stored javascript function and deserializes its return value.

Arguments

• function - A The function object

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.

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

where T: DeserializeOwned,

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

Arguments

• name - A string representing the name of the javascript function to call.

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.

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(&module, "f", json_args!())?;

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

where T: DeserializeOwned,

Get a value from a runtime instance

Arguments

• 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, if there are issues with, 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(&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

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 modules, executing the module, or if the result cannot be deserialized.

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", "rustyscript.register_entrypoint(() => 'test')");
runtime.load_module(&module);

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.

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 modules, executing the module, or if the result cannot be deserialized.

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", "rustyscript.register_entrypoint(() => 'test')");
runtime.load_modules(&module, vec![]);

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

where T: DeserializeOwned,

Executes the entrypoint function of a module within the Deno runtime.

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.

Example

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

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

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

pub fn execute_module<T>( module: &Module, side_modules: Vec<&Module>, runtime_options: RuntimeOptions, entrypoint_args: &FunctionArguments, ) -> 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.

Example

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

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