@gjsify/node-gi 0.60.0 → 0.62.0

package/gi.js

@@ -12,6 +12,7 @@ import * as native from './index.js';
 // NativeScript Android variant).
 import { setImmediate, setInterval, clearInterval, runtimeProcess, windowingEnvWrites } from '#host';
 import { createGioDBus } from './overrides/gio-dbus.js';
+import { createGioSettings } from './overrides/gio-settings.js';
 
 // The raw native GObject handle on a wrapped instance, so it can be unwrapped again
 // when passed back into the engine as a GI argument.
@@ -120,7 +121,9 @@ function unwrapProps(props) {
 // An enum object's GError-domain descriptor ({ name, quark }), so GLib.Error.matches
 // can resolve an error-enum (Gio.IOErrorEnum) to the domain it represents. Attached by
 // makeEnum when the enum is registered as a GError domain.
-const ERROR_DOMAIN = Symbol('nodeGiErrorDomain');
+// A registry symbol, so a host-side stand-in for an enum the typelib lacks (Gtk.DialogError on
+// Android) can declare itself an error domain without importing this module.
+const ERROR_DOMAIN = Symbol.for('nodeGiErrorDomain');
 
 // GLib.Error, L1: the engine throws one of these on a failed sync GI invoke (via the
 // builder registered below) and `requireGi('GLib').Error` is this constructor, so a
@@ -204,6 +207,10 @@ const CLASS_INFO = Symbol('nodeGiClassInfo');
 // Gio.File.prototype) reaches the wrapper only through this registry; when two classes
 // promisify the SAME method name it picks the registration whose class the instance is-a.
 const promisifiedMethods = new Map();
+// Wrappers `_promisify` made, so a second `_promisify` of the same name does not take one for an override.
+const promisifiedWrappers = new WeakSet();
+// The introspected method thunks of makeGiMethod: present on a prototype, but never a user override.
+const nativeThunks = new WeakSet();
 
 function wrapReturn(value) {
     if (native.isGObjectHandle(value)) return wrapInstance(value);
@@ -685,9 +692,12 @@ function decorateGioNamespace(baseNs) {
         }
         return dbus;
     };
+    // Same laziness, for the same reason: patching Gio.Settings touches its prototype.
+    let settings;
     return new Proxy(baseNs, {
         get(t, prop) {
             if (prop === '_promisify') return promisify;
+            if (prop === 'Settings') return (settings ??= createGioSettings(t));
             if (prop === 'DBus') return getDBus().DBus;
             if (prop === 'DBusProxy') return getDBus().DBusProxy;
             if (prop === 'DBusExportedObject') return getDBus().DBusExportedObject;
@@ -1624,8 +1634,15 @@ function prototypeMethodHandle(self, where) {
 // GtkStack's takes 0` was this thunk, not the typelib.
 function makeGiMethod(where, method, arity) {
     const fn = function (...args) {
-        return wrapReturn(native.callMethod(prototypeMethodHandle(this, where), method, unwrapArgs(args)));
+        const handle = prototypeMethodHandle(this, where);
+        // Each class prototype materialises its INHERITED methods as its own thunks, so a
+        // `Gio._promisify(Gio.OutputStream.prototype, …)` is not on a FileOutputStream's chain;
+        // the registration is honoured here, where the instance is known.
+        const promisified = promisifiedMethods.size === 0 ? undefined : resolveRegistered(handle, method);
+        if (promisified !== undefined) return promisified.apply(this, args);
+        return wrapReturn(native.callMethod(handle, method, unwrapArgs(args)));
     };
+    nativeThunks.add(fn);
     Object.defineProperty(fn, 'name', { value: method, configurable: true });
     Object.defineProperty(fn, 'length', { value: arity, configurable: true });
     return fn;
@@ -1984,9 +2001,28 @@ function deriveFinishName(asyncName) {
 
 // Build the promisified wrapper for `asyncName`. Uses `this` (the instance proxy)
 // so it works both bound from the registry and as a prototype method.
-function makePromisified(asyncName, finishName) {
+//
+// `override` is a plain JS function already installed on the prototype under `asyncName`
+// (a test double, a subclass hook): GJS's _promisify wraps whatever the prototype holds at
+// that moment, so the wrapper drives the override instead of the native method.
+function makePromisified(asyncName, finishName, override = undefined) {
     const giAsync = camelToSnake(asyncName);
     return function promisified(...args) {
+        if (override !== undefined) {
+            if (args.length > 0 && typeof args[args.length - 1] === 'function') return override.apply(this, args);
+            const self = this;
+            return new Promise((resolve, reject) => {
+                override.call(self, ...args, (source, res) => {
+                    try {
+                        const value = (source ?? self)[finishName](res);
+                        if (Array.isArray(value) && value.length > 1 && value[0] === true) value.shift();
+                        resolve(value);
+                    } catch (error) {
+                        reject(error);
+                    }
+                });
+            });
+        }
         const handle = this[HANDLE];
         // A trailing callback → plain async method (the caller drives the callback).
         // Wrap it so its (source, result) args are marshalled to wrapped instances —
@@ -2044,7 +2080,16 @@ function promisify(proto, asyncName, finishName = undefined) {
         throw new TypeError('Gio._promisify: asyncName must be a string');
     }
     const finish = finishName === undefined ? deriveFinishName(asyncName) : finishName;
-    const wrapper = makePromisified(asyncName, finish);
+    // GJS refuses a missing method at the call, not at first use.
+    if (typeof proto[asyncName] !== 'function') throw new Error(`${proto} has no method named ${asyncName}`);
+    if (typeof proto[finish] !== 'function') throw new Error(`${proto} has no method named ${finish}`);
+    const present = Object.getOwnPropertyDescriptor(proto, asyncName)?.value;
+    const override =
+        typeof present === 'function' && !promisifiedWrappers.has(present) && !nativeThunks.has(present)
+            ? present
+            : undefined;
+    const wrapper = makePromisified(asyncName, finish, override);
+    promisifiedWrappers.add(wrapper);
     // Install on the prototype (so proto[asyncName] IS the promisified method, and a
     // registerClass subclass — which resolves its userProto — picks it up) AND in
     // the global registry (introspected instances resolve methods dynamically, with
@@ -2077,6 +2122,18 @@ function promisify(proto, asyncName, finishName = undefined) {
     }
 }
 
+// The registered wrapper for `methodName` only when the instance IS-A the class it was registered
+// on; unlike resolvePromisified there is no fallback, because a native thunk is already the
+// right call for every other class.
+function resolveRegistered(handle, methodName) {
+    const registrations = promisifiedMethods.get(methodName);
+    if (registrations === undefined) return undefined;
+    for (const r of registrations) {
+        if (r.namespace !== undefined && native.isInstanceOf(handle, r.namespace, r.typeName)) return r.wrapper;
+    }
+    return undefined;
+}
+
 // Resolve the promisified wrapper for `methodName` on an instance handle. The
 // common case is a single registration (fast path); when several classes
 // promisified the same method name, pick the one whose class the instance is-a.

package/overrides/gio-settings.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
+//
+// Adapted from GJS (refs/gjs/modules/core/overrides/Gio.js, "Override Gio.Settings and
+// Gio.SettingsSchema"). Copyright (c) GJS contributors. MIT OR LGPL-2.0-or-later.
+//
+// Why this exists: the C API of GSettings does not fail, it ABORTS. An unknown schema id or an
+// unknown key is a `g_error` (G_LOG_LEVEL_ERROR, fatal), so on a bare binding one typo kills the
+// process with no catchable error — measured on node-gi, GLib 2.88: `new Gio.Settings({schema_id:
+// 'no.such'})` and `s.get_int('nope')` both exit the process. GJS wraps both in a JS check that
+// throws; this is the same wrapper, so `try { … } catch` means the same on either runtime
+// (ADR 0099 conformance row `errors`).
+//
+// Two deliberate differences from the GJS override:
+//   • the constructor check is a Proxy `construct` trap — a node-gi class has no `_init` to wrap;
+//   • `set_int` / `set_uint` range-check their value, which in GJS is the argument marshaller's
+//     job. node-gi's marshaller wraps modulo 2^32 (`set_uint('k', -1)` stores 4294967295), a
+//     general divergence recorded in status/open-todos/node-gi.md; this keeps the settings
+//     surface honest without touching the addon, so it also holds in an already-built payload.
+
+const INT32_MIN = -(2 ** 31);
+const INT32_MAX = 2 ** 31 - 1;
+const UINT32_MAX = 2 ** 32 - 1;
+
+const CHECKED = [
+    'get_boolean',
+    'set_boolean',
+    'get_double',
+    'set_double',
+    'get_enum',
+    'set_enum',
+    'get_flags',
+    'set_flags',
+    'get_int',
+    'set_int',
+    'get_int64',
+    'set_int64',
+    'get_string',
+    'set_string',
+    'get_strv',
+    'set_strv',
+    'get_uint',
+    'set_uint',
+    'get_uint64',
+    'set_uint64',
+    'get_value',
+    'set_value',
+    'bind',
+    'bind_writable',
+    'create_action',
+    'get_default_value',
+    'get_user_value',
+    'is_writable',
+    'reset',
+];
+
+/** The range a setter's JS number must be in; GJS's marshaller throws this exact message. */
+const RANGES = {
+    set_int: [INT32_MIN, INT32_MAX, 'int32'],
+    set_uint: [0, UINT32_MAX, 'uint32'],
+};
+
+/**
+ * Patch `Gio.Settings` / `Gio.SettingsSchema` like GJS does, once, and return the class to hand
+ * out (a Proxy whose `new` refuses a schema that is not installed instead of aborting).
+ * @param {{ Settings: any, SettingsSchema: any, SettingsSchemaSource: any }} Gio the introspected namespace
+ */
+export function createGioSettings(Gio) {
+    const Settings = Gio.Settings;
+    const schemaProto = Gio.SettingsSchema.prototype;
+    const proto = Settings.prototype;
+
+    const realGetKey = schemaProto.get_key;
+    schemaProto.get_key = function get_key(key) {
+        if (!this.has_key(key)) throw new Error(`GSettings key ${key} not found in schema ${this.get_id()}`);
+        return realGetKey.call(this, key);
+    };
+
+    // The key and child lists are per instance and a schema's keys never change, so one read each.
+    const keysOf = new WeakMap();
+    const childrenOf = new WeakMap();
+    const checkKey = (self, key) => {
+        let keys = keysOf.get(self);
+        if (keys === undefined) keysOf.set(self, (keys = self.settings_schema.list_keys()));
+        if (!keys.includes(key)) throw new Error(`GSettings key ${key} not found in schema ${self.schema_id}`);
+    };
+
+    for (const name of CHECKED) {
+        const real = proto[name];
+        if (typeof real !== 'function') continue;
+        const range = RANGES[name];
+        proto[name] = function (key, ...args) {
+            checkKey(this, key);
+            if (range !== undefined) {
+                const [min, max, type] = range;
+                const value = args[0];
+                if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+                    throw new Error(`Argument value: value is out of range for ${type}`);
+                }
+            }
+            return real.call(this, key, ...args);
+        };
+    }
+
+    const realGetChild = proto.get_child;
+    proto.get_child = function get_child(name) {
+        let children = childrenOf.get(this);
+        if (children === undefined) childrenOf.set(this, (children = this.list_children()));
+        if (!children.includes(name)) {
+            throw new Error(`Child ${name} not found in GSettings schema ${this.schema_id}`);
+        }
+        return realGetChild.call(this, name);
+    };
+
+    // A boxed instance is a Proxy over a handle with no prototype link to its class, so
+    // `instanceof Gio.SettingsSchema` is false for the very schema `lookup` returned. Recognise it
+    // by the methods the constructor needs instead.
+    const isSchema = (value) =>
+        value instanceof Gio.SettingsSchema ||
+        (value !== null &&
+            typeof value === 'object' &&
+            typeof value.get_id === 'function' &&
+            typeof value.list_keys === 'function');
+
+    return new Proxy(Settings, {
+        // Read with the class itself as receiver: node-gi's class Proxy hides `$gtype` from any
+        // other receiver (so a subclass does not inherit its base's), which would include this one.
+        get(target, prop) {
+            return Reflect.get(target, prop);
+        },
+        construct(target, args) {
+            const props = args[0] ?? {};
+            const schemaIdProp = ['schema', 'schema-id', 'schema_id', 'schemaId'].find((p) => p in props);
+            const schemaProp = ['settings-schema', 'settings_schema', 'settingsSchema'].find((p) => p in props);
+            if (!schemaIdProp && !schemaProp) {
+                throw new Error("One of property 'schema-id' or 'settings-schema' are required for Gio.Settings");
+            }
+            if (schemaProp && !isSchema(props[schemaProp])) {
+                throw new Error(`Value of property '${schemaProp}' is not of type Gio.SettingsSchema`);
+            }
+            const schema = schemaProp
+                ? props[schemaProp]
+                : Gio.SettingsSchemaSource.get_default()?.lookup(props[schemaIdProp], true);
+            if (!schema) throw new Error(`GSettings schema ${props[schemaIdProp]} not found`);
+            const schemaPath = schema.get_path();
+            if (props.path === undefined && !schemaPath) {
+                throw new Error(`Attempting to create schema '${schema.get_id()}' without a path`);
+            }
+            if (props.path !== undefined && schemaPath && props.path !== schemaPath) {
+                throw new Error(`GSettings created for path '${props.path}', but schema specifies '${schemaPath}'`);
+            }
+            // newTarget stays the real class: a node-gi class is an exotic constructor, and the
+            // Proxy must not become the `new.target` its wrapper builds the instance from.
+            return Reflect.construct(target, args);
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",

package/src/calls.cc

@@ -46,6 +46,10 @@ struct NodeGiCallback {
   // immortal: GDK leaves a ~1 s repeating timeout armed, so the context reports
   // work forever while nothing is ever ready to dispatch.
   bool pumpCounted = false;
+  // IN containers (typed-array `contents`, string arrays) of the call that armed a scope=async
+  // callback. The callee reads them until the operation completes, so they outlive the invoke and
+  // are released with the callback — `g_file_replace_contents_async` wrote freed memory otherwise.
+  std::vector<InContainer> heldContainers;
 };
 
 static void NodeGiCallbackPumpRelease(NodeGiCallback* cb) {
@@ -58,6 +62,7 @@ static void NodeGiCallbackPumpRelease(NodeGiCallback* cb) {
 static void NodeGiCallbackFree(NodeGiCallback* cb) {
   if (cb == nullptr) return;
   NodeGiCallbackPumpRelease(cb);  // never fired (error/teardown path)
+  for (const InContainer& c : cb->heldContainers) FreeInContainer(c);
   if (cb->jsFn != nullptr) napi_delete_reference(cb->env, cb->jsFn);
   if (cb->closure != nullptr) gi_callable_info_destroy_closure(cb->info, cb->closure);
   if (cb->info != nullptr) gi_base_info_unref(cb->info);
@@ -965,6 +970,16 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   if (!success) {
     for (NodeGiCallback* cb : created) NodeGiCallbackPumpRelease(cb);
   }
+  // The IN containers of an async call stay alive until its callback is released.
+  if (success) {
+    for (NodeGiCallback* cb : created) {
+      if (cb->scope == GI_SCOPE_TYPE_ASYNC) {
+        cb->heldContainers = std::move(inContainers);
+        inContainers.clear();
+        break;
+      }
+    }
+  }
   // Call-scope closures are only valid for the duration of the invoke; free them
   // now (notified/async closures are owned by the callee / self-freeing).
   for (NodeGiCallback* cb : callScope) NodeGiCallbackFree(cb);