@ruby/wasm-wasi 2.6.2 → 2.7.0

package/dist/esm/vm.d.ts

@@ -2,39 +2,172 @@ import type { RubyJsJsRuntime } from "./bindgen/interfaces/ruby-js-js-runtime.js
 import type { RubyJsRubyRuntime } from "./bindgen/interfaces/ruby-js-ruby-runtime.js";
 import { JsAbiValue } from "./bindgen/legacy/rb-js-abi-host.js";
 import { Binding, RbAbiValue } from "./binding.js";
+/**
+ * A function type that instantiates a Ruby component
+ */
+export type RubyComponentInstantiator = ((getCoreModule: (path: string) => WebAssembly.Module, importObject: any, instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance | Promise<WebAssembly.Instance>) => Promise<({
+    rubyRuntime: typeof RubyJsRubyRuntime;
+})>);
+export type RubyInitComponentOptions = {
+    /**
+     * A lower-level instantiation function that instantiates the Ruby component with the given component
+     * that implements "ruby:js/js-runtime" WIT interface.
+     */
+    instantiate: (_: typeof RubyJsJsRuntime) => Promise<typeof RubyJsRubyRuntime>;
+    /**
+     * The arguments to pass to the Ruby VM. Note that the first argument must be the Ruby program name.
+     *
+     * @default ["ruby.wasm", "-EUTF-8", "-e_=0"]
+     */
+    args?: string[];
+} | {
+    /**
+     * An `instantiate` function generated by `@bytecodealliance/jco` that instantiates the Ruby component.
+     */
+    instantiate: RubyComponentInstantiator;
+    /**
+     * A function that returns a WebAssembly Core module within the Ruby component transpiled by `@bytecodealliance/jco`.
+     */
+    getCoreModule: (path: string) => Promise<WebAssembly.Module>;
+    /**
+     * An optional function used to instantiate a WebAssembly Core module
+     */
+    instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance | Promise<WebAssembly.Instance>;
+    /**
+     * WASI Preview 2 implementation, typically imported from `import * as wasip2 from "@bytecodealliance/preview2-shim"`
+     */
+    wasip2: any;
+    /**
+     * The arguments to pass to the Ruby VM. Note that the first argument must be the Ruby program name.
+     *
+     * @default ["ruby.wasm", "-EUTF-8", "-e_=0"]
+     */
+    args?: string[];
+};
+export type RubyInitModuleOptions = {
+    /**
+     * The WebAssembly module that contains the Ruby VM
+     */
+    module: WebAssembly.Module;
+    /**
+     * WASI Preview 1 implementation supporting reactor model ABI
+     */
+    wasip1: {
+        wasiImport: WebAssembly.ModuleImports;
+        initialize(instance: WebAssembly.Instance): void;
+    };
+    /**
+     * The arguments to pass to the Ruby VM. Note that the first argument must be the Ruby program name.
+     * @default ["ruby.wasm", "-EUTF-8", "-e_=0"]
+     */
+    args?: string[];
+    /**
+     * A hook to add additional imports to the WebAssembly instance
+     */
+    addToImports?: (imports: WebAssembly.Imports) => void;
+    /**
+     * A hook called with the WebAssembly memory instance just after the Ruby VM is instantiated
+     */
+    setMemory?: (memory: WebAssembly.Memory) => void;
+};
+export type RubyInitOptions = RubyInitComponentOptions | RubyInitModuleOptions;
 /**
  * A Ruby VM instance
- *
- * @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();
- *
+ * @see {@link RubyVM.instantiateComponent} and {@link RubyVM.instantiateModule} to create a new instance
+ * @category Essentials
  */
 export declare class RubyVM {
+    /**
+     * @private Only for internal use.
+     */
     guest: Binding;
     private instance;
     private transport;
     private exceptionFormatter;
     private interfaceState;
+    /**
+     * Instantiate a Ruby VM with the given WebAssembly Core module with WASI Preview 1 implementation.
+     *
+     * @param options The options to instantiate the Ruby VM
+     * @returns A promise that resolves to the Ruby VM instance and the WebAssembly instance
+     * @category Essentials
+     *
+     * @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 });
+     *
+     */
+    static instantiateModule(options: RubyInitModuleOptions): Promise<{
+        vm: RubyVM;
+        instance: WebAssembly.Instance;
+    }>;
+    /**
+     * Instantiate a Ruby VM with the given WebAssembly component with WASI Preview 2 implementation.
+     *
+     * @param options The options to instantiate the Ruby VM
+     * @returns A promise that resolves to the Ruby VM instance
+     * @category Essentials
+     *
+     * @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,
+     * });
+     *
+     */
+    static instantiateComponent(options: RubyInitComponentOptions): Promise<{
+        vm: RubyVM;
+    }>;
+    /**
+     * Create a new Ruby VM instance with low-level initialization control.
+     *
+     * @category Low-level initialization
+     * @example
+     *
+     * ```javascript
+     * 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();
+     * ```
+     *
+     */
+    constructor();
+    /**
+     * @private Only for internal use.
+     */
     constructor(binding?: Binding);
-    static _instantiate(initComponent: (_: typeof RubyJsJsRuntime) => Promise<typeof RubyJsRubyRuntime>, options: {
-        args?: string[];
-    }): Promise<RubyVM>;
+    private static _instantiate;
     /**
      * Initialize the Ruby VM with the given command line arguments
      * @param args The command line arguments to pass to Ruby. Must be
      * an array of strings starting with the Ruby program name.
+     * @category Low-level initialization
      */
     initialize(args?: string[]): void;
     /**
@@ -45,12 +178,14 @@ export declare class RubyVM {
      * @param 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.
+     * @category Low-level initialization
      */
     setInstance(instance: WebAssembly.Instance): Promise<void>;
     /**
      * Add intrinsic import entries, which is necessary to interact JavaScript
      * and Ruby's WebAssembly instance.
      * @param imports The import object to add to the WebAssembly instance
+     * @category Low-level initialization
      */
     addToImports(imports: WebAssembly.Imports): void;
     private throwProhibitRewindException;
@@ -63,6 +198,7 @@ export declare class RubyVM {
      * Runs a string of Ruby code from JavaScript
      * @param code The Ruby code to run
      * @returns the result of the last expression
+     * @category Essentials
      *
      * @example
      * vm.eval("puts 'hello world'");
@@ -76,6 +212,7 @@ export declare class RubyVM {
      * Returns a promise that resolves when execution completes.
      * @param code The Ruby code to run
      * @returns a promise that resolves to the result of the last expression
+     * @category Essentials
      *
      * @example
      * const text = await vm.evalAsync(`
@@ -131,6 +268,7 @@ declare class JsValueTransport {
 }
 /**
  * A RbValue is an object that represents a value in Ruby
+ * @category Essentials
  */
 export declare class RbValue {
     private inner;

package/dist/esm/vm.js

@@ -3,24 +3,111 @@ import { addRbJsAbiHostToImports, } from "./bindgen/legacy/rb-js-abi-host.js";
 import { ComponentBinding, LegacyBinding } from "./binding.js";
 /**
  * A Ruby VM instance
- *
- * @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();
- *
+ * @see {@link RubyVM.instantiateComponent} and {@link RubyVM.instantiateModule} to create a new instance
+ * @category Essentials
  */
 export class RubyVM {
+    /**
+     * Instantiate a Ruby VM with the given WebAssembly Core module with WASI Preview 1 implementation.
+     *
+     * @param options The options to instantiate the Ruby VM
+     * @returns A promise that resolves to the Ruby VM instance and the WebAssembly instance
+     * @category Essentials
+     *
+     * @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 });
+     *
+     */
+    static async instantiateModule(options) {
+        var _a, _b;
+        const { module, wasip1 } = options;
+        const vm = new RubyVM();
+        const imports = {
+            wasi_snapshot_preview1: wasip1.wasiImport,
+        };
+        vm.addToImports(imports);
+        (_a = options.addToImports) === null || _a === void 0 ? void 0 : _a.call(options, imports);
+        const instance = await WebAssembly.instantiate(module, imports);
+        await vm.setInstance(instance);
+        (_b = options.setMemory) === null || _b === void 0 ? void 0 : _b.call(options, instance.exports.memory);
+        wasip1.initialize(instance);
+        vm.initialize(options.args);
+        return { vm, instance };
+    }
+    /**
+     * Instantiate a Ruby VM with the given WebAssembly component with WASI Preview 2 implementation.
+     *
+     * @param options The options to instantiate the Ruby VM
+     * @returns A promise that resolves to the Ruby VM instance
+     * @category Essentials
+     *
+     * @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,
+     * });
+     *
+     */
+    static async instantiateComponent(options) {
+        let initComponent;
+        if ("getCoreModule" in options) {
+            // A convenience overload to instantiate with "instantiate" function generated by jco
+            initComponent = async (jsRuntime) => {
+                const { instantiate, getCoreModule, wasip2 } = options;
+                const { cli, clocks, filesystem, io, random, sockets, http } = wasip2;
+                const importObject = {
+                    "ruby:js/js-runtime": jsRuntime,
+                    "wasi:cli/environment": cli.environment,
+                    "wasi:cli/exit": cli.exit,
+                    "wasi:cli/stderr": cli.stderr,
+                    "wasi:cli/stdin": cli.stdin,
+                    "wasi:cli/stdout": cli.stdout,
+                    "wasi:cli/terminal-input": cli.terminalInput,
+                    "wasi:cli/terminal-output": cli.terminalOutput,
+                    "wasi:cli/terminal-stderr": cli.terminalStderr,
+                    "wasi:cli/terminal-stdin": cli.terminalStdin,
+                    "wasi:cli/terminal-stdout": cli.terminalStdout,
+                    "wasi:clocks/monotonic-clock": clocks.monotonicClock,
+                    "wasi:clocks/wall-clock": clocks.wallClock,
+                    "wasi:filesystem/preopens": filesystem.preopens,
+                    "wasi:filesystem/types": filesystem.types,
+                    "wasi:io/error": io.error,
+                    "wasi:io/poll": io.poll,
+                    "wasi:io/streams": io.streams,
+                    "wasi:random/random": random.random,
+                    "wasi:sockets/tcp": sockets.tcp,
+                    "wasi:http/types": http.types,
+                    "wasi:http/incoming-handler": http.incomingHandler,
+                    "wasi:http/outgoing-handler": http.outgoingHandler,
+                };
+                const component = await instantiate(getCoreModule, importObject, options.instantiateCore);
+                return component.rubyRuntime;
+            };
+        }
+        else {
+            initComponent = options.instantiate;
+        }
+        const vm = await this._instantiate({}, initComponent);
+        return { vm };
+    }
     constructor(binding) {
         this.instance = null;
         this.interfaceState = {
@@ -69,7 +156,7 @@ export class RubyVM {
         this.transport = new JsValueTransport();
         this.exceptionFormatter = new RbExceptionFormatter();
     }
-    static async _instantiate(initComponent, options) {
+    static async _instantiate(options, initComponent) {
         const binding = new ComponentBinding();
         const vm = new RubyVM(binding);
         class JsAbiValue {
@@ -97,14 +184,21 @@ export class RubyVM {
      * Initialize the Ruby VM with the given command line arguments
      * @param args The command line arguments to pass to Ruby. Must be
      * an array of strings starting with the Ruby program name.
+     * @category Low-level initialization
      */
     initialize(args = ["ruby.wasm", "-EUTF-8", "-e_=0"]) {
         const c_args = args.map((arg) => arg + "\0");
-        this.guest.rubyInit();
-        this.guest.rubySysinit(c_args);
-        this.guest.rubyOptions(c_args);
+        this.guest.rubyInit(c_args);
         try {
-            this.eval(`require "/bundle/setup"`);
+            this.eval(`
+        # Require Bundler standalone setup
+        if File.exist?("/bundle/bundler/setup.rb")
+          require "/bundle/bundler/setup.rb"
+        elsif File.exist?("/bundle/setup.rb")
+          # For non-CM builds, which doesn't use Bundler's standalone mode
+          require "/bundle/setup.rb"
+        end
+      `);
         }
         catch (e) {
             console.warn("Failed to load /bundle/setup", e);
@@ -118,6 +212,7 @@ export class RubyVM {
      * @param 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.
+     * @category Low-level initialization
      */
     async setInstance(instance) {
         this.instance = instance;
@@ -127,6 +222,7 @@ export class RubyVM {
      * Add intrinsic import entries, which is necessary to interact JavaScript
      * and Ruby's WebAssembly instance.
      * @param imports The import object to add to the WebAssembly instance
+     * @category Low-level initialization
      */
     addToImports(imports) {
         this.guest.addToImports(imports);
@@ -332,6 +428,7 @@ export class RubyVM {
      * Runs a string of Ruby code from JavaScript
      * @param code The Ruby code to run
      * @returns the result of the last expression
+     * @category Essentials
      *
      * @example
      * vm.eval("puts 'hello world'");
@@ -347,6 +444,7 @@ export class RubyVM {
      * Returns a promise that resolves when execution completes.
      * @param code The Ruby code to run
      * @returns a promise that resolves to the result of the last expression
+     * @category Essentials
      *
      * @example
      * const text = await vm.evalAsync(`
@@ -429,6 +527,7 @@ class JsValueTransport {
 }
 /**
  * A RbValue is an object that represents a value in Ruby
+ * @category Essentials
  */
 export class RbValue {
     /**