@gtkx/runtime 1.0.0-rc.1 → 1.0.0-rc.2

package/src/object.ts

@@ -23,6 +23,7 @@ const gObjectGetProperty = bind(
     [objectT("borrowed"), stringT("borrowed"), VALUE_T],
     voidT,
 );
+
 const gObjectSetProperty = bind(
     LIB,
     "g_object_set_property",
@@ -39,15 +40,23 @@ const gObjectSetProperty = bind(
  * @param props Property names mapped to `[descriptor, value]` pairs.
  * @returns The handle of the newly created object.
  */
-export function newObjectWithProperties(gtype: bigint, props: Record<string, unknown>): ExternalObject<Handle> {
+function newObjectWithProperties(gtype: bigint, props: Record<string, unknown>): ExternalObject<Handle> {
     const names: string[] = [];
     const values: ExternalObject<Handle>[] = [];
 
     for (const name in props) {
-        const entry = props[name];
-        if (!Array.isArray(entry)) continue;
-        const [descriptor, value] = entry;
-        if (value === undefined) continue;
+        const entry: unknown = props[name];
+
+        if (!Array.isArray(entry)) {
+            continue;
+        }
+
+        const [descriptor, value] = entry as [Descriptor, unknown];
+
+        if (value === undefined) {
+            continue;
+        }
+
         names.push(name);
         values.push(toValue(descriptor, value));
     }
@@ -63,9 +72,10 @@ export function newObjectWithProperties(gtype: bigint, props: Record<string, unk
  * @param propertyName The property name.
  * @param descriptor Describes the property's type.
  */
-export function getObjectProperty(obj: object, propertyName: string, descriptor: Descriptor): unknown {
+function getObjectProperty(obj: object, propertyName: string, descriptor: Descriptor): unknown {
     const value = newValueForDescriptor(descriptor);
     gObjectGetProperty(getHandle(obj), propertyName, value);
+
     return fromValue(value);
 }
 
@@ -78,6 +88,8 @@ export function getObjectProperty(obj: object, propertyName: string, descriptor:
  * @param descriptor Describes the property's type.
  * @param jsValue The value to set.
  */
-export function setObjectProperty(obj: object, propertyName: string, descriptor: Descriptor, jsValue: unknown): void {
+function setObjectProperty(obj: object, propertyName: string, descriptor: Descriptor, jsValue: unknown): void {
     gObjectSetProperty(getHandle(obj), propertyName, toValue(descriptor, jsValue));
 }
+
+export { newObjectWithProperties, getObjectProperty, setObjectProperty };

package/src/promisify.ts

@@ -1,11 +1,43 @@
 import { tryGetHandle } from "./registry.js";
 
+/**
+ * Extracts the finished value from the async result a GIO-style operation completes with.
+ *
+ * @template R - The async result type passed to the completion callback.
+ * @template T - The finished value type.
+ */
+type FinishResult<R extends object, T> = (result: R) => T;
+
+type Settlement<R extends object, T> = {
+    finish: FinishResult<R, T>;
+    creationStack: Error | undefined;
+    resolve: (value: T) => void;
+    reject: (reason: Error) => void;
+};
+
 const attachCreationStack = (error: unknown, creationStack: Error | undefined): void => {
-    if (creationStack === undefined || !(error instanceof Error)) return;
-    if (error.cause !== undefined || !Object.isExtensible(error)) return;
+    if (creationStack === undefined || !(error instanceof Error)) {
+        return;
+    }
+
+    if (error.cause !== undefined || !Object.isExtensible(error)) {
+        return;
+    }
+
     error.cause = creationStack;
 };
 
+const settle = <R extends object, T>(settlement: Settlement<R, T>, asyncResult: object): void => {
+    const { finish, creationStack, resolve, reject } = settlement;
+
+    try {
+        resolve(finish(asyncResult as R));
+    } catch (error) {
+        attachCreationStack(error, creationStack);
+        reject(error instanceof Error ? error : new Error(String(error)));
+    }
+};
+
 /**
  * Wraps a GIO-style asynchronous function that takes a completion callback into a
  * promise, invoking the finish function to extract the result. Outside production,
@@ -17,24 +49,19 @@ const attachCreationStack = (error: unknown, creationStack: Error | undefined):
  * @param leading Arguments passed to `asyncFn` before the cancellable and callback.
  * @returns A promise resolving to the finished result, or rejecting if `finish` throws.
  */
-export const promisify = <R extends object, T>(
+const promisify = <R extends object, T>(
     asyncFn: (...args: unknown[]) => void,
-    finish: (result: R) => T,
+    finish: FinishResult<R, T>,
     cancellable: object | null | undefined,
     ...leading: unknown[]
 ): Promise<T> =>
     new Promise<T>((resolve, reject) => {
-        let creationStack: Error | undefined;
-        if (process.env.NODE_ENV !== "production") {
-            creationStack = new Error("gtkx async operation started here");
-            Error.captureStackTrace(creationStack, promisify);
-        }
+        const creationStack =
+            process.env.NODE_ENV === "production" ? undefined : new Error("gtkx async operation started here");
+
         asyncFn(...leading, tryGetHandle(cancellable), (_source: object | null, asyncResult: object) => {
-            try {
-                resolve(finish(asyncResult as R));
-            } catch (error) {
-                attachCreationStack(error, creationStack);
-                reject(error);
-            }
+            settle({ finish, creationStack, resolve, reject }, asyncResult);
         });
     });
+
+export { promisify, type FinishResult };

package/src/properties.ts

@@ -0,0 +1,115 @@
+import type { ExternalObject, Handle, RegisterClassProperty } from "@gtkx/native";
+import type { AnyClass } from "@gtkx/utils";
+import { camelCase } from "@gtkx/utils";
+import { bind } from "./bind.js";
+import { LIB, PARAM_T, VALUE_T } from "./library.js";
+import { getHandle } from "./registry.js";
+import { fromValue, intoValue } from "./value.js";
+
+type PropertyAccessor = {
+    name: string;
+    storage: symbol;
+    pspec: object;
+};
+
+type PropertySpec = object;
+type NotifyingObject = { notify?: (propertyName: string) => void };
+
+const FIRST_PROPERTY_ID = 1;
+const paramSpecDefaultValue = bind(LIB, "g_param_spec_get_default_value", [PARAM_T], VALUE_T);
+
+const underscoreCase = (name: string): string => name.replaceAll("-", "_");
+const accessorNames = (name: string): string[] => [...new Set([name, underscoreCase(name), camelCase(name)])];
+
+function readStored(instance: Record<symbol, unknown>, accessor: PropertyAccessor): unknown {
+    if (!Object.hasOwn(instance, accessor.storage)) {
+        const defaults = paramSpecDefaultValue(getHandle(accessor.pspec)) as ExternalObject<Handle>;
+        instance[accessor.storage] = fromValue(defaults);
+    }
+
+    return instance[accessor.storage];
+}
+
+function defineAccessor(prototype: object, accessor: PropertyAccessor, alias: string): void {
+    if (Object.getOwnPropertyDescriptor(prototype, alias) !== undefined) {
+        return;
+    }
+
+    Object.defineProperty(prototype, alias, {
+        configurable: true,
+        enumerable: true,
+        get(this: Record<symbol, unknown>) {
+            return readStored(this, accessor);
+        },
+        set(this: Record<symbol, unknown>, value: unknown) {
+            if (readStored(this, accessor) === value) {
+                return;
+            }
+
+            this[accessor.storage] = value;
+            (this as NotifyingObject).notify?.(accessor.name);
+        },
+    });
+}
+
+function installAccessors(klass: AnyClass, accessor: PropertyAccessor): void {
+    const prototype = (klass as { prototype: object }).prototype;
+
+    for (const alias of accessorNames(accessor.name)) {
+        defineAccessor(prototype, accessor, alias);
+    }
+}
+
+function resolveAccessor(accessors: PropertyAccessor[], propertyId: number): PropertyAccessor {
+    const accessor = accessors[propertyId - FIRST_PROPERTY_ID];
+
+    if (accessor === undefined) {
+        throw new RangeError(`registerClass: no property registered for id ${String(propertyId)}`);
+    }
+
+    return accessor;
+}
+
+function makeGetProperty(accessors: PropertyAccessor[]) {
+    return function getProperty(this: object, propertyId: number, value: object): void {
+        const accessor = resolveAccessor(accessors, propertyId);
+        const current = (this as Record<string, unknown>)[camelCase(accessor.name)];
+        intoValue(getHandle(value), current);
+    };
+}
+
+function makeSetProperty(accessors: PropertyAccessor[]) {
+    return function setProperty(this: object, propertyId: number, value: object): void {
+        const accessor = resolveAccessor(accessors, propertyId);
+        const jsValue = fromValue(getHandle(value));
+        (this as Record<string, unknown>)[camelCase(accessor.name)] = jsValue;
+    };
+}
+
+function buildAccessors(klass: AnyClass, properties: Record<string, PropertySpec>): PropertyAccessor[] {
+    const accessors: PropertyAccessor[] = [];
+
+    for (const [name, pspec] of Object.entries(properties)) {
+        const accessor: PropertyAccessor = { name, storage: Symbol(`gtkx:property:${name}`), pspec };
+        installAccessors(klass, accessor);
+        accessors.push(accessor);
+    }
+
+    return accessors;
+}
+
+function toNativeProperties(properties: Record<string, PropertySpec>): RegisterClassProperty[] {
+    return Object.values(properties).map((pspec, index) => ({
+        id: index + FIRST_PROPERTY_ID,
+        pspec: getHandle(pspec),
+    }));
+}
+
+export {
+    buildAccessors,
+    makeGetProperty,
+    makeSetProperty,
+    toNativeProperties,
+    type PropertyAccessor,
+    type PropertySpec,
+};

package/src/register-class.ts

@@ -1,10 +1,19 @@
+import type { Descriptor } from "@gtkx/native";
 import {
+    registerClass as nativeRegisterClass,
     type RegisterClassOptions as NativeRegisterClassOptions,
     type RegisterClassVfunc as NativeRegisterClassVfunc,
-    registerClass as nativeRegisterClass,
 } 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,
@@ -14,12 +23,25 @@ import {
 } from "./registry.js";
 import { TYPE_INVALID, typeInterfaces } from "./type.js";
 
-type RegisterClassOptions = { typeName?: string };
+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; vfuncs: DiscoveredInterfaceVfunc[] };
+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
@@ -31,8 +53,9 @@ type InterfaceVfuncBinding = { gtype: bigint; vfuncs: DiscoveredInterfaceVfunc[]
  * @param options Registration options, such as an explicit type name.
  * @returns The same class, now registered.
  */
-export function registerClass<T extends AnyClass>(klass: T, options: RegisterClassOptions = {}): T {
+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`);
     }
@@ -43,11 +66,12 @@ export function registerClass<T extends AnyClass>(klass: T, options: RegisterCla
         throw new Error("registerClass: cannot derive a GType name (anonymous class with no typeName option)");
     }
 
-    const classVfuncs = discoverClassVfuncs(klass);
+    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);
+    const nativeOptions = toNativeOptions(classVfuncs, interfaceBindings, properties);
     const newType: bigint = nativeRegisterClass(name, parentType, nativeOptions);
     registerClassType(klass, newType);
 
@@ -58,20 +82,57 @@ function resolveParentType(klass: AnyClass): bigint {
     return (
         walkClassChain(getParentClass(klass), (cls) => {
             const gtype = getClassType(cls);
-            return gtype !== TYPE_INVALID ? gtype : undefined;
+
+            return gtype === TYPE_INVALID ? undefined : gtype;
         }) ?? TYPE_INVALID
     );
 }
 
 function ownInstanceMethodNames(klass: AnyClass): string[] {
     const proto = (klass as { prototype?: object }).prototype;
-    if (!proto) return [];
+
+    if (!proto) {
+        return [];
+    }
+
     return Object.getOwnPropertyNames(proto).filter((name) => {
-        if (name === "constructor") return false;
-        return typeof (proto as Record<string, unknown>)[name] === "function";
+        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,
@@ -79,31 +140,30 @@ function collectDiscoveredVfuncs<K extends "class" | "interface">(
 ): DiscoveredVfunc<K>[] {
     const proto = (klass as { prototype: Record<string, VfuncFn> }).prototype;
     const result: DiscoveredVfunc<K>[] = [];
+
     for (const methodName of ownInstanceMethodNames(klass)) {
-        if (skip?.has(methodName)) continue;
-        const descriptor = resolveDescriptor(methodName);
-        if (!descriptor) continue;
-        const fn = proto[methodName];
-        if (!fn) continue;
-        result.push({
-            ...descriptor,
-            methodName,
-            fn: wrapVfunc(fn, descriptor.argDescriptors, descriptor.returnDescriptor),
-        });
+        const discovered = buildDiscoveredVfunc(proto, methodName, resolveDescriptor, skip);
+
+        if (discovered) {
+            result.push(discovered);
+        }
     }
+
     return result;
 }
 
-const UNSUPPORTED_CONSTRUCT_VFUNCS: Set<string> = new Set(["constructed", "setProperty", "getProperty"]);
-
 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`,
+                `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;
     });
 }
@@ -122,12 +182,15 @@ function discoverInheritedInterfaceVfuncs(
     claimedMethodNames: Set<string>,
 ): InterfaceVfuncBinding[] {
     const bindings: InterfaceVfuncBinding[] = [];
+
     for (const interfaceGtype of typeInterfaces(parentGtype)) {
-        const vfuncs = discoverInterfaceVfuncs(klass, interfaceGtype, claimedMethodNames);
-        if (vfuncs.length > 0) {
-            bindings.push({ gtype: interfaceGtype, vfuncs });
+        const [first, ...rest] = discoverInterfaceVfuncs(klass, interfaceGtype, claimedMethodNames);
+
+        if (first !== undefined) {
+            bindings.push({ gtype: interfaceGtype, vtableSize: first.vtableSize, vfuncs: [first, ...rest] });
         }
     }
+
     return bindings;
 }
 
@@ -137,11 +200,16 @@ function discoverInterfaceVfuncs(
     claimedMethodNames: Set<string>,
 ): DiscoveredInterfaceVfunc[] {
     const vfuncRegistry = getInterfaceVfuncRegistry(interfaceGtype);
-    if (!vfuncRegistry) return [];
+
+    if (!vfuncRegistry) {
+        return [];
+    }
+
     return collectDiscoveredVfuncs(
         klass,
         (methodName) => {
             const entry = vfuncRegistry[methodName];
+
             return entry?.kind === "interface" ? entry : undefined;
         },
         claimedMethodNames,
@@ -152,27 +220,86 @@ function findClassVfuncDescriptor(klass: AnyClass, methodName: string): VfuncDes
     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;
-    if (!hasClassVfuncs && !hasInterfaces) {
+    const hasProperties = Object.keys(properties).length > 0;
+
+    if (!hasClassVfuncs && !hasInterfaces && !hasProperties) {
         return undefined;
     }
+
     const options: NativeRegisterClassOptions = {};
-    if (hasClassVfuncs) options.vfuncs = [...classVfuncs];
+
+    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 };