Class RubyVM

A Ruby VM instance

See

RubyVM.instantiateComponent and RubyVM.instantiateModule to create a new instance

Essentials

instantiateModule instantiateComponent eval evalAsync

Low-level initialization

constructor initialize setInstance addToImports

Other

printVersion wrap

Essentials

StaticinstantiateModule

  • instantiateModule(
        options: RubyInitModuleOptions,
    ): Promise<{ vm: RubyVM; instance: Instance }>

    Instantiate a Ruby VM with the given WebAssembly Core module with WASI Preview 1 implementation.

    Parameters

    Returns Promise<{ vm: RubyVM; instance: Instance }>

    A promise that resolves to the Ruby VM instance and the WebAssembly instance

    Example

    import { WASI } from "@bjorn3/browser_wasi_shim";
    const wasip1 = new WASI([], [], []);
    const module = await WebAssembly.compile("./path/to/ruby.wasm");
    const { vm } = await RubyVM.instantiateModule({ module, wasip1 });

StaticinstantiateComponent

  • instantiateComponent(options: RubyInitComponentOptions): Promise<{ vm: RubyVM }>

    Instantiate a Ruby VM with the given WebAssembly component with WASI Preview 2 implementation.

    Parameters

    Returns Promise<{ vm: RubyVM }>

    A promise that resolves to the Ruby VM instance

    Example

    // First, you need to transpile the Ruby component to a JavaScript module using jco.
    // $ jco transpile --no-wasi-shim --instantiation --valid-lifting-optimization ./ruby.component.wasm -o ./component
    // Then, you can instantiate the Ruby VM with the component:

    import * as wasip2 from "@bytecodealliance/preview2-shim"
    import fs from "fs/promises";
    import path from "path";

    const { instantiate } = await import("./component/ruby.component.js");
    const getCoreModule = async (relativePath) => {
      const buffer = await fs.readFile(path.join("./component", relativePath));
      return WebAssembly.compile(buffer);
    }

    const { vm } = await RubyVM.instantiateComponent({
      instantiate, getCoreModule, wasip2,
    });

eval

  • eval(code: string): RbValue

    Runs a string of Ruby code from JavaScript

    Parameters

    • code: string

      The Ruby code to run

    Returns RbValue

    the result of the last expression

    Example

    vm.eval("puts 'hello world'");
    const result = vm.eval("1 + 2");
    console.log(result.toString()); // 3

evalAsync

  • evalAsync(code: string): Promise<RbValue>

    Runs a string of Ruby code with top-level JS::Object#await Returns a promise that resolves when execution completes.

    Parameters

    • code: string

      The Ruby code to run

    Returns Promise<RbValue>

    a promise that resolves to the result of the last expression

    Example

    const text = await vm.evalAsync(`
      require 'js'
      response = JS.global.fetch('https://example.com').await
      response.text.await
    `);
    console.log(text.toString()); // <html>...</html>

Low-level initialization

constructor

  • new RubyVM(): RubyVM

    Create a new Ruby VM instance with low-level initialization control.

    Returns RubyVM

    Example

    const wasi = new WASI();
    const vm = new RubyVM();
    const imports = {
      wasi_snapshot_preview1: wasi.wasiImport,
    };

    vm.addToImports(imports);

    const instance = await WebAssembly.instantiate(rubyModule, imports);
    await vm.setInstance(instance);
    wasi.initialize(instance);
    vm.initialize();

initialize

  • initialize(args?: string[]): void

    Initialize the Ruby VM with the given command line arguments

    Parameters

    • args: string[] = ...

      The command line arguments to pass to Ruby. Must be an array of strings starting with the Ruby program name.

    Returns void

setInstance

  • setInstance(instance: Instance): Promise<void>

    Set a given instance to interact JavaScript and Ruby's WebAssembly instance. This method must be called before calling Ruby API.

    Parameters

    • instance: Instance

      The WebAssembly instance to interact with. Must be instantiated from a Ruby built with JS extension, and built with Reactor ABI instead of command line.

    Returns Promise<void>

addToImports

  • addToImports(imports: Imports): void

    Add intrinsic import entries, which is necessary to interact JavaScript and Ruby's WebAssembly instance.

    Parameters

    • imports: Imports

      The import object to add to the WebAssembly instance

    Returns void

Other

printVersion

wrap

  • wrap(value: any): RbValue

    Wrap a JavaScript value into a Ruby JS::Object

    Parameters

    • value: any

      The value to convert to RbValue

    Returns RbValue

    the RbValue object representing the given JS value

    Example

    const hash = vm.eval(`Hash.new`)
    hash.call("store", vm.eval(`"key1"`), vm.wrap(new Object()));

Settings

Member Visibility

On This Page

Essentials
Low-level initialization
Other