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.
| Version | Package |
|---|---|
head |
@ruby/head-wasm-wasi |
3.3 |
@ruby/3.3-wasm-wasi |
3.2 |
@ruby/3.2-wasm-wasi |
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.
-
$0Object (optional, default{stdout:console.log,stderr:console.warn})-
$0.stdout -
$0.stderr
-
-
stdoutA function that will be called when stdout is written to. Defaults toconsole.log. -
stderrA function that will be called when stderr is written to. Defaults toconsole.warn.
Returns any An object that can be used as an overlay of WASI imports.
A Ruby VM instance
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 the Ruby VM with the given command line arguments
-
argsThe 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"])
Set a given instance to interact JavaScript and Ruby's WebAssembly instance. This method must be called before calling Ruby API.
-
instanceThe WebAssembly instance to interact with. Must be instantiated from a Ruby built with JS extension, and built with Reactor ABI instead of command line.
Add intrinsic import entries, which is necessary to interact JavaScript and Ruby's WebAssembly instance.
-
importsThe import object to add to the WebAssembly instance
Print the Ruby version to stdout
Runs a string of Ruby code from JavaScript
-
codeThe Ruby code to run
vm.eval("puts 'hello world'");
const result = vm.eval("1 + 2");
console.log(result.toString()); // 3Returns any the result of the last expression
Runs a string of Ruby code with top-level JS::Object#await
Returns a promise that resolves when execution completes.
-
codeThe Ruby code to run
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 a JavaScript value into a Ruby JS::Object
-
valueThe value to convert to RbValue
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
A RbValue is an object that represents a value in Ruby
Call a given method with given arguments
-
calleename of the Ruby method to call -
args...any arguments to pass to the method. Must be an array of RbValue
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.
Call a given method that may call JS::Object#await with given arguments
-
calleename of the Ruby method to call -
args...any arguments to pass to the method. Must be an array of RbValue
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.
- See: https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive
-
hintPreferred type of the result primitive value."number","string", or"default".
Returns a string representation of the value by calling to_s
Returns a JavaScript object representation of the value
by calling to_js.
Returns null if the value is not convertible to a JavaScript object.
Extends Error
Error class thrown by Ruby execution
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.