@gtkx/runtime 0.0.1 → 1.0.0-rc.2

package/src/register-class.ts

@@ -0,0 +1,305 @@
+import type { Descriptor } from "@gtkx/native";
+import {
+    registerClass as nativeRegisterClass,
+    type RegisterClassOptions as NativeRegisterClassOptions,
+    type RegisterClassVfunc as NativeRegisterClassVfunc,
+} from "@gtkx/native";
+import { type AnyClass, getParentClass, walkClassChain } from "@gtkx/utils";
+import { wrapCallback } from "./callback.js";
+import {
+    buildAccessors,
+    makeGetProperty,
+    makeSetProperty,
+    type PropertyAccessor,
+    type PropertySpec,
+    toNativeProperties,
+} from "./properties.js";
+import {
+    getClassType,
+    getInterfaceVfuncRegistry,
+    getVfuncRegistry,
+    registerClassType,
+    type VfuncDescriptor,
+} from "./registry.js";
+import { TYPE_INVALID, typeInterfaces } from "./type.js";
+
+type RegisterClassOptions = {
+    typeName?: string;
+    /**
+     * Properties to install on the new type, keyed by canonical property name. Each value is the
+     * `GObject.ParamSpec` describing it, for example `GObject.paramSpecString(...)`. Accessors are
+     * generated on the prototype for the dashed, underscored and camelCased spellings of the name
+     * unless the class already defines one, and writing through them emits `notify`.
+     */
+    properties?: Record<string, PropertySpec>;
+};
+
+type VfuncFn = NativeRegisterClassVfunc["fn"];
+type DiscoveredVfunc<K extends "class" | "interface"> = VfuncDescriptor<K> & { methodName: string; fn: VfuncFn };
+type DiscoveredClassVfunc = DiscoveredVfunc<"class">;
+type DiscoveredInterfaceVfunc = DiscoveredVfunc<"interface">;
+type InterfaceVfuncBinding = { gtype: bigint; vtableSize: number; vfuncs: DiscoveredInterfaceVfunc[] };
+
+const UNSUPPORTED_CONSTRUCT_VFUNCS: Set<string> = new Set(["constructed", "setProperty", "getProperty"]);
+const VALUE_ARG_INDEX = 2;
+
+/**
+ * Registers a subclass of a wrapper class as a new GType, wiring up any class and
+ * inherited-interface virtual functions it overrides. Throws if the class does not
+ * extend a registered wrapper class, has no derivable type name, or overrides an
+ * unsupported construct-time vtable slot.
+ *
+ * @param klass The subclass to register.
+ * @param options Registration options, such as an explicit type name.
+ * @returns The same class, now registered.
+ */
+function registerClass<T extends AnyClass>(klass: T, options: RegisterClassOptions = {}): T {
+    const parentType = resolveParentType(klass);
+
+    if (parentType === TYPE_INVALID) {
+        throw new TypeError(`registerClass: ${klass.name} must extend a registered wrapper class`);
+    }
+
+    const name = options.typeName ?? klass.name;
+
+    if (!name) {
+        throw new Error("registerClass: cannot derive a GType name (anonymous class with no typeName option)");
+    }
+
+    const properties = options.properties ?? {};
+    const accessors = buildAccessors(klass, properties);
+    const classVfuncs = [...discoverClassVfuncs(klass), ...propertyVfuncs(klass, accessors)];
+    const claimedMethodNames = new Set(classVfuncs.map((vfunc) => vfunc.methodName));
+    const interfaceBindings = discoverInheritedInterfaceVfuncs(klass, parentType, claimedMethodNames);
+    const nativeOptions = toNativeOptions(classVfuncs, interfaceBindings, properties);
+    const newType: bigint = nativeRegisterClass(name, parentType, nativeOptions);
+    registerClassType(klass, newType);
+
+    return klass;
+}
+
+function resolveParentType(klass: AnyClass): bigint {
+    return (
+        walkClassChain(getParentClass(klass), (cls) => {
+            const gtype = getClassType(cls);
+
+            return gtype === TYPE_INVALID ? undefined : gtype;
+        }) ?? TYPE_INVALID
+    );
+}
+
+function ownInstanceMethodNames(klass: AnyClass): string[] {
+    const proto = (klass as { prototype?: object }).prototype;
+
+    if (!proto) {
+        return [];
+    }
+
+    return Object.getOwnPropertyNames(proto).filter((name) => {
+        if (name === "constructor") {
+            return false;
+        }
+
+        return typeof Object.getOwnPropertyDescriptor(proto, name)?.value === "function";
+    });
+}
+
+function buildDiscoveredVfunc<K extends "class" | "interface">(
+    proto: Record<string, VfuncFn>,
+    methodName: string,
+    resolveDescriptor: (methodName: string) => VfuncDescriptor<K> | undefined,
+    skip: Set<string> | undefined,
+): DiscoveredVfunc<K> | undefined {
+    if (skip?.has(methodName)) {
+        return undefined;
+    }
+
+    const descriptor = resolveDescriptor(methodName);
+
+    if (!descriptor) {
+        return undefined;
+    }
+
+    const fn = proto[methodName];
+
+    if (!fn) {
+        return undefined;
+    }
+
+    return {
+        ...descriptor,
+        methodName,
+        fn: wrapVfunc(fn, descriptor.argDescriptors, descriptor.returnDescriptor),
+    };
+}
+
+function collectDiscoveredVfuncs<K extends "class" | "interface">(
+    klass: AnyClass,
+    resolveDescriptor: (methodName: string) => VfuncDescriptor<K> | undefined,
+    skip?: Set<string>,
+): DiscoveredVfunc<K>[] {
+    const proto = (klass as { prototype: Record<string, VfuncFn> }).prototype;
+    const result: DiscoveredVfunc<K>[] = [];
+
+    for (const methodName of ownInstanceMethodNames(klass)) {
+        const discovered = buildDiscoveredVfunc(proto, methodName, resolveDescriptor, skip);
+
+        if (discovered) {
+            result.push(discovered);
+        }
+    }
+
+    return result;
+}
+
+function discoverClassVfuncs(klass: AnyClass): DiscoveredClassVfunc[] {
+    return collectDiscoveredVfuncs(klass, (methodName) => {
+        const descriptor = findClassVfuncDescriptor(klass, methodName);
+
+        if (descriptor && UNSUPPORTED_CONSTRUCT_VFUNCS.has(methodName)) {
+            throw new Error(
+                `registerClass: overriding the GObject construct-time vtable slot '${methodName}' is not ` +
+                "supported; run construct-time initialization in the subclass constructor, after " +
+                "super(...), instead",
+            );
+        }
+
+        return descriptor ?? undefined;
+    });
+}
+
+function wrapVfunc(
+    fn: VfuncFn,
+    argDescriptors: NativeRegisterClassVfunc["argDescriptors"],
+    returnDescriptor: NativeRegisterClassVfunc["returnDescriptor"],
+): VfuncFn {
+    return wrapCallback(fn as (...args: unknown[]) => unknown, { argDescriptors, returnDescriptor }, "this");
+}
+
+function discoverInheritedInterfaceVfuncs(
+    klass: AnyClass,
+    parentGtype: bigint,
+    claimedMethodNames: Set<string>,
+): InterfaceVfuncBinding[] {
+    const bindings: InterfaceVfuncBinding[] = [];
+
+    for (const interfaceGtype of typeInterfaces(parentGtype)) {
+        const [first, ...rest] = discoverInterfaceVfuncs(klass, interfaceGtype, claimedMethodNames);
+
+        if (first !== undefined) {
+            bindings.push({ gtype: interfaceGtype, vtableSize: first.vtableSize, vfuncs: [first, ...rest] });
+        }
+    }
+
+    return bindings;
+}
+
+function discoverInterfaceVfuncs(
+    klass: AnyClass,
+    interfaceGtype: bigint,
+    claimedMethodNames: Set<string>,
+): DiscoveredInterfaceVfunc[] {
+    const vfuncRegistry = getInterfaceVfuncRegistry(interfaceGtype);
+
+    if (!vfuncRegistry) {
+        return [];
+    }
+
+    return collectDiscoveredVfuncs(
+        klass,
+        (methodName) => {
+            const entry = vfuncRegistry[methodName];
+
+            return entry?.kind === "interface" ? entry : undefined;
+        },
+        claimedMethodNames,
+    );
+}
+
+function findClassVfuncDescriptor(klass: AnyClass, methodName: string): VfuncDescriptor<"class"> | null {
+    return (
+        walkClassChain(getParentClass(klass), (cls) => {
+            const entry = getVfuncRegistry(cls)?.[methodName];
+
+            return entry?.kind === "class" ? entry : undefined;
+        }) ?? null
+    );
+}
+
+function propertyVfuncs(klass: AnyClass, accessors: PropertyAccessor[]): DiscoveredClassVfunc[] {
+    if (accessors.length === 0) {
+        return [];
+    }
+
+    return [
+        buildPropertyVfunc(klass, "getProperty", makeGetProperty(accessors), true),
+        buildPropertyVfunc(klass, "setProperty", makeSetProperty(accessors), false),
+    ];
+}
+
+// `get_property` fills a GValue the caller owns, so the marshalled copy handed to JavaScript has to
+// be written back into it; `set_property` only reads its GValue and needs no copy back.
+function markValueCallerAllocated(argDescriptors: Descriptor[]): Descriptor[] {
+    return argDescriptors.map((arg, index) =>
+        index === VALUE_ARG_INDEX ? { ...arg, callerAllocated: true } : arg);
+}
+
+function buildPropertyVfunc(
+    klass: AnyClass,
+    methodName: string,
+    fn: VfuncFn,
+    isValueOut: boolean,
+): DiscoveredClassVfunc {
+    const descriptor = findClassVfuncDescriptor(klass, methodName);
+
+    if (!descriptor) {
+        throw new Error(`registerClass: the parent class exposes no '${methodName}' vtable slot`);
+    }
+
+    const argDescriptors = isValueOut
+        ? markValueCallerAllocated(descriptor.argDescriptors)
+        : descriptor.argDescriptors;
+
+    return {
+        ...descriptor,
+        methodName,
+        argDescriptors,
+        fn: wrapVfunc(fn, argDescriptors, descriptor.returnDescriptor),
+    };
+}
+
+function toNativeOptions(
+    classVfuncs: DiscoveredClassVfunc[],
+    interfaceBindings: InterfaceVfuncBinding[],
+    properties: Record<string, PropertySpec>,
+): NativeRegisterClassOptions | undefined {
+    const hasInterfaces = interfaceBindings.length > 0;
+    const hasClassVfuncs = classVfuncs.length > 0;
+    const hasProperties = Object.keys(properties).length > 0;
+
+    if (!hasClassVfuncs && !hasInterfaces && !hasProperties) {
+        return undefined;
+    }
+
+    const options: NativeRegisterClassOptions = {};
+
+    if (hasProperties) {
+        options.properties = toNativeProperties(properties);
+    }
+
+    if (hasClassVfuncs) {
+        options.vfuncs = [...classVfuncs];
+    }
+
+    if (hasInterfaces) {
+        options.interfaces = interfaceBindings.map((binding) => ({
+            type: binding.gtype,
+            vtableSize: binding.vtableSize,
+            vfuncs: [...binding.vfuncs],
+        }));
+    }
+
+    return options;
+}
+
+export { registerClass };

package/src/registry.ts

@@ -0,0 +1,311 @@
+import type { AnyClass } from "@gtkx/utils";
+import {
+    type ExternalObject,
+    getType,
+    getWrapper,
+    type Handle,
+    type RegisterClassVfunc as NativeRegisterClassVfunc,
+    setWrapper,
+} from "@gtkx/native";
+import type { Mixin, MixinReceiver } from "./mixin.js";
+import { TYPE_INVALID, type TypedClass, typeInterfaces, typeIsA, typeName, typeParent } from "./type.js";
+
+/**
+ * Static side of class `C` with its construct signature preserved but the member
+ * named `K` (default `"new"`) removed.
+ */
+type StaticBase<C, K extends PropertyKey = "new"> = Omit<C, K> &
+    (C extends new (...args: infer A) => infer R ? new (...args: A) => R : never);
+
+type VfuncDescriptor<K extends "class" | "interface"> = {
+    kind: K;
+    className: string;
+    vfuncName: string;
+    byteOffset: number;
+    vtableSize: number;
+    argDescriptors: NativeRegisterClassVfunc["argDescriptors"];
+    returnDescriptor: NativeRegisterClassVfunc["returnDescriptor"];
+};
+
+type VfuncRegistry = Record<string, VfuncDescriptor<"class"> | VfuncDescriptor<"interface">>;
+
+const classRegistry: Map<bigint, AnyClass> = new Map();
+const interfaceMixinRegistry: Map<bigint, Mixin> = new Map();
+const composedClassRegistry: Map<bigint, AnyClass> = new Map();
+const handleMap: WeakMap<object, ExternalObject<Handle>> = new WeakMap();
+const vfuncRegistry: WeakMap<object, VfuncRegistry> = new WeakMap();
+const interfaceVfuncRegistry: Map<bigint, VfuncRegistry> = new Map();
+
+function setClassType(cls: AnyClass, type: bigint): void {
+    (cls.prototype as { [K in keyof TypedClass]: TypedClass[K] }).__type__ = type;
+}
+
+function getClassType(cls: AnyClass): bigint {
+    const proto: object = cls.prototype;
+
+    return Object.hasOwn(proto, "__type__") ? (proto as TypedClass).__type__ : TYPE_INVALID;
+}
+
+/** Returns the GType tag of the given wrapper instance. */
+function getInstanceType(instance: object): bigint {
+    return getClassType(instance.constructor as AnyClass);
+}
+
+function registerClassType(cls: AnyClass, type: bigint): void {
+    if (type === TYPE_INVALID) {
+        return;
+    }
+
+    classRegistry.set(type, cls);
+    setClassType(cls, type);
+}
+
+/**
+ * Registers a wrapper class as the JS representation of a GType, optionally
+ * installing a registry of virtual functions.
+ * @param cls Wrapper class to associate with the type.
+ * @param type GType the class wraps.
+ * @param vfuncs Virtual functions the class overrides.
+ */
+function registerWrapperClass(cls: AnyClass, type: bigint, vfuncs?: VfuncRegistry): void {
+    registerClassType(cls, type);
+
+    if (vfuncs) {
+        registerVfuncRegistry(cls, vfuncs);
+    }
+}
+
+/**
+ * Registers a GInterface, associating its GType with a mixin used to compose the
+ * interface onto wrapper classes and an optional virtual function registry.
+ * @param cls Class carrying the interface's GType tag.
+ * @param type GType of the interface.
+ * @param mixin Mixin that applies the interface to a wrapper class.
+ * @param vfuncs Virtual functions the interface exposes.
+ */
+function registerInterface(cls: AnyClass, type: bigint, mixin: Mixin, vfuncs?: VfuncRegistry): void {
+    if (type === TYPE_INVALID) {
+        return;
+    }
+
+    setClassType(cls, type);
+    interfaceMixinRegistry.set(type, mixin);
+
+    if (vfuncs) {
+        registerInterfaceVfuncRegistry(type, vfuncs);
+    }
+}
+
+/**
+ * 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);
+ * with an explicit class, creates a bare instance backed by the handle. Returns
+ * null for a null or undefined handle.
+ * @param handle Native handle to wrap.
+ * @param cls Wrapper class to instantiate, or omitted to resolve it from the runtime type.
+ */
+function wrapHandle(handle: null | undefined, cls?: AnyClass): null;
+function wrapHandle<T extends object>(handle: ExternalObject<Handle>, cls: AnyClass<T>): T;
+
+function wrapHandle<T extends object>(
+    handle: ExternalObject<Handle> | null | undefined,
+    cls: AnyClass<T>,
+): T | null;
+
+function wrapHandle(handle: ExternalObject<Handle>, cls?: AnyClass): TypedClass;
+function wrapHandle(handle: ExternalObject<Handle> | null | undefined, cls?: AnyClass): TypedClass | null;
+
+function wrapHandle(handle: ExternalObject<Handle> | null | undefined, cls?: AnyClass): object | null {
+    if (handle === null || handle === undefined) {
+        return null;
+    }
+
+    if (cls === undefined) {
+        return getOrCreateWrapper(handle);
+    }
+
+    const instance: object = Object.create(cls.prototype) as object;
+    setHandle(instance, handle);
+
+    return instance;
+}
+
+/**
+ * Returns the wrapper class registered for a GType, walking up to ancestor types,
+ * and throws if none is registered.
+ */
+function getWrapperClass(type: bigint): AnyClass {
+    const cls = resolveWrapperClass(type);
+
+    if (!cls) {
+        throw new Error(`No registered wrapper class for type '${typeName(type) ?? String(type)}'`);
+    }
+
+    return cls;
+}
+
+function resolveWrapperClass(type: bigint): AnyClass | null {
+    let currentType = type;
+
+    while (currentType !== TYPE_INVALID) {
+        const cls = classRegistry.get(currentType);
+
+        if (cls) {
+            return cls;
+        }
+
+        currentType = typeParent(currentType);
+    }
+
+    return null;
+}
+
+function applyInterfaceMixin(cls: AnyClass, type: bigint, baseType: bigint, applied: Set<bigint>): AnyClass {
+    if (applied.has(type) || typeIsA(baseType, type)) {
+        return cls;
+    }
+
+    const mixin = interfaceMixinRegistry.get(type);
+
+    if (mixin === undefined) {
+        return cls;
+    }
+
+    applied.add(type);
+
+    return mixin(cls as AnyClass<MixinReceiver>);
+}
+
+function createComposedClass(base: AnyClass, runtimeType: bigint): AnyClass {
+    const baseType = getClassType(base);
+    const applied: Set<bigint> = new Set();
+    let cls: AnyClass = base;
+
+    for (const type of typeInterfaces(runtimeType)) {
+        cls = applyInterfaceMixin(cls, type, baseType, applied);
+    }
+
+    return applied.size === 0 ? base : cls;
+}
+
+function resolveComposedClass(runtimeType: bigint): AnyClass | null {
+    const exact = classRegistry.get(runtimeType);
+
+    if (exact) {
+        return exact;
+    }
+
+    const cached = composedClassRegistry.get(runtimeType);
+
+    if (cached) {
+        return cached;
+    }
+
+    const base = resolveWrapperClass(runtimeType);
+
+    if (base === null) {
+        return null;
+    }
+
+    const composed = createComposedClass(base, runtimeType);
+
+    if (composed === base) {
+        return base;
+    }
+
+    setClassType(composed, runtimeType);
+    composedClassRegistry.set(runtimeType, composed);
+
+    return composed;
+}
+
+function getOrCreateWrapper(handle: ExternalObject<Handle>): object {
+    const existing = getWrapper(handle);
+
+    if (existing) {
+        return existing;
+    }
+
+    const runtimeType: bigint = getType(handle);
+
+    if (runtimeType === TYPE_INVALID) {
+        throw new Error("Cannot resolve runtime GLib type from handle");
+    }
+
+    const cls = resolveComposedClass(runtimeType);
+
+    if (!cls) {
+        throw new Error(`Expected registered GLib type, got type ${String(runtimeType)}`);
+    }
+
+    const instance: object = Object.create(cls.prototype) as object;
+    registerWrapper(handle, instance);
+
+    return instance;
+}
+
+/** Returns the native handle bound to a wrapper instance, throwing if none is set. */
+function getHandle(instance: object): ExternalObject<Handle> {
+    const handle = handleMap.get(instance);
+
+    if (handle === undefined) {
+        const name = (instance as { constructor?: { name?: string } }).constructor?.name ?? "object";
+        throw new Error(`No native handle associated with ${name}`);
+    }
+
+    return handle;
+}
+
+/** Returns the native handle bound to an instance, or undefined when there is none or the instance is null. */
+function tryGetHandle(instance: object | null | undefined): ExternalObject<Handle> | undefined {
+    return instance == null ? undefined : handleMap.get(instance);
+}
+
+/** Associates a native handle with a wrapper instance. */
+function setHandle(instance: object, handle: ExternalObject<Handle>): void {
+    handleMap.set(instance, handle);
+}
+
+function registerWrapper(handle: ExternalObject<Handle>, instance: object): void {
+    setHandle(instance, handle);
+    setWrapper(handle, instance);
+}
+
+function registerVfuncRegistry(cls: object, registry: VfuncRegistry): void {
+    vfuncRegistry.set(cls, registry);
+}
+
+function getVfuncRegistry(cls: object): VfuncRegistry | undefined {
+    return vfuncRegistry.get(cls);
+}
+
+function registerInterfaceVfuncRegistry(type: bigint, registry: VfuncRegistry): void {
+    if (type === TYPE_INVALID) {
+        return;
+    }
+
+    interfaceVfuncRegistry.set(type, registry);
+}
+
+function getInterfaceVfuncRegistry(type: bigint): VfuncRegistry | undefined {
+    return interfaceVfuncRegistry.get(type);
+}
+
+export {
+    getClassType,
+    getInstanceType,
+    registerClassType,
+    registerWrapperClass,
+    registerInterface,
+    wrapHandle,
+    getWrapperClass,
+    resolveWrapperClass,
+    getHandle,
+    tryGetHandle,
+    setHandle,
+    getVfuncRegistry,
+    getInterfaceVfuncRegistry,
+    type StaticBase,
+    type VfuncDescriptor,
+    type VfuncRegistry,
+};