@gtkx/runtime 0.0.1 → 1.0.0-rc.2

package/src/lifecycle.ts

@@ -0,0 +1,101 @@
+import { keepAlive, quit as nativeQuit } from "@gtkx/native";
+import { blockMatchedSignalHandlers } from "./signal.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.
+ */
+type ApplicationLike = {
+    getIsRegistered(): boolean;
+    register(cancellable: null): boolean;
+    activate(): void;
+    quit(): void;
+    run(argv: string[]): number;
+    getWindows?(): object[];
+    removeWindow?(window: object): void;
+    on(signal: "activate" | "shutdown", handler: () => void): unknown;
+};
+
+const shutdownCallbacks: (() => void)[] = [];
+/**
+ * Runs every registered exit callback and shuts down the native runtime. Safe to
+ * call more than once; only the first call takes effect.
+ */
+const quit: () => void = createQuit();
+
+function createQuit(): () => void {
+    let hasQuit = false;
+
+    return () => {
+        if (hasQuit) {
+            return;
+        }
+
+        hasQuit = true;
+
+        for (const callback of shutdownCallbacks) {
+            callback();
+        }
+
+        nativeQuit();
+    };
+}
+
+/**
+ * Registers a callback to run once when the process quits, before the native
+ * runtime is torn down.
+ *
+ * @param callback Invoked during shutdown.
+ */
+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 => {
+    application.on("activate", () => {
+        keepAlive(true);
+    });
+
+    application.on("shutdown", () => {
+        keepAlive(false);
+    });
+
+    if (!application.getIsRegistered()) {
+        application.register(null);
+    }
+
+    application.activate();
+};
+
+/**
+ * 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.
+ *
+ * @param application The application to shut down.
+ */
+const quitApplication = (application: ApplicationLike): void => {
+    if (!application.getIsRegistered()) {
+        return;
+    }
+
+    const windows = application.getWindows?.() ?? [];
+
+    for (const window of windows) {
+        application.removeWindow?.(window);
+    }
+
+    application.on("shutdown", () => {
+        application.quit();
+    });
+
+    blockMatchedSignalHandlers(application, "activate");
+    application.run([]);
+};
+
+export { onExit, quit, runApplication, quitApplication, type ApplicationLike };

package/src/listeners.ts

@@ -0,0 +1,112 @@
+import { isSignalHandlerConnected, type SignalHandler } from "./signal.js";
+
+type SignalConnectable = {
+    connect(signal: string, handler: SignalHandler, isAfter?: boolean): number;
+    disconnect(handlerId: number): void;
+};
+
+const listenerTable: WeakMap<object, Map<string, Map<SignalHandler, number>>> = new WeakMap();
+
+const findListenerHandlerId = (instance: object, signal: string, handler: SignalHandler): number | undefined =>
+    listenerTable.get(instance)?.get(signal)?.get(handler);
+
+const trackListener = (instance: object, signal: string, handler: SignalHandler, handlerId: number): void => {
+    let bySignal = listenerTable.get(instance);
+
+    if (!bySignal) {
+        bySignal = new Map();
+        listenerTable.set(instance, bySignal);
+    }
+
+    let byHandler = bySignal.get(signal);
+
+    if (!byHandler) {
+        byHandler = new Map();
+        bySignal.set(signal, byHandler);
+    }
+
+    byHandler.set(handler, handlerId);
+};
+
+const untrackHandlerId = (instance: object, signal: string, handlerId: number): void => {
+    const bySignal = listenerTable.get(instance);
+    const byHandler = bySignal?.get(signal);
+
+    if (byHandler === undefined) {
+        return;
+    }
+
+    for (const [handler, id] of byHandler) {
+        if (id === handlerId) {
+            byHandler.delete(handler);
+        }
+    }
+
+    if (byHandler.size === 0) {
+        bySignal?.delete(signal);
+    }
+};
+
+/**
+ * Connects a handler to a signal and tracks it so it can later be removed with
+ * {@link offSignal}.
+ *
+ * @param instance The object emitting the signal.
+ * @param signal The signal name to connect to.
+ * @param handler The callback invoked on each emission.
+ * @param isAfter When true, run the handler after the default handler.
+ */
+function onSignal(instance: SignalConnectable, signal: string, handler: SignalHandler, isAfter?: boolean): void {
+    const handlerId = instance.connect(signal, handler, isAfter);
+    trackListener(instance, signal, handler, handlerId);
+}
+
+/**
+ * Connects a handler that runs at most once, disconnecting itself after the first
+ * emission.
+ *
+ * @param instance The object emitting the signal.
+ * @param signal The signal name to connect to.
+ * @param handler The callback invoked on the first emission.
+ * @param isAfter When true, run the handler after the default handler.
+ */
+function onceSignal(instance: SignalConnectable, signal: string, handler: SignalHandler, isAfter?: boolean): void {
+    let handlerId = 0;
+
+    const wrapped: SignalHandler = (...args) => {
+        untrackHandlerId(instance, signal, handlerId);
+        instance.disconnect(handlerId);
+
+        return handler(...args);
+    };
+
+    handlerId = instance.connect(signal, wrapped, isAfter);
+    trackListener(instance, signal, wrapped, handlerId);
+    trackListener(instance, signal, handler, handlerId);
+}
+
+/**
+ * Disconnects a handler previously connected with {@link onSignal} or
+ * {@link onceSignal}. Does nothing if the handler is not currently connected.
+ *
+ * @param instance The object the handler was connected to.
+ * @param signal The signal name the handler was connected to.
+ * @param handler The handler to disconnect.
+ */
+function offSignal(instance: SignalConnectable, signal: string, handler: SignalHandler): void {
+    const handlerId = findListenerHandlerId(instance, signal, handler);
+
+    if (handlerId === undefined) {
+        return;
+    }
+
+    untrackHandlerId(instance, signal, handlerId);
+
+    if (!isSignalHandlerConnected(instance, handlerId)) {
+        return;
+    }
+
+    instance.disconnect(handlerId);
+}
+
+export { onSignal, onceSignal, offSignal };

package/src/mixin.ts

@@ -0,0 +1,73 @@
+import type { AnyClass } from "@gtkx/utils";
+
+type MixinReceiver = {
+    connect(signal: string, handler: (...args: unknown[]) => unknown, isAfter?: boolean): number;
+    emit(signal: string, ...args: unknown[]): unknown;
+};
+
+/**
+ * A factory that, given a base class, returns a subclass adding extra members to
+ * be merged onto a target prototype.
+ */
+type Mixin = (base: AnyClass<MixinReceiver>) => AnyClass;
+
+function isDefinedInClassChain(prototype: object, key: string): boolean {
+    let current: object | null = prototype;
+
+    while (current !== null && current !== Object.prototype) {
+        if (Object.hasOwn(current, key)) {
+            return true;
+        }
+
+        current = Reflect.getPrototypeOf(current);
+    }
+
+    return false;
+}
+
+function copyLayerMember(target: AnyClass, layer: object, key: string): void {
+    if (key === "constructor") {
+        return;
+    }
+
+    if (isDefinedInClassChain(target.prototype, key)) {
+        return;
+    }
+
+    const descriptor = Object.getOwnPropertyDescriptor(layer, key);
+
+    if (descriptor !== undefined) {
+        Object.defineProperty(target.prototype, key, descriptor);
+    }
+}
+
+/**
+ * Copies each mixin's prototype members onto the target class prototype, skipping
+ * any member already defined anywhere in the target's class chain.
+ *
+ * @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 {
+            return 0;
+        }
+
+        emit(): unknown {
+            return undefined;
+        }
+    };
+
+    for (const mixin of mixins) {
+        copyLayerMembers(target, mixin(empty).prototype);
+    }
+}
+
+export { installMixins, type MixinReceiver, type Mixin };

package/src/native-value.ts

@@ -0,0 +1,135 @@
+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 { resolveDescriptorType } from "./type.js";
+
+type MarshalledKind = "object" | "struct" | "boxed" | "fundamental" | "array" | "hashtable";
+type MarshalledDescriptor = Extract<Descriptor, { kind: MarshalledKind }>;
+
+const MARSHALLED_KINDS: Set<Descriptor["kind"]> = new Set<MarshalledKind>([
+    "object",
+    "struct",
+    "boxed",
+    "fundamental",
+    "array",
+    "hashtable",
+]);
+
+function isMarshalledDescriptor(descriptor: Descriptor): descriptor is MarshalledDescriptor {
+    return MARSHALLED_KINDS.has(descriptor.kind);
+}
+
+function mapCollection(
+    descriptor: ArrayDescriptor,
+    value: unknown,
+    convert: (itemDescriptor: Descriptor, item: unknown) => unknown,
+): unknown[] {
+    return (value as unknown[]).map((item) => convert(descriptor.itemDescriptor, item));
+}
+
+function collectionFromNative(descriptor: ArrayDescriptor, value: unknown): unknown {
+    return value === null ? null : mapCollection(descriptor, value, fromNative);
+}
+
+function boxedFromNative(descriptor: Descriptor, value: unknown): unknown {
+    return value == null
+        ? null
+        : wrapHandle(value as ExternalObject<Handle>, getWrapperClass(resolveDescriptorType(descriptor)));
+}
+
+function fundamentalFromNative(descriptor: FundamentalDescriptor, value: unknown): unknown {
+    return value == null
+        ? null
+        : wrapHandle(
+                value as ExternalObject<Handle>,
+                descriptor.wrapperClass ?? getWrapperClass(resolveDescriptorType(descriptor)),
+            );
+}
+
+function hashTableFromNative(descriptor: HashTableDescriptor, value: unknown): unknown {
+    if (value === null) {
+        return null;
+    }
+
+    const entries = value as [unknown, unknown][];
+
+    return new Map(
+        entries.map(([key, val]): [unknown, unknown] => [
+            fromNative(descriptor.keyDescriptor, key),
+            fromNative(descriptor.valueDescriptor, val),
+        ]),
+    );
+}
+
+/**
+ * Converts a raw value returned from native code into its JavaScript form,
+ * wrapping object, struct, boxed, and fundamental handles and recursively
+ * converting arrays and hash tables according to the descriptor.
+ *
+ * @param descriptor Describes the native type of the value.
+ * @param value The raw native value to convert.
+ */
+function fromNative(descriptor: Descriptor, value: unknown): unknown {
+    if (!isMarshalledDescriptor(descriptor)) {
+        return value;
+    }
+
+    switch (descriptor.kind) {
+        case "object": {
+            return wrapHandle(value as ExternalObject<Handle> | null);
+        }
+        case "struct": {
+            return wrapHandle(value as ExternalObject<Handle> | null, (descriptor as StructDescriptor).wrapperClass);
+        }
+        case "boxed": {
+            return boxedFromNative(descriptor, value);
+        }
+        case "fundamental": {
+            return fundamentalFromNative(descriptor, value);
+        }
+        case "array": {
+            return collectionFromNative(descriptor, value);
+        }
+        case "hashtable": {
+            return hashTableFromNative(descriptor, value);
+        }
+    }
+}
+
+function collectionToNative(descriptor: ArrayDescriptor, value: unknown): unknown {
+    return value == null ? null : mapCollection(descriptor, value, toNative);
+}
+
+function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unknown {
+    if (value == null) {
+        return null;
+    }
+
+    return [...(value as Map<unknown, unknown>)].map(([key, val]): [unknown, unknown] => [
+        toNative(descriptor.keyDescriptor, key),
+        toNative(descriptor.valueDescriptor, val),
+    ]);
+}
+
+function toNative(descriptor: Descriptor, value: unknown): unknown {
+    if (!isMarshalledDescriptor(descriptor)) {
+        return value;
+    }
+
+    switch (descriptor.kind) {
+        case "object":
+        case "struct":
+        case "boxed":
+        case "fundamental": {
+            return tryGetHandle(value as object | null | undefined) ?? null;
+        }
+        case "array": {
+            return collectionToNative(descriptor, value);
+        }
+        case "hashtable": {
+            return hashTableToNative(descriptor, value);
+        }
+    }
+}
+
+export { fromNative, toNative };

package/src/object.ts

@@ -0,0 +1,95 @@
+import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
+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 { 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"),
+);
+
+const gObjectGetProperty = bind(
+    LIB,
+    "g_object_get_property",
+    [objectT("borrowed"), stringT("borrowed"), VALUE_T],
+    voidT,
+);
+
+const gObjectSetProperty = bind(
+    LIB,
+    "g_object_set_property",
+    [objectT("borrowed"), stringT("borrowed"), VALUE_T],
+    voidT,
+);
+
+/**
+ * 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.
+ *
+ * @param gtype The GType of the object to construct.
+ * @param props Property names mapped to `[descriptor, value]` pairs.
+ * @returns The handle of the newly created object.
+ */
+function newObjectWithProperties(gtype: bigint, props: Record<string, unknown>): ExternalObject<Handle> {
+    const names: string[] = [];
+    const values: ExternalObject<Handle>[] = [];
+
+    for (const name in props) {
+        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));
+    }
+
+    return gObjectNewWithProperties(gtype, names.length, names, values) as ExternalObject<Handle>;
+}
+
+/**
+ * Reads a GObject property and converts it to its JavaScript value using the
+ * descriptor.
+ *
+ * @param obj The object to read from.
+ * @param propertyName The property name.
+ * @param descriptor Describes the property's type.
+ */
+function getObjectProperty(obj: object, propertyName: string, descriptor: Descriptor): unknown {
+    const value = newValueForDescriptor(descriptor);
+    gObjectGetProperty(getHandle(obj), propertyName, value);
+
+    return fromValue(value);
+}
+
+/**
+ * Writes a JavaScript value to a GObject property, converting it to native form
+ * using the descriptor.
+ *
+ * @param obj The object to write to.
+ * @param propertyName The property name.
+ * @param descriptor Describes the property's type.
+ * @param jsValue The value to set.
+ */
+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

@@ -0,0 +1,67 @@
+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;
+    }
+
+    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,
+ * the call site's stack is captured and attached as the rejection error's cause.
+ *
+ * @param asyncFn The async function, called with the leading arguments, the cancellable, and a completion callback.
+ * @param finish Extracts the result from the async result passed to the completion callback.
+ * @param cancellable A cancellable object, or null/undefined for none.
+ * @param leading Arguments passed to `asyncFn` before the cancellable and callback.
+ * @returns A promise resolving to the finished result, or rejecting if `finish` throws.
+ */
+const promisify = <R extends object, T>(
+    asyncFn: (...args: unknown[]) => void,
+    finish: FinishResult<R, T>,
+    cancellable: object | null | undefined,
+    ...leading: unknown[]
+): Promise<T> =>
+    new Promise<T>((resolve, reject) => {
+        const creationStack =
+            process.env.NODE_ENV === "production" ? undefined : new Error("gtkx async operation started here");
+
+        asyncFn(...leading, tryGetHandle(cancellable), (_source: object | null, asyncResult: object) => {
+            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,
+};