@ruby/wasm-wasi 2.3.0-2023-12-03-a → 2.3.0-2023-12-05-a

package/README.md

@@ -1,8 +1,183 @@
 # @ruby/wasm-wasi
 
-This package is a template for each channel-specific package.
+[![npm version](https://badge.fury.io/js/@ruby%2Fwasm-wasi.svg)](https://www.npmjs.com/package/@ruby/wasm-wasi)
 
-| Channel | Package                                            |
+This package core API for Ruby on WebAssembly targeting WASI-compatible environments. WebAssembly binaries are distributed in version-specific packages.
+
+See [Cheat Sheet](https://github.com/ruby/ruby.wasm/blob/main/docs/cheat_sheet.md) for how to use this package.
+
+## Ruby Version Support
+
+| Version | Package                                            |
 | ------- | -------------------------------------------------- |
 | `head`  | [`@ruby/head-wasm-wasi`](./../ruby-head-wasm-wasi) |
 | `3.2`   | [`@ruby/3.2-wasm-wasi`](./../ruby-3.2-wasm-wasi)   |
+
+## API
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### RubyVM
+
+A Ruby VM instance
+
+#### Examples
+
+```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();
+```
+
+#### 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","--disable-gems","-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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+const ary = vm.eval("[1, 2, 3]");
+ary.call("push", 4);
+console.log(ary.call("sample").toString());
+```
+
+#### toPrimitive
+
+- **See**: <https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/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/dist/browser.script.umd.js

@@ -2969,12 +2969,14 @@
         wrap(value) {
             return this.transport.importJsValue(value, this);
         }
+        /** @private */
         privateObject() {
             return {
                 transport: this.transport,
                 exceptionFormatter: this.exceptionFormatter,
             };
         }
+        /** @private */
         rbValueOfPointer(pointer) {
             const abiValue = new RbAbiValue(pointer, this.guest);
             return new RbValue(abiValue, this, this.privateObject());
@@ -3099,8 +3101,27 @@
     class RbExceptionFormatter {
         constructor() {
             this.literalsCache = null;
+            this.isFormmatting = false;
         }
         format(error, vm, privateObject) {
+            // All Ruby exceptions raised during formatting exception message should
+            // be caught and return a fallback message.
+            // Therefore, we don't need to worry about infinite recursion here ideally
+            // but checking re-entrancy just in case.
+            class RbExceptionFormatterError extends Error {
+            }
+            if (this.isFormmatting) {
+                throw new RbExceptionFormatterError("Unexpected exception occurred during formatting exception message");
+            }
+            this.isFormmatting = true;
+            try {
+                return this._format(error, vm, privateObject);
+            }
+            finally {
+                this.isFormmatting = false;
+            }
+        }
+        _format(error, vm, privateObject) {
             const [zeroLiteral, oneLiteral, newLineLiteral] = (() => {
                 if (this.literalsCache == null) {
                     const zeroOneNewLine = [
@@ -3115,18 +3136,43 @@
                     return this.literalsCache;
                 }
             })();
-            const backtrace = error.call("backtrace");
+            let className;
+            let backtrace;
+            let message;
+            try {
+                className = error.call("class").toString();
+            }
+            catch (e) {
+                className = "unknown";
+            }
+            try {
+                message = error.toString();
+            }
+            catch (e) {
+                message = "unknown";
+            }
+            try {
+                backtrace = error.call("backtrace");
+            }
+            catch (e) {
+                return this.formatString(className, message);
+            }
             if (backtrace.call("nil?").toString() === "true") {
-                return this.formatString(error.call("class").toString(), error.toString());
+                return this.formatString(className, message);
+            }
+            try {
+                const firstLine = backtrace.call("at", zeroLiteral);
+                const restLines = backtrace
+                    .call("drop", oneLiteral)
+                    .call("join", newLineLiteral);
+                return this.formatString(className, message, [
+                    firstLine.toString(),
+                    restLines.toString(),
+                ]);
+            }
+            catch (e) {
+                return this.formatString(className, message);
             }
-            const firstLine = backtrace.call("at", zeroLiteral);
-            const restLines = backtrace
-                .call("drop", oneLiteral)
-                .call("join", newLineLiteral);
-            return this.formatString(error.call("class").toString(), error.toString(), [
-                firstLine.toString(),
-                restLines.toString(),
-            ]);
         }
         formatString(klass, message, backtrace) {
             if (backtrace) {

package/dist/browser.umd.js

@@ -2927,12 +2927,14 @@
       wrap(value) {
           return this.transport.importJsValue(value, this);
       }
+      /** @private */
       privateObject() {
           return {
               transport: this.transport,
               exceptionFormatter: this.exceptionFormatter,
           };
       }
+      /** @private */
       rbValueOfPointer(pointer) {
           const abiValue = new RbAbiValue(pointer, this.guest);
           return new RbValue(abiValue, this, this.privateObject());
@@ -3057,8 +3059,27 @@
   class RbExceptionFormatter {
       constructor() {
           this.literalsCache = null;
+          this.isFormmatting = false;
       }
       format(error, vm, privateObject) {
+          // All Ruby exceptions raised during formatting exception message should
+          // be caught and return a fallback message.
+          // Therefore, we don't need to worry about infinite recursion here ideally
+          // but checking re-entrancy just in case.
+          class RbExceptionFormatterError extends Error {
+          }
+          if (this.isFormmatting) {
+              throw new RbExceptionFormatterError("Unexpected exception occurred during formatting exception message");
+          }
+          this.isFormmatting = true;
+          try {
+              return this._format(error, vm, privateObject);
+          }
+          finally {
+              this.isFormmatting = false;
+          }
+      }
+      _format(error, vm, privateObject) {
           const [zeroLiteral, oneLiteral, newLineLiteral] = (() => {
               if (this.literalsCache == null) {
                   const zeroOneNewLine = [
@@ -3073,18 +3094,43 @@
                   return this.literalsCache;
               }
           })();
-          const backtrace = error.call("backtrace");
+          let className;
+          let backtrace;
+          let message;
+          try {
+              className = error.call("class").toString();
+          }
+          catch (e) {
+              className = "unknown";
+          }
+          try {
+              message = error.toString();
+          }
+          catch (e) {
+              message = "unknown";
+          }
+          try {
+              backtrace = error.call("backtrace");
+          }
+          catch (e) {
+              return this.formatString(className, message);
+          }
           if (backtrace.call("nil?").toString() === "true") {
-              return this.formatString(error.call("class").toString(), error.toString());
+              return this.formatString(className, message);
+          }
+          try {
+              const firstLine = backtrace.call("at", zeroLiteral);
+              const restLines = backtrace
+                  .call("drop", oneLiteral)
+                  .call("join", newLineLiteral);
+              return this.formatString(className, message, [
+                  firstLine.toString(),
+                  restLines.toString(),
+              ]);
+          }
+          catch (e) {
+              return this.formatString(className, message);
           }
-          const firstLine = backtrace.call("at", zeroLiteral);
-          const restLines = backtrace
-              .call("drop", oneLiteral)
-              .call("join", newLineLiteral);
-          return this.formatString(error.call("class").toString(), error.toString(), [
-              firstLine.toString(),
-              restLines.toString(),
-          ]);
       }
       formatString(klass, message, backtrace) {
           if (backtrace) {

package/dist/cjs/index.d.ts

@@ -89,7 +89,9 @@ export declare class RubyVM {
      * hash.call("store", vm.eval(`"key1"`), vm.wrap(new Object()));
      */
     wrap(value: any): RbValue;
+    /** @private */
     private privateObject;
+    /** @private */
     private rbValueOfPointer;
 }
 /**
@@ -167,7 +169,9 @@ type RubyVMPrivate = {
 };
 declare class RbExceptionFormatter {
     private literalsCache;
+    private isFormmatting;
     format(error: RbValue, vm: RubyVM, privateObject: RubyVMPrivate): string;
+    private _format;
     formatString(klass: string, message: string, backtrace?: [string, string]): string;
 }
 /**

package/dist/cjs/index.js

@@ -336,12 +336,14 @@ class RubyVM {
     wrap(value) {
         return this.transport.importJsValue(value, this);
     }
+    /** @private */
     privateObject() {
         return {
             transport: this.transport,
             exceptionFormatter: this.exceptionFormatter,
         };
     }
+    /** @private */
     rbValueOfPointer(pointer) {
         const abiValue = new RbAbi.RbAbiValue(pointer, this.guest);
         return new RbValue(abiValue, this, this.privateObject());
@@ -468,8 +470,27 @@ var ruby_tag_type;
 class RbExceptionFormatter {
     constructor() {
         this.literalsCache = null;
+        this.isFormmatting = false;
     }
     format(error, vm, privateObject) {
+        // All Ruby exceptions raised during formatting exception message should
+        // be caught and return a fallback message.
+        // Therefore, we don't need to worry about infinite recursion here ideally
+        // but checking re-entrancy just in case.
+        class RbExceptionFormatterError extends Error {
+        }
+        if (this.isFormmatting) {
+            throw new RbExceptionFormatterError("Unexpected exception occurred during formatting exception message");
+        }
+        this.isFormmatting = true;
+        try {
+            return this._format(error, vm, privateObject);
+        }
+        finally {
+            this.isFormmatting = false;
+        }
+    }
+    _format(error, vm, privateObject) {
         const [zeroLiteral, oneLiteral, newLineLiteral] = (() => {
             if (this.literalsCache == null) {
                 const zeroOneNewLine = [
@@ -484,18 +505,43 @@ class RbExceptionFormatter {
                 return this.literalsCache;
             }
         })();
-        const backtrace = error.call("backtrace");
+        let className;
+        let backtrace;
+        let message;
+        try {
+            className = error.call("class").toString();
+        }
+        catch (e) {
+            className = "unknown";
+        }
+        try {
+            message = error.toString();
+        }
+        catch (e) {
+            message = "unknown";
+        }
+        try {
+            backtrace = error.call("backtrace");
+        }
+        catch (e) {
+            return this.formatString(className, message);
+        }
         if (backtrace.call("nil?").toString() === "true") {
-            return this.formatString(error.call("class").toString(), error.toString());
+            return this.formatString(className, message);
+        }
+        try {
+            const firstLine = backtrace.call("at", zeroLiteral);
+            const restLines = backtrace
+                .call("drop", oneLiteral)
+                .call("join", newLineLiteral);
+            return this.formatString(className, message, [
+                firstLine.toString(),
+                restLines.toString(),
+            ]);
+        }
+        catch (e) {
+            return this.formatString(className, message);
         }
-        const firstLine = backtrace.call("at", zeroLiteral);
-        const restLines = backtrace
-            .call("drop", oneLiteral)
-            .call("join", newLineLiteral);
-        return this.formatString(error.call("class").toString(), error.toString(), [
-            firstLine.toString(),
-            restLines.toString(),
-        ]);
     }
     formatString(klass, message, backtrace) {
         if (backtrace) {

package/dist/esm/index.d.ts

@@ -89,7 +89,9 @@ export declare class RubyVM {
      * hash.call("store", vm.eval(`"key1"`), vm.wrap(new Object()));
      */
     wrap(value: any): RbValue;
+    /** @private */
     private privateObject;
+    /** @private */
     private rbValueOfPointer;
 }
 /**
@@ -167,7 +169,9 @@ type RubyVMPrivate = {
 };
 declare class RbExceptionFormatter {
     private literalsCache;
+    private isFormmatting;
     format(error: RbValue, vm: RubyVM, privateObject: RubyVMPrivate): string;
+    private _format;
     formatString(klass: string, message: string, backtrace?: [string, string]): string;
 }
 /**

package/dist/esm/index.js

@@ -332,12 +332,14 @@ export class RubyVM {
     wrap(value) {
         return this.transport.importJsValue(value, this);
     }
+    /** @private */
     privateObject() {
         return {
             transport: this.transport,
             exceptionFormatter: this.exceptionFormatter,
         };
     }
+    /** @private */
     rbValueOfPointer(pointer) {
         const abiValue = new RbAbi.RbAbiValue(pointer, this.guest);
         return new RbValue(abiValue, this, this.privateObject());
@@ -462,8 +464,27 @@ var ruby_tag_type;
 class RbExceptionFormatter {
     constructor() {
         this.literalsCache = null;
+        this.isFormmatting = false;
     }
     format(error, vm, privateObject) {
+        // All Ruby exceptions raised during formatting exception message should
+        // be caught and return a fallback message.
+        // Therefore, we don't need to worry about infinite recursion here ideally
+        // but checking re-entrancy just in case.
+        class RbExceptionFormatterError extends Error {
+        }
+        if (this.isFormmatting) {
+            throw new RbExceptionFormatterError("Unexpected exception occurred during formatting exception message");
+        }
+        this.isFormmatting = true;
+        try {
+            return this._format(error, vm, privateObject);
+        }
+        finally {
+            this.isFormmatting = false;
+        }
+    }
+    _format(error, vm, privateObject) {
         const [zeroLiteral, oneLiteral, newLineLiteral] = (() => {
             if (this.literalsCache == null) {
                 const zeroOneNewLine = [
@@ -478,18 +499,43 @@ class RbExceptionFormatter {
                 return this.literalsCache;
             }
         })();
-        const backtrace = error.call("backtrace");
+        let className;
+        let backtrace;
+        let message;
+        try {
+            className = error.call("class").toString();
+        }
+        catch (e) {
+            className = "unknown";
+        }
+        try {
+            message = error.toString();
+        }
+        catch (e) {
+            message = "unknown";
+        }
+        try {
+            backtrace = error.call("backtrace");
+        }
+        catch (e) {
+            return this.formatString(className, message);
+        }
         if (backtrace.call("nil?").toString() === "true") {
-            return this.formatString(error.call("class").toString(), error.toString());
+            return this.formatString(className, message);
+        }
+        try {
+            const firstLine = backtrace.call("at", zeroLiteral);
+            const restLines = backtrace
+                .call("drop", oneLiteral)
+                .call("join", newLineLiteral);
+            return this.formatString(className, message, [
+                firstLine.toString(),
+                restLines.toString(),
+            ]);
+        }
+        catch (e) {
+            return this.formatString(className, message);
         }
-        const firstLine = backtrace.call("at", zeroLiteral);
-        const restLines = backtrace
-            .call("drop", oneLiteral)
-            .call("join", newLineLiteral);
-        return this.formatString(error.call("class").toString(), error.toString(), [
-            firstLine.toString(),
-            restLines.toString(),
-        ]);
     }
     formatString(klass, message, backtrace) {
         if (backtrace) {

package/dist/index.umd.js

@@ -933,12 +933,14 @@
       wrap(value) {
           return this.transport.importJsValue(value, this);
       }
+      /** @private */
       privateObject() {
           return {
               transport: this.transport,
               exceptionFormatter: this.exceptionFormatter,
           };
       }
+      /** @private */
       rbValueOfPointer(pointer) {
           const abiValue = new RbAbiValue(pointer, this.guest);
           return new RbValue(abiValue, this, this.privateObject());
@@ -1063,8 +1065,27 @@
   class RbExceptionFormatter {
       constructor() {
           this.literalsCache = null;
+          this.isFormmatting = false;
       }
       format(error, vm, privateObject) {
+          // All Ruby exceptions raised during formatting exception message should
+          // be caught and return a fallback message.
+          // Therefore, we don't need to worry about infinite recursion here ideally
+          // but checking re-entrancy just in case.
+          class RbExceptionFormatterError extends Error {
+          }
+          if (this.isFormmatting) {
+              throw new RbExceptionFormatterError("Unexpected exception occurred during formatting exception message");
+          }
+          this.isFormmatting = true;
+          try {
+              return this._format(error, vm, privateObject);
+          }
+          finally {
+              this.isFormmatting = false;
+          }
+      }
+      _format(error, vm, privateObject) {
           const [zeroLiteral, oneLiteral, newLineLiteral] = (() => {
               if (this.literalsCache == null) {
                   const zeroOneNewLine = [
@@ -1079,18 +1100,43 @@
                   return this.literalsCache;
               }
           })();
-          const backtrace = error.call("backtrace");
+          let className;
+          let backtrace;
+          let message;
+          try {
+              className = error.call("class").toString();
+          }
+          catch (e) {
+              className = "unknown";
+          }
+          try {
+              message = error.toString();
+          }
+          catch (e) {
+              message = "unknown";
+          }
+          try {
+              backtrace = error.call("backtrace");
+          }
+          catch (e) {
+              return this.formatString(className, message);
+          }
           if (backtrace.call("nil?").toString() === "true") {
-              return this.formatString(error.call("class").toString(), error.toString());
+              return this.formatString(className, message);
+          }
+          try {
+              const firstLine = backtrace.call("at", zeroLiteral);
+              const restLines = backtrace
+                  .call("drop", oneLiteral)
+                  .call("join", newLineLiteral);
+              return this.formatString(className, message, [
+                  firstLine.toString(),
+                  restLines.toString(),
+              ]);
+          }
+          catch (e) {
+              return this.formatString(className, message);
           }
-          const firstLine = backtrace.call("at", zeroLiteral);
-          const restLines = backtrace
-              .call("drop", oneLiteral)
-              .call("join", newLineLiteral);
-          return this.formatString(error.call("class").toString(), error.toString(), [
-              firstLine.toString(),
-              restLines.toString(),
-          ]);
       }
       formatString(klass, message, backtrace) {
           if (backtrace) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruby/wasm-wasi",
-  "version": "2.3.0-2023-12-03-a",
+  "version": "2.3.0-2023-12-05-a",
   "description": "WebAssembly port of CRuby with WASI",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",