opal_proxy 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1398d427665fc0e194ff83e2d460400d42bc44302332d823723cd1b6c33d7182
-  data.tar.gz: ae36c54be48b23bab603f5238356835e65c7b3fc7e3534ad64608a79f5c40c97
+  metadata.gz: 16f6f216939bb7ad43a3e8046eba3a468376b385b7c517e7f114ba3ed4fb6f8e
+  data.tar.gz: 2fd8b4d5b95354facae44f4978a2b8ed566ff70d005269d2ab715ab1e60a69f6
 SHA512:
-  metadata.gz: 81c9493e8dfb5fafa896ac9f0184b4d98a0b37813bcd1b538d7e3b9521a5ffabc213e5c58793199438d0a31d23fcb682cd3d4fb8d22606f9e1a1d4ad258e1c6b
-  data.tar.gz: 3ab3b1320f3956d54ac30baf2b2784e2529a3691bcb11b8c68a90f11aa83e0b52179b1c009711a00de57164ca447a4c83def16885930ef56336549d72a7c7056
+  metadata.gz: 378e55ea22b7d67177c22cf580e4adf00fc92d9d76d67c3ee531fdc8a462a2471b12625639d8c7a82d213a6960b96e4a0f86511b5a5df2c733edd0da3416dbad
+  data.tar.gz: f4520e248767de0a95bb026eba5adadf06e0b0473626436421ff27759a73a4c455862a640535ccef3b0a62cb4b9b54d9108fbadb00b2907a689e2eea19e8c6cf

data/.rubocop.yml

@@ -1,6 +1,42 @@
 AllCops:
+  NewCops: enable
+  SuggestExtensions: false
   TargetRubyVersion: 3.1
 
+Metrics/ClassLength:
+  Exclude:
+    - "test/**/*.rb"
+  Max: 150
+
+Metrics/MethodLength:
+  Exclude:
+    - "lib/js/**/*.rb"
+    - "test/**/*.rb"
+
+Lint/LiteralAsCondition:
+  Exclude:
+    - "lib/js/**/*.rb"
+
+Lint/UnusedMethodArgument:
+  Exclude:
+    - "lib/js/**/*.rb"
+
+Lint/UselessAssignment:
+  Exclude:
+    - "lib/js/**/*.rb"
+
+Lint/Void:
+  Exclude:
+    - "lib/js/**/*.rb"
+
+Naming/PredicateMethod:
+  Exclude:
+    - "lib/js/**/*.rb"
+
+Style/CommandLiteral:
+  Exclude:
+    - "lib/js/**/*.rb"
+
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 

data/CHANGELOG.md

@@ -1,9 +1,19 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-07-24
+## [0.2.0] - 2026-08-19
+
+- Preserve `JS::Promise` wrappers across `then` and `catch` chains.
+- Wrap callback receivers and arguments, and unwrap callback return values.
+- Support JavaScript iterables and array-like objects through `Enumerable`.
+- Make `respond_to?` reflect native property availability.
+- Improve exact, camelCase, and acronym-aware property lookup.
+- Refresh native property introspection for dynamically added properties.
+- Add deterministic browser coverage without external network dependencies.
 
-- Initial release
+## [0.1.1] - 2025-08-08
 
-## [0.1.0] - 2025-08-08
+- Add `[]=` method to Proxy.
+
+## [0.1.0] - 2025-07-24
 
-- Add `[]=` method to Proxy
+- Initial release.

data/README.md

@@ -58,14 +58,44 @@ window.set_timeout(-> {
   puts "1. Timeout test OK (1s delay)"
 }, 1000)
 window.fetch("https://jsonplaceholder.typicode.com/todos/1")
-  .then do |response|
-    response.json().then do |data|
-      puts "5. Fetched: #{data["title"]}"
-      document.get_element_by_id("output").inner_html += "<p>5. Fetched: #{data["title"]}</p>"
-    end
+  .then { |response| response.json }
+  .then do |data|
+    puts "5. Fetched: #{data["title"]}"
+    document.get_element_by_id("output").inner_html += "<p>5. Fetched: #{data["title"]}</p>"
   end
+  .catch { |error| warn error["message"] }
+```
+
+Promise callbacks automatically unwrap returned `JS::Proxy` and `JS::Promise` values,
+so native Promise flattening works across chained `then`, `catch`, and `finally` calls.
+
+## Interop behavior
+
+Property lookup tries the original name first, then camelCase and common JavaScript
+acronyms such as `HTML`, `URL`, and `URI`. For example, both `inner_html` and
+`document_uri` map to their DOM equivalents.
+
+JavaScript properties that collide with Ruby methods can always be accessed with `[]`:
+
+```ruby
+proxy["count"]
+proxy["class"]
 ```
 
+When a Ruby block is passed to a JavaScript method, it is appended as the final callback
+argument. The callback receives its JavaScript `this` value first, followed by the native
+callback arguments, all wrapped when necessary:
+
+```ruby
+target.add_event_listener("click") do |receiver, event|
+  event.prevent_default
+  puts receiver
+end
+```
+
+`JS::Proxy` is enumerable for JavaScript iterable and array-like objects, including
+arrays, `Set`, `Map`, `NodeList`, and objects with numeric indexes and a `length`.
+
 ## JQuery example
 
 ```ruby

data/lib/js/proxy.rb

@@ -1,12 +1,20 @@
+# backtick_javascript: true
+# frozen_string_literal: true
+
 require "opal"
 require "native"
 
 module JS
+  # Shared conversion helpers for values crossing the Ruby/JavaScript boundary.
   module Helpers
     def wrap_result(result)
-      if `result && typeof result.then === 'function'`
+      return nil if `result == null`
+
+      if `typeof result.then === "function" && !result.then.$$owner`
         Promise.new(result)
-      elsif `typeof result === 'object' && result !== null`
+      elsif `result instanceof Number || result instanceof String || result instanceof Boolean`
+        `result.valueOf()`
+      elsif `typeof result === "object"`
         Proxy.new(result)
       else
         result
@@ -14,114 +22,151 @@ module JS
     end
 
     def native_methods
-      @native_methods ||= %x{
-        let obj = #{to_n};
-        const props = new Set();
+      %x{
+        let object = #{to_n};
+        const properties = new Set();
+
+        while (object !== null) {
+          for (const key of Reflect.ownKeys(object)) {
+            if (typeof key === "symbol") continue;
 
-        while (obj !== null) {
-          for (const key of Reflect.ownKeys(obj)) {
-            const stringKey = key.toString()
-            const rubyName = #{to_rb_name(`stringKey`)}
+            const nativeName = key.toString();
+            const rubyName = #{to_rb_name(`nativeName`)};
 
-            if (typeof key !== 'symbol' && stringKey !== rubyName ) { props.add(rubyName); }
-            props.add(stringKey);
+            properties.add(nativeName);
+            properties.add(rubyName);
           }
-          obj = Object.getPrototypeOf(obj);
+          object = Object.getPrototypeOf(object);
         }
 
-        return Array.from(props);
+        return Array.from(properties);
       }
     end
+
+    private
+
+    def unwrap_result(result)
+      Native.try_convert(result, result)
+    end
   end
 
+  # Provides Ruby-style access to the properties and methods of a JavaScript object.
   class Proxy
     include Enumerable
     include Helpers
 
-    attr_accessor :native
-
-    IRREGULARS = %w(html url uri)
+    IRREGULARS = %w[html url uri].freeze
 
     def initialize(native)
-      @native = Native(native)
+      self.native = native
     end
 
-    def method_missing(name, *args, &block)
-      js_name = to_js_name(name)
-
-      unless existing_property?(js_name) || js_name.end_with?("=")
-        raise NoMethodError, "undefined method `#{name}` for #{self}"
-      end
+    def native
+      Native(to_n)
+    end
 
-      if js_name.end_with?("=")
-        prop = js_name[0..-2]
-        native[prop] = args.first
-      else
-        val = native[js_name]
-
-        if `typeof val === 'function'`
-          js_args = args.dup
-
-          if block
-            js_callback = %x{
-              function() {
-                let args = Array.prototype.slice.call(arguments);
-                return #{block.call(self.class.new(`this`), *args)};
-              }
-            }
-            js_args << js_callback
-          end
-
-          result = `val.apply(#{to_n}, #{js_args.to_n})`
-          wrap_result(result)
-        elsif `typeof val === 'object' && val !== null`
-          wrap_result(val)
-        else
-          val
-        end
-      end
+    def native=(value)
+      @native = Native.try_convert(value, value)
     end
 
-    def to_str
-      `#{to_n}.toString()`
+    def method_missing(name, *args, &block)
+      setter = name.end_with?("=")
+      property = resolve_property_name(name, allow_missing: setter)
+
+      return super unless property
+      return write_property(property, args.first) if setter
+
+      read_property(property, args, block)
     end
 
     def respond_to_missing?(name, include_private = false)
-      true
+      setter = name.end_with?("=")
+      !!resolve_property_name(name, allow_missing: setter) || super
     end
 
-    def each
-      return enum_for(:each) unless respond_to?(:length)
+    def each(&block)
+      return enum_for(:each) unless block
 
-      length = self.length
-      (0...length).each do |i|
-        yield self[i]
+      if iterable?
+        each_iterable(&block)
+      elsif array_like?
+        each_array_like(&block)
+      else
+        raise TypeError, "#{self.class} does not wrap an iterable or array-like object"
       end
+
+      self
     end
 
     def [](index)
-      val = native[index]
-      wrap_result(val)
+      wrap_result(`#{to_n}[#{index}]`)
     end
 
-    def []=(k, v)
-      native[k] = v
-      wrap_result(native)
+    def []=(key, value)
+      converted = unwrap_result(value)
+      `#{to_n}[#{key}] = #{converted}`
+      value
     end
 
     def to_n
-      native.to_n
+      @native
+    end
+
+    def to_str
+      `String(#{to_n})`
     end
 
     def length
-      native.length
+      `#{to_n}.length`
     end
 
     private
 
-    def to_js_name(name)
-      name.to_s.split('_').map.with_index do |part, index|
-        if IRREGULARS.include? part.gsub("=", "").downcase
+    def read_property(property, args, block)
+      value = `#{to_n}[#{property}]`
+      return wrap_result(value) unless `typeof value === "function"`
+
+      invoke_native_function(value, args, block)
+    end
+
+    def write_property(property, value)
+      converted = unwrap_result(value)
+      `#{to_n}[#{property}] = #{converted}`
+      value
+    end
+
+    def invoke_native_function(callable, args, block)
+      arguments = args.dup
+      arguments << callback_for(block) if block
+      wrap_result(`callable.apply(#{to_n}, #{arguments.to_n})`)
+    end
+
+    def callback_for(block)
+      %x{
+        return function() {
+          const callbackArgs = Array.prototype.slice.call(arguments).map(function(argument) {
+            return #{wrap_result(`argument`)};
+          });
+          const receiver = #{wrap_result(`this`)};
+          return #{unwrap_result(block.call(`receiver`, *`callbackArgs`))};
+        };
+      }
+    end
+
+    def resolve_property_name(name, allow_missing: false)
+      ruby_name = name.to_s.delete_suffix("=")
+      candidates = js_name_candidates(ruby_name)
+      candidates.find { |candidate| existing_property?(candidate) } ||
+        (candidates.last if allow_missing)
+    end
+
+    def js_name_candidates(name)
+      [name, camelize(name), camelize(name, acronyms: true)].uniq
+    end
+
+    def camelize(name, acronyms: false)
+      name.split("_").map.with_index do |part, index|
+        if acronyms && IRREGULARS.include?(part.downcase)
           part.upcase
         else
           index.zero? ? part : part.capitalize
@@ -132,51 +177,70 @@ module JS
     def to_rb_name(name)
       name
         .to_s
-        .gsub(/([A-Z]+)/) { "_#{$1.downcase}" }
-        .sub(/^_/, '')
+        .gsub(/([A-Z]+)([A-Z][a-z])/, "\\1_\\2")
+        .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+        .tr("-", "_")
+        .downcase
     end
 
     def existing_property?(property)
       `#{property} in #{to_n}`
     end
-  end
 
-  class Promise < Proxy
-    include Helpers
+    def iterable?
+      `typeof Symbol !== "undefined" && typeof #{to_n}[Symbol.iterator] === "function"`
+    end
 
-    def then(&block)
-      js_callback = %x{
-        function(value) {
-          var ruby_result = #{block.call(wrap_result(`value`))};
-          if (ruby_result && typeof ruby_result.then === 'function') {
-            return ruby_result;
-          } else if (ruby_result && typeof ruby_result.to_n === 'function') {
-            return ruby_result.to_n();
-          } else {
-            return ruby_result;
-          }
-        }
+    def array_like?
+      %x{
+        const length = #{to_n}.length;
+        return typeof length === "number" &&
+          Number.isFinite(length) &&
+          length >= 0 &&
+          Math.floor(length) === length;
       }
+    end
+
+    def each_iterable
+      iterator = `#{to_n}[Symbol.iterator]()`
+
+      loop do
+        step = `iterator.next()`
+        break if `step.done`
 
-      self.native = `#{to_n}.then(#{js_callback})`
+        yield wrap_result(`step.value`)
+      end
+    end
+
+    def each_array_like
+      (0...length).each { |index| yield self[index] }
+    end
+  end
+
+  # Ruby wrapper for JavaScript promises with chain-preserving return values.
+  class Promise < Proxy
+    def then(&block)
+      result = block ? `#{to_n}.then(#{promise_callback(block)})` : `#{to_n}.then()`
+      Promise.new(result)
     end
 
     def catch(&block)
-      js_callback = %x{
-        function(error) {
-          var ruby_result = #{block.call(wrap_result(`error`))};
-
-          if (ruby_result && typeof ruby_result.then === 'function') {
-            return ruby_result;
-          } else if (ruby_result && typeof ruby_result.to_n === 'function') {
-            return ruby_result.to_n();
-          } else {
-            return ruby_result;
-          }
-        }
-      }
+      result = block ? `#{to_n}.catch(#{promise_callback(block)})` : `#{to_n}.catch()`
+      Promise.new(result)
+    end
 
-      self.native = `#{to_n}.catch(#{js_callback})`
+    private
+
+    def promise_callback(block)
+      %x{
+        const proxy = #{self};
+
+        return function(value) {
+          const wrappedValue = proxy.$wrap_result(value);
+          const rubyResult = block.$call(wrappedValue);
+          return proxy.$unwrap_result(rubyResult);
+        };
+      }
     end
   end
 end

data/lib/opal_proxy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpalProxy
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/opal_proxy.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
-if RUBY_ENGINE == 'opal'
+if RUBY_ENGINE == "opal"
   require_relative "js/proxy"
 else
   require "opal"
   require_relative "opal_proxy/version"
 
-  Opal.append_path File.expand_path('lib', __dir__)
+  Opal.append_path File.expand_path("lib", __dir__)
 end
 
+# Namespace for Opal Proxy versioning and Ruby-side integration.
 module OpalProxy
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opal_proxy
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Joseph Schito
@@ -24,8 +24,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.8.2
 description: Opal Proxy provides a dynamic interface to JavaScript objects in Opal,
-  allowing seamless property access, method calls, and Promise handling using idiomatic
-  Ruby syntax.
+  with idiomatic property access, method calls, and Promise handling.
 email:
 - joseph.schito@gmail.com
 executables: []
@@ -48,6 +47,7 @@ metadata:
   homepage_uri: https://github.com/josephschito/opal_proxy
   source_code_uri: https://github.com/josephschito/opal_proxy
   changelog_uri: https://github.com/josephschito/opal_proxy/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Dynamic Ruby-style wrapper for JavaScript objects in Opal.
 test_files: []