npm - @ruby/head-wasm-wasi - Versions diffs - 2.3.0-2023-11-29-b - Mend

@ruby/head-wasm-wasi 2.3.0-2023-11-29-b

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.md +336 -0
package/dist/LICENSE +21 -0
package/dist/NOTICE +1293 -0
package/dist/bindgen/rb-abi-guest.d.ts +140 -0
package/dist/bindgen/rb-js-abi-host.d.ts +53 -0
package/dist/browser.cjs.js +3248 -0
package/dist/browser.d.ts +10 -0
package/dist/browser.esm.js +3243 -0
package/dist/browser.script.cjs.js +3375 -0
package/dist/browser.script.d.ts +5 -0
package/dist/browser.script.esm.js +3373 -0
package/dist/browser.script.iife.js +4778 -0
package/dist/browser.script.umd.js +3381 -0
package/dist/browser.umd.js +3251 -0
package/dist/index.cjs.js +1195 -0
package/dist/index.d.ts +192 -0
package/dist/index.esm.js +1190 -0
package/dist/index.umd.js +1201 -0
package/dist/node.cjs.js +1212 -0
package/dist/node.d.ts +10 -0
package/dist/node.esm.js +1210 -0
package/dist/ruby+stdlib.wasm +0 -0
package/dist/ruby.debug+stdlib.wasm +0 -0
package/dist/ruby.wasm +0 -0
package/package.json +71 -0

package/README.md ADDED Viewed

@@ -0,0 +1,336 @@
+# @ruby/head-wasm-wasi
+WebAssembly port of CRuby with WASI.
+This package distributes the latest `master` branch of CRuby.
+## Installation
+For installing `@ruby/head-wasm-wasi` family, just run this command in your shell:
+```console
+$ npm install --save @ruby/head-wasm-wasi@latest
+# or if you want the nightly snapshot
+$ npm install --save @ruby/head-wasm-wasi@next
+# or you can specify the exact snapshot version
+$ npm install --save @ruby/head-wasm-wasi@2.3.0-2023-11-26-a
+```
+## Quick Start (for Node.js)
+See [the example project](https://github.com/ruby/ruby.wasm/tree/main/packages/npm-packages/ruby-wasm-wasi/example) for more details.
+```javascript
+import fs from "fs/promises";
+import { DefaultRubyVM } from "@ruby/wasm-wasi/dist/node.cjs.js";
+const main = async () => {
+  const binary = await fs.readFile(
+    //  Tips: Replace the binary with debug info if you want symbolicated stack trace.
+    //  (only nightly release for now)
+    //  "./node_modules/@ruby/head-wasm-wasi/dist/ruby.debug+stdlib.wasm"
+    "./node_modules/@ruby/head-wasm-wasi/dist/ruby.wasm"
+  );
+  const module = await WebAssembly.compile(binary);
+  const { vm } = await DefaultRubyVM(module);
+  vm.eval(`
+    luckiness = ["Lucky", "Unlucky"].sample
+    puts "You are #{luckiness}"
+  `);
+};
+main();
+```
+Then you can run the example project in your terminal:
+```console
+$ node --experimental-wasi-unstable-preview1 index.node.js
+```
+## Quick Start (for Browser)
+In browser, you need a WASI polyfill. See [the example project](https://github.com/ruby/ruby.wasm/tree/main/packages/npm-packages/ruby-wasm-wasi/example) for more details.
+```html
+<html>
+  <script src="https://cdn.jsdelivr.net/npm/@ruby/wasm-wasi@latest/dist/browser.umd.js"></script>
+  <script>
+    const { DefaultRubyVM } = window["ruby-wasm-wasi"];
+    const main = async () => {
+      // Fetch and instantiate WebAssembly binary
+      const response = await fetch(
+        //      Tips: Replace the binary with debug info if you want symbolicated stack trace.
+        //      (only nightly release for now)
+        //      "https://cdn.jsdelivr.net/npm/@ruby/head-wasm-wasi@next/dist/ruby.debug+stdlib.wasm"
+        "https://cdn.jsdelivr.net/npm/@ruby/head-wasm-wasi@latest/dist/ruby.wasm"
+      );
+      const buffer = await response.arrayBuffer();
+      const module = await WebAssembly.compile(buffer);
+      const { vm } = await DefaultRubyVM(module);
+      vm.printVersion();
+      vm.eval(`
+        require "js"
+        luckiness = ["Lucky", "Unlucky"].sample
+        JS::eval("document.body.innerText = '#{luckiness}'")
+      `);
+    };
+    main();
+  </script>
+  <body></body>
+</html>
+```
+## GC limitation with JavaScript interoperability
+Since JavaScript's GC system and Ruby's GC system are separated and not cooperative, they cannot collect cyclic references between JavaScript and Ruby objects.
+The following code will cause a memory leak:
+```javascript
+class JNode {
+  setRNode(rnode) {
+    this.rnode = rnode;
+  }
+}
+jnode = new JNode();
+rnode = vm.eval(`
+class RNode
+  def set_jnode(jnode)
+    @jnode = jnode
+  end
+end
+RNode.new
+`);
+rnode.call("set_jnode", vm.wrap(jnode));
+jnode.setRNode(rnode);
+```
+<!-- The APIs section was generated by `npx documentation readme ../ruby-wasm-wasi/dist/index.esm.js --section=APIs` -->
+## APIs
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+#### Table of Contents
+- [RubyVM](#rubyvm)
+  - [Examples](#examples)
+  - [initialize](#initialize)
+    - [Parameters](#parameters)
+  - [setInstance](#setinstance)
+    - [Parameters](#parameters-1)
+  - [addToImports](#addtoimports)
+    - [Parameters](#parameters-2)
+  - [printVersion](#printversion)
+  - [eval](#eval)
+    - [Parameters](#parameters-3)
+    - [Examples](#examples-1)
+  - [evalAsync](#evalasync)
+    - [Parameters](#parameters-4)
+    - [Examples](#examples-2)
+  - [wrap](#wrap)
+    - [Parameters](#parameters-5)
+    - [Examples](#examples-3)
+- [RbValue](#rbvalue)
+  - [call](#call)
+    - [Parameters](#parameters-6)
+    - [Examples](#examples-4)
+  - [toPrimitive](#toprimitive)
+    - [Parameters](#parameters-7)
+  - [toString](#tostring)
+  - [toJS](#tojs)
+- [RbError](#rberror)
+### 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","-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
+## Building the package from source
+The instructions for building a Ruby targeting WebAssembly are available [here](https://github.com/ruby/ruby.wasm#building-from-source).
+Then, you can run the following command in your shell:
+```console
+# Check the directory structure of your Ruby build
+$ tree -L 3 path/to/wasm32-unknown-wasi-full-js/
+path/to/wasm32-unknown-wasi-full-js/
+├── usr
+│   └── local
+│       ├── bin
+│       ├── include
+│       ├── lib
+│       └── share
+└── var
+    └── lib
+        └── gems
+$ ./build-package.sh path/to/wasm32-unknown-wasi-full-js/
+Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/intrinsics.js"
+Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-abi-guest.d.ts"
+Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-abi-guest.js"
+Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-js-abi-host.d.ts"
+Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-js-abi-host.js"
+src/index.ts → dist/index.umd.js, dist/index.esm.js, dist/index.cjs.js...
+created dist/index.umd.js, dist/index.esm.js, dist/index.cjs.js in 682ms
+```

package/dist/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2022 Yuta Saito
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.