feat: javascript helpers extension

fix #881

Author: alandefreitas

include/mrdocs/Support/JavaScript.hpp

@@ -57,9 +57,6 @@ class Handlebars;
 */
 namespace js {
 
-/** Grants friend-level access to internal JS bridge scopes.
-*/
-struct Access;
 class Context;
 class Scope;
 
@@ -135,7 +132,6 @@ class MRDOCS_DECL
 private:
     std::shared_ptr<Impl> impl_;
 
-    friend struct Access;
     friend class Value;
     friend class Scope;
 
@@ -198,8 +194,6 @@ class Scope
 {
     std::shared_ptr<Context::Impl> impl_;
 
-    friend struct Access;
-
 public:
     /** Constructor.
 
@@ -428,7 +422,6 @@ class MRDOCS_DECL Value
     /// Opaque engine value handle stored as an integer (engine-specific inside the implementation).
     std::uint32_t val_;
 
-    friend struct Access;
     friend class Scope;
 
     /** Wrap an existing engine value without transferring ownership.

src/lib/Support/JavaScript.cpp

@@ -77,9 +77,9 @@ invokeHelper(Value const& fn, dom::Array const& args)
     // of symbol contexts which contain circular references.
     std::vector<dom::Value> callArgs;
     callArgs.reserve(args.size() - 1);
-    for (auto it = args.begin(); it != std::prev(args.end()); ++it)
+    for (std::size_t i = 0; i < args.size() - 1; ++i)
     {
-        callArgs.push_back(*it);
+        callArgs.push_back(args.get(i));
     }
 
     auto ret = fn.apply(callArgs);
@@ -128,6 +128,12 @@ toString(jerry_value_t v)
 // - Runtime errors (thrown exceptions) are prefixed with "Unexpected: " if they
 //   don't already contain that marker, helping distinguish them from parse errors
 // - This prefix is intentionally consistent to aid debugging and testing
+//
+// LIMITATION: The "Unexpected" heuristic isn't perfect - some runtime errors
+// may contain "Unexpected" in their message and won't get the prefix, while
+// some custom syntax-like errors might get prefixed incorrectly. This is
+// acceptable because the prefix is for debugging convenience, not semantic
+// correctness.
 static Error
 makeError(jerry_value_t exc)
 {
@@ -138,8 +144,12 @@ makeError(jerry_value_t exc)
     std::string msg;
     if (jerry_value_is_object(obj))
     {
-        jerry_value_t msg_prop
-            = jerry_object_get(obj, jerry_string_sz("message"));
+        // Note: jerry_string_sz is used here instead of makeString because
+        // makeString is defined later in this file and we need to extract
+        // error messages early in the error handling path.
+        jerry_value_t msg_key = jerry_string_sz("message");
+        jerry_value_t msg_prop = jerry_object_get(obj, msg_key);
+        jerry_value_free(msg_key);
         if (!jerry_value_is_exception(msg_prop))
         {
             msg = toString(msg_prop);
@@ -245,12 +255,23 @@ struct Context::Impl {
 std::mutex Context::Impl::init_mtx;
 unsigned Context::Impl::jerry_refcount = 0;
 
+// Acquire the context lock for thread-safe JerryScript operations.
+//
+// Thread Safety Model:
+// - JerryScript is single-threaded; all engine calls must be serialized.
+// - Each Context::Impl has a recursive_mutex protecting its JerryScript state.
+// - Values hold shared_ptr<Impl> to keep the context alive and use this
+//   function before any jerry_* calls.
+// - The recursive_mutex allows nested locking (e.g., a trap callback that
+//   needs to call toJsValue which also locks).
+//
+// @param impl  Shared context state, or nullptr for moved-from Values.
+// @return      RAII lock guard; empty if impl is null.
 static std::unique_lock<std::recursive_mutex>
 lockContext(std::shared_ptr<Context::Impl> const& impl)
 {
-    // Prevent concurrent use of a JerryScript context without requiring callers
-    // to remember which locks to take. Accepts null shared_ptr so callers can
-    // use it uniformly in move/copy paths.
+    // Accepts null shared_ptr so callers can use it uniformly in move/copy
+    // paths where the source Value may have been moved-from (val_ == 0).
     if (impl)
     {
         return std::unique_lock<std::recursive_mutex>(impl->mtx);
@@ -985,8 +1006,9 @@ Value::size() const
     if (isArray())
     {
         auto lock = lockContext(impl_);
-        jerry_value_t lenVal
-            = jerry_object_get(to_js(val_), jerry_string_sz("length"));
+        jerry_value_t lenKey = makeString("length");
+        jerry_value_t lenVal = jerry_object_get(to_js(val_), lenKey);
+        jerry_value_free(lenKey);
         if (jerry_value_is_exception(lenVal))
         {
             jerry_value_free(lenVal);
@@ -1172,7 +1194,7 @@ makeObjectProxy(dom::Object obj, std::shared_ptr<Context::Impl> impl)
             return toJsValue(val, h->impl);
         });
 
-    jerry_value_t get_key = jerry_string_sz("get");
+    jerry_value_t get_key = makeString("get");
     jerry_value_t sr = jerry_object_set(handler, get_key, get_fn);
     jerry_value_free(sr);
     jerry_value_free(get_key);
@@ -1195,7 +1217,7 @@ makeObjectProxy(dom::Object obj, std::shared_ptr<Context::Impl> impl)
             return jerry_boolean(h->value.getObject().exists(propName));
         });
 
-    jerry_value_t has_key = jerry_string_sz("has");
+    jerry_value_t has_key = makeString("has");
     sr = jerry_object_set(handler, has_key, has_fn);
     jerry_value_free(sr);
     jerry_value_free(has_key);
@@ -1221,15 +1243,15 @@ makeObjectProxy(dom::Object obj, std::shared_ptr<Context::Impl> impl)
             jerry_value_t arr = jerry_array(keys.size());
             for (uint32_t i = 0; i < keys.size(); ++i)
             {
-                jerry_value_t keyVal = jerry_string_sz(keys[i].c_str());
+                jerry_value_t keyVal = makeString(keys[i]);
                 jerry_value_t setRes = jerry_object_set_index(arr, i, keyVal);
                 jerry_value_free(setRes);
                 jerry_value_free(keyVal);
             }
             return arr;
         });
 
-    jerry_value_t ownKeys_key = jerry_string_sz("ownKeys");
+    jerry_value_t ownKeys_key = makeString("ownKeys");
     sr = jerry_object_set(handler, ownKeys_key, ownKeys_fn);
     jerry_value_free(sr);
     jerry_value_free(ownKeys_key);
@@ -1257,53 +1279,58 @@ makeObjectProxy(dom::Object obj, std::shared_ptr<Context::Impl> impl)
             jerry_value_t val = toJsValue(h->value.getObject().get(propName), h->impl);
             jerry_value_t setRes;
 
-            jerry_value_t valueKey = jerry_string_sz("value");
+            jerry_value_t valueKey = makeString("value");
             setRes = jerry_object_set(desc, valueKey, val);
             jerry_value_free(setRes);
             jerry_value_free(valueKey);
             jerry_value_free(val);
 
-            jerry_value_t writableKey = jerry_string_sz("writable");
+            jerry_value_t writableKey = makeString("writable");
             setRes = jerry_object_set(desc, writableKey, jerry_boolean(true));
             jerry_value_free(setRes);
             jerry_value_free(writableKey);
 
-            jerry_value_t enumKey = jerry_string_sz("enumerable");
+            jerry_value_t enumKey = makeString("enumerable");
             setRes = jerry_object_set(desc, enumKey, jerry_boolean(true));
             jerry_value_free(setRes);
             jerry_value_free(enumKey);
 
-            jerry_value_t configKey = jerry_string_sz("configurable");
+            jerry_value_t configKey = makeString("configurable");
             setRes = jerry_object_set(desc, configKey, jerry_boolean(true));
             jerry_value_free(setRes);
             jerry_value_free(configKey);
 
             return desc;
         });
 
-    jerry_value_t getOwnPropDesc_key = jerry_string_sz("getOwnPropertyDescriptor");
+    jerry_value_t getOwnPropDesc_key = makeString("getOwnPropertyDescriptor");
     sr = jerry_object_set(handler, getOwnPropDesc_key, getOwnPropDesc_fn);
     jerry_value_free(sr);
     jerry_value_free(getOwnPropDesc_key);
     jerry_value_free(getOwnPropDesc_fn);
 
-    // Store a reference to the holder on the handler so traps can access it
+    // Store a reference to the holder on the handler so traps can access it.
+    //
+    // Ownership chain: proxy → handler → holderRef → native_ptr(holder)
+    //
+    // When the proxy is garbage collected, handler is released, which releases
+    // holderRef, which triggers DomValueHolder::free_cb to delete the holder.
+    // This happens synchronously when refcounts reach zero (not deferred to GC).
     jerry_value_t holderRef = jerry_object();
     jerry_object_set_native_ptr(holderRef, &kDomProxyInfo, holder);
-    jerry_value_t holderKey = jerry_string_sz("__holder__");
+    jerry_value_t holderKey = makeString("__holder__");
     sr = jerry_object_set(handler, holderKey, holderRef);
     jerry_value_free(sr);
     jerry_value_free(holderKey);
-    jerry_value_free(holderRef);
+    jerry_value_free(holderRef);  // handler now owns the reference
 
     // Create the proxy
     jerry_value_t proxy = jerry_proxy(target, handler);
     jerry_value_free(target);
-    jerry_value_free(handler);
+    jerry_value_free(handler);  // proxy now owns handler (and transitively holder)
 
-    // 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 proxy creation fails, handler was still freed above, which releases
+    // holderRef, which deletes holder via free_cb. Return empty object.
     if (jerry_value_is_exception(proxy))
     {
         jerry_value_free(proxy);