@gjsify/node-gi 0.64.1 → 0.64.4

package/src/common.h

@@ -363,7 +363,7 @@ inline NodeGiIntResult NodeGiJsToInteger(Napi::Value v, GITypeTag tag, GIArgumen
   }
 }
 
-enum class NodeGiIntContext { kArgument, kField, kReturnValue };
+enum class NodeGiIntContext { kArgument, kField, kReturnValue, kListElement, kHashElement };
 inline const char* NodeGiIntTagName(GITypeTag tag) {
   switch (tag) {
     case GI_TYPE_TAG_INT8: return "int8";
@@ -385,13 +385,31 @@ inline void NodeGiThrowIntOutOfRange(Napi::Env env, GITypeTag tag, NodeGiIntCont
     msg = std::string("Argument ") + (name != nullptr ? name : "") + ": value is out of range for " + t;
   } else {
     msg = "value " + shown + " is out of range for " +
-          (ctx == NodeGiIntContext::kField ? std::string("Field '") + (name ? name : "") + "'"
-                                           : std::string("Return value")) +
+          (ctx == NodeGiIntContext::kField
+               ? std::string("Field '") + (name ? name : "") + "'"
+               : ctx == NodeGiIntContext::kListElement   ? std::string("List element")
+               : ctx == NodeGiIntContext::kHashElement   ? std::string("Hash element")
+                                                         : std::string("Return value")) +
           " (type " + t + ")";
   }
   Napi::Error::New(env, msg).ThrowAsJavaScriptException();
 }
 
+// The text gjs_debug_value (refs/gjs/gi/../jsapi-util-string.cpp) prints for the offending
+// value in a list/hash element error: a Number goes through C++ ostream (%g, 6 digits), a
+// BigInt is shown as its signed 64-bit value with a "(modulo 2^64)" suffix.
+inline std::string NodeGiDebugValue(Napi::Value v) {
+  if (v.IsBigInt()) {
+    bool lossless = false;
+    return std::to_string(v.As<Napi::BigInt>().Int64Value(&lossless)) + "n (modulo 2^64)";
+  }
+  Napi::Number n = v.ToNumber();
+  if (n.IsEmpty()) return std::string();
+  char buf[G_ASCII_DTOSTR_BUF_SIZE];
+  g_ascii_formatd(buf, sizeof(buf), "%g", n.DoubleValue());  // locale-independent, like ostream
+  return buf;
+}
+
 // IN array elements and GValue int/uint, GJS-exact: these WRAP instead of refusing.
 // An array element goes through js_value_to_c_strict (refs/gjs/gi/arg.cpp:543), which
 // is ToInt32/ToUint32 truncated to the tag for 8/16/32 bits and ToInt64/ToUint64 —

package/src/marshal.cc

@@ -1060,6 +1060,8 @@ static bool IsSupportedElementType(GITypeInfo* elem, std::string* why, bool byVa
     case GI_TYPE_TAG_UTF8:
     case GI_TYPE_TAG_FILENAME:
       return true;
+    // A gunichar is a 4-byte cell; only a C array writes one (no list/hash node).
+    case GI_TYPE_TAG_UNICHAR: return cArrayCell;
     case GI_TYPE_TAG_INTERFACE: {
       GIBaseInfo* iface = gi_type_info_get_interface(elem);
       bool ok = iface != nullptr && (GI_IS_OBJECT_INFO(iface) || GI_IS_INTERFACE_INFO(iface));
@@ -1178,7 +1180,8 @@ size_t CElementSize(GITypeInfo* elem) {
     case GI_TYPE_TAG_INT16:
     case GI_TYPE_TAG_UINT16: return 2;
     case GI_TYPE_TAG_INT32:
-    case GI_TYPE_TAG_UINT32: return 4;
+    case GI_TYPE_TAG_UINT32:
+    case GI_TYPE_TAG_UNICHAR: return 4;
     case GI_TYPE_TAG_INT64:
     case GI_TYPE_TAG_UINT64: return 8;
     case GI_TYPE_TAG_FLOAT: return sizeof(gfloat);
@@ -1601,16 +1604,16 @@ Napi::Value ReadOutOrReturn(Napi::Env env, GICallableInfo* callable, GITypeInfo*
 // the element, so it gets a ref (objects) or an independent copy (boxed) instead.
 // Throws + returns false on an unsupported element.
 static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v, GIArgument* a,
-                                GITransfer elemTransfer, bool wrapIntegers = false) {
+                                GITransfer elemTransfer, NodeGiIntContext intContext = NodeGiIntContext::kListElement,
+                                bool wrapIntegers = false) {
   memset(a, 0, sizeof(*a));
   switch (gi_type_info_get_tag(elem)) {
     // Scalar coercions via the terminate-safe helpers (common.h): a swallowed
     // napi failure mid worker.terminate() must degrade to a zero, not cascade
     // into Error::New(nullptr)'s fatal sites.
     case GI_TYPE_TAG_BOOLEAN: a->v_boolean = NodeGiToBool(v); return true;
-    // Integers WRAP here, in an array (arg.cpp gjs_array_to_auto_array) — see
-    // NodeGiJsToIntegerWrap (common.h). A GList/GHashTable element keeps the older
-    // coercion: gjs's rule for those is not probed yet.
+    // Integers WRAP in an array (arg.cpp gjs_array_to_auto_array, NodeGiJsToIntegerWrap in
+    // common.h) and are REFUSED out of range in a GList/GHashTable node.
     case GI_TYPE_TAG_INT8:
     case GI_TYPE_TAG_UINT8:
     case GI_TYPE_TAG_INT16:
@@ -1621,16 +1624,20 @@ static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v,
     case GI_TYPE_TAG_UINT64:
       if (wrapIntegers)
         return NodeGiJsToIntegerWrap(v, gi_type_info_get_tag(elem), a) == NodeGiIntResult::kOk;
-      switch (gi_type_info_get_tag(elem)) {
-        case GI_TYPE_TAG_INT8: a->v_int8 = static_cast<gint8>(NodeGiToInt32(v)); return true;
-        case GI_TYPE_TAG_UINT8: a->v_uint8 = static_cast<guint8>(NodeGiToUint32(v)); return true;
-        case GI_TYPE_TAG_INT16: a->v_int16 = static_cast<gint16>(NodeGiToInt32(v)); return true;
-        case GI_TYPE_TAG_UINT16: a->v_uint16 = static_cast<guint16>(NodeGiToUint32(v)); return true;
-        case GI_TYPE_TAG_INT32: a->v_int32 = NodeGiToInt32(v); return true;
-        case GI_TYPE_TAG_UINT32: a->v_uint32 = NodeGiToUint32(v); return true;
-        case GI_TYPE_TAG_INT64: a->v_int64 = JsValueToInt64(v); return true;
-        default: a->v_uint64 = JsValueToUint64(v); return true;
+      // A list/hash node is checked, not wrapped (arg.cpp gjs_value_to_basic_gi_argument
+      // -> gjs_arg_set_from_js_value): out of range is a plain Error.
+      switch (NodeGiJsToInteger(v, gi_type_info_get_tag(elem), a, nullptr)) {
+        case NodeGiIntResult::kPending: return false;
+        case NodeGiIntResult::kOutOfRange:
+          NodeGiThrowIntOutOfRange(env, gi_type_info_get_tag(elem), intContext, nullptr,
+                                   NodeGiDebugValue(v));
+          return false;
+        case NodeGiIntResult::kOk: return true;
       }
+      return true;
+    // gjs_array_to_auto_array<char32_t> wraps like uint32 (arg.cpp js_value_to_c_strict).
+    case GI_TYPE_TAG_UNICHAR:
+      return NodeGiJsToIntegerWrap(v, GI_TYPE_TAG_UINT32, a) == NodeGiIntResult::kOk;
     case GI_TYPE_TAG_FLOAT: a->v_float = static_cast<gfloat>(NodeGiToDouble(v)); return true;
     case GI_TYPE_TAG_DOUBLE: a->v_double = NodeGiToDouble(v); return true;
     case GI_TYPE_TAG_GTYPE: {
@@ -2267,6 +2274,20 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfe
     return true;
   }
 
+  // A JS string as a gunichar C array → its code points (arg.cpp:584, gjs_string_to_ucs4).
+  if (at == GI_ARRAY_TYPE_C && etag == GI_TYPE_TAG_UNICHAR && v.IsString()) {
+    std::string s = v.As<Napi::String>().Utf8Value();
+    glong n = 0;
+    gunichar* ucs = g_utf8_to_ucs4_fast(s.c_str(), static_cast<glong>(s.size()), &n);
+    void* buf = g_malloc0(elemSize * (n + (zt ? 1 : 0)));
+    if (n > 0) memcpy(buf, ucs, elemSize * n);
+    g_free(ucs);
+    *outPtr = buf;
+    *outCount = static_cast<long>(n);
+    gi_base_info_unref(elem);
+    return true;
+  }
+
   if (!v.IsArray()) {
     gi_base_info_unref(elem);
     Napi::TypeError::New(env, "expected an array for the array argument")
@@ -2301,7 +2322,7 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfe
     }
     GIArgument a;
     ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a, elemTransfer,
-                             /*wrapIntegers=*/true);
+                             NodeGiIntContext::kListElement, /*wrapIntegers=*/true);
     if (!ok) break;
     // Copy the element's storage bytes (LE: the low elemSize bytes of the union
     // alias the active field — v_string/v_pointer for pointers, the scalar
@@ -2448,7 +2469,8 @@ static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransf
     } else {
       GIArgument ka;
       Napi::Value keyNum = Napi::Number::New(env, static_cast<double>(g_ascii_strtoll(ks.c_str(), nullptr, 10)));
-      ok = ElementToGIArgument(env, kt, keyNum, &ka, GI_TRANSFER_NOTHING);
+      ok = ElementToGIArgument(env, kt, keyNum, &ka, GI_TRANSFER_NOTHING,
+                               NodeGiIntContext::kHashElement, /*wrapIntegers=*/true);
       if (!ok) break;
       kp = gi_type_info_hash_pointer_from_argument(kt, &ka);
     }
@@ -2459,7 +2481,7 @@ static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransf
     Napi::Value val = obj.Get(key);
     gpointer vp = nullptr;
     GIArgument va;
-    ok = ElementToGIArgument(env, vt, val, &va, elemTransfer);
+    ok = ElementToGIArgument(env, vt, val, &va, elemTransfer, NodeGiIntContext::kHashElement);
     if (!ok) {
       g_free(kp);
       break;

package/src/signals.cc

@@ -7,22 +7,36 @@ namespace nodegi {
 
 // ---- signals (milestone 1) ----
 //
-// A GClosure that wraps a JS callback. The callback is held by a strong
-// napi_ref; the closure's finalize notifier drops it. The generic marshal
-// converts the signal's GValue params to JS — the EMITTER instance (param 0)
-// first, then the signal's own params (1..n), matching GJS — and the JS return
-// into the signal return GValue.
+// A GClosure that wraps a JS callback. The closure's finalize notifier drops the
+// napi_ref. The generic marshal converts the signal's GValue params to JS — the
+// EMITTER instance (param 0) first, then the signal's own params (1..n), matching
+// GJS — and the JS return into the signal return GValue.
 //
-// Narrowed-leak semantics (with the toggle-ref bridge): a handler that does NOT
-// close over its own object is now collectable once C is the sole owner
-// (toggle-down → weak → GC). A handler that DOES close over its object forms a
-// GObject -> GClosure -> napi_ref -> callback -> wrapper -> handle cycle the GC
-// cannot break across C, so it keeps the object alive until disconnect — which is
-// the GJS-faithful contract (a connected self-referential handler is a reason to
-// stay alive). disconnect drops the closure's napi_ref (JsClosureFinalize),
-// breaking the cycle so the next GC collects the object. The callback ref stays
-// STRONG while connected (a connected handler must fire). Verified by the
-// signal-cycle case in test/gc-identity.test.mjs.
+// REF STRENGTH IS THE WHOLE CONTRACT, and it differs per closure KIND, exactly as
+// in GJS (refs/gjs/gi/closure.h: `create_marshaled` roots, `create_for_signal`
+// does not):
+//
+//   * GENERIC closure (a JS function marshalled as a GClosure IN-arg, invoked by
+//     arbitrary C) — STRONG. Nothing on the JS side owns it; the ref IS the owner.
+//   * SIGNAL closure (`.connect()`) and TEMPLATE-CALLBACK closure — WEAK. A
+//     handler that captures its own emitter otherwise forms a
+//     GObject → GClosure → napi_ref → callback → wrapper → toggle ref → GObject
+//     cycle that spans C, and no GC can break it: `obj.connect('x', () => obj.y)`
+//     made `obj` immortal. GJS has the identical cycle on paper and collects it,
+//     because its signal closures keep the callable UNROOTED and trace it from
+//     the owning wrapper (ObjectInstance::m_closures / trace_impl), which puts
+//     the whole cycle inside one heap the GC can reason about.
+//
+// node-gi has no tracing hook, so the equivalent edge is built in JS: index.js
+// retains the callback in a WeakMap keyed by the canonical handle — the only
+// ephemeron V8 offers over a non-extensible External, and the same shape
+// `associate_closure` has. The handle is reachable exactly when GJS would trace
+// the closure (JS holds the wrapper, or C owns the object and toggle.cc roots
+// it), so a connected handler still fires for as long as anything can emit to it,
+// and the self-referential cycle collects. A collected callback leaves the weak
+// ref empty and the marshal returns early (it already tolerates a null value).
+// Measured against gjs 1.88.1 with a FinalizationRegistry witness; verified by the
+// signal-cycle cases in test/gc-identity.test.mjs.
 
 struct JsClosureData {
   napi_env env;
@@ -191,8 +205,11 @@ static void JsGenericClosureMarshal(GClosure* closure, GValue* return_value, gui
 
 // JS function → a floating marshaled GClosure (the engine's twin of GJS's
 // Gjs::Closure::create_marshaled for "boxed" closure args — refs/gjs/gi/
-// arg-cache.cpp GClosureInTransferNone::in). The closure holds a strong ref to
-// the function; JsClosureFinalize drops it when the closure is invalidated /
+// arg-cache.cpp GClosureInTransferNone::in). The closure holds a STRONG ref to
+// the function — deliberately, and unlike the signal/template closures above:
+// `create_marshaled` defaults `root = true` (refs/gjs/gi/closure.h), because no
+// JS-side owner exists for a closure handed to arbitrary C. JsClosureFinalize
+// drops it when the closure is invalidated /
 // finalized (the callee released its last ref, or the invoke-site released the
 // only ref because the callee never kept one). Ref/sink + release policy lives at
 // the marshalling site (marshal.cc / calls.cc CreatedClosures).
@@ -231,9 +248,11 @@ Napi::Value ConnectSignal(const Napi::CallbackInfo& info) {
     return env.Null();
   }
 
+  // WEAK (refcount 0) — the keep-alive is the JS-side handle→callback edge
+  // index.js installs; see the ref-strength contract at the top of this file.
   JsClosureData* jc = g_new0(JsClosureData, 1);
   jc->env = env;
-  napi_create_reference(env, info[2], 1, &jc->callback);
+  napi_create_reference(env, info[2], 0, &jc->callback);
 
   GClosure* closure = g_closure_new_simple(sizeof(GClosure), jc);
   g_closure_set_marshal(closure, JsClosureMarshal);
@@ -468,13 +487,17 @@ static GClosure* NodeGiScopeCreateClosure(void* selfScope, void* builder,
   }
 
   // Wrap the resolved (instance-bound, arg-wrapping) JS function in a JsClosure —
-  // the same closure type a `.connect()` produces. The closure owns a strong ref to
-  // the function; g_object_watch_closure ties its lifetime to the widget (the
-  // handler `this`) and invalidates it when the widget is finalized, exactly like
+  // the same closure type a `.connect()` produces, and WEAK for the same reason:
+  // the resolver's dispatcher captures the widget handle, so a strong ref made
+  // every templated widget immortal. gi.js's resolveTemplateCallback retains the
+  // dispatcher on the widget handle before returning it, which is what GJS's Gtk
+  // override does with `Gi.associateClosure(lifetimeObject, …)`
+  // (refs/gjs/modules/core/overrides/Gtk.js). g_object_watch_closure additionally
+  // ties the closure to the widget and invalidates it on finalize, exactly like
   // GtkBuilderCScope's own create_closure.
   JsClosureData* jc = g_new0(JsClosureData, 1);
   jc->env = rawEnv;
-  napi_create_reference(rawEnv, resolved, 1, &jc->callback);
+  napi_create_reference(rawEnv, resolved, 0, &jc->callback);
   GClosure* closure = g_closure_new_simple(sizeof(GClosure), jc);
   g_closure_set_marshal(closure, JsClosureMarshal);
   g_closure_add_finalize_notifier(closure, jc, JsClosureFinalize);