register_helper: accept javascript function as string (#7)

This updates `register_helper` to accept a string of JavaScript source code
which will be interpreted as the helper function.

Author: gi

README.md

@@ -82,6 +82,32 @@ See https://handlebarsjs.com/guide/#custom-helpers.
 
 ### Block Helpers
 
+Block helpers make it possible to define custom iterators and other
+functionality that can invoke the passed block with a new context.
+
+Currently, there is a limitation with the underlying JavaScript engine: it does
+not allow for reentrant calls from within attached Ruby functions: see
+[MiniRacer#225](https://github.com/rubyjs/mini_racer/issues/225). Thus, the
+block function returned to the helper (in `options.fn`) cannot be  invoked.
+
+Thus, for block helpers, a string of JavaScript must define the helper function:
+```ruby
+handlebars = Handlebars::Engine.new
+handlebars.register_helper(map: <<~JS)
+  function(...args) {
+    const ctx = this;
+    const opts = args.pop();
+    const items = args[0];
+    const separator = args[1];
+    const mapped = items.map((item) => opts.fn(item));
+    return mapped.join(separator);
+  }
+JS
+template = handlebars.compile("{{#map items '|'}}'{{this}}'{{/map}}")
+template.call({ items: [1, 2, 3] })
+# => "'1'|2'|'3'"
+```
+
 See https://handlebarsjs.com/guide/#block-helpers.
 
 ### Partials

lib/handlebars/engine.rb

@@ -63,16 +63,28 @@ def template(*args)
 
     # Registers helpers accessible by any template in the environment.
     #
+    # The function can be either a proc or a string:
+    # * When the function is a proc, it can be either passed in as a normal
+    #   parameter or as a block.
+    # * When the function is a string, it is interpreted as a JavaScript
+    #   function.
+    #
     # @param name [String, Symbol] the name of the helper
+    # @param function [Proc, String] the helper function
     # @yieldparam context [Hash] the current context
     # @yieldparam arguments [Object] the arguments (optional)
     # @yieldparam options [Hash] the options hash (optional)
     # @see https://handlebarsjs.com/api-reference/runtime.html#handlebars-registerhelper-name-helper
-    def register_helper(name = nil, **helpers, &block)
-      helpers[name] = block if name
+    def register_helper(name = nil, function = nil, **helpers, &block)
+      helpers[name] = block || function if name
       helpers.each do |n, f|
-        attach(n, &f)
-        call(:registerHelper, [n.to_s, n.to_sym], eval: true)
+        case f
+        when Proc
+          attach(n, &f)
+          evaluate("registerHelper('#{n}', #{n})")
+        when String, Symbol
+          evaluate("Handlebars.registerHelper('#{n}', #{f})")
+        end
       end
     end
 
@@ -217,14 +229,7 @@ def init!
     end
 
     def js_args(args)
-      args.map { |arg|
-        case arg
-        when Symbol
-          arg
-        else
-          JSON.generate(arg)
-        end
-      }
+      args.map { |arg| JSON.generate(arg) }
     end
   end
 end

spec/handlebars/engine_spec.rb

@@ -150,21 +150,32 @@
     let(:template) { "{{#{name} name name=name}}" }
 
     before do
-      allow(function).to receive(:call).with(any_args).and_call_original
-      engine.register_helper(name, &function)
+      engine.register_helper(name, function)
     end
 
     it "is defined" do
       expect(engine).to respond_to(:register_helper)
     end
 
     context "with positional parameters" do
-      before do
-        engine.register_helper(name, &function)
+      context "when function is argument" do
+        before do
+          engine.register_helper(name, function)
+        end
+
+        describe "rendering" do
+          include_examples "rendering"
+        end
       end
 
-      describe "rendering" do
-        include_examples "rendering"
+      context "when function is block" do
+        before do
+          engine.register_helper(name, &function)
+        end
+
+        describe "rendering" do
+          include_examples "rendering"
+        end
       end
     end
 
@@ -178,7 +189,11 @@
       end
     end
 
-    describe "parameters" do
+    context "with a Ruby function" do
+      before do
+        allow(function).to receive(:call).with(any_args).and_call_original
+      end
+
       describe "the first parameter" do
         it "is the context" do
           render_context.transform_keys!(&:to_s)
@@ -233,6 +248,80 @@
         end
       end
     end
+
+    context "with a JavaScript function" do
+      let(:function) {
+        <<~JS
+          function (...args) {
+            args.unshift(this);
+            return tester(...args);
+          }
+        JS
+      }
+      let(:tester) { ->(_ctx, *_args, _opts) { rendered } }
+
+      before do
+        allow(tester).to receive(:call).with(any_args).and_call_original
+        engine_context.attach("tester", tester)
+      end
+
+      describe "rendering" do
+        include_examples "rendering"
+      end
+
+      describe "`this`" do
+        it "is the context" do
+          render_context.transform_keys!(&:to_s)
+          args = [render_context, any_args, anything]
+          render
+          expect(tester).to have_received(:call).with(*args)
+        end
+      end
+
+      describe "the first parameter(s)" do
+        it "is the positional argument(s)" do
+          args = [anything, *render_context.values_at(:name), anything]
+          render
+          expect(tester).to have_received(:call).with(*args)
+        end
+      end
+
+      describe "the last parameter" do
+        it "is the options" do
+          opts = include(
+            "data" => kind_of(Hash),
+            "hash" => { "name" => render_context[:name] },
+            "name" => name.to_s,
+          )
+          args = [anything, any_args, opts]
+          render
+          expect(tester).to have_received(:call).with(*args)
+        end
+      end
+
+      context "with a block helper" do
+        let(:template) { "{{##{name} age}}function{{else}}inverse{{/#{name}}}" }
+        let(:function) {
+          <<~JS
+            function (age, opts) {
+              return age > 0 ? opts.fn() : opts.inverse();
+            }
+          JS
+        }
+
+        describe "the options" do
+          it "includes the main block function" do
+            render_context[:age] = 30
+            expect(render).to eq("function")
+          end
+
+          it "includes the else block function" do
+            render_context[:age] = 0
+            expect(render).to eq("inverse")
+          end
+        end
+      end
+    end
   end
 
   describe "#unregister_helper" do