@ruby/wasm-wasi
TypeScript icon, indicating that this package has built-in type declarations

2.6.2 • Public • Published

@ruby/wasm-wasi

npm version

This package provides core APIs for Ruby on WebAssembly targeting WASI-compatible environments. WebAssembly binaries are distributed in version-specific packages.

See Cheat Sheet for how to use this package.

Ruby Version Support

Version Package
head @ruby/head-wasm-wasi
3.3 @ruby/3.3-wasm-wasi
3.2 @ruby/3.2-wasm-wasi

API

consolePrinter

Create a console printer that can be used as an overlay of WASI imports. See the example below for how to use it.

const imports = {
  wasi_snapshot_preview1: wasi.wasiImport,
};
const printer = consolePrinter();
printer.addToImports(imports);

const instance = await WebAssembly.instantiate(module, imports);
printer.setMemory(instance.exports.memory);

Note that the stdout and stderr functions are called with text, not bytes. This means that bytes written to stdout/stderr will be decoded as UTF-8 and then passed to the stdout/stderr functions every time a write occurs without buffering.

Parameters

  • $0 Object (optional, default {stdout:console.log,stderr:console.warn})

    • $0.stdout
    • $0.stderr
  • stdout A function that will be called when stdout is written to. Defaults to console.log.

  • stderr A function that will be called when stderr is written to. Defaults to console.warn.

Returns any An object that can be used as an overlay of WASI imports.

RubyVM

A Ruby VM instance

Examples

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 the Ruby VM with the given command line arguments

Parameters
  • args The command line arguments to pass to Ruby. Must be an array of strings starting with the Ruby program name. (optional, default ["ruby.wasm","-EUTF-8","-e_=0"])

setInstance

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

Parameters
  • 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.

addToImports

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

Parameters
  • imports The import object to add to the WebAssembly instance

printVersion

Print the Ruby version to stdout

eval

Runs a string of Ruby code from JavaScript

Parameters
  • code The Ruby code to run
Examples
vm.eval("puts 'hello world'");
const result = vm.eval("1 + 2");
console.log(result.toString()); // 3

Returns any the result of the last expression

evalAsync

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

Parameters
  • code The Ruby code to run
Examples
const text = await vm.evalAsync(`
  require 'js'
  response = JS.global.fetch('https://example.com').await
  response.text.await
`);
console.log(text.toString()); // <html>...</html>

Returns any a promise that resolves to the result of the last expression

wrap

Wrap a JavaScript value into a Ruby JS::Object

Parameters
  • value The value to convert to RbValue
Examples
const hash = vm.eval(`Hash.new`);
hash.call("store", vm.eval(`"key1"`), vm.wrap(new Object()));

Returns any the RbValue object representing the given JS value

RbValue

A RbValue is an object that represents a value in Ruby

call

Call a given method with given arguments

Parameters
  • callee name of the Ruby method to call
  • args ...any arguments to pass to the method. Must be an array of RbValue
Examples
const ary = vm.eval("[1, 2, 3]");
ary.call("push", vm.wrap(4));
console.log(ary.call("sample").toString());

Returns any The result of the method call as a new RbValue.

callAsync

Call a given method that may call JS::Object#await with given arguments

Parameters
  • callee name of the Ruby method to call
  • args ...any arguments to pass to the method. Must be an array of RbValue
Examples
const client = vm.eval(`
  require 'js'
  class HttpClient
    def get(url)
      JS.global.fetch(url).await
    end
  end
  HttpClient.new
`);
const response = await client.callAsync(
  "get",
  vm.eval(`"https://example.com"`),
);

Returns any A Promise that resolves to the result of the method call as a new RbValue.

toPrimitive

Parameters
  • hint Preferred type of the result primitive value. "number", "string", or "default".

toString

Returns a string representation of the value by calling to_s

toJS

Returns a JavaScript object representation of the value by calling to_js.

Returns null if the value is not convertible to a JavaScript object.

RbError

Extends Error

Error class thrown by Ruby execution

RbFatalError

Extends RbError

Error class thrown by Ruby execution when it is not possible to recover. This is usually caused when Ruby VM is in an inconsistent state.

Package Sidebar

Install

npm i @ruby/wasm-wasi

Weekly Downloads

3,278

Version

2.6.2

License

MIT

Unpacked Size

449 kB

Total Files

50

Last publish

Collaborators

  • kddeisz
  • mametter
  • hsbt
  • kateinoigakukun