@gtkx/runtime 1.5.0 → 1.6.0

package/src/register-class.ts

@@ -45,6 +45,7 @@ import {
     TYPE_NONE,
     type TypedClass,
     typeFundamental,
+    typeInterfacePrerequisites,
     typeInterfaces,
     typeIsA,
     typeName,
@@ -195,7 +196,7 @@ type SignalSpec = {
     /** GType of the value an emission returns, defaulting to none. */
     returnType?: SignalGType;
     /**
-     * How the emission combines what its handlers return, limited to the two accumulators GObject
+     * How the emission combines what its handlers return, limited to the accumulators GObject
      * ships: `"first-wins"` stops the emission at the first handler and keeps its result, and
      * `"true-handled"` runs handlers until one returns `true`, which requires a boolean
      * `returnType`. Without one, every handler runs and the last result stands.
@@ -316,7 +317,7 @@ type RegisterClassOptions<
      * in lowercase letters, digits, `-` and `_`, and be new to the type: one an ancestor type or a
      * listed interface already carries throws, and so does one carrying an uppercase letter, which
      * GObject would carry under that exact spelling, out of reach of both its dashed spelling and
-     * its `on<SignalName>` default handler. The two word separators spell the same signal, so a
+     * its `on<SignalName>` default handler. Either word separator spells the same signal, so a
      * signal declared as `data_changed` is connected to and emitted as `data-changed` too.
      *
      * Instances connect and emit by name through the same `connect`, `on`, `once`, `off` and
@@ -381,6 +382,7 @@ const PROPERTY_VFUNC_SPECS: PropertyVfuncSpec[] = [
 ];
 
 const PROPERTY_VFUNC_NAMES: Set<string> = new Set(PROPERTY_VFUNC_SPECS.map((spec) => spec.methodName));
+const VFUNC_METHOD_PATTERN = /^vfunc[A-Z0-9]/;
 const TYPE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9\-_+]{2,}$/;
 const UPPER_CASE_PATTERN = /[A-Z]/;
 const SIGNAL_OVERRIDE_PATTERN = /^on[A-Z]/;
@@ -456,6 +458,7 @@ function registerClass(klass: AnyClass, options: AnyRegisterClassOptions = {}):
 
     const name = resolveTypeName(klass, options);
     const declaredTypes = resolveInterfaceTypes(klass, options.implements ?? []);
+    assertInterfacePrerequisites(klass, parentType, declaredTypes);
     const adoptedTypes = declaredTypes.filter((gtype) => !typeIsA(parentType, gtype));
     const properties = options.properties ?? {};
     const signals = resolveDeclaredSignals(klass, options.signals ?? {});
@@ -471,6 +474,7 @@ function registerClass(klass: AnyClass, options: AnyRegisterClassOptions = {}):
 
     const claimedMethodNames = new Set(classVfuncs.map((vfunc) => vfunc.methodName));
     const interfaceBindings = discoverInterfaceBindings(methods, parentType, declaredTypes, claimedMethodNames);
+    assertClaimedVfuncs(klass, methods, claimedMethodNames, interfaceBindings);
 
     const nativeOptions = withNativeSignals(
         toNativeOptions(classVfuncs, interfaceBindings, properties, options),
@@ -677,6 +681,61 @@ function wrapVfunc(
     );
 }
 
+const claimedVfuncNames = (
+    claimedMethodNames: Set<string>,
+    interfaceBindings: InterfaceVfuncBinding[],
+): Set<string> => {
+    const claimed = new Set(claimedMethodNames);
+
+    for (const binding of interfaceBindings) {
+        for (const vfunc of binding.vfuncs) {
+            claimed.add(vfunc.methodName);
+        }
+    }
+
+    return claimed;
+};
+
+const isPrerequisiteMet = (parentType: bigint, declaredTypes: bigint[], prerequisite: bigint): boolean =>
+    typeIsA(parentType, prerequisite) || declaredTypes.includes(prerequisite);
+
+function assertPrerequisitesFor(klass: AnyClass, parentType: bigint, declaredTypes: bigint[], iface: bigint): void {
+    for (const prerequisite of typeInterfacePrerequisites(iface)) {
+        if (!isPrerequisiteMet(parentType, declaredTypes, prerequisite)) {
+            throw new TypeError(
+                `registerClass: ${klass.name} does not meet prerequisite ` +
+                `'${typeName(prerequisite) ?? String(prerequisite)}' of interface ` +
+                `'${typeName(iface) ?? String(iface)}'`,
+            );
+        }
+    }
+}
+
+function assertInterfacePrerequisites(klass: AnyClass, parentType: bigint, declaredTypes: bigint[]): void {
+    for (const iface of declaredTypes) {
+        assertPrerequisitesFor(klass, parentType, declaredTypes, iface);
+    }
+}
+
+function assertClaimedVfuncs(
+    klass: AnyClass,
+    methods: MethodTable,
+    claimedMethodNames: Set<string>,
+    interfaceBindings: InterfaceVfuncBinding[],
+): void {
+    const claimed = claimedVfuncNames(claimedMethodNames, interfaceBindings);
+
+    for (const methodName of methods.keys()) {
+        if (VFUNC_METHOD_PATTERN.test(methodName) && !claimed.has(methodName)) {
+            throw new Error(
+                `registerClass: ${klass.name}.${methodName} matches no vtable slot on any ancestor ` +
+                "or implemented interface, so the override would never be called; check the name against " +
+                "the parent class's virtual methods",
+            );
+        }
+    }
+}
+
 function discoverInterfaceBindings(
     methods: MethodTable,
     parentGtype: bigint,

package/src/registry.ts

@@ -10,11 +10,12 @@ import {
     setWrapper,
 } from "@gtkx/native";
 import { type AnyClass, walkClassChain } from "@gtkx/utils";
-import { copyLayerMembers, type Mixin, type MixinReceiver } from "./mixin.js";
+import { copyLayerMembers, installMixins, type Mixin, type MixinReceiver } from "./mixin.js";
 import {
     TYPE_INVALID,
     TYPE_OBJECT,
     type TypedClass,
+    typeFundamental,
     typeInterfaces,
     typeIsA,
     typeName,
@@ -31,6 +32,22 @@ import {
 type StaticBase<C, K extends PropertyKey> = Omit<C, K> &
     (C extends abstract new (...args: infer A) => infer R ? abstract new (...args: A) => R : never);
 
+/**
+ * Static side of class `C` with its construct signature retargeted to produce `I`. A generated
+ * wrapper class is declared locally and exported as a registered constant; its instance type is
+ * exported as an interface extending the local class so declaration merging and module
+ * augmentation keep working, and this type makes constructing the constant produce that interface.
+ */
+type WrapperClass<C, I> = Omit<C, "prototype"> & {
+    /** Prototype retyped to the exported instance interface, so `instanceof` narrows to it. */
+    prototype: I;
+} &
+(C extends new (...args: infer A) => unknown
+    ? new (...args: A) => I
+    : C extends abstract new (...args: infer A) => unknown
+        ? abstract new (...args: A) => I
+        : never);
+
 /** One overridable vtable slot: where it sits in the vtable struct and how it is marshalled. */
 type VfuncDescriptor = {
     /** GIR name of the type struct holding the slot, without its namespace, such as `WidgetClass`. */
@@ -374,6 +391,31 @@ function registerInterface(cls: AnyClass, type: bigint, mixin: Mixin, layout?: I
     }
 }
 
+/**
+ * Copies the members of registered interfaces onto a wrapper class, resolving each interface's
+ * mixin through the registry rather than taking the mixin itself, so a class states which
+ * interfaces it implements by referencing their classes. The interfaces must already be
+ * registered through `registerInterface`; generated code guarantees that by declaring interfaces
+ * ahead of the classes that implement them.
+ *
+ * @param cls Wrapper class adopting the interfaces.
+ * @param interfaces Registered interface classes to adopt, in order.
+ * @throws If an entry is not a registered interface.
+ */
+function installInterfaces(cls: AnyClass, interfaces: AnyClass[]): void {
+    const mixins = interfaces.map((iface) => {
+        const mixin = getInterfaceMixin(getClassType(iface));
+
+        if (mixin === undefined) {
+            throw new Error(`installInterfaces: ${iface.name} is not a registered interface`);
+        }
+
+        return mixin;
+    });
+
+    installMixins(cls, mixins);
+}
+
 /**
  * Wraps a native handle in a JS wrapper instance. With no class, resolves and
  * reuses the wrapper for the handle's runtime GType (composing interface mixins),
@@ -443,6 +485,23 @@ function getWrapperClass(type: bigint): AnyClass {
     return cls;
 }
 
+function getExactWrapperClass(type: bigint, label?: string): AnyClass {
+    if (type === TYPE_INVALID) {
+        throw new Error(`No GType is registered under '${label ?? String(type)}'`);
+    }
+
+    const cls = classRegistry.get(type);
+
+    if (cls === undefined) {
+        throw new Error(
+            `No wrapper class is registered for '${label ?? typeName(type) ?? String(type)}': ` +
+            "its module was dropped from the bundle or never imported",
+        );
+    }
+
+    return cls;
+}
+
 function resolveWrapperClass(type: bigint): AnyClass | null {
     let currentType = type;
 
@@ -491,7 +550,35 @@ function createComposedClass(base: AnyClass, runtimeType: bigint): AnyClass {
     return applied.size === 0 ? base : cls;
 }
 
-function resolveComposedClass(runtimeType: bigint): AnyClass | null {
+function isWrappableBase(fallbackType: bigint): boolean {
+    return fallbackType === TYPE_INVALID || typeFundamental(fallbackType) === TYPE_OBJECT;
+}
+
+function isBetweenWalkAndRuntime(fallbackType: bigint, walkedType: bigint, runtimeType: bigint): boolean {
+    return fallbackType !== walkedType && typeIsA(fallbackType, walkedType) && typeIsA(runtimeType, fallbackType);
+}
+
+function chooseWrapBase(walked: AnyClass | null, fallback: AnyClass | undefined, runtimeType: bigint): AnyClass | null {
+    if (fallback === undefined || !isWrappableBase(getClassType(fallback))) {
+        return walked;
+    }
+
+    if (walked === null || isBetweenWalkAndRuntime(getClassType(fallback), getClassType(walked), runtimeType)) {
+        return fallback;
+    }
+
+    return walked;
+}
+
+function stampComposedClass(composed: AnyClass, runtimeType: bigint): AnyClass {
+    setClassType(composed, runtimeType);
+    wrapperClasses.add(composed);
+    composedClassRegistry.set(runtimeType, composed);
+
+    return composed;
+}
+
+function resolveComposedClass(runtimeType: bigint, fallbackClass?: () => AnyClass): AnyClass | null {
     const exact = classRegistry.get(runtimeType);
 
     if (exact) {
@@ -504,7 +591,8 @@ function resolveComposedClass(runtimeType: bigint): AnyClass | null {
         return cached;
     }
 
-    const base = resolveWrapperClass(runtimeType);
+    const walked = resolveWrapperClass(runtimeType);
+    const base = chooseWrapBase(walked, fallbackClass?.(), runtimeType);
 
     if (base === null) {
         return null;
@@ -512,37 +600,37 @@ function resolveComposedClass(runtimeType: bigint): AnyClass | null {
 
     const composed = createComposedClass(base, runtimeType);
 
-    if (composed === base) {
-        return base;
+    if (composed !== base) {
+        return stampComposedClass(composed, runtimeType);
     }
 
-    setClassType(composed, runtimeType);
-    wrapperClasses.add(composed);
-    composedClassRegistry.set(runtimeType, composed);
+    if (base === walked) {
+        return base;
+    }
 
-    return composed;
+    return stampComposedClass(class extends base {}, runtimeType);
 }
 
-function wrapObject(value: unknown): object | null {
-    return value == null ? null : getOrCreateWrapper(value as ExternalObject<Handle>);
+function wrapObject(value: unknown, fallbackClass?: () => AnyClass): object | null {
+    return value == null ? null : getOrCreateWrapper(value as ExternalObject<Handle>, fallbackClass);
 }
 
-function wrapCallScopedObject(value: unknown): object | null {
-    return value == null ? null : wrapperFor(value as ExternalObject<Handle>, bindCallScopedWrapper);
+function wrapCallScopedObject(value: unknown, fallbackClass?: () => AnyClass): object | null {
+    return value == null ? null : wrapperFor(value as ExternalObject<Handle>, bindCallScopedWrapper, fallbackClass);
 }
 
 function existingWrapperFor(handle: ExternalObject<Handle>): object | null {
     return handleMap.has(handle) ? handle : getWrapper(handle);
 }
 
-function createWrapper(handle: ExternalObject<Handle>): object {
+function createWrapper(handle: ExternalObject<Handle>, fallbackClass?: () => AnyClass): object {
     const runtimeType: bigint = getType(handle);
 
     if (runtimeType === TYPE_INVALID) {
         throw new Error("Cannot resolve runtime GLib type from handle");
     }
 
-    const cls = resolveComposedClass(runtimeType);
+    const cls = resolveComposedClass(runtimeType, fallbackClass);
 
     if (!cls) {
         throw new Error(`Expected registered GLib type, got type ${String(runtimeType)}`);
@@ -551,21 +639,21 @@ function createWrapper(handle: ExternalObject<Handle>): object {
     return Object.create(cls.prototype) as object;
 }
 
-function wrapperFor(handle: ExternalObject<Handle>, bind: WrapperBinding): object {
+function wrapperFor(handle: ExternalObject<Handle>, bind: WrapperBinding, fallbackClass?: () => AnyClass): object {
     const existing = existingWrapperFor(handle);
 
     if (existing) {
         return existing;
     }
 
-    const instance = createWrapper(handle);
+    const instance = createWrapper(handle, fallbackClass);
     bind(handle, instance);
 
     return instance;
 }
 
-function getOrCreateWrapper(handle: ExternalObject<Handle>): object {
-    return wrapperFor(handle, registerWrapper);
+function getOrCreateWrapper(handle: ExternalObject<Handle>, fallbackClass?: () => AnyClass): object {
+    return wrapperFor(handle, registerWrapper, fallbackClass);
 }
 
 function instanceClassName(instance: object): string {
@@ -639,8 +727,10 @@ export {
     registerWrapperClass,
     registerWrapperClassResolver,
     registerInterface,
+    installInterfaces,
     wrapFundamentalHandle,
     wrapHandle,
+    getExactWrapperClass,
     getWrapperClass,
     resolveWrapperClass,
     getHandle,
@@ -657,5 +747,6 @@ export {
     type InterfaceProperty,
     type StaticBase,
     type VfuncDescriptor,
+    type WrapperClass,
     type WrapperClassResolver,
 };

package/src/type.ts

@@ -29,6 +29,14 @@ const gTypeParent = bind(LIB, "g_type_parent", [biguint64T], biguint64T);
 const gTypeFundamental = bind(LIB, "g_type_fundamental", [biguint64T], biguint64T);
 const gTypeName = bind(LIB, "g_type_name", [biguint64T], stringT("borrowed"));
 const gTypeInterfaces = bind(LIB, "g_type_interfaces", [biguint64T, refT(uint32T)], sizedArrayT(biguint64T, 1, "full"));
+
+const gTypeInterfacePrerequisites = bind(
+    LIB,
+    "g_type_interface_prerequisites",
+    [biguint64T, refT(uint32T)],
+    sizedArrayT(biguint64T, 1, "full"),
+);
+
 /** GType tag for an invalid or uninitialized type. */
 const TYPE_INVALID = 0n;
 /** GType tag for the absence of a value (`void`). */
@@ -137,11 +145,26 @@ function typeInterfaces(type: bigint): bigint[] {
     return gTypeInterfaces(type, nInterfacesRef) as bigint[];
 }
 
+function typeInterfacePrerequisites(type: bigint): bigint[] {
+    const nPrerequisitesRef = { value: 0 };
+
+    return gTypeInterfacePrerequisites(type, nPrerequisitesRef) as bigint[];
+}
+
 /** Returns the GType registered under the given name, or `TYPE_INVALID` if none exists. */
 function typeFromName(name: string): bigint {
     return gTypeFromName(name) as bigint;
 }
 
+/**
+ * Keeps the given wrapper classes in a tree-shaken bundle: a generated bootstrap names the classes
+ * its namespace cannot operate without as arguments here, which is a reference a bundler retains.
+ *
+ * @param wrappers Wrapper classes to keep.
+ * @returns The same classes, untouched.
+ */
+const retainWrapperClasses = (wrappers: readonly unknown[]): readonly unknown[] => wrappers;
+
 function typeFundamental(type: bigint): bigint {
     return gTypeFundamental(type) as bigint;
 }
@@ -283,8 +306,10 @@ export {
     getStrvType,
     isResolvableDescriptor,
     isTypedClass,
+    retainWrapperClasses,
     typeIsA,
     typeParent,
+    typeInterfacePrerequisites,
     typeInterfaces,
     typeFromName,
     typeFundamental,

package/src/value.ts

@@ -15,6 +15,7 @@ import {
     fundamentalT,
     int8T,
     int32T,
+    type ObjectDescriptor,
     objectT,
     stringT,
     uint8T,
@@ -128,6 +129,7 @@ const stringValueType = bindValueType("string", stringT("borrowed"));
 const enumValueType = bindValueType("enum", int32T);
 const flagsValueType = bindValueType("flags", uint32T);
 const objectValueType = bindValueType("object", objectT("borrowed"));
+const objectValueFundamentals: Set<bigint> = new Set([TYPE_OBJECT, TYPE_INTERFACE]);
 const paramValueType = bindValueType("param", PARAM_T);
 const variantValueType = bindValueType("variant", VARIANT_T);
 const pointerValueType = bindValueType("pointer", uint64T);
@@ -718,10 +720,32 @@ function fromValue(value: ExternalObject<Handle>): unknown {
     return get(value);
 }
 
-const fromValueForDescriptor = (descriptor: Descriptor, value: ExternalObject<Handle>): unknown =>
-    descriptor.kind === "array" && descriptor.arrayKind === "gbytearray"
-        ? byteArrayValueGetterFor(descriptor.isBytes === true)(value)
-        : fromValue(value);
+const objectValueWithFallback = (
+    descriptor: ObjectDescriptor,
+    value: ExternalObject<Handle>,
+): { wrapped: unknown } | null => {
+    if (descriptor.fallbackClass === undefined || !objectValueFundamentals.has(typeFundamental(getValueType(value)))) {
+        return null;
+    }
+
+    return { wrapped: wrapObject(objectValueType.get(value), descriptor.fallbackClass) };
+};
+
+const fromValueForDescriptor = (descriptor: Descriptor, value: ExternalObject<Handle>): unknown => {
+    if (descriptor.kind === "array" && descriptor.arrayKind === "gbytearray") {
+        return byteArrayValueGetterFor(descriptor.isBytes === true)(value);
+    }
+
+    if (descriptor.kind === "object") {
+        const withFallback = objectValueWithFallback(descriptor, value);
+
+        if (withFallback !== null) {
+            return withFallback.wrapped;
+        }
+    }
+
+    return fromValue(value);
+};
 
 const inferredValueGuard: ValueGuard = (jsValue) => inferValueGType(jsValue, wrapperGType(jsValue)) !== TYPE_INVALID;