@gtkx/runtime 1.0.0-rc.3 → 1.0.0

package/src/index.ts

@@ -1,14 +1,35 @@
 import "./exit-hook.js";
 
+/** @public */
+export { type ApplicationClass, type CommandLineApplication, createApplication } from "./application-class.js";
+/** @public */
+export { type ClosureCallback, ClosureMarshalError, toClosure, tryToClosure } from "./closure.js";
+/** @public */
 export { createErrorDomain, type ErrorDomain } from "./error.js";
-export { type ApplicationLike, onExit, quit, quitApplication, runApplication } from "./lifecycle.js";
+/** @public */
+export { onExit, quit, quitApplication, runApplication, type RunApplicationResult } from "./lifecycle.js";
+/** @public */
 export { offSignal, onceSignal, onSignal } from "./listeners.js";
+/** @public */
 export { installMixins, type Mixin } from "./mixin.js";
+/** @public */
 export { fromNative, toNative } from "./native-value.js";
-export { getObjectProperty, newObjectWithProperties, setObjectProperty } from "./object.js";
-export { type FinishResult, promisify } from "./promisify.js";
-export { registerClass } from "./register-class.js";
+/** @public */
 export {
+    type ConstructBinding,
+    type ConstructBindings,
+    getObjectProperty,
+    newObjectWithProperties,
+    registerConstructProperties,
+    setObjectProperty,
+} from "./object.js";
+/** @public */
+export { promisify } from "./promisify.js";
+/** @public */
+export { type Interface, registerClass } from "./register-class.js";
+/** @public */
+export {
+    getClassType,
     getHandle,
     getInstanceType,
     getWrapperClass,
@@ -16,11 +37,13 @@ export {
     registerWrapperClass,
     type StaticBase,
     setHandle,
-    tryGetHandle,
     wrapHandle,
 } from "./registry.js";
-export { connectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
+/** @public */
+export { connectSignal, disconnectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
+/** @public */
 export { t } from "./t.js";
+/** @public */
 export {
     resolveType,
     TYPE_BOOLEAN,
@@ -55,5 +78,11 @@ export {
     typeParent,
     valueIsA,
 } from "./type.js";
+/** @public */
 export { getBoxedValue, setBoxedValue } from "./value.js";
-export { alloc, type ExternalObject, type Handle, read, setWrapper, write } from "@gtkx/native";
+/** @public */
+export { callParent, callVfunc } from "./vfunc-call.js";
+/** @public */
+export { alloc, type ExternalObject, type Handle, read, write } from "@gtkx/native";
+/** @public */
+export { type AnyClass } from "@gtkx/utils";

package/src/internal.ts

@@ -1,5 +1,6 @@
 export { checkError, createErrorDomain } from "./error.js";
 export { registerClassType, resolveWrapperClass, wrapHandle } from "./registry.js";
+export { hasSignalListener } from "./signal.js";
 export { resolveType } from "./type.js";
 export {
     fromValue,

package/src/library.ts

@@ -2,6 +2,7 @@ import { type BoxedDescriptor, boxedT, type FundamentalDescriptor, fundamentalT
 
 const LIB = "libgobject-2.0.so.0,libglib-2.0.so.0";
 const VALUE_SIZE = 24;
+const CLOSURE_SIZE = 32;
 const VALUE_T: BoxedDescriptor = boxedT("GValue", { sharedLibrary: LIB, getTypeFnName: "g_value_get_type" });
 
 const PARAM_T: FundamentalDescriptor = fundamentalT(LIB, "g_param_spec_ref", "g_param_spec_unref", {
@@ -14,4 +15,4 @@ const VARIANT_T: FundamentalDescriptor = fundamentalT(LIB, "g_variant_ref", "g_v
     typeName: "GVariant",
 });
 
-export { LIB, VALUE_SIZE, VALUE_T, PARAM_T, VARIANT_T };
+export { CLOSURE_SIZE, LIB, VALUE_SIZE, VALUE_T, PARAM_T, VARIANT_T };

package/src/lifecycle.ts

@@ -1,22 +1,46 @@
 import { keepAlive, quit as nativeQuit } from "@gtkx/native";
-import { blockMatchedSignalHandlers } from "./signal.js";
+import { isDerivedApplication, type LocalCommandLineApplication, shutDownThroughRun } from "./application-class.js";
 
 /**
- * Minimal structural interface of a GTK4/GIO application needed to register, run,
- * and shut it down, plus the signals its lifecycle helpers connect to.
+ * The GIO and GTK application surface {@link runApplication} and {@link quitApplication} drive, so any
+ * application subclass satisfies it structurally; the window members only `Gtk.Application` defines are
+ * optional.
  */
 type ApplicationLike = {
+    /** Returns whether the application has already been registered. */
     getIsRegistered(): boolean;
+    /** Returns whether another process owns the application ID, making this one a remote instance. */
+    getIsRemote?(): boolean;
+    /** Registers the application with the session, returning whether it succeeded. */
     register(cancellable: null): boolean;
+    /** Emits `activate`, bringing up the application's initial user interface. */
     activate(): void;
-    quit(): void;
+    /**
+     * Runs GLib's own `g_application_run`, whose tail emits `shutdown`, destroys the application
+     * implementation and clears the registration.
+     */
     run(argv: string[]): number;
+    /** Returns the windows currently attached to the application. */
     getWindows?(): object[];
+    /** Detaches a window, so it no longer holds the application open. */
     removeWindow?(window: object): void;
+    /** Connects a handler to the application's `activate` or `shutdown` signal. */
     on(signal: "activate" | "shutdown", handler: () => void): unknown;
+    /** Emits one of the application's own signals. */
+    emit(signal: "shutdown"): unknown;
+};
+
+/** What {@link runApplication} reports about the process it just started. */
+type RunApplicationResult = {
+    /** Whether this process owns the application ID and may build a user interface. */
+    isPrimary: boolean;
+    /** The status GLib determined for the command line, which the process should exit with. */
+    exitStatus: number;
 };
 
 const shutdownCallbacks: (() => void)[] = [];
+const startedApplications: WeakSet<object> = new WeakSet();
+const shutDownApplications: WeakSet<object> = new WeakSet();
 /**
  * Runs every registered exit callback and shuts down the native runtime. Safe to
  * call more than once; only the first call takes effect.
@@ -51,13 +75,9 @@ const onExit = (callback: () => void): void => {
     shutdownCallbacks.push(callback);
 };
 
-/**
- * Registers the application if needed and activates it, keeping the runtime alive
- * while it is active and releasing it on shutdown.
- *
- * @param application The application to register and activate.
- */
-const runApplication = (application: ApplicationLike): void => {
+const startApplication = (application: ApplicationLike & LocalCommandLineApplication, argv: string[]): number => {
+    startedApplications.add(application);
+
     application.on("activate", () => {
         keepAlive(true);
     });
@@ -66,21 +86,78 @@ const runApplication = (application: ApplicationLike): void => {
         keepAlive(false);
     });
 
-    if (!application.getIsRegistered()) {
-        application.register(null);
+    return application.runLocalCommandLine(argv)[2];
+};
+
+const restartApplication = (application: ApplicationLike): number => {
+    shutDownApplications.delete(application);
+
+    if (!application.register(null)) {
+        return 1;
     }
 
     application.activate();
+
+    return 0;
 };
 
 /**
- * Closes all of the application's windows and drives its main loop until it quits,
- * so pending shutdown work can complete before the process exits.
+ * Hands `argv` to GLib's own command line handling, which parses the application's options, prints
+ * `--help`, runs `handle-local-options`, registers the application, and either activates it or
+ * forwards the command line to the process that already owns the application ID. The runtime is
+ * held alive while the application is active and released on shutdown.
+ *
+ * `g_application_run()` is not what starts the application, because it would drive its own main loop
+ * and freeze Node; only the local command line handling it delegates to runs here. {@link
+ * quitApplication} calls it once no window holds the application open, to reach the teardown only it
+ * performs.
+ *
+ * GLib parses a given application's command line at most once, so starting an application that has
+ * already run registers and activates it instead of reading `argv` again.
+ *
+ * When another process already owns the application ID, this one registers as a remote instance: no
+ * user interface may be built here, because a remote application has no `GtkApplicationImpl` and
+ * attaching a window to it crashes.
+ *
+ * @param application The application to start.
+ * @param argv The command line, whose first entry names the program as `--help` should print it.
+ * @returns Whether this process may build a user interface, and the status to exit with.
+ */
+const runApplication = (application: ApplicationLike, argv: string[]): RunApplicationResult => {
+    if (!isDerivedApplication(application)) {
+        throw new Error(
+            "runApplication: this application was not built by GTKX, so its command line cannot be " +
+            "parsed and it cannot be shut down safely; render <GtkApplication> or <AdwApplication>, " +
+            "or construct it with createApplication from @gtkx/runtime",
+        );
+    }
+
+    const exitStatus = startedApplications.has(application)
+        ? restartApplication(application)
+        : startApplication(application, argv);
+
+    const isPrimary = application.getIsRegistered() && application.getIsRemote?.() !== true;
+
+    if (isPrimary) {
+        keepAlive(true);
+    }
+
+    return { isPrimary, exitStatus };
+};
+
+/**
+ * Detaches every window from the application and runs GLib's own shutdown, which emits `shutdown`,
+ * destroys the application implementation and releases the D-Bus registration. Does nothing for an
+ * application that is not registered, so a repeated call is a no-op.
+ *
+ * GLib's own shutdown is reachable once per application: reaching it marks the application as
+ * quitting, which GLib never undoes. An application that has already quit falls back to emitting
+ * `shutdown`, which releases the runtime and leaves the registration for GLib to drop at finalize.
  *
  * @param application The application to shut down.
  */
 const quitApplication = (application: ApplicationLike): void => {
-    if (!application.getIsRegistered()) {
+    if (!application.getIsRegistered() || shutDownApplications.has(application)) {
         return;
     }
 
@@ -90,12 +167,12 @@ const quitApplication = (application: ApplicationLike): void => {
         application.removeWindow?.(window);
     }
 
-    application.on("shutdown", () => {
-        application.quit();
-    });
+    shutDownThroughRun(application);
 
-    blockMatchedSignalHandlers(application, "activate");
-    application.run([]);
+    if (application.getIsRegistered()) {
+        shutDownApplications.add(application);
+        application.emit("shutdown");
+    }
 };
 
-export { onExit, quit, runApplication, quitApplication, type ApplicationLike };
+export { onExit, quit, runApplication, quitApplication, type ApplicationLike, type RunApplicationResult };

package/src/listeners.ts

@@ -1,7 +1,13 @@
-import { isSignalHandlerConnected, type SignalHandler } from "./signal.js";
+import { isSignalHandlerConnected, type SignalHandler, untrackConnection } from "./signal.js";
 
+/**
+ * The connect and disconnect surface {@link onSignal}, {@link onceSignal} and {@link offSignal}
+ * drive on an emitter.
+ */
 type SignalConnectable = {
+    /** Connects a handler to a signal and returns its handler id. */
     connect(signal: string, handler: SignalHandler, isAfter?: boolean): number;
+    /** Disconnects the handler previously connected under the given id. */
     disconnect(handlerId: number): void;
 };
 
@@ -75,6 +81,7 @@ function onceSignal(instance: SignalConnectable, signal: string, handler: Signal
 
     const wrapped: SignalHandler = (...args) => {
         untrackHandlerId(instance, signal, handlerId);
+        untrackConnection(instance, handlerId);
         instance.disconnect(handlerId);
 
         return handler(...args);
@@ -101,6 +108,7 @@ function offSignal(instance: SignalConnectable, signal: string, handler: SignalH
     }
 
     untrackHandlerId(instance, signal, handlerId);
+    untrackConnection(instance, handlerId);
 
     if (!isSignalHandlerConnected(instance, handlerId)) {
         return;

package/src/mixin.ts

@@ -1,7 +1,13 @@
-import type { AnyClass } from "@gtkx/utils";
+import { type AnyClass, getParentClass } from "@gtkx/utils";
 
+/**
+ * The signal plumbing every base class passed to a {@link Mixin} provides, so mixed-in interface
+ * members can connect and emit without knowing the concrete class.
+ */
 type MixinReceiver = {
+    /** Connects a handler to a signal and returns its handler id. */
     connect(signal: string, handler: (...args: unknown[]) => unknown, isAfter?: boolean): number;
+    /** Emits a signal with the given arguments and returns whatever the emission produced. */
     emit(signal: string, ...args: unknown[]): unknown;
 };
 
@@ -41,6 +47,12 @@ function copyLayerMember(target: AnyClass, layer: object, key: string): void {
     }
 }
 
+function copyLayerMembers(target: AnyClass, layer: object): void {
+    for (const key of Object.getOwnPropertyNames(layer)) {
+        copyLayerMember(target, layer, key);
+    }
+}
+
 /**
  * Copies each mixin's prototype members onto the target class prototype, skipping
  * any member already defined anywhere in the target's class chain.
@@ -48,12 +60,6 @@ function copyLayerMember(target: AnyClass, layer: object, key: string): void {
  * @param target The class whose prototype receives the mixin members.
  * @param mixins The mixins to apply, in order.
  */
-function copyLayerMembers(target: AnyClass, layer: object): void {
-    for (const key of Object.getOwnPropertyNames(layer)) {
-        copyLayerMember(target, layer, key);
-    }
-}
-
 function installMixins(target: AnyClass, mixins: Mixin[]): void {
     const empty: AnyClass<MixinReceiver> = class {
         connect(): number {
@@ -70,4 +76,17 @@ function installMixins(target: AnyClass, mixins: Mixin[]): void {
     }
 }
 
-export { installMixins, type MixinReceiver, type Mixin };
+function dropLayerMembers(layer: AnyClass, names: Set<string>): void {
+    for (const name of names) {
+        Reflect.deleteProperty(layer.prototype, name);
+    }
+}
+
+function insertMixinLayer(target: AnyClass, mixin: Mixin, inheritedNames: Set<string>): void {
+    const layer = mixin(getParentClass(target) as AnyClass<MixinReceiver>);
+    dropLayerMembers(layer, inheritedNames);
+    Object.setPrototypeOf(target.prototype, layer.prototype);
+    Object.setPrototypeOf(target, layer);
+}
+
+export { insertMixinLayer, installMixins, type MixinReceiver, type Mixin };

package/src/native-value.ts

@@ -1,6 +1,6 @@
 import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
 import type { ArrayDescriptor, FundamentalDescriptor, HashTableDescriptor, StructDescriptor } from "./descriptors.js";
-import { getWrapperClass, tryGetHandle, wrapHandle } from "./registry.js";
+import { getHandle, getWrapperClass, wrapHandle, wrapObject } from "./registry.js";
 import { resolveDescriptorType } from "./type.js";
 
 type MarshalledKind = "object" | "struct" | "boxed" | "fundamental" | "array" | "hashtable";
@@ -76,7 +76,7 @@ function fromNative(descriptor: Descriptor, value: unknown): unknown {
 
     switch (descriptor.kind) {
         case "object": {
-            return wrapHandle(value as ExternalObject<Handle> | null);
+            return wrapObject(value);
         }
         case "struct": {
             return wrapHandle(value as ExternalObject<Handle> | null, (descriptor as StructDescriptor).wrapperClass);
@@ -111,6 +111,14 @@ function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unk
     ]);
 }
 
+/**
+ * Converts a JavaScript value into the raw form native code expects, unwrapping
+ * object, struct, boxed, and fundamental wrappers back to their handles and
+ * recursively converting arrays and maps according to the descriptor.
+ *
+ * @param descriptor Describes the native type to convert to.
+ * @param value The JavaScript value to convert.
+ */
 function toNative(descriptor: Descriptor, value: unknown): unknown {
     if (!isMarshalledDescriptor(descriptor)) {
         return value;
@@ -121,7 +129,9 @@ function toNative(descriptor: Descriptor, value: unknown): unknown {
         case "struct":
         case "boxed":
         case "fundamental": {
-            return tryGetHandle(value as object | null | undefined) ?? null;
+            const instance = value as object | null | undefined;
+
+            return instance == null ? null : getHandle(instance);
         }
         case "array": {
             return collectionToNative(descriptor, value);

package/src/object.ts

@@ -1,21 +1,25 @@
-import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
+import { type Descriptor, type ExternalObject, type Handle, newObject } from "@gtkx/native";
+import { type AnyClass, getParentClass } from "@gtkx/utils";
 import { bind } from "./bind.js";
-import { biguint64T, objectT, sizedArrayT, stringT, uint32T, voidT } from "./descriptors.js";
-import { LIB, VALUE_SIZE, VALUE_T } from "./library.js";
-import { getHandle } from "./registry.js";
+import { objectT, stringT, voidT } from "./descriptors.js";
+import { LIB, VALUE_T } from "./library.js";
+import { type ConstructProperty, constructPropertyFor } from "./properties.js";
+import { getHandle, registerWrapper } from "./registry.js";
 import { fromValue, newValueForDescriptor, toValue } from "./value.js";
 
-const gObjectNewWithProperties = bind(
-    LIB,
-    "g_object_new_with_properties",
-    [
-        biguint64T,
-        uint32T,
-        sizedArrayT(stringT("borrowed"), 1, "borrowed"),
-        sizedArrayT(VALUE_T, 1, "borrowed", VALUE_SIZE),
-    ],
-    objectT("full"),
-);
+/**
+ * One construct property a wrapper class accepts: the canonical `GObject` name it is set under,
+ * and the descriptor its value is marshalled through.
+ */
+type ConstructBinding = [name: string, descriptor: Descriptor];
+/** The construct properties a wrapper class accepts, keyed by the camelCased name callers give them. */
+type ConstructBindings = Record<string, ConstructBinding>;
+type ResolvedBindings = { generation: number; bindings: ConstructBindings };
+
+const declaredBindings: WeakMap<AnyClass, ConstructBindings> = new WeakMap();
+const resolvedBindings: WeakMap<AnyClass, ResolvedBindings> = new WeakMap();
+const declarations = { generation: 0 };
+const NO_BINDINGS: ConstructBindings = Object.create(null) as ConstructBindings;
 
 const gObjectGetProperty = bind(
     LIB,
@@ -31,37 +35,120 @@ const gObjectSetProperty = bind(
     voidT,
 );
 
+function collectDeclaredBindings(cls: AnyClass): ConstructBindings[] {
+    const declared: ConstructBindings[] = [];
+    let current: AnyClass | null = cls;
+
+    while (current !== null) {
+        const own = declaredBindings.get(current);
+
+        if (own !== undefined) {
+            declared.push(own);
+        }
+
+        current = getParentClass(current);
+    }
+
+    return declared;
+}
+
+function mergeDeclaredBindings(cls: AnyClass): ConstructBindings {
+    const declared = collectDeclaredBindings(cls);
+    const merged: ConstructBindings = Object.create(null) as ConstructBindings;
+
+    for (let index = declared.length - 1; index >= 0; index--) {
+        Object.assign(merged, declared[index]);
+    }
+
+    return merged;
+}
+
+function constructBindingsFor(cls: AnyClass | undefined): ConstructBindings {
+    if (cls === undefined) {
+        return NO_BINDINGS;
+    }
+
+    const cached = resolvedBindings.get(cls);
+
+    if (cached?.generation === declarations.generation) {
+        return cached.bindings;
+    }
+
+    const bindings = mergeDeclaredBindings(cls);
+    resolvedBindings.set(cls, { generation: declarations.generation, bindings });
+
+    return bindings;
+}
+
+/**
+ * Declares the construct properties a wrapper class accepts, so `newObjectWithProperties`
+ * marshals each one through its descriptor rather than resolving it from the
+ * `GObject.ParamSpec` the type installs. A class inherits the declarations of its ancestors.
+ * Registering takes effect immediately, including for classes already constructed from and for
+ * subclasses that already inherited an earlier declaration.
+ *
+ * @param cls The wrapper class the properties are declared on.
+ * @param bindings CamelCased property names mapped to their canonical name and descriptor.
+ */
+function registerConstructProperties(cls: AnyClass, bindings: ConstructBindings): void {
+    declaredBindings.set(cls, bindings);
+    declarations.generation += 1;
+}
+
+function constructPropertyForEntry(
+    source: { gtype: bigint; bindings: ConstructBindings; wrapper: object },
+    name: string,
+    value: unknown,
+): ConstructProperty | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    const binding = source.bindings[name];
+
+    if (binding === undefined) {
+        return constructPropertyFor(source.gtype, name, value, source.wrapper);
+    }
+
+    return { name: binding[0], value: toValue(binding[1], value) };
+}
+
 /**
  * Constructs a new GObject of the given type, setting the supplied construct
- * properties. Entries whose value is `undefined` or not a `[descriptor, value]`
- * pair are skipped.
+ * properties, and binds `wrapper` to it. A property the wrapper's class declares
+ * through `registerConstructProperties` is marshalled through its descriptor; any
+ * other one is marshalled through the `GObject.ParamSpec` the type installs under
+ * that name, dashed or camelCased, and is skipped when the type installs none.
+ * A value that ParamSpec would refuse throws before GObject sees it: a `TypeError`
+ * for a read-only property and for a value of a type the property cannot hold, and
+ * a `RangeError` for a value the ParamSpec rejects.
+ * Properties whose value is `undefined` are skipped. A type registered with
+ * `registerClass` binds the wrapper before its `constructed` slot runs, so an
+ * override of that slot already sees a usable instance.
  *
  * @param gtype The GType of the object to construct.
- * @param props Property names mapped to `[descriptor, value]` pairs.
+ * @param props Property names mapped to the values to set them to.
+ * @param wrapper The wrapper instance to bind to the new object.
  * @returns The handle of the newly created object.
  */
-function newObjectWithProperties(gtype: bigint, props: Record<string, unknown>): ExternalObject<Handle> {
+function newObjectWithProperties(gtype: bigint, props: object, wrapper: object): ExternalObject<Handle> {
     const names: string[] = [];
     const values: ExternalObject<Handle>[] = [];
+    const bindings = constructBindingsFor(wrapper.constructor as AnyClass | undefined);
+    const source = { gtype, bindings, wrapper };
 
-    for (const name in props) {
-        const entry: unknown = props[name];
+    for (const name of Object.keys(props)) {
+        const property = constructPropertyForEntry(source, name, Reflect.get(props, name));
 
-        if (!Array.isArray(entry)) {
-            continue;
+        if (property !== undefined) {
+            names.push(property.name);
+            values.push(property.value);
         }
-
-        const [descriptor, value] = entry as [Descriptor, unknown];
-
-        if (value === undefined) {
-            continue;
-        }
-
-        names.push(name);
-        values.push(toValue(descriptor, value));
     }
 
-    return gObjectNewWithProperties(gtype, names.length, names, values) as ExternalObject<Handle>;
+    newObject(gtype, names, values, wrapper, registerWrapper);
+
+    return getHandle(wrapper);
 }
 
 /**
@@ -92,4 +179,11 @@ function setObjectProperty(obj: object, propertyName: string, descriptor: Descri
     gObjectSetProperty(getHandle(obj), propertyName, toValue(descriptor, jsValue));
 }
 
-export { newObjectWithProperties, getObjectProperty, setObjectProperty };
+export {
+    newObjectWithProperties,
+    getObjectProperty,
+    registerConstructProperties,
+    setObjectProperty,
+    type ConstructBinding,
+    type ConstructBindings,
+};