@gjsify/node-gi 0.64.0 → 0.64.2

package/gi.js

@@ -7,6 +7,7 @@
 // Reference: gjs/modules/esm/gi.js for the require shape; node-gtk (romgrk, MIT) for the
 // binding lineage. Hand-authored JS — the package ships no build step.
 import * as native from './index.js';
+import { ensureNative, onNativeLoaded } from './index.js';
 // Timers, `process` and the windowing env record come from the host seam (host.node.js
 // explains why they are the runtime's own, not the globals; host.nativescript.js is the
 // NativeScript Android variant).
@@ -48,11 +49,21 @@ function camelToSnake(name) {
     return name.replace(/([A-Z])/g, '_$1').toLowerCase();
 }
 
+// Memoized: the wrapper's get/set/has traps convert on EVERY property access, the
+// answer depends on nothing but the name, and the set of names a program uses is
+// bounded by its source text — three regex passes per access buy nothing.
+const kebabNames = new Map();
+
 function toKebab(name) {
-    return name
-        .replace(/([A-Z])/g, '-$1')
-        .replace(/_/g, '-')
-        .toLowerCase();
+    let kebab = kebabNames.get(name);
+    if (kebab === undefined) {
+        kebab = name
+            .replace(/([A-Z])/g, '-$1')
+            .replace(/_/g, '-')
+            .toLowerCase();
+        kebabNames.set(name, kebab);
+    }
+    return kebab;
 }
 
 // Repeated passes of the same callback must marshal to the SAME native-facing function:
@@ -221,26 +232,10 @@ function wrapGError(handle, withPosition = false, hideAbove = wrapGError) {
 // domain must already name something, so `new GLib.Error()` is refused here rather
 // than producing a GError no `matches()` can ever hit.
 function newErrorLiteral(domain, code, message) {
-    const quark = toDomainQuark(domain);
-    if (native.callFunction('GLib', 'quark_to_string', [quark]) === null) {
+    if (native.callFunction('GLib', 'quark_to_string', [domain]) === null) {
         throw new TypeError(`Error.new_literal: ${domain} is not a valid domain`);
     }
-    return native.callStaticMethod('GLib', 'Error', 'new_literal', [quark, code, message]);
-}
-
-// GJS's uint32 conversion for a `domain` argument (gi/js-value-inl.h,
-// js_value_to_c_checked): `undefined` and a non-finite NUMBER become 0 silently,
-// anything else goes through ToNumber and is REFUSED when it misses uint32 range.
-// node-gi's own NodeGiToUint32 has no range check, so the node-gi-only spelling
-// `err.matches('g-io-error-quark', code)` converted to NaN→0 and quietly matched
-// nothing; GJS cannot run that line at all, so neither can this.
-function toDomainQuark(domain) {
-    if (domain === undefined || (typeof domain === 'number' && !Number.isFinite(domain))) return 0;
-    const quark = Number(domain);
-    if (Number.isNaN(quark) || quark < 0 || quark > 0xffffffff) {
-        throw new Error('Argument domain: value is out of range for uint32');
-    }
-    return quark >>> 0;
+    return native.callStaticMethod('GLib', 'Error', 'new_literal', [domain, code, message]);
 }
 
 // `GLib.Error`: a plain FUNCTION, not a `class … extends Error` — GJS's
@@ -303,7 +298,7 @@ Object.defineProperties(GLibError.prototype, {
                 `method GLib.Error.matches: At least 2 arguments required, but only ${arguments.length} passed`,
             );
         }
-        return native.callBoxedMethod(this[HANDLE], 'matches', [toDomainQuark(domain), code]);
+        return native.callBoxedMethod(this[HANDLE], 'matches', [domain, code]);
     }),
 });
 defineErrorFields(GLibError.prototype, 'GLib.Error', undefined);
@@ -366,17 +361,19 @@ function makeErrorDomainClass(namespace, typeName, members, quark) {
 // Called by the engine on a failed GI invoke, with ownership of the GError* already
 // transferred to the boxed handle. Named, so the position properties report the
 // application frame rather than this one.
-native.setErrorBuilder(function buildThrownGError(handle, quark, code, message) {
-    // Same cross-version pairing: an addon older than this JS calls the builder with
-    // the GError's FIELDS (domainName, quark, code, message) rather than a handle, and
-    // there is no second `errorClass` argument to give it. Rebuilding the GError from
-    // the fields keeps the ONE shape on that pairing too — it costs only the original
-    // GError's address, which nothing can read.
-    if (typeof handle === 'string') {
-        return wrapGError(newErrorLiteral(quark, code, message), true, buildThrownGError);
-    }
-    return wrapGError(handle, true, buildThrownGError);
-});
+onNativeLoaded(() =>
+    native.setErrorBuilder(function buildThrownGError(handle, quark, code, message) {
+        // Same cross-version pairing: an addon older than this JS calls the builder with
+        // the GError's FIELDS (domainName, quark, code, message) rather than a handle, and
+        // there is no second `errorClass` argument to give it. Rebuilding the GError from
+        // the fields keeps the ONE shape on that pairing too — it costs only the original
+        // GError's address, which nothing can read.
+        if (typeof handle === 'string') {
+            return wrapGError(newErrorLiteral(quark, code, message), true, buildThrownGError);
+        }
+        return wrapGError(handle, true, buildThrownGError);
+    }),
+);
 
 // Stamps a makeClass prototype with its { namespace, typeName } so Gio._promisify can
 // record WHICH introspected class a registration belongs to — matched against the
@@ -396,6 +393,13 @@ const promisifiedWrappers = new WeakSet();
 const nativeThunks = new WeakSet();
 
 function wrapReturn(value) {
+    // EVERY engine value comes through here — each return, each OUT tuple element and
+    // each signal argument (wrapSignalCallback) — and the five tag probes below are
+    // five N-API crossings. A handle is always an OBJECT (a tagged napi External), so a
+    // primitive can answer for itself: a `notify::label` handler's `(emitter, pspec)`
+    // then costs two probes for the emitter instead of ten for the pair, and the string
+    // argument of an ordinary `emit('changed', 'x')` costs none.
+    if (value === null || typeof value !== 'object') return value;
     if (native.isGObjectHandle(value)) return wrapInstance(value);
     // A GLib.Variant is ALSO a boxed handle by tag, so it must be checked first to get
     // the Variant ergonomics rather than a plain method-routing proxy.
@@ -442,7 +446,7 @@ function resolveTemplateCallback(handle, handlerName) {
         return desc.value.apply(proxy, args.map(wrapReturn));
     };
 }
-native.setTemplateCallbackResolver(resolveTemplateCallback);
+onNativeLoaded(() => native.setTemplateCallbackResolver(resolveTemplateCallback));
 
 // Run a registered class's JS constructor for a GObject the ENGINE instantiated from C
 // — typically a GtkBuilder composite-template InternalChild, which has no JS-`new` to
@@ -465,7 +469,7 @@ function runCtorForCObject(handle, gtypeName) {
         adoptHandle = prev;
     }
 }
-native.setConstructCallback(runCtorForCObject);
+onNativeLoaded(() => native.setConstructCallback(runCtorForCObject));
 
 // A non-GObject GObject-fundamental (GskRenderNode, GdkEvent) as an OPAQUE,
 // round-trippable handle: the native tagged External already carries the pointer and
@@ -543,36 +547,51 @@ function wrapBoxed(handle) {
 // GParamSpec-typed value surface as. Carries [HANDLE] so it round-trips back into the
 // engine and `instanceof GObject.ParamSpec` recognises it. value_type/owner_type are
 // native GType handles, like gjs's GType objects.
+// The accessors live HERE, on one shared prototype, and read the handle off `this`.
+// Built per instance they were eleven fresh closures plus a twelve-slot object on
+// EVERY notify emission — the engine hands the pspec to the handler whether or not
+// the handler looks at it, so that allocation landed on every property write of the
+// real-GObject engine. On gjs these same members live on GObject.ParamSpec.prototype,
+// so prototype-held is also the closer shape.
+const paramSpecProto = {
+    get name() {
+        return native.paramSpecProp(this[HANDLE], 'name');
+    },
+    get nick() {
+        return native.paramSpecProp(this[HANDLE], 'nick');
+    },
+    get blurb() {
+        return native.paramSpecProp(this[HANDLE], 'blurb');
+    },
+    get flags() {
+        return native.paramSpecProp(this[HANDLE], 'flags');
+    },
+    get value_type() {
+        return native.paramSpecProp(this[HANDLE], 'valueType');
+    },
+    get owner_type() {
+        return native.paramSpecProp(this[HANDLE], 'ownerType');
+    },
+    get default_value() {
+        return wrapReturn(native.paramSpecProp(this[HANDLE], 'defaultValue'));
+    },
+    get_name() {
+        return native.paramSpecProp(this[HANDLE], 'name');
+    },
+    get_nick() {
+        return native.paramSpecProp(this[HANDLE], 'nick');
+    },
+    get_blurb() {
+        return native.paramSpecProp(this[HANDLE], 'blurb');
+    },
+    get_default_value() {
+        return wrapReturn(native.paramSpecProp(this[HANDLE], 'defaultValue'));
+    },
+};
+
 function wrapParamSpec(handle) {
-    const prop = (which) => native.paramSpecProp(handle, which);
-    const pspec = {
-        [HANDLE]: handle,
-        get name() {
-            return prop('name');
-        },
-        get nick() {
-            return prop('nick');
-        },
-        get blurb() {
-            return prop('blurb');
-        },
-        get flags() {
-            return prop('flags');
-        },
-        get value_type() {
-            return prop('valueType');
-        },
-        get owner_type() {
-            return prop('ownerType');
-        },
-        get default_value() {
-            return wrapReturn(prop('defaultValue'));
-        },
-        get_name: () => prop('name'),
-        get_nick: () => prop('nick'),
-        get_blurb: () => prop('blurb'),
-        get_default_value: () => wrapReturn(prop('defaultValue')),
-    };
+    const pspec = Object.create(paramSpecProto);
+    pspec[HANDLE] = handle;
     return pspec;
 }
 
@@ -911,13 +930,50 @@ function decorateGioNamespace(baseNs) {
     });
 }
 
+// The internals of the PROXY links on an introspected prototype chain: the Proxy
+// itself -> its target plus the materializer its getOwnPropertyDescriptor trap runs
+// (`null` for a Proxy that traps no descriptor read). Registered by
+// makeClassPrototype and vfuncChainProto; read only by findProtoDescriptor.
+//
+// Why: a descriptor read THROUGH a Proxy costs ~110 ns of V8 invariant machinery on
+// top of the handler, and an introspected chain is mostly Proxies. Measured on the
+// bench's depth-3 subject, a full MISS walk took 328 ns — 154 ns on the
+// makeClassPrototype link, 65 ns on vfuncChainProto, 12 ns on the one plain link.
+// With the target in hand the same answer costs 27 ns, because the trap body is
+// exactly `materialize(prop); return Reflect.getOwnPropertyDescriptor(target, prop)`
+// and running it directly skips only the machinery, never a step of the computation.
+//
+// This is NOT a cache of the ANSWER: nothing is remembered between calls. The target
+// is the object every mutation of the prototype lands on — none of the handlers trap
+// `set`, `defineProperty`, `deleteProperty` or `setPrototypeOf`, so
+// `Cls.prototype.m = f`, `Object.defineProperty(…)`, `delete` and a spliced chain
+// write through to it — and the descriptor still comes from a fresh read of it. That
+// has to hold, because GJS pins nothing: on gjs 1.88.1 every one of those mutations
+// is observable on an already-wrapped instance (measured), so an answer cache would
+// need an invalidation signal JS does not offer. test/proto-descriptor-liveness.test.mjs
+// is the proof obligation.
+const protoInternals = new WeakMap();
+
 // Walk a JS prototype chain (excluding Object.prototype) for an own property
 // descriptor of `prop` — used to surface a registerClass subclass's own methods
-// /getters/setters on the GObject wrapper.
+// /getters/setters on the GObject wrapper. One full walk runs per property GET, per
+// SET and per `emit`, so the Proxy bypass above is on the hottest path there is.
 function findProtoDescriptor(proto, prop) {
-    for (let p = proto; p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
-        const d = Object.getOwnPropertyDescriptor(p, prop);
+    for (let p = proto; p !== null && p !== Object.prototype;) {
+        const internals = protoInternals.get(p);
+        if (internals === undefined) {
+            const d = Object.getOwnPropertyDescriptor(p, prop);
+            if (d !== undefined) return d;
+            p = Object.getPrototypeOf(p);
+            continue;
+        }
+        const { target, materialize } = internals;
+        if (materialize !== null) materialize(prop);
+        const d = Object.getOwnPropertyDescriptor(target, prop);
         if (d !== undefined) return d;
+        // The target's prototype, not the Proxy's: neither handler traps
+        // getPrototypeOf, so these are the same link — one fewer trap to pay.
+        p = Object.getPrototypeOf(target);
     }
     return undefined;
 }
@@ -1063,7 +1119,27 @@ function assignTemplateChildren(instance, handle, reg) {
 // resolves the same three spellings at the point of use instead — same reachability,
 // no accessor synthesis. Learn6502's SourceView is exactly why this matters: its
 // property is `line-numbers` and its accessor is `lineNumbers`.
+// Resolved per prototype, INCLUDING the "this class declares none" answer (null).
+// The native store calls runJsPropertySetter on every write of a custom property, so
+// without this a class with no accessor at all — the common case — paid three
+// prototype-chain walks and two regex rewrites per assignment to learn nothing. GJS
+// settles the same question once, at registerClass time (`_checkAccessors` mirrors
+// the declared spelling onto the other two); a prototype gaining an accessor later is
+// outside what either runtime honours.
+const propertySettersByProto = new WeakMap();
+
 function findPropertySetter(userProto, propertyName) {
+    let perProto = propertySettersByProto.get(userProto);
+    if (perProto === undefined) propertySettersByProto.set(userProto, (perProto = new Map()));
+    let setter = perProto.get(propertyName);
+    if (setter === undefined) {
+        setter = resolvePropertySetter(userProto, propertyName) ?? null;
+        perProto.set(propertyName, setter);
+    }
+    return setter ?? undefined;
+}
+
+function resolvePropertySetter(userProto, propertyName) {
     const underscored = propertyName.replace(/-/g, '_');
     const camel = propertyName.replace(/-([a-z])/g, (m) => m[1].toUpperCase());
     for (const spelling of [propertyName, underscored, camel]) {
@@ -1095,9 +1171,9 @@ function runJsPropertySetter(handle, propertyName) {
 // function` until the next release republishes the binary. Every native call added
 // here degrades instead; without the callback, a post-construction set simply does
 // not reach the JS setter, which is what 0.50.0 did.
-if (typeof native.setPropertySetCallback === 'function') {
-    native.setPropertySetCallback(runJsPropertySetter);
-}
+onNativeLoaded(() => {
+    if (typeof native.setPropertySetCallback === 'function') native.setPropertySetCallback(runJsPropertySetter);
+});
 
 // Which properties the construct-time replay must run.
 //
@@ -1306,6 +1382,7 @@ export function startMainContextPump() {
     // GLib's default main context — a JS-timer pump would only iterate the
     // context recursively from within its own dispatch.
     if (hostPumpsItself()) return () => {};
+    ensureNative();
     pumpRefCount++;
     if (pumpTimer === null) {
         if (pendingView === null) pendingView = native.makePumpPendingCount();
@@ -1548,6 +1625,30 @@ function wrapInstance(handle, userProto) {
         materialised.add(name);
         return had;
     };
+    // The `connect`/`connect_after`/`emit`/`disconnect` thunks of this wrapper, each
+    // built on its first use (see the `get` trap). A null prototype so an unrelated
+    // name — `constructor`, `toString` — cannot be mistaken for a built shortcut.
+    const signalShortcuts = Object.create(null);
+    // The GI-method thunks of this wrapper, built on first use, `null` for a name
+    // that resolves to no introspected method. A thunk is a pure function of
+    // (handle, name) and presence is already memoized per GType (instanceHasMethod),
+    // so the only thing that changes by keeping it is IDENTITY — and a STABLE one is
+    // the GJS shape: there the method lives on the prototype, so `obj.m === obj.m`
+    // (the reason a user prototype's own function is handed back unbound, #1175).
+    // Built fresh, every `obj.m(…)` in a loop allocated a closure and re-asked for
+    // the type name across the N-API boundary. Null prototype: `constructor` and
+    // friends must not read as a cached thunk.
+    const giMethodThunks = Object.create(null);
+    const giMethodThunk = (prop) => {
+        let thunk = giMethodThunks[prop];
+        if (thunk === undefined) {
+            thunk = instanceHasMethod(handle, prop)
+                ? (...args) => wrapReturn(native.callMethod(handle, prop, unwrapArgs(args)))
+                : null;
+            giMethodThunks[prop] = thunk;
+        }
+        return thunk ?? undefined;
+    };
     const proxy = new Proxy(target, {
         get(t, prop) {
             if (prop === HANDLE) return handle;
@@ -1561,10 +1662,16 @@ function wrapInstance(handle, userProto) {
                 // introspectable ancestor (GObject.Object), yet on gjs 1.88.1
                 // `socks5.connect` IS g_proxy_connect (Gio.Proxy, 3 IN args) — measured.
                 // The same native walk the GI-method fallback below uses sees it.
-                if (instanceHasMethod(handle, prop)) {
-                    return (...args) => wrapReturn(native.callMethod(handle, prop, unwrapArgs(args)));
-                }
+                const method = giMethodThunk(prop);
+                if (method !== undefined) return method;
             }
+            // The four signal shortcuts below close over nothing but `handle`, so they
+            // are per-wrapper constants — yet the switch rebuilt one on EVERY access,
+            // i.e. one throwaway closure per `obj.emit(…)` in a loop. Built once here
+            // and reused; on gjs these live on GObject.Object.prototype and have stable
+            // identity too. Lazy, because most wrappers never reach for one.
+            const shortcut = signalShortcuts[prop];
+            if (shortcut !== undefined) return shortcut;
             switch (prop) {
                 case '$typeName':
                     // The instance's concrete RUNTIME GType name —
@@ -1581,24 +1688,25 @@ function wrapInstance(handle, userProto) {
                 case 'connect':
                     // Record the (user fn → id) mapping so signal_handlers_*_by_func can
                     // resolve the private-closure handler back to its ids (see the registry).
-                    return (signal, cb) => {
+                    return (signalShortcuts.connect = (signal, cb) => {
                         const id = native.connectSignal(handle, signal, wrapSignalCallback(cb), false);
                         recordSignalHandler(handle, cb, id);
                         return id;
-                    };
+                    });
                 case 'connect_after':
-                    return (signal, cb) => {
+                    return (signalShortcuts.connect_after = (signal, cb) => {
                         const id = native.connectSignal(handle, signal, wrapSignalCallback(cb), true);
                         recordSignalHandler(handle, cb, id);
                         return id;
-                    };
+                    });
                 case 'emit':
-                    return (signal, ...args) => wrapReturn(native.emitSignal(handle, signal, unwrapArgs(args)));
+                    return (signalShortcuts.emit = (signal, ...args) =>
+                        wrapReturn(native.emitSignal(handle, signal, unwrapArgs(args))));
                 case 'disconnect':
-                    return (id) => {
+                    return (signalShortcuts.disconnect = (id) => {
                         forgetSignalHandlerId(handle, id);
                         return native.disconnectSignal(handle, id);
-                    };
+                    });
                 default:
                     break;
             }
@@ -1674,10 +1782,7 @@ function wrapInstance(handle, userProto) {
             // camelCase like Gwebgl's `getString`) and only falls back to the
             // snake_case alias. Converting here would destroy a literal camelCase
             // GI name.
-            if (instanceHasMethod(handle, prop)) {
-                return (...args) => wrapReturn(native.callMethod(handle, prop, unwrapArgs(args)));
-            }
-            return undefined;
+            return giMethodThunk(prop);
         },
         set(t, prop, value) {
             if (typeof prop === 'string') {
@@ -1748,7 +1853,8 @@ function wrapInstance(handle, userProto) {
 // the introspected parent's `vfunc_x` is a thunk into the actual C vtable entry.
 // Non-`vfunc_` lookups fall through to Object.prototype (so the base prototype
 // keeps its normal object behaviour).
-const vfuncChainProto = new Proxy(Object.create(Object.prototype), {
+const vfuncChainTarget = Object.create(Object.prototype);
+const vfuncChainProto = new Proxy(vfuncChainTarget, {
     get(target, prop, receiver) {
         if (typeof prop === 'string' && prop.startsWith('vfunc_')) {
             const vfuncName = prop.slice('vfunc_'.length);
@@ -1763,6 +1869,10 @@ const vfuncChainProto = new Proxy(Object.create(Object.prototype), {
         return Reflect.get(target, prop, receiver);
     },
 });
+// No descriptor trap here: a `vfunc_*` access is synthesized by `get` alone and was
+// never reported as a descriptor, so the walk's answer for this link always came from
+// the target. `null` materializer = "read the target, that is the whole trap".
+protoInternals.set(vfuncChainProto, { target: vfuncChainTarget, materialize: null });
 
 // Surface a lazy `$gtype` getter on an introspected class/struct ctor: the real
 // GObject GType (a node-gi GType handle), resolved on first read via the engine
@@ -1930,7 +2040,7 @@ function makeClassPrototype(namespace, typeName) {
         }
         return arity >= 0 && define(prop, makeGiMethod(where, prop, arity));
     };
-    return new Proxy(target, {
+    const proto = new Proxy(target, {
         get(t, prop, receiver) {
             materialize(prop);
             return Reflect.get(t, prop, receiver);
@@ -1943,6 +2053,10 @@ function makeClassPrototype(namespace, typeName) {
             return materialize(prop) || Reflect.has(t, prop);
         },
     });
+    // Let findProtoDescriptor run the descriptor trap's body directly on the target —
+    // same two steps, without V8's per-trap invariant checks (see protoInternals).
+    protoInternals.set(proto, { target, materialize });
+    return proto;
 }
 
 function makeClass(namespace, typeName) {
@@ -2462,6 +2576,8 @@ function paramSpecGTyped(type) {
 const ParamSpec = Object.freeze({
     string: paramSpecPlain('string'),
     boolean: paramSpecPlain('boolean'),
+    char: paramSpecRanged('char'),
+    uchar: paramSpecRanged('uchar'),
     int: paramSpecRanged('int'),
     uint: paramSpecRanged('uint'),
     int64: paramSpecRanged('int64'),
@@ -3126,6 +3242,7 @@ function mirrorWindowingEnvIntoCrt() {
  * @returns {Record<string, unknown>}
  */
 export function requireGi(namespace, version) {
+    ensureNative();
     native.requireNamespace(namespace, version);
     // The one moment the win32 CRT-environment mirror can run: the addon is loaded, so there
     // is a GLib to call, and nothing has built a font map or loaded a fontconfig

package/host.nativescript.js

@@ -44,6 +44,12 @@
 /** @type {'nativescript'} */
 export const RUNTIME = 'nativescript';
 
+/**
+ * Whether the addon may be loaded on first use instead of at import — see index.js.
+ * @type {boolean}
+ */
+export const LAZY_NATIVE = true;
+
 // Timers from the global scope: NativeScript has no node:timers, and there is no
 // GLib-backed replacement to avoid here. setImmediate is not a V8 builtin.
 export const setImmediate =

package/host.node.js

@@ -55,6 +55,12 @@ export const RUNTIME =
             ? 'deno'
             : 'node';
 
+/**
+ * Whether the addon may be loaded on first use instead of at import — see index.js.
+ * @type {boolean}
+ */
+export const LAZY_NATIVE = false;
+
 // GJS host mode: `GjsifyNapi.init()` installs the loader as
 // `globalThis.__gjsifyNapiLoadAddon` and re-installs it if another consumer (the
 // @gjsify/napi L1) already captured + deleted it. Needs the GjsifyNapi typelib