@gjsify/node-gi 0.64.0 → 0.64.2

package/src/calls.cc

@@ -1242,6 +1242,57 @@ static GIFunctionInfo* ResolveInstanceMethod(GIRepository* repo, GType gtype, GI
   return func;
 }
 
+// Resolved instance methods, keyed by the instance's concrete GType and the name
+// as JS spelled it. The resolution above is the expensive half of a GI call —
+// dup the default repository, walk the GType parents for the nearest
+// GIObjectInfo, then search own + interface + inherited method tables twice (the
+// literal name, then the snake_case alias) — and it repeats IDENTICALLY on every
+// call, because a typelib's method tables do not change at runtime. MEASURED on
+// this machine (gjs 1.88.1 / GLib 2.88.3): `set_property` on a registerClass
+// subclass cost 8224 ns through callMethod against 2815 ns for the same
+// g_object_set_property through setProperty — 5.4 µs of pure re-resolution per
+// call, which is most of what a property write on the real-GObject engine spends.
+//
+// Only a HIT is cached. A miss must stay uncached: namespaces load lazily, so a
+// name that resolves to nothing now can resolve after the typelib that declares
+// it is required — caching the miss would make load order change behaviour.
+//
+// The cache OWNS the ref it holds (GIFunctionInfos live as long as the process
+// anyway, and the entry count is bounded by the methods a program actually
+// calls); callers get a borrowed pointer and must not unref it. Written only
+// from the JS thread, like every other entry point here.
+static std::map<std::pair<GType, std::string>, GIFunctionInfo*> g_instanceMethodCache;
+
+// The resolution of ResolveInstanceMethod, memoized. Returns a BORROWED pointer
+// (never unref) or nullptr.
+static GIFunctionInfo* ResolveInstanceMethodCached(GType gtype, const std::string& method) {
+  const std::pair<GType, std::string> key(gtype, method);
+  auto it = g_instanceMethodCache.find(key);
+  if (it != g_instanceMethodCache.end()) return it->second;
+
+  GIRepository* repo = DupDefaultRepository();
+  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
+  GIFunctionInfo* func = nullptr;
+  if (objInfo != nullptr) {
+    func = ResolveInstanceMethod(repo, gtype, objInfo, method);
+    gi_base_info_unref(objInfo);
+  }
+  g_object_unref(repo);
+  if (func != nullptr) g_instanceMethodCache.emplace(key, func);
+  return func;
+}
+
+// Whether `gtype` has introspection info at all — the distinction callMethod
+// reports as "no introspection info for X" before it even looks for a method.
+static bool HasObjectInfo(GType gtype) {
+  GIRepository* repo = DupDefaultRepository();
+  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
+  const bool found = objInfo != nullptr;
+  if (objInfo != nullptr) gi_base_info_unref(objInfo);
+  g_object_unref(repo);
+  return found;
+}
+
 // callMethod(handle, methodName, args?: unknown[]) -> unknown
 // Resolve an instance method by walking the instance's GIObjectInfo (own +
 // implemented-interface methods at each level, then up the parent chain), then
@@ -1262,20 +1313,14 @@ Napi::Value CallMethod(const Napi::CallbackInfo& info) {
                                                               : Napi::Array::New(env, 0);
 
   GType gtype = G_OBJECT_TYPE(obj);
-  GIRepository* repo = DupDefaultRepository();
+  GIFunctionInfo* func = ResolveInstanceMethodCached(gtype, method);
 
-  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
-  if (objInfo == nullptr) {
-    g_object_unref(repo);
+  if (func == nullptr && !HasObjectInfo(gtype)) {
     Napi::Error::New(env, std::string("no introspection info for ") + G_OBJECT_TYPE_NAME(obj))
         .ThrowAsJavaScriptException();
     return env.Null();
   }
 
-  GIFunctionInfo* func = ResolveInstanceMethod(repo, gtype, objInfo, method);
-  gi_base_info_unref(objInfo);
-  g_object_unref(repo);
-
   if (func == nullptr) {
     // On a terminating env the method-name read (info[1].Utf8Value) degrades to
     // "" (a swallowed napi failure), so resolution misses and we land here — but
@@ -1290,15 +1335,13 @@ Napi::Value CallMethod(const Napi::CallbackInfo& info) {
     return env.Null();
   }
   if (!gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func))) {
-    gi_base_info_unref(func);
     Napi::TypeError::New(env, method + " is not an instance method").ThrowAsJavaScriptException();
     return env.Null();
   }
 
-  Napi::Value result =
-      InvokeFunctionInfo(env, func, obj, args, std::string(G_OBJECT_TYPE_NAME(obj)) + "." + method);
-  gi_base_info_unref(func);
-  return result;
+  // The cache owns `func`; this is a borrowed pointer.
+  return InvokeFunctionInfo(env, func, obj, args,
+                            std::string(G_OBJECT_TYPE_NAME(obj)) + "." + method);
 }
 
 // hasMethod(handle, methodName) -> boolean
@@ -1321,20 +1364,10 @@ Napi::Value HasMethod(const Napi::CallbackInfo& info) {
   if (obj == nullptr) return env.Null();
   std::string method = info[1].As<Napi::String>().Utf8Value();
 
-  GType gtype = G_OBJECT_TYPE(obj);
-  GIRepository* repo = DupDefaultRepository();
-  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
-  if (objInfo == nullptr) {
-    g_object_unref(repo);
-    return Napi::Boolean::New(env, false);
-  }
-  GIFunctionInfo* func = ResolveInstanceMethod(repo, gtype, objInfo, method);
-  gi_base_info_unref(objInfo);
-  g_object_unref(repo);
+  GIFunctionInfo* func = ResolveInstanceMethodCached(G_OBJECT_TYPE(obj), method);
   if (func == nullptr) return Napi::Boolean::New(env, false);
-  const bool invocable = gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func));
-  gi_base_info_unref(func);
-  return Napi::Boolean::New(env, invocable);
+  return Napi::Boolean::New(env,
+                            gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func)));
 }
 
 // hasClassMethod(namespace, typeName, methodName) -> boolean

package/src/class.cc

@@ -44,6 +44,8 @@ static GType UnwrapGType(Napi::Env env, Napi::Value v) {
 static GType TypeNameToGType(const std::string& t) {
   if (t == "string" || t == "utf8") return G_TYPE_STRING;
   if (t == "boolean" || t == "bool") return G_TYPE_BOOLEAN;
+  if (t == "char") return G_TYPE_CHAR;
+  if (t == "uchar") return G_TYPE_UCHAR;
   if (t == "int") return G_TYPE_INT;
   if (t == "uint") return G_TYPE_UINT;
   if (t == "int64") return G_TYPE_INT64;
@@ -95,6 +97,19 @@ static GParamSpec* BuildParamSpec(Napi::Env env, Napi::Object spec, std::string*
                                  : (def.IsNumber() ? NodeGiToBool(def) : FALSE);
     return g_param_spec_boolean(nm, nm, nm, d, flags);
   }
+  if (type == "char") {
+    return g_param_spec_char(nm, nm, nm, hasMin ? static_cast<gint8>(mn) : G_MININT8,
+                             hasMax ? static_cast<gint8>(mx) : G_MAXINT8,
+                             def.IsNumber() ? static_cast<gint8>(def.As<Napi::Number>().Int32Value()) : 0,
+                             flags);
+  }
+  if (type == "uchar") {
+    return g_param_spec_uchar(nm, nm, nm, hasMin ? static_cast<guint8>(mn) : 0,
+                              hasMax ? static_cast<guint8>(mx) : G_MAXUINT8,
+                              def.IsNumber() ? static_cast<guint8>(def.As<Napi::Number>().Uint32Value())
+                                             : 0,
+                              flags);
+  }
   if (type == "int") {
     return g_param_spec_int(nm, nm, nm, hasMin ? static_cast<gint>(mn) : G_MININT,
                             hasMax ? static_cast<gint>(mx) : G_MAXINT,

package/src/common.h

@@ -35,6 +35,7 @@
 #endif
 
 #ifndef _WIN32
+#include <cmath>
 #include <dlfcn.h>  // dlopen/dlsym the GtkWidgetClass template API (no GTK link)
 #endif
 #include <napi.h>
@@ -280,6 +281,180 @@ inline uint64_t JsValueToUint64(Napi::Value v) {
   return n.IsEmpty() ? 0 : static_cast<uint64_t>(n.Int64Value());
 }
 
+// IN integers, GJS-exact (refs/gjs/gi/js-value-inl.h, arg-inl.h): an integer tag
+// REFUSES an out-of-range value instead of wrapping it. The rule is not uniform and is
+// copied as is, never made stricter: 8/16-bit run ToInt32 first (so it wraps mod 2^32)
+// and then compare against the tag range; int32 is not checked at all; uint32 and the
+// 64-bit tags refuse what falls outside their range. undefined and a non-finite Number
+// become 0. `shown` receives the text GJS prints for the offending value.
+// kPending: a BigInt/Symbol hit ToNumber, the TypeError is already pending — the caller
+// must stop without throwing a second error.
+enum class NodeGiIntResult { kOk, kOutOfRange, kPending };
+inline NodeGiIntResult NodeGiJsToInteger(Napi::Value v, GITypeTag tag, GIArgument* out,
+                                         std::string* shown) {
+  const bool is64 = tag == GI_TYPE_TAG_INT64 || tag == GI_TYPE_TAG_UINT64;
+  if (is64 && v.IsBigInt()) {
+    bool lossless = false;
+    if (tag == GI_TYPE_TAG_INT64) {
+      out->v_int64 = v.As<Napi::BigInt>().Int64Value(&lossless);
+    } else {
+      out->v_uint64 = v.As<Napi::BigInt>().Uint64Value(&lossless);
+    }
+    if (!lossless && shown != nullptr) *shown = "0";
+    return lossless ? NodeGiIntResult::kOk : NodeGiIntResult::kOutOfRange;
+  }
+  Napi::Number n = v.ToNumber();
+  if (n.IsEmpty()) return NodeGiIntResult::kPending;
+  double d = n.DoubleValue();
+  switch (tag) {
+    case GI_TYPE_TAG_INT8:
+    case GI_TYPE_TAG_UINT8:
+    case GI_TYPE_TAG_INT16:
+    case GI_TYPE_TAG_UINT16: {
+      int32_t i = n.Int32Value();
+      int32_t lo = tag == GI_TYPE_TAG_INT8 ? INT8_MIN : tag == GI_TYPE_TAG_INT16 ? INT16_MIN : 0;
+      int32_t hi = tag == GI_TYPE_TAG_INT8 ? INT8_MAX : tag == GI_TYPE_TAG_UINT8 ? UINT8_MAX
+                   : tag == GI_TYPE_TAG_INT16 ? INT16_MAX : UINT16_MAX;
+      if (shown != nullptr) *shown = std::to_string(i);
+      if (i < lo || i > hi) return NodeGiIntResult::kOutOfRange;
+      if (tag == GI_TYPE_TAG_INT8) out->v_int8 = static_cast<int8_t>(i);
+      else if (tag == GI_TYPE_TAG_UINT8) out->v_uint8 = static_cast<uint8_t>(i);
+      else if (tag == GI_TYPE_TAG_INT16) out->v_int16 = static_cast<int16_t>(i);
+      else out->v_uint16 = static_cast<uint16_t>(i);
+      return NodeGiIntResult::kOk;
+    }
+    case GI_TYPE_TAG_INT32:
+      out->v_int32 = n.Int32Value();
+      return NodeGiIntResult::kOk;
+    case GI_TYPE_TAG_UINT32: {
+      bool zero = v.IsUndefined() || (v.IsNumber() && !std::isfinite(d));
+      if (zero) {
+        out->v_uint32 = 0;
+        return NodeGiIntResult::kOk;
+      }
+      if (shown != nullptr) *shown = std::to_string(d);
+      if (std::isnan(d) || d < 0 || d > static_cast<double>(UINT32_MAX))
+        return NodeGiIntResult::kOutOfRange;
+      out->v_uint32 = static_cast<uint32_t>(d);
+      return NodeGiIntResult::kOk;
+    }
+    case GI_TYPE_TAG_INT64: {
+      double t = std::isfinite(d) ? std::trunc(d) : 0;
+      if (t < -9223372036854775808.0 || t >= 9223372036854775808.0) {
+        if (shown != nullptr)
+          *shown = std::to_string(t < 0 ? INT64_MIN : INT64_MAX);
+        return NodeGiIntResult::kOutOfRange;
+      }
+      out->v_int64 = static_cast<int64_t>(t);
+      return NodeGiIntResult::kOk;
+    }
+    case GI_TYPE_TAG_UINT64: {
+      double t = std::isfinite(d) ? std::trunc(d) : 0;
+      if (t < 0 || t >= 18446744073709551616.0) {
+        if (shown != nullptr)
+          *shown = std::to_string(t < 0 ? uint64_t{0} : UINT64_MAX);
+        return NodeGiIntResult::kOutOfRange;
+      }
+      out->v_uint64 = static_cast<uint64_t>(t);
+      return NodeGiIntResult::kOk;
+    }
+    default:
+      return NodeGiIntResult::kOk;
+  }
+}
+
+enum class NodeGiIntContext { kArgument, kField, kReturnValue, kListElement, kHashElement };
+inline const char* NodeGiIntTagName(GITypeTag tag) {
+  switch (tag) {
+    case GI_TYPE_TAG_INT8: return "int8";
+    case GI_TYPE_TAG_UINT8: return "uint8";
+    case GI_TYPE_TAG_INT16: return "int16";
+    case GI_TYPE_TAG_UINT16: return "uint16";
+    case GI_TYPE_TAG_INT32: return "int32";
+    case GI_TYPE_TAG_UINT32: return "uint32";
+    case GI_TYPE_TAG_INT64: return "int64";
+    default: return "uint64";
+  }
+}
+// GJS's three texts (arg-cache.cpp / arg.cpp), plain Error.
+inline void NodeGiThrowIntOutOfRange(Napi::Env env, GITypeTag tag, NodeGiIntContext ctx,
+                                     const char* name, const std::string& shown) {
+  std::string t = NodeGiIntTagName(tag);
+  std::string msg;
+  if (ctx == NodeGiIntContext::kArgument) {
+    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 : "") + "'"
+               : 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 —
+// modulo 2^64 — for 64 bits; a BigInt takes ToBigInt64/ToBigUint64 (also modulo 2^64)
+// on a 64-bit tag and is a TypeError on a narrower one. kPending: that TypeError is
+// already pending, the caller must stop without throwing a second error.
+inline uint64_t NodeGiWrapToUint64(double d) {
+  if (!std::isfinite(d)) return 0;
+  double m = std::fmod(std::trunc(d), 18446744073709551616.0);
+  return m < 0 ? uint64_t{0} - static_cast<uint64_t>(-m) : static_cast<uint64_t>(m);
+}
+inline NodeGiIntResult NodeGiJsToIntegerWrap(Napi::Value v, GITypeTag tag, GIArgument* out) {
+  const bool is64 = tag == GI_TYPE_TAG_INT64 || tag == GI_TYPE_TAG_UINT64;
+  if (is64 && v.IsBigInt()) {
+    bool lossless = false;
+    out->v_uint64 = v.As<Napi::BigInt>().Uint64Value(&lossless);
+    return NodeGiIntResult::kOk;
+  }
+  Napi::Number n = v.ToNumber();
+  if (n.IsEmpty()) return NodeGiIntResult::kPending;
+  switch (tag) {
+    case GI_TYPE_TAG_INT8: out->v_int8 = static_cast<int8_t>(n.Int32Value()); break;
+    case GI_TYPE_TAG_UINT8: out->v_uint8 = static_cast<uint8_t>(n.Uint32Value()); break;
+    case GI_TYPE_TAG_INT16: out->v_int16 = static_cast<int16_t>(n.Int32Value()); break;
+    case GI_TYPE_TAG_UINT16: out->v_uint16 = static_cast<uint16_t>(n.Uint32Value()); break;
+    case GI_TYPE_TAG_INT32: out->v_int32 = n.Int32Value(); break;
+    case GI_TYPE_TAG_UINT32: out->v_uint32 = n.Uint32Value(); break;
+    case GI_TYPE_TAG_INT64:
+    case GI_TYPE_TAG_UINT64: out->v_uint64 = NodeGiWrapToUint64(n.DoubleValue()); break;
+    default: break;
+  }
+  return NodeGiIntResult::kOk;
+}
+
+// GValue char/uchar/int64/uint64: refused out of range with gjs_value_to_g_value's own
+// text (refs/gjs/gi/value.cpp:602-690, throw_expect_type), a plain Error. `what` is the
+// "expected" noun gjs prints; the offending value is its JS ToString.
+inline void NodeGiThrowGValueOutOfRange(Napi::Env env, Napi::Value v, const char* what) {
+  Napi::String s = v.ToString();
+  std::string shown = s.IsEmpty() ? std::string() : s.Utf8Value();
+  Napi::Error::New(env, std::string("Wrong type ") + (v.IsBigInt() ? "bigint" : "number") + "; " +
+                            what + " expected. But it's out of range: " + shown)
+      .ThrowAsJavaScriptException();
+}
+
 // OUT (WarnIfUnsafe{Int,Uint}64): GJS ALWAYS returns a JS Number for a 64-bit int
 // (never a BigInt) and emits this g_warning when the value falls outside the range
 // a double represents exactly (|v| > 2^53 - 1 == Number.MAX_SAFE_INTEGER), because
@@ -391,7 +566,8 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures = nullptr,
                     CreatedBytes* bytes = nullptr,
                     CreatedValues* values = nullptr,
-                    const char* argName = nullptr);
+                    const char* argName = nullptr,
+                    NodeGiIntContext intContext = NodeGiIntContext::kArgument);
 
 // ---- IN container building -----------------------------------------
 //

package/src/marshal.cc

@@ -516,7 +516,8 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures,
                     CreatedBytes* bytes,
                     CreatedValues* values,
-                    const char* argName) {
+                    const char* argName,
+                    NodeGiIntContext intContext) {
   if (v.IsEmpty()) {
     // Residue of a swallowed napi failure (a fallible Get()/coercion upstream
     // failed on a terminating env, or a throwing getter left the exception
@@ -536,16 +537,24 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
   GITypeTag tag = gi_type_info_get_tag(type);
   switch (tag) {
     case GI_TYPE_TAG_BOOLEAN: out->v_boolean = NodeGiToBool(v); return true;
-    case GI_TYPE_TAG_INT8: out->v_int8 = static_cast<int8_t>(NodeGiToInt32(v)); return true;
-    case GI_TYPE_TAG_UINT8: out->v_uint8 = static_cast<uint8_t>(NodeGiToUint32(v)); return true;
-    case GI_TYPE_TAG_INT16: out->v_int16 = static_cast<int16_t>(NodeGiToInt32(v)); return true;
-    case GI_TYPE_TAG_UINT16: out->v_uint16 = static_cast<uint16_t>(NodeGiToUint32(v)); return true;
-    case GI_TYPE_TAG_INT32: out->v_int32 = NodeGiToInt32(v); return true;
-    case GI_TYPE_TAG_UINT32: out->v_uint32 = NodeGiToUint32(v); return true;
-    // 64-bit: accept a BigInt losslessly (else a Number, truncated) — never let a
-    // BigInt reach ToNumber() (fatal abort). See JsValueTo{Int,Uint}64 in common.h.
-    case GI_TYPE_TAG_INT64: out->v_int64 = JsValueToInt64(v); return true;
-    case GI_TYPE_TAG_UINT64: out->v_uint64 = JsValueToUint64(v); return true;
+    case GI_TYPE_TAG_INT8:
+    case GI_TYPE_TAG_UINT8:
+    case GI_TYPE_TAG_INT16:
+    case GI_TYPE_TAG_UINT16:
+    case GI_TYPE_TAG_INT32:
+    case GI_TYPE_TAG_UINT32:
+    case GI_TYPE_TAG_INT64:
+    case GI_TYPE_TAG_UINT64: {
+      std::string shown;
+      switch (NodeGiJsToInteger(v, tag, out, &shown)) {
+        case NodeGiIntResult::kOk: return true;
+        case NodeGiIntResult::kPending: return false;
+        case NodeGiIntResult::kOutOfRange:
+          NodeGiThrowIntOutOfRange(env, tag, intContext, argName, shown);
+          return false;
+      }
+      return false;
+    }
     case GI_TYPE_TAG_FLOAT: out->v_float = static_cast<float>(NodeGiToDouble(v)); return true;
     case GI_TYPE_TAG_DOUBLE: out->v_double = NodeGiToDouble(v); return true;
     case GI_TYPE_TAG_UTF8:
@@ -1051,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));
@@ -1169,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);
@@ -1592,21 +1604,40 @@ 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) {
+                                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;
-    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;
-    case GI_TYPE_TAG_UINT64: a->v_uint64 = JsValueToUint64(v); return true;
+    // 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:
+    case GI_TYPE_TAG_UINT16:
+    case GI_TYPE_TAG_INT32:
+    case GI_TYPE_TAG_UINT32:
+    case GI_TYPE_TAG_INT64:
+    case GI_TYPE_TAG_UINT64:
+      if (wrapIntegers)
+        return NodeGiJsToIntegerWrap(v, gi_type_info_get_tag(elem), a) == NodeGiIntResult::kOk;
+      // 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: {
@@ -1814,7 +1845,10 @@ bool JsToAnswerArgument(Napi::Env env, Napi::Value v, GITypeInfo* ti, GITransfer
   }
   std::string held;
   return JsToGIArgument(env, v, ti, out, &held, transfer, nullptr, nullptr, nullptr, nullptr,
-                        argName);
+                        argName,
+                        argName != nullptr && strcmp(argName, "return value") == 0
+                            ? NodeGiIntContext::kReturnValue
+                            : NodeGiIntContext::kArgument);
 }
 
 }  // namespace
@@ -2240,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")
@@ -2273,7 +2321,8 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfe
       continue;
     }
     GIArgument a;
-    ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a, elemTransfer);
+    ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a, elemTransfer,
+                             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
@@ -2420,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);
     }
@@ -2431,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;
@@ -2973,7 +3023,8 @@ Napi::Value SetBoxedField(const Napi::CallbackInfo& info) {
   GIArgument arg;
   memset(&arg, 0, sizeof(arg));
   std::string heldString;
-  if (JsToGIArgument(env, value, ftype, &arg, &heldString, GI_TRANSFER_NOTHING, nullptr)) {
+  if (JsToGIArgument(env, value, ftype, &arg, &heldString, GI_TRANSFER_NOTHING, nullptr,
+                     nullptr, nullptr, nullptr, name.c_str(), NodeGiIntContext::kField)) {
     if (!gi_field_info_set_field(field, bh->ptr, &arg)) {
       Napi::Error::New(env, std::string("Writing field ") + typeName + "." + name + " is not supported")
           .ThrowAsJavaScriptException();

package/src/object.cc

@@ -444,17 +444,53 @@ bool JsToGValue(Napi::Env env, Napi::Value js, GValue* v) {
     // napi failure mid worker.terminate() must degrade to a zero, not cascade
     // into Error::New(nullptr)'s fatal sites (the terminate-mid-`newObject` path).
     case G_TYPE_BOOLEAN: g_value_set_boolean(v, NodeGiToBool(js)); return true;
-    case G_TYPE_CHAR: g_value_set_schar(v, static_cast<gint8>(NodeGiToInt32(js))); return true;
-    case G_TYPE_UCHAR: g_value_set_uchar(v, static_cast<guchar>(NodeGiToUint32(js))); return true;
-    case G_TYPE_INT: g_value_set_int(v, NodeGiToInt32(js)); return true;
-    case G_TYPE_UINT: g_value_set_uint(v, NodeGiToUint32(js)); return true;
-    // 64-bit (glong/gulong are 64-bit on LP64): accept a BigInt losslessly, else a
-    // truncated Number — never let a BigInt reach ToNumber(). Shared with the GI
-    // scalar marshaller via JsValueTo{Int,Uint}64 (common.h).
+    // char/uchar/int64/uint64 refuse an out-of-range value and int/uint wrap, as gjs's
+    // gjs_value_to_g_value does (value.cpp:602-690) — the same rule the constructor
+    // properties and signal arguments reach. A BigInt on a 32-bit tag is ToNumber's
+    // TypeError, left pending.
+    case G_TYPE_CHAR:
+    case G_TYPE_UCHAR:
+    case G_TYPE_INT64:
+    case G_TYPE_UINT64: {
+      GITypeTag tag = ft == G_TYPE_CHAR    ? GI_TYPE_TAG_INT8
+                      : ft == G_TYPE_UCHAR ? GI_TYPE_TAG_UINT8
+                      : ft == G_TYPE_INT64 ? GI_TYPE_TAG_INT64
+                                           : GI_TYPE_TAG_UINT64;
+      GIArgument a;
+      memset(&a, 0, sizeof(a));
+      switch (NodeGiJsToInteger(js, tag, &a, nullptr)) {
+        case NodeGiIntResult::kPending: return false;
+        case NodeGiIntResult::kOutOfRange:
+          NodeGiThrowGValueOutOfRange(env, js,
+                                      ft == G_TYPE_CHAR    ? "char"
+                                      : ft == G_TYPE_UCHAR ? "unsigned char"
+                                      : ft == G_TYPE_INT64 ? "64-bit integer"
+                                                           : "unsigned 64-bit integer");
+          return false;
+        case NodeGiIntResult::kOk: break;
+      }
+      if (ft == G_TYPE_CHAR) g_value_set_schar(v, a.v_int8);
+      else if (ft == G_TYPE_UCHAR) g_value_set_uchar(v, a.v_uint8);
+      else if (ft == G_TYPE_INT64) g_value_set_int64(v, a.v_int64);
+      else g_value_set_uint64(v, a.v_uint64);
+      return true;
+    }
+    case G_TYPE_INT:
+    case G_TYPE_UINT: {
+      GIArgument a;
+      memset(&a, 0, sizeof(a));
+      if (NodeGiJsToIntegerWrap(js, ft == G_TYPE_INT ? GI_TYPE_TAG_INT32 : GI_TYPE_TAG_UINT32,
+                                &a) == NodeGiIntResult::kPending)
+        return false;
+      if (ft == G_TYPE_INT) g_value_set_int(v, a.v_int32);
+      else g_value_set_uint(v, a.v_uint32);
+      return true;
+    }
+    // glong/gulong are 64-bit on LP64: accept a BigInt losslessly, else a truncated
+    // Number — never let a BigInt reach ToNumber(). Shared with the GI scalar marshaller
+    // via JsValueTo{Int,Uint}64 (common.h). gjs has no G_TYPE_LONG case here at all.
     case G_TYPE_LONG: g_value_set_long(v, static_cast<glong>(JsValueToInt64(js))); return true;
     case G_TYPE_ULONG: g_value_set_ulong(v, static_cast<gulong>(JsValueToUint64(js))); return true;
-    case G_TYPE_INT64: g_value_set_int64(v, JsValueToInt64(js)); return true;
-    case G_TYPE_UINT64: g_value_set_uint64(v, JsValueToUint64(js)); return true;
     case G_TYPE_FLOAT: g_value_set_float(v, static_cast<float>(NodeGiToDouble(js))); return true;
     case G_TYPE_DOUBLE: g_value_set_double(v, NodeGiToDouble(js)); return true;
     case G_TYPE_ENUM: g_value_set_enum(v, NodeGiToInt32(js)); return true;
@@ -611,7 +647,16 @@ Napi::Value ConstructGObject(Napi::Env env, GType gtype, Napi::Object props,
     }
     g_value_init(&values[i], pspec->value_type);
     initialised = i + 1;
-    if (!JsToGValue(env, props.Get(nameStorage[i]), &values[i])) {
+    Napi::Value propValue = props.Get(nameStorage[i]);
+    if (!propValue.IsEmpty() && propValue.IsUndefined()) {
+      // gjs refuses `undefined` for every property type (object.cpp:2090).
+      Napi::Error::New(env, "Invalid value 'undefined' for property " + std::string(pspec->name) +
+                                " in object initializer.")
+          .ThrowAsJavaScriptException();
+      ok = false;
+      break;
+    }
+    if (!JsToGValue(env, propValue, &values[i])) {
       ok = false;
       break;
     }
@@ -734,6 +779,30 @@ Napi::Value SetProperty(const Napi::CallbackInfo& info) {
     Napi::TypeError::New(env, "no such property '" + name + "'").ThrowAsJavaScriptException();
     return env.Undefined();
   }
+  // gjs refuses an out-of-range value for these property types on assignment
+  // (object.cpp, with its own text); JsToGValue below now refuses them too, with the
+  // gjs_value_to_g_value text.
+  GITypeTag intTag = GI_TYPE_TAG_VOID;
+  switch (G_TYPE_FUNDAMENTAL(pspec->value_type)) {
+    case G_TYPE_CHAR: intTag = GI_TYPE_TAG_INT8; break;
+    case G_TYPE_UCHAR: intTag = GI_TYPE_TAG_UINT8; break;
+    case G_TYPE_UINT: intTag = GI_TYPE_TAG_UINT32; break;
+    case G_TYPE_INT64: intTag = GI_TYPE_TAG_INT64; break;
+    case G_TYPE_UINT64: intTag = GI_TYPE_TAG_UINT64; break;
+    default: break;
+  }
+  if (intTag != GI_TYPE_TAG_VOID) {
+    GIArgument probe;
+    std::string shown;
+    NodeGiIntResult r = NodeGiJsToInteger(info[2], intTag, &probe, &shown);
+    if (r == NodeGiIntResult::kPending) return env.Undefined();
+    if (r == NodeGiIntResult::kOutOfRange) {
+      Napi::Error::New(env, "value " + shown + " is out of range for " + pspec->name +
+                                " (type " + NodeGiIntTagName(intTag) + ")")
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+  }
   GValue v = G_VALUE_INIT;
   g_value_init(&v, pspec->value_type);
   if (JsToGValue(env, info[2], &v)) {