feat: javascript helpers extension

fix #881

Author: alandefreitas

src/lib/Gen/hbs/Builder.cpp

@@ -57,14 +57,20 @@ templateDirs(Config const& config, std::string_view generator, std::string_view
 
 namespace paths {
 
-std::string selectExistingTemplateDir(std::vector<std::string> const& candidates)
+std::string selectExistingTemplateDir(
+    std::vector<std::string> const& candidates,
+    Preference pref)
 {
+    std::string selected;
     for (auto const& dir : candidates)
     {
-        if (files::exists(dir))
-            return dir;
+        if (!files::exists(dir))
+            continue;
+        selected = dir;
+        if (pref == Preference::FirstExisting)
+            break;
     }
-    return {};
+    return selected;
 }
 
 std::string formatCandidateDirs(std::vector<std::string> const& candidates)
@@ -89,10 +95,11 @@ static std::string pickTemplateDir(
     Config const& config,
     std::string_view generator,
     std::string_view subdir,
-    std::string_view purpose)
+    std::string_view purpose,
+    paths::Preference pref)
 {
     auto dirs = templateDirs(config, generator, subdir);
-    if (auto const selected = paths::selectExistingTemplateDir(dirs); !selected.empty())
+    if (auto const selected = paths::selectExistingTemplateDir(dirs, pref); !selected.empty())
         return selected;
 
     auto const searched = paths::formatCandidateDirs(dirs);
@@ -254,8 +261,7 @@ Builder(
         loadPartials(hbs_, dir);
 
     // Load JavaScript helpers
-    auto const helperDirs = templateDirs(config, domCorpus.fileExtension, "helpers");
-    for (auto const& dir : helperDirs)
+    for (auto const& dir : templateDirs(config, domCorpus.fileExtension, "helpers"))
     {
         if (!files::exists(dir))
             continue;
@@ -330,32 +336,31 @@ Builder(
     hbs_.registerHelper("relativize", dom::makeInvocable(relativize_fn));
 
     // Load layout templates
-    std::string indexTemplateFilename =
-        std::format("index.{}.hbs", domCorpus.fileExtension);
-    std::string wrapperTemplateFilename =
-        std::format("wrapper.{}.hbs", domCorpus.fileExtension);
     auto const layoutDirs = templateDirs(config, domCorpus.fileExtension, "layouts");
-    for (std::string const& filename : {indexTemplateFilename, wrapperTemplateFilename})
+
+    auto loadLayoutTemplate = [&](std::string const& filename) -> Expected<void, Error>
     {
         bool loaded = false;
         for (auto const& dir : layoutDirs)
         {
-            std::string pathName = files::appendPath(dir, filename);
+            auto const pathName = files::appendPath(dir, filename);
             if (!files::exists(pathName))
                 continue;
-            auto text = files::getFileText(pathName);
-            if (!text)
-            {
-                text.error().Throw();
-            }
-            templates_[filename] = std::move(text.value());
+            MRDOCS_TRY(auto text, files::getFileText(pathName));
+            templates_[filename] = std::move(text); // later dirs override
             loaded = true;
         }
         if (!loaded)
         {
             formatError("Template {} not found in addons search path", filename).Throw();
         }
-    }
+        return {};
+    };
+
+    if (auto exp = loadLayoutTemplate(std::format("index.{}.hbs", domCorpus.fileExtension)); !exp)
+        exp.error().Throw();
+    if (auto exp = loadLayoutTemplate(std::format("wrapper.{}.hbs", domCorpus.fileExtension)); !exp)
+        exp.error().Throw();
 }
 
 //------------------------------------------------
@@ -503,35 +508,35 @@ std::string
 Builder::
 layoutDir() const
 {
-    return pickTemplateDir(domCorpus->config, domCorpus.fileExtension, "layouts", "layout");
+    return pickTemplateDir(domCorpus->config, domCorpus.fileExtension, "layouts", "layout", paths::Preference::LastExisting);
 }
 
 std::string
 Builder::
 templatesDir() const
 {
-    return pickTemplateDir(domCorpus->config, domCorpus.fileExtension, {}, "template");
+    return pickTemplateDir(domCorpus->config, domCorpus.fileExtension, {}, "template", paths::Preference::LastExisting);
 }
 
 std::string
 Builder::
 templatesDir(std::string_view subdir) const
 {
-    return pickTemplateDir(domCorpus->config, domCorpus.fileExtension, subdir, "template");
+    return pickTemplateDir(domCorpus->config, domCorpus.fileExtension, subdir, "template", paths::Preference::LastExisting);
 }
 
 std::string
 Builder::
 commonTemplatesDir() const
 {
-    return pickTemplateDir(domCorpus->config, "common", {}, "common template");
+    return pickTemplateDir(domCorpus->config, "common", {}, "common template", paths::Preference::LastExisting);
 }
 
 std::string
 Builder::
 commonTemplatesDir(std::string_view const subdir) const
 {
-    return pickTemplateDir(domCorpus->config, "common", subdir, "common template");
+    return pickTemplateDir(domCorpus->config, "common", subdir, "common template", paths::Preference::LastExisting);
 }
 
 

src/lib/Gen/hbs/Builder.hpp

@@ -26,7 +26,11 @@ namespace mrdocs {
 namespace hbs {
 
 namespace paths {
-std::string selectExistingTemplateDir(std::vector<std::string> const& candidates);
+enum class Preference { FirstExisting, LastExisting };
+
+std::string selectExistingTemplateDir(
+    std::vector<std::string> const& candidates,
+    Preference pref = Preference::LastExisting);
 }
 
 /** Builds reference output as a string for any Info type

src/lib/Support/JavaScript.cpp

@@ -29,6 +29,18 @@ std::mutex g_init_mtx;
 unsigned g_jerry_refcount = 0;
 }
 
+bool
+isOptionsObject(dom::Value const& v)
+{
+    if (!v.isObject())
+        return false;
+    // Handlebars options objects usually carry these markers.
+    return static_cast<bool>(v.get("hash")) ||
+        static_cast<bool>(v.get("data")) ||
+        static_cast<bool>(v.get("fn")) ||
+        static_cast<bool>(v.get("inverse"));
+}
+
 static std::string toString(jerry_value_t v)
 {
     // Callers must hold the context lock.
@@ -204,6 +216,47 @@ void Value::swap(Value& other) noexcept
 static dom::Value toDomValue(jerry_value_t v, std::shared_ptr<Context::Impl> const& impl);
 static jerry_value_t toJsValue(dom::Value const& v, std::shared_ptr<Context::Impl> const& impl);
 
+static Expected<Value, Error> resolveHelperFunction(
+    Scope& scope,
+    std::string_view name,
+    std::string_view script)
+{
+    if (auto exp = scope.eval(script))
+    {
+        if (exp->isFunction())
+            return *exp;
+    }
+    else
+    {
+        return Unexpected(exp.error());
+    }
+
+    std::string wrapped;
+    wrapped.reserve(script.size() + 2);
+    wrapped.push_back('(');
+    wrapped.append(script);
+    wrapped.push_back(')');
+
+    if (auto expr = scope.eval(wrapped))
+    {
+        if (expr->isFunction())
+            return *expr;
+    }
+    else
+    {
+        return Unexpected(expr.error());
+    }
+
+    if (Value global = scope.getGlobalObject())
+    {
+        Value candidate = global.get(name);
+        if (candidate.isFunction())
+            return candidate;
+    }
+
+    return Unexpected(Error(std::string("helper is not a function: ") + std::string(name)));
+}
+
 Type Value::type() const noexcept
 {
     if (!val_)
@@ -830,9 +883,7 @@ static dom::Value toDomValue(jerry_value_t v, std::shared_ptr<Context::Impl> con
     if (jerry_value_is_array(v))
     {
         dom::Array arr;
-        jerry_value_t lenVal = jerry_object_get(v, jerry_string_sz("length"));
-        uint32_t len = (uint32_t)jerry_value_as_number(lenVal);
-        jerry_value_free(lenVal);
+        uint32_t len = jerry_array_length(v);
         for (uint32_t i = 0; i < len; ++i)
         {
             jerry_value_t elem = jerry_object_get_index(v, i);
@@ -846,9 +897,7 @@ static dom::Value toDomValue(jerry_value_t v, std::shared_ptr<Context::Impl> con
     {
         dom::Object obj;
         jerry_value_t keys = jerry_object_keys(v);
-        jerry_value_t lenVal = jerry_object_get(keys, jerry_string_sz("length"));
-        uint32_t len = (uint32_t)jerry_value_as_number(lenVal);
-        jerry_value_free(lenVal);
+        uint32_t len = jerry_array_length(keys);
         for (uint32_t i = 0; i < len; ++i)
         {
             jerry_value_t key = jerry_object_get_index(keys, i);
@@ -877,33 +926,7 @@ registerHelper(
     std::string_view script)
 {
     Scope scope(ctx);
-    auto exp = scope.eval(script);
-    if (!exp)
-        return Unexpected(exp.error());
-    Value fn = *exp;
-    if (!fn.isFunction())
-    {
-        // Try treating the script as a function expression by parenthesizing it.
-        std::string wrapped("(");
-        wrapped.append(script);
-        wrapped.append(")");
-        auto expr = scope.eval(wrapped);
-        if (!expr)
-            return Unexpected(expr.error());
-        if (expr->isFunction())
-            fn = *expr;
-    }
-    if (!fn.isFunction())
-    {
-        // Fallback: scripts that declare a named function without returning it
-        // (e.g., `function helper() {}`) leave the function on the global object.
-        // Look it up by the helper name to preserve the legacy helper lookup behavior.
-        Value global = scope.getGlobalObject();
-        if (global)
-            fn = global.get(name);
-    }
-    if (!fn.isFunction())
-        return Unexpected(Error(std::string("helper is not a function: ") + std::string(name)));
+    MRDOCS_TRY(Value fn, resolveHelperFunction(scope, name, script));
 
     // Store helper on global object (preserve existing helpers if present)
     Value helpers = scope.getGlobal("MrDocsHelpers").value_or(Value{});
@@ -919,10 +942,11 @@ registerHelper(
     {
         std::vector<dom::Value> vec(args.begin(), args.end());
 
-        // Handlebars passes an options object as the final argument; drop it so
-        // helpers see only user-supplied parameters (matches legacy behavior).
-        if (vec.size() >= 3)
-            vec.resize(2);
+        // Handlebars passes an options object last; drop it so helpers see only
+        // user-supplied parameters (legacy behavior), but keep positional args intact.
+        if (!vec.empty() && isOptionsObject(vec.back()))
+            vec.pop_back();
+
         auto ret = fn.call(vec);
         if (!ret) return Unexpected(ret.error());
         auto domRet = ret->getDom();

test-files/golden-tests/generator/hbs/js-helper/helpers.adoc

@@ -7,9 +7,9 @@
 * string: string:hi
 * null: null:
 * undefined: undefined:
-* array: array:a,b
+* array: array:a,b,3
 * hash: hash:a=1,b=two
-* glue: x
+* glue: x|y|z
 * block: otherwise
 
 [.small]#Created with https://www.mrdocs.com[MrDocs]#

test-files/golden-tests/generator/hbs/js-helper/helpers.html

@@ -8,9 +8,9 @@
     <li id="string">string:hi</li>
     <li id="null">null:</li>
     <li id="undefined">undefined:</li>
-    <li id="array">array:a,b</li>
+    <li id="array">array:a,b,3</li>
     <li id="hash">hash:a&#x3D;1,b&#x3D;two</li>
-    <li id="glue">x</li>
+    <li id="glue">x|y|z</li>
     <li id="block">otherwise</li>
 </ul>
 </body>