feat: javascript helpers extension

fix #881

Author: alandefreitas

include/mrdocs/Support/JavaScript.hpp

@@ -1063,17 +1063,32 @@ isFunction() const noexcept
     as a helper function that can be called from
     Handlebars templates.
 
-    The helper source is resolved via `resolveHelperFunction`
-    (direct eval → parenthesized eval → global lookup),
-    stored on the shared `MrDocsHelpers` object, and invoked with the Handlebars
-    options object supplied as the final argument.
+    The helper source is resolved in the following order:
+
+    1. **Parenthesized eval** - wraps the script in parentheses and evaluates.
+       Handles function declarations without side effects.
+       Example: `"function add(a, b) { return a + b; }"`
+
+    2. **Direct eval** - evaluates the script as-is.
+       Handles IIFEs and expressions that return functions.
+       Example: `"(function(){ return function(x){ return x*2; }; })()"`
+
+    3. **Global lookup** - looks up the helper name on the global object.
+       Handles scripts that define globals before returning.
+       Example: `"var helper = function(x){ return x; }; helper;"`
+
+    The resolved function is stored on the shared `MrDocsHelpers` global object
+    and registered with Handlebars. When invoked, positional arguments are passed
+    to the JavaScript function (the Handlebars options object is stripped to avoid
+    expensive recursive conversion of symbol contexts).
 
     @param hbs The Handlebars instance to register the helper into
     @param name The name of the helper function
     @param ctx The JavaScript context to use
     @param script The JavaScript code that defines the helper function
+    @return Success, or an error if the script could not be resolved to a function
 */
-MRDOCS_DECL
+[[nodiscard]] MRDOCS_DECL
 Expected<void, Error>
 registerHelper(
     mrdocs::Handlebars& hbs,

src/lib/Gen/hbs/Builder.cpp

@@ -53,12 +53,19 @@ std::vector<std::string>
 makeHelperDirs(std::vector<std::string> const& roots, std::string_view ext)
 {
     std::vector<std::string> dirs;
-    dirs.reserve(roots.size());
+    dirs.reserve(roots.size() * 2);
+
+    // Preserve root precedence: for each root load common first, then format.
+    // Later roots (supplemental addons) still override earlier ones.
     for (auto const& root : roots)
     {
-        auto const dir = files::appendPath(root, "generator", ext, "helpers");
-        if (files::exists(dir))
-            dirs.push_back(dir);
+        auto const commonDir = files::appendPath(root, "generator", "common", "helpers");
+        if (files::exists(commonDir))
+            dirs.push_back(commonDir);
+
+        auto const formatDir = files::appendPath(root, "generator", ext, "helpers");
+        if (files::exists(formatDir))
+            dirs.push_back(formatDir);
     }
     return dirs;
 }

src/lib/Support/JavaScript.cpp

@@ -72,10 +72,10 @@ invokeHelper(Value const& fn, dom::Array const& args)
     // Passing the options object would trigger expensive recursive conversion
     // of symbol contexts which contain circular references.
     std::vector<dom::Value> callArgs;
-    callArgs.reserve(args.size());
-    for (std::size_t i = 0; i + 1 < args.size(); ++i)
+    callArgs.reserve(args.size() - 1);
+    for (auto it = args.begin(); it != std::prev(args.end()); ++it)
     {
-        callArgs.push_back(args.at(i));
+        callArgs.push_back(*it);
     }
 
     auto ret = fn.apply(callArgs);
@@ -1270,6 +1270,15 @@ makeObjectProxy(dom::Object obj, std::shared_ptr<Context::Impl> impl)
     jerry_value_free(target);
     jerry_value_free(handler);
 
+    // If proxy creation fails, return an empty object rather than an exception.
+    // The holder is cleaned up via the free_cb when holderRef (attached to
+    // handler) is garbage collected.
+    if (jerry_value_is_exception(proxy))
+    {
+        jerry_value_free(proxy);
+        return jerry_object();
+    }
+
     return proxy;
 }
 
@@ -1537,26 +1546,22 @@ resolveHelperFunction(
     std::string_view name,
     std::string_view script)
 {
-    // Attempt to coerce user-provided helper source into a callable: first
-    // evaluate directly, then as a parenthesized expression, then fall back to
-    // a global lookup. This mirrors Handlebars' permissive helper loading while
-    // still rejecting non-functions with clear errors. Note: first two paths
-    // can execute side effects twice if the first expression is not a
-    // function; callers rely on deterministic ordering.
+    // Coerce user-provided helper source into a callable. Resolution order:
+    //
+    // 1. Parenthesized eval - handles function declarations without side effects
+    //    e.g., "function add(a,b) { return a+b; }" -> "(function add(a,b)...)"
+    //
+    // 2. Direct eval - handles IIFEs and expressions that return functions
+    //    e.g., "(function(){ return function(){}; })()"
+    //
+    // 3. Global lookup - handles scripts that define globals
+    //    e.g., "var helper = function(){}; helper;"
+    //
+    // This order minimizes side effects: parenthesized eval of a function
+    // declaration is pure, while direct eval may execute statements.
     Error firstErr("code did not evaluate to a function");
 
-    if (auto exp = scope.eval(script))
-    {
-        if (exp->isFunction())
-        {
-            return *exp;
-        }
-    }
-    else
-    {
-        firstErr = exp.error();
-    }
-
+    // Try parenthesized first (common case: function declarations)
     std::string wrapped;
     wrapped.reserve(script.size() + 2);
     wrapped.push_back('(');
@@ -1572,9 +1577,24 @@ resolveHelperFunction(
     }
     else
     {
-        return Unexpected(expr.error());
+        firstErr = expr.error();
+    }
+
+    // Try direct eval (IIFEs, expressions)
+    if (auto exp = scope.eval(script))
+    {
+        if (exp->isFunction())
+        {
+            return *exp;
+        }
+    }
+    else if (firstErr.message() == "code did not evaluate to a function")
+    {
+        // Keep the more informative error
+        firstErr = exp.error();
     }
 
+    // Fall back to global lookup
     if (Value global = scope.getGlobalObject())
     {
         Value candidate = global.get(name);