jsg 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e678932e88c5f4332664d8f94c855c6cf5c37eccb4c0ff55779061d20ee7a8f
-  data.tar.gz: eded22db06e19449e076d82332e9aa00db620fff95fd6c69d1b3a6710815eb2c
+  metadata.gz: 656528ab1a482268d018a12df7b3cd5fda4d74f08368926f7fb665a4f5f3621f
+  data.tar.gz: a63fec4f4c89edc7e116aa878781aa9235bcdf17967f12508ccea62ab5bcef19
 SHA512:
-  metadata.gz: e7f34af3bdec9dd82ed50497bbe141bfd95c2bfc8dd0417fa9312a2893ce1547ddeb438d806070f151693aef6695bfd8fd79571fc010edcdf66dd72b84a8b742
-  data.tar.gz: 1cb61dbdeb8b53b6697e3521b86ef0db32e3050d66ac69fc658a7a22601cc3a6c62fe08c402e205a7378546f9f8761cfdd6914063b93881f3c45204badab815c
+  metadata.gz: e231cea6d1794b20a9bffc034ac38020968288177af7c49f973b7901deb4a02cf4c86fa7ec8655e5ac7c078293c9b986d9cb8fdfd712d199ed349b80ca74ef80
+  data.tar.gz: cfc908766616ad9b18026b20369caf5d01e79e7d2bde8463d8af9f619a3c1b86c5d686476b007759c15fa9dfc4dfa74e0ee375dac929bff53e9fd123e0c472ed

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-29
+
+- First release published from GitHub Actions with RubyGems trusted publishing (`.github/workflows/release.yml`, triggered by `v*` tags).
+- CI runs the ruby.wasm tests on Node.js 24. Node 22's WASI crashes once Ruby loads files from a mounted directory.
+
+## [0.2.0] - 2026-09-29
+
+- Fix `require "jsg"`: the library moved from the gem root to `lib/jsg.rb`, so it is on the load path.
+- Fix the syntax additions never running: `JSGPatch` is now prepended to `JS::Object` instead of included. The js gem defines `method_missing`, `respond_to_missing?`, `to_a` and `nil?` on `JS::Object` itself, which shadowed the included module. With js 2.10 (where `JS::Object` is a `BasicObject`) 0.1.x also failed to load with `uninitialized constant JS::Object::JSGPatch`.
+- Rewrite the helpers so they no longer call themselves recursively once active (`to_a`, `isJSArray`, `__props`).
+- `?` methods use JavaScript truthiness. `undefined?` is only true for `undefined`. `each` also iterates array-like objects such as a `NodeList`.
+- A capitalized name without arguments returns the constructor (`JS.global.URLSearchParams.new(...)`). Other JavaScript errors are no longer swallowed.
+- Add `tap` to `JS::Object` again (lost when js 2.10 made it a `BasicObject`), so `createElement("h2").tap { ... }` works.
+- Remove the `==` override. The js gem already compares with `true`, `false` and `nil`.
+- The template's index.html loads `src/main.rb` with `JS::RequireRemote` instead of overriding `require_relative` globally. `rbwasm build` never packed `src/` into the wasm file.
+- Update the template to ruby.wasm 2.10.1 (browser script, `js` and `ruby_wasm` gems). `jsg build` builds Ruby 4.0 with `bundle exec rbwasm`.
+- `jsg new` reports errors instead of silently ignoring them, and gets a `--skip-build` option. `jsg server` accepts a port and explains how to install WEBrick when it is missing. New `jsg version`.
+- The gem depends on `js` and `ruby_wasm` `~> 2.10` on every platform, and no longer on `erb` (a default gem).
+- Add a README and tests (rspec for the command line tool, ruby.wasm on Node.js for `lib/jsg.rb`).
+
+## [0.1.2] - 2024-05-18
+
+- Don't require
+
 ## [0.1.0] - 2024-05-09
 
 - Initial release

data/README.md

@@ -1,34 +1,119 @@
-# Jsg
+# jsg
 
-TODO: Delete this and the text below, and describe your gem
+jsg helps you set up [ruby.wasm](https://github.com/ruby/ruby.wasm) browser projects, and it adds a friendlier syntax on top of the [js gem](https://rubygems.org/gems/js).
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/jsg`. To experiment with that code, run `bin/console` for an interactive prompt.
+It has two parts:
+
+- the `jsg` command, which creates, builds and serves a project
+- `require "jsg"` inside the browser, which lets you write `document.title` instead of `JS.global[:document][:title]`
+
+jsg 0.2 targets ruby.wasm 2.10.1 and builds Ruby 4.0 for the browser.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```bash
+gem install jsg
+```
+
+This also installs `ruby_wasm`, which provides the `rbwasm` build tool. `jsg server` needs WEBrick, which is not a default gem anymore:
+
+```bash
+gem install webrick
+```
+
+## Creating a project
+
+```bash
+jsg new myapp   # copy the template into ./myapp, then run jsg build
+cd myapp
+jsg server      # serve the folder on http://localhost:8080 (or the next free port)
+```
+
+`jsg new myapp --skip-build` only copies the template. The project contains:
+
+- `index.html`, with a `<script type="text/ruby">` block that requires jsg and loads `src/main.rb`
+- `src/main.rb`, the place for your code
+- `assets/browser.script.iife.js`, ruby.wasm's browser script, set up to load `assets/ruby-app.wasm`
+- `Gemfile` with `ruby_wasm`, `js` and `jsg`
+- a `.gitignore` for the `build/` and `rubies/` folders
 
-Install the gem and add to the application's Gemfile by executing:
+`jsg build` runs `bundle install` and then `bundle exec rbwasm build --ruby-version 4.0 -o assets/ruby-app.wasm`. The wasm file contains Ruby and the gems from the Gemfile, not your own files: `index.html` fetches `src/main.rb` from the web server with `JS::RequireRemote`, so a page reload picks up your changes. Run `jsg build` again only when you change the Gemfile. The first build compiles CRuby and the gems for WebAssembly and takes a while. Later builds reuse the `build/` and `rubies/` folders.
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## Syntax
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+```ruby
+require "jsg"
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+d = JSG.document
+d.getElementById("spinner").style.display = "none"
 
-## Usage
+d.createElement("h2").tap do |h2|
+  h2.innerText = "Examples"
+  d.body.appendChild(h2)
+end
+```
 
-TODO: Write usage instructions here
+What `require "jsg"` adds to `JS::Object`:
+
+| You write | Result |
+| --- | --- |
+| `element.innerText` | property value, converted with `to_rb` |
+| `element.innerText = "Hi"` | sets the property (the value is converted with `to_js`) |
+| `document.getElementById("x")` | calls the method, result converted with `to_rb` |
+| `element.hidden?`, `list.includes?(3)` | `true`/`false`, using JavaScript truthiness |
+| `JS.global.URLSearchParams.new("a=1")` | a capitalized name without arguments returns the constructor |
+| `obj.missing` | a property that is `undefined` raises `NoMethodError` |
+
+`to_rb` converts JavaScript values to Ruby:
+
+| JavaScript | Ruby |
+| --- | --- |
+| number | `Float` (`3` becomes `3.0`) |
+| string | `String` |
+| boolean | `true` / `false` |
+| bigint | `Integer` |
+| symbol | `Symbol` |
+| `null` | `nil` |
+| Array | `Array`, elements converted too |
+| anything else, including `undefined` | stays a `JS::Object` |
+
+More helpers:
+
+```ruby
+JSG.window        # JS.global, also JSG.w
+JSG.document      # JS.global[:document], also JSG.d
+JSG.q("p")        # document.querySelectorAll("p")
+JSG.global        # anything else is forwarded to the JS module
+
+list = JSG.q("li")
+list.to_a         # array-like objects (NodeList, ...) to a Ruby Array
+list.each { |li| li.classList.add("done") }
+obj.to_a(convertTypes: false) # keep the elements as JS::Object
+
+value.nil?        # true for null and undefined
+value.undefined?  # true only for undefined
+value.typeof?(:string)
+el.tap { |e| ... } # like Kernel#tap (JS::Object is a BasicObject since js 2.10)
+value == true     # comparing with true, false and nil works (JavaScript's == rules)
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+bin/setup
+bundle exec rake    # rspec, the ruby.wasm tests and rubocop
+```
+
+To release a new version, update `lib/jsg/version.rb` and `CHANGELOG.md`, commit, and push a matching tag:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+git tag v0.2.1
+git push origin v0.2.1
+```
 
-## Contributing
+The `Release` workflow runs the tests and publishes the gem to RubyGems.org with trusted publishing, so no API key is stored in GitHub.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jsg.
+The specs in `spec/` test the command line tool on your normal Ruby. `lib/jsg.rb` needs the js gem, which only works inside ruby.wasm, so its tests in `test/wasm` run the prebuilt ruby.wasm on Node.js (`bundle exec rake test:wasm`, needs Node.js 24 or newer and npm).
 
 ## License
 

data/exe/jsg

@@ -1,98 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-#require "jsg"
+require_relative "../lib/jsg/cli"
 
-require "erb"
-require "fileutils"
-
-module JSG
-  # create a new project at project_name
-  def self.create_project(project_name)
-    base_path = File.expand_path("../template", __dir__)
-    destination = File.join(Dir.pwd, project_name)
-
-    if Dir.exist?(destination)
-      raise "Sorry #{destination} already exists, please choose other name or delete the folder"
-    end
-    FileUtils.mkdir_p(destination)
-
-    Dir.glob("#{base_path}/**/*").each do |file_path|
-      next if File.directory?(file_path)
-
-      
-      content = File.read(file_path)
-      result = if file_path.end_with?(".erb")
-                 template = ERB.new(content)
-                 template.result(binding)
-               else
-                 content
-               end
-
-      relative_path = file_path.sub("#{base_path}/", "").gsub(/\.erb$/, "")
-      new_file_path = File.join(destination, relative_path)
-
-      p new_file_path
-
-      new_file_path.gsub!("gitignore", ".gitignore")
-      FileUtils.mkdir_p(File.dirname(new_file_path))
-      File.write(new_file_path, result)
-    end
-  end
-
-  def self.build
-    system("bundle install")
-    system("rbwasm build -o assets/ruby-app.wasm")
-  end
-
-  def self.server
-    require 'webrick'
-
-    port = 8080
-    
-    loop do
-      begin
-        server = WEBrick::HTTPServer.new(BindAddres: '0.0.0.0', :Port => port, :DocumentRoot => Dir.pwd)
-        trap('INT') { server.shutdown }
-        puts "Serving at port http://0.0.0.0.:#{port}"
-        server.start
-        break
-      rescue Errno::EADDRINUSE
-        port += 1
-      end
-    end
-    
-  end
-end
-
-command = ARGV.shift # First argument is the command
-
-case command
-when "new"
-  #options = parse_options
-  project_name = ARGV.shift # Next argument should be the project name
-
-  if project_name
-    begin
-      JSG.create_project(project_name)
-    # check if we have an internet connection or think about caching this somewhere. 
-      Dir.chdir(project_name) do
-        JSG.build
-      end
-    rescue StandardError => e 
-    end
-  else
-    puts "Error: Project name is required."
-    #puts "For help, run: jsg new --help"
-    exit 1
-  end
-when "build"
-  JSG.build
-when "serve", "server"
-  JSG.server
-else
-  puts "Unknown command: #{command}"
-  puts "Use 'jsg new projectname' for creating new projects."
-  puts "Use 'jsg build to build the .wasm file of the project."
-  puts "Use 'jsg server to start a server."
-  exit 1
-end
+exit JSG::CLI.run(ARGV.dup)

data/lib/jsg/cli.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require_relative "version"
+
+module JSG
+  class Error < StandardError; end
+
+  # The `jsg` command line tool. Runs on the host, not inside ruby.wasm,
+  # so it must not require "js".
+  module CLI
+    TEMPLATE_PATH = File.expand_path("../../template", __dir__)
+    # Ruby version that `jsg build` compiles to WebAssembly. Matches the
+    # @ruby/4.0-wasm-wasi browser script in template/assets.
+    WASM_RUBY_VERSION = "4.0"
+
+    USAGE = <<~TEXT
+      Usage:
+        jsg new PROJECT [--skip-build]  create a new project (and build it)
+        jsg build                       bundle install, then build assets/ruby-app.wasm (Ruby 4.0)
+        jsg server [PORT]               serve the current directory (default port 8080)
+        jsg version                     print the jsg version
+    TEXT
+
+    module_function
+
+    def run(argv)
+      command = argv.shift
+      case command
+      when "new"
+        skip_build = !argv.delete("--skip-build").nil?
+        project_name = argv.shift
+        return usage_error("Error: Project name is required.") unless project_name
+
+        destination = create_project(project_name)
+        Dir.chdir(destination) { build } unless skip_build
+      when "build"
+        build
+      when "serve", "server"
+        server(port: Integer(argv.shift || 8080))
+      when "version", "-v", "--version"
+        puts VERSION
+      else
+        return usage_error("Unknown command: #{command}") if command
+
+        puts USAGE
+      end
+      0
+    rescue Error => e
+      warn e.message
+      1
+    end
+
+    def usage_error(message)
+      warn message
+      warn USAGE
+      1
+    end
+
+    # Copies the template into dir/project_name. Files ending in .erb are
+    # rendered with project_name available. Returns the destination path.
+    def create_project(project_name, dir: Dir.pwd)
+      destination = File.join(dir, project_name)
+      if File.exist?(destination)
+        raise Error, "Sorry, #{destination} already exists. Please choose another name or delete the folder."
+      end
+
+      Dir.glob("**/*", base: TEMPLATE_PATH).sort.each do |relative_path|
+        source = File.join(TEMPLATE_PATH, relative_path)
+        next if File.directory?(source)
+
+        content = File.read(source)
+        content = ERB.new(content).result_with_hash(project_name: project_name) if relative_path.end_with?(".erb")
+
+        target = relative_path.delete_suffix(".erb")
+        target = target.sub(%r{(\A|/)gitignore\z}, "\\1.gitignore")
+        target_path = File.join(destination, target)
+        FileUtils.mkdir_p(File.dirname(target_path))
+        File.write(target_path, content)
+        puts "create #{File.join(project_name, target)}"
+      end
+      destination
+    end
+
+    def build
+      system("bundle", "install") or raise Error, "bundle install failed"
+      system("bundle", "exec", "rbwasm", "build", "--ruby-version", WASM_RUBY_VERSION, "-o", "assets/ruby-app.wasm") or
+        raise Error, "rbwasm build failed"
+    end
+
+    def server(port: 8080)
+      begin
+        require "webrick"
+      rescue LoadError
+        raise Error, "jsg server needs the webrick gem. Install it with: gem install webrick"
+      end
+
+      loop do
+        server = WEBrick::HTTPServer.new(BindAddress: "0.0.0.0", Port: port, DocumentRoot: Dir.pwd)
+        trap("INT") { server.shutdown }
+        puts "Serving #{Dir.pwd} at http://localhost:#{port}"
+        server.start
+        break
+      rescue Errno::EADDRINUSE
+        port += 1
+      end
+    end
+  end
+end

data/lib/jsg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSG
-  VERSION = "0.1.2"
+  VERSION = "0.2.1"
 end

data/lib/jsg.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative "jsg/version"
+require "js"
+
+# Syntax additions for JS::Object.
+#
+# The module is prepended to JS::Object (not included), because the js gem
+# defines method_missing, respond_to_missing?, to_a and (since js 2.10) nil?
+# directly on JS::Object. An included module sits behind the class in the
+# ancestor chain, so those methods would never be reached.
+#
+# The methods in here only use JS::Object#[], #call, #typeof and
+# #strictly_eql? to talk to JavaScript, never the method_missing shortcuts,
+# so they cannot recurse into themselves.
+module JSGPatch
+  SETTER = /\A[A-Za-z_]\w*=\z/
+  PREDICATE = /\A[A-Za-z_]\w*\?\z/
+
+  # Methods added to the JS module.
+  module ClassMethods
+    #  JS.try_convert_to_rb(obj) -> Ruby Object or JS::Object
+    #
+    #  Converts the given object to a Ruby object using to_rb. Returns the
+    #  argument unchanged if it cannot be converted.
+    def try_convert_to_rb(obj)
+      obj.respond_to?(:to_rb) ? obj.to_rb : obj
+    end
+  end
+
+  # Converts an array-like JavaScript object (Array, NodeList, arguments, ...)
+  # to a Ruby Array. The elements are converted with to_rb unless
+  # convertTypes is false.
+  # rubocop:disable-next Naming/MethodParameterName, Naming/VariableName
+  def to_a(convertTypes: true)
+    as_array = JS.global[:Array].call(:from, self)
+    Array.new(as_array[:length].to_i) do |index|
+      item = as_array[index]
+      convertTypes ? item.to_rb : item
+    end
+  end
+
+  # Converts JavaScript primitives and arrays to Ruby objects:
+  # number -> Float, string -> String, boolean -> true/false,
+  # bigint -> Integer, symbol -> Symbol, null -> nil, Array -> Array.
+  # Everything else (objects, functions, undefined) is returned as JS::Object.
+  def to_rb
+    case typeof
+    when "number" then to_f
+    when "string" then to_s
+    when "boolean" then strictly_eql?(JS::True)
+    when "bigint" then to_i
+    when "symbol" then self[:description].to_s.to_sym
+    when "object"
+      return nil if strictly_eql?(JS::Null)
+
+      isJSArray ? to_a : self
+    else
+      self
+    end
+  end
+
+  def isJSArray # rubocop:disable Naming/MethodName, Naming/PredicateMethod
+    JS.global[:Array].call(:isArray, self).strictly_eql?(JS::True)
+  end
+
+  def typeof?(type)
+    typeof == type.to_s
+  end
+
+  # Iterates over the elements of an array-like object (anything with a
+  # numeric length), otherwise over the property names of the object and its
+  # prototype chain.
+  def each(&block)
+    return Enumerator.new { |yielder| each { |item| yielder << item } } unless block
+
+    if array_like?
+      to_a.each(&block)
+    else
+      __props.each(&block)
+    end
+    self
+  end
+
+  # Kernel#tap, which JS::Object lost when the js gem 2.10 made it a
+  # BasicObject. (#then is left out on purpose: Promises have their own.)
+  def tap
+    yield self
+    self
+  end
+
+  # true for JavaScript null and undefined
+  def nil?
+    strictly_eql?(JS::Null) || strictly_eql?(JS::Undefined)
+  end
+
+  # true only for JavaScript undefined
+  def undefined?
+    strictly_eql?(JS::Undefined)
+  end
+
+  # Property names of the object and its prototype chain, as Symbols.
+  def __props
+    object = JS.global[:Object]
+    props = []
+    current = self
+    until current.nil?
+      names = object.call(:getOwnPropertyNames, current)
+      props.concat(names.to_a)
+      current = object.call(:getPrototypeOf, current)
+    end
+    props.uniq.map(&:to_sym)
+  end
+
+  #   element.innerText = "Hello"   # sets a property (value converted with to_js)
+  #   element.hidden?               # property or method result as true/false (JS truthiness)
+  #   document.title                # reads a property, converted with to_rb
+  #   document.getElementById("x")  # calls a method, result converted with to_rb
+  #   JS.global.URLSearchParams     # capitalized name without arguments: returns the constructor
+  #
+  # Anything else, e.g. a property that is undefined, goes to the js gem's
+  # method_missing.
+  def method_missing(sym, *args, &block)
+    name = sym.to_s
+
+    if SETTER.match?(name) && args.length == 1 && block.nil?
+      self[name[0..-2]] = args[0]
+      return args[0]
+    end
+
+    if PREDICATE.match?(name)
+      value = self[name[0..-2]]
+      value = call(name[0..-2], *args, &block) if value.typeof == "function"
+      return JS.global.call(:Boolean, value).strictly_eql?(JS::True)
+    end
+
+    value = self[sym]
+    case value.typeof
+    when "undefined"
+      super
+    when "function"
+      # Calling a class like URLSearchParams without `new` throws, so return
+      # the constructor itself and let the caller use `.new(...)`.
+      return value if args.empty? && block.nil? && name.match?(/\A[A-Z]/)
+
+      call(sym, *args, &block).to_rb
+    else
+      value.to_rb
+    end
+  end
+
+  def respond_to_missing?(sym, _include_private = false)
+    name = sym.to_s
+    return true if SETTER.match?(name) || PREDICATE.match?(name)
+    return false unless typeof?(:object) || typeof?(:function)
+
+    !self[sym].undefined?
+  end
+
+  private
+
+  def array_like?
+    return false unless typeof?(:object) && !nil?
+
+    isJSArray || self[:length].typeof?(:number)
+  end
+end
+
+# Applying the patch to JS::Object. See the comment on JSGPatch for why this is
+# a prepend and not an include.
+class JS::Object # rubocop:disable Style/ClassAndModuleChildren
+  prepend ::JSGPatch
+end
+
+module JS
+  extend JSGPatch::ClassMethods
+end
+
+# Shortcuts for the global object and the document.
+module JSG
+  class Error < StandardError; end
+
+  def self.window
+    JS.global
+  end
+
+  def self.document
+    JS.global[:document]
+  end
+
+  def self.querySelectorAll(*args) # rubocop:disable Naming/MethodName
+    document.querySelectorAll(*args)
+  end
+
+  singleton_class.alias_method :w, :window
+  singleton_class.alias_method :d, :document
+  singleton_class.alias_method :q, :querySelectorAll
+
+  # Forwards everything else to the JS module, e.g. JSG.global or JSG.eval.
+  def self.method_missing(method, ...)
+    if JS.respond_to?(method)
+      JS.send(method, ...)
+    else
+      super
+    end
+  end
+
+  def self.respond_to_missing?(method, include_private = false)
+    JS.respond_to?(method, include_private) || super
+  end
+end

data/sig/jsg.rbs

@@ -1,4 +1,4 @@
-module Jsg
+module JSG
   VERSION: String
   # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 end

data/template/Gemfile

@@ -2,8 +2,9 @@
 
 source "https://rubygems.org"
 
-# gem "rails"
-
-gem "ruby_wasm", "~> 2.6"
-gem "js", "~> 2.6"
-gem 'jsg'
+# ruby_wasm provides the rbwasm build tool, js is the JavaScript bridge used
+# inside the browser. Keep both on the same version as
+# assets/browser.script.iife.js (ruby.wasm 2.10.1).
+gem "ruby_wasm", "~> 2.10.1"
+gem "js", "~> 2.10.1"
+gem "jsg", "~> 0.2"