@gtkx/runtime 1.5.0 → 2.0.0-beta.1

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/signal.ts

@@ -1,9 +1,9 @@
 import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
-import { getOrInsert, toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import { toCamelIdentifier, upperFirst } from "@gtkx/utils";
 import { type Arg, isCallerAllocatedArg, isInoutArg, isOutputArg } from "./arg.js";
-import { bind, createBindCache } from "./bind.js";
+import { bind } from "./bind.js";
 import { wrapCallback } from "./callback.js";
-import { toClosure } from "./closure.js";
+import { newCCallbackClosure, toClosure } from "./closure.js";
 import {
     arrayT,
     biguint64T,
@@ -69,7 +69,6 @@ type EmitArg = Arg & {
     value?: unknown;
 };
 
-const connectCache = createBindCache();
 const connectionTable: WeakMap<object, Map<string, Set<number>>> = new WeakMap();
 const gQuarkFromString = bind(LIB, "g_quark_from_string", [stringT("borrowed")], uint32T);
 const gSignalLookup = bind(LIB, "g_signal_lookup", [stringT("borrowed"), biguint64T], uint32T);
@@ -129,21 +128,8 @@ const isSignalHandlerConnected = (instance: object, handlerId: number): boolean
     gSignalHandlerIsConnected(getHandle(instance), handlerId) as boolean;
 
 const trackConnection = (instance: object, signal: string, handlerId: number): void => {
-    let bySignal = connectionTable.get(instance);
-
-    if (!bySignal) {
-        bySignal = new Map();
-        connectionTable.set(instance, bySignal);
-    }
-
-    let handlerIds = bySignal.get(signal);
-
-    if (!handlerIds) {
-        handlerIds = new Set();
-        bySignal.set(signal, handlerIds);
-    }
-
-    handlerIds.add(handlerId);
+    const bySignal = connectionTable.getOrInsertComputed(instance, () => new Map<string, Set<number>>());
+    bySignal.getOrInsertComputed(signal, () => new Set<number>()).add(handlerId);
 };
 
 const untrackConnection = (instance: object, handlerId: number): void => {
@@ -238,23 +224,11 @@ const buildSignalNames = (type: bigint): string[] => {
     return [...names];
 };
 
-const signalNamesFor = (type: bigint): string[] => getOrInsert(signalNameCache, type, buildSignalNames);
+const signalNamesFor = (type: bigint): string[] => signalNameCache.getOrInsertComputed(type, buildSignalNames);
 
 const getSignalId = (instance: object, signal: string): number =>
     signalIdFor((instance as TypedClass).__type__, signal);
 
-function connectBind(type: bigint, signal: string, callback: CallbackDescriptor): (...values: unknown[]) => unknown {
-    const key = `${String(type)}\0${getSignalBaseName(signal)}`;
-
-    return connectCache(
-        key,
-        LIB,
-        "g_signal_connect_data",
-        [objectT("borrowed"), stringT("borrowed"), callback, uint32T],
-        uint64T,
-    );
-}
-
 /**
  * Connects a handler to a GObject signal on an instance and returns the handler id.
  * @param instance Emitter to connect to.
@@ -265,8 +239,9 @@ function connectSignal(instance: object, signal: string, spec: SignalConnectSpec
     const { callback, handler, isAfter } = spec;
     const wrapped = wrapCallback(handler, callback, "signal");
     const type: bigint = (instance as TypedClass).__type__;
-    const connect = connectBind(type, signal, callback);
-    const handlerId = connect(getHandle(instance), signal, wrapped, isAfter ? 1 : 0) as number;
+    const key = `${String(type)}\0${getSignalBaseName(signal)}`;
+    const closure = newCCallbackClosure(key, callback, wrapped);
+    const handlerId = gSignalConnectClosure(getHandle(instance), signal, closure, isAfter) as number;
     trackConnection(instance, getSignalBaseName(signal), handlerId);
 
     return handlerId;

package/src/t.ts

@@ -41,10 +41,7 @@ type T = {
     unichar: typeof helpers.unicharT;
     /** Descriptor for an opaque `gpointer` argument, taken from a typed array's memory or a numeric address. */
     buffer: typeof helpers.bufferT;
-    /**
-     * Builds a descriptor for a C string, whose optional length sizes the caller-allocated buffer
-     * used when the string is passed by reference.
-     */
+    /** Builds a C-string descriptor with optional caller-allocated length. */
     string: typeof helpers.stringT;
     /** Builds a descriptor for a `GObject`, wrapped in the class registered for its runtime GType. */
     object: typeof helpers.objectT;
@@ -82,28 +79,15 @@ type T = {
     cursorArray: typeof helpers.cursorArrayT;
     /** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */
     callback: typeof helpers.callbackT;
-    /**
-     * Binds a native function, wiring up argument directions, `GError` checking, and packing output
-     * arguments into the result.
-     */
+    /** Binds a native function with argument directions, errors, and packed outputs. */
     fn: typeof fn;
-    /**
-     * Binds a struct field at a fixed offset, compiling its descriptor once into an accessor that
-     * reads and writes it.
-     */
+    /** Binds a struct field at a fixed offset. */
     field: typeof field;
-    /**
-     * Binds a struct field whose offset is supplied per access, for walking records stored at a
-     * stride in a buffer.
-     */
+    /** Binds a struct field whose offset is supplied per access. */
     fieldAt: typeof fieldAt;
 };
 
-/**
- * Type descriptor builder: a collection of factory helpers that describe C types for
- * FFI marshalling, plus `bind` to bind a native function and `fn` to describe a
- * function signature.
- */
+/** FFI descriptor factories and native function binders. */
 const t: T = {
     bind,
     int8: helpers.int8T,

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;
 }
@@ -221,6 +244,14 @@ function isResolvableDescriptor(descriptor: Descriptor): descriptor is Resolvabl
     return RESOLVABLE_DESCRIPTOR_KINDS.has(descriptor.kind);
 }
 
+function resolveEnumOrFlagsType(descriptor: Extract<Descriptor, { kind: "enum" | "flags" }>): bigint {
+    if (descriptor.getTypeFnName === "") {
+        return descriptor.isSigned ? TYPE_INT : TYPE_UINT;
+    }
+
+    return resolveType(descriptor.sharedLibrary, descriptor.getTypeFnName);
+}
+
 function resolveDescriptorType(descriptor: Descriptor): bigint {
     if (descriptor.kind === "biguint64" && "type" in descriptor) {
         return TYPE_GTYPE;
@@ -239,7 +270,7 @@ function resolveDescriptorType(descriptor: Descriptor): bigint {
     switch (descriptor.kind) {
         case "enum":
         case "flags": {
-            return resolveType(descriptor.sharedLibrary, descriptor.getTypeFnName);
+            return resolveEnumOrFlagsType(descriptor);
         }
         case "boxed": {
             return resolveBoxedType(descriptor);
@@ -283,8 +314,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);
@@ -420,6 +422,14 @@ const arrayValueType = (descriptor: ArrayDescriptor): ValueType => {
     throw new Error(`Unsupported array type ${descriptor.arrayKind} of ${descriptor.itemDescriptor.kind}`);
 };
 
+const resolveEnumOrFlagsValueType = (descriptor: Extract<Descriptor, { kind: "enum" | "flags" }>): ValueType => {
+    if (descriptor.getTypeFnName === "") {
+        return descriptor.kind === "flags" ? flagsValueType : enumValueType;
+    }
+
+    return enumOrFlagsValueType(resolveType(descriptor.sharedLibrary, descriptor.getTypeFnName));
+};
+
 const resolveValueType = (descriptor: Descriptor): ValueType => {
     if (descriptor.kind === "biguint64" && "type" in descriptor) {
         return typeValueType;
@@ -438,7 +448,7 @@ const resolveValueType = (descriptor: Descriptor): ValueType => {
     switch (descriptor.kind) {
         case "enum":
         case "flags": {
-            return enumOrFlagsValueType(resolveType(descriptor.sharedLibrary, descriptor.getTypeFnName));
+            return resolveEnumOrFlagsValueType(descriptor);
         }
         case "boxed": {
             return boxedValueType(resolveBoxedType(descriptor));
@@ -718,10 +728,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;
 

package/src/variant.ts

@@ -34,10 +34,7 @@ type BasicValueMap<Nested> = {
 
 /** Single-character code of one of the GVariant basic types in {@link BasicValueMap}. */
 type BasicCode = keyof BasicValueMap<unknown>;
-/**
- * JavaScript type a byte array (`ay`) unpacks to: the same one the generated bindings use for byte sequences, so a
- * `Uint8Array` under the `v2ByteArrays` future flag and a `number[]` otherwise.
- */
+/** JavaScript type a byte array (`ay`) unpacks to. */
 type ByteArray = ReturnType<GLib.Bytes["unrefToArray"]>;
 /** Values a byte array (`ay`) packs from. */
 type ByteArrayInput = Uint8Array | number[];
@@ -503,8 +500,7 @@ const toVariant = <S extends string>(typeString: S, value: VariantInput<S>): GLi
 /**
  * Unpacks a `GLib.Variant` into the JavaScript value its GVariant type describes, the inverse of
  * {@link toVariant}. A dictionary keyed by strings unpacks to a record and one keyed by anything
- * else to a `Map`, an array to an array, a byte array (`ay`) to the byte array type the generated
- * bindings use (`Uint8Array` under the `v2ByteArrays` future flag, `number[]` otherwise), a tuple
+ * else to a `Map`, an array to an array, a byte array (`ay`) to a `Uint8Array`, a tuple
  * to an array of its members, a maybe to its value or `null`, and a nested variant to the
  * `GLib.Variant` itself unless `recursive` is set, in which case it is unwrapped all the way down.
  *

package/src/vfunc-call.ts

@@ -1,6 +1,5 @@
-import type { BindVfuncOptions } from "@gtkx/native";
 import type { AnyClass } from "@gtkx/utils";
-import { bindVfunc } from "@gtkx/native";
+import { bindVfunc, type BindVfuncOptions } from "@gtkx/native";
 import { type Arg, isCallerAllocatedArg, requiresInputArg } from "./arg.js";
 import { buildNativeArgTypes, fromNativeCallable } from "./fn.js";
 import { toNative } from "./native-value.js";
@@ -106,21 +105,9 @@ function buildInvoker(slot: ResolvedSlot, instanceType: bigint | undefined, call
 }
 
 function cachedInvoker(cache: InvokerCache, owner: AnyClass, key: string, build: () => Invoker): Invoker {
-    let byKey = cache.get(owner);
+    const byKey = cache.getOrInsertComputed(owner, () => new Map<string, Invoker>());
 
-    if (byKey === undefined) {
-        byKey = new Map();
-        cache.set(owner, byKey);
-    }
-
-    let invoker = byKey.get(key);
-
-    if (invoker === undefined) {
-        invoker = build();
-        byKey.set(key, invoker);
-    }
-
-    return invoker;
+    return byKey.getOrInsertComputed(key, build);
 }
 
 function resolveParentSlot(klass: AnyClass, parentType: bigint, methodName: string): ResolvedSlot | undefined {