@gtkx/runtime 0.0.1 → 1.0.0-rc.1

package/src/descriptors.ts

@@ -0,0 +1,208 @@
+import type { ArrayKind, Descriptor, Ownership } from "@gtkx/native";
+import type { AnyClass } from "@gtkx/utils";
+
+export type Int8Descriptor = Extract<Descriptor, { kind: "int8" }>;
+export type Uint8Descriptor = Extract<Descriptor, { kind: "uint8" }>;
+export type Int16Descriptor = Extract<Descriptor, { kind: "int16" }>;
+export type Uint16Descriptor = Extract<Descriptor, { kind: "uint16" }>;
+export type Int32Descriptor = Extract<Descriptor, { kind: "int32" }>;
+export type Uint32Descriptor = Extract<Descriptor, { kind: "uint32" }>;
+export type Int64Descriptor = Extract<Descriptor, { kind: "int64" }>;
+export type Uint64Descriptor = Extract<Descriptor, { kind: "uint64" }>;
+export type BigInt64Descriptor = Extract<Descriptor, { kind: "bigint64" }>;
+export type BigUint64Descriptor = Extract<Descriptor, { kind: "biguint64" }>;
+export type Float32Descriptor = Extract<Descriptor, { kind: "float32" }>;
+export type Float64Descriptor = Extract<Descriptor, { kind: "float64" }>;
+export type EnumDescriptor = Extract<Descriptor, { kind: "enum" }>;
+export type FlagsDescriptor = Extract<Descriptor, { kind: "flags" }>;
+export type BooleanDescriptor = Extract<Descriptor, { kind: "boolean" }>;
+export type StringDescriptor = Extract<Descriptor, { kind: "string" }>;
+export type ObjectDescriptor = Extract<Descriptor, { kind: "object" }>;
+export type UnicharDescriptor = Extract<Descriptor, { kind: "unichar" }>;
+export type VoidDescriptor = Extract<Descriptor, { kind: "void" }>;
+export type BufferDescriptor = Extract<Descriptor, { kind: "buffer" }>;
+export type BoxedDescriptor = Extract<Descriptor, { kind: "boxed" }>;
+export type StructDescriptor = Extract<Descriptor, { kind: "struct" }> & { wrapperClass?: AnyClass };
+export type FundamentalDescriptor = Extract<Descriptor, { kind: "fundamental" }> & { wrapperClass?: AnyClass };
+export type ArrayDescriptor = Extract<Descriptor, { kind: "array" }>;
+export type HashTableDescriptor = Extract<Descriptor, { kind: "hashtable" }>;
+export type CallbackDescriptor = Extract<Descriptor, { kind: "callback" }>;
+export type RefDescriptor = Extract<Descriptor, { kind: "ref" }>;
+export type TypeDescriptor = BigUint64Descriptor & { type: true };
+
+type BoxedOptions = {
+    callerAllocated?: boolean;
+    ownership?: Ownership;
+    sharedLibrary?: string;
+    getTypeFnName?: string;
+    freeFnName?: string;
+    size?: number;
+};
+
+type CallbackOptions = {
+    hasDestroy?: boolean;
+    userDataIndex?: number;
+    scope?: CallbackDescriptor["scope"];
+};
+
+type ArrayOptions = {
+    elementSize?: number | undefined;
+    sizeParamIndex?: number | undefined;
+    fixedSize?: number | undefined;
+};
+
+type FundamentalOptions = {
+    ownership?: Ownership;
+    typeName?: string;
+    wrapperClass?: AnyClass;
+};
+
+type StructOptions = {
+    callerAllocated?: boolean;
+    size?: number;
+    wrapperClass?: AnyClass;
+};
+
+export const int8T: Int8Descriptor = { kind: "int8" };
+export const uint8T: Uint8Descriptor = { kind: "uint8" };
+export const int16T: Int16Descriptor = { kind: "int16" };
+export const uint16T: Uint16Descriptor = { kind: "uint16" };
+export const int32T: Int32Descriptor = { kind: "int32" };
+export const uint32T: Uint32Descriptor = { kind: "uint32" };
+export const int64T: Int64Descriptor = { kind: "int64" };
+export const uint64T: Uint64Descriptor = { kind: "uint64" };
+export const bigint64T: BigInt64Descriptor = { kind: "bigint64" };
+export const biguint64T: BigUint64Descriptor = { kind: "biguint64" };
+export const gtypeT: TypeDescriptor = { kind: "biguint64", type: true };
+export const float32T: Float32Descriptor = { kind: "float32" };
+export const float64T: Float64Descriptor = { kind: "float64" };
+export const booleanT: BooleanDescriptor = { kind: "boolean" };
+export const voidT: VoidDescriptor = { kind: "void" };
+export const unicharT: UnicharDescriptor = { kind: "unichar" };
+export const bufferT: BufferDescriptor = { kind: "buffer" };
+
+export const stringT = (ownership: Ownership = "borrowed", length?: number): StringDescriptor =>
+    length === undefined ? { kind: "string", ownership } : { kind: "string", ownership, length };
+
+export const objectT = (ownership: Ownership = "borrowed"): ObjectDescriptor => ({ kind: "object", ownership });
+
+export const refT = (innerDescriptor: Descriptor, inout = false): RefDescriptor =>
+    inout ? { kind: "ref", innerDescriptor, inout: true } : { kind: "ref", innerDescriptor };
+
+export const hashTableT = (
+    keyDescriptor: Descriptor,
+    valueDescriptor: Descriptor,
+    ownership: Ownership = "borrowed",
+): HashTableDescriptor => ({
+    kind: "hashtable",
+    keyDescriptor,
+    valueDescriptor,
+    ownership,
+});
+
+export const enumT = (sharedLibrary: string, getTypeFnName: string, signed: boolean): EnumDescriptor => ({
+    kind: "enum",
+    sharedLibrary,
+    getTypeFnName,
+    signed,
+});
+
+export const flagsT = (sharedLibrary: string, getTypeFnName: string, signed: boolean): FlagsDescriptor => ({
+    kind: "flags",
+    sharedLibrary,
+    getTypeFnName,
+    signed,
+});
+
+export const boxedT = (typeName: string, options: BoxedOptions = {}): BoxedDescriptor => {
+    const result: BoxedDescriptor = {
+        kind: "boxed",
+        ownership: options.ownership ?? "borrowed",
+        typeName,
+    };
+    if (options.sharedLibrary !== undefined) result.sharedLibrary = options.sharedLibrary;
+    if (options.getTypeFnName !== undefined) result.getTypeFnName = options.getTypeFnName;
+    if (options.freeFnName !== undefined) result.freeFnName = options.freeFnName;
+    if (options.callerAllocated) result.callerAllocated = true;
+    if (options.size !== undefined) result.size = options.size;
+    return result;
+};
+
+export const structT = (ownership: Ownership = "borrowed", options: StructOptions = {}): StructDescriptor => {
+    const result: StructDescriptor = { kind: "struct", ownership };
+    if (options.size !== undefined) result.size = options.size;
+    if (options.wrapperClass !== undefined) result.wrapperClass = options.wrapperClass;
+    if (options.callerAllocated) result.callerAllocated = true;
+    return result;
+};
+
+export const fundamentalT = (
+    sharedLibrary: string,
+    refFnName: string,
+    unrefFnName: string,
+    options: FundamentalOptions = {},
+): FundamentalDescriptor => {
+    const ownership = options.ownership ?? "borrowed";
+    const result: FundamentalDescriptor = { kind: "fundamental", ownership, sharedLibrary, refFnName, unrefFnName };
+    if (options.typeName !== undefined) result.typeName = options.typeName;
+    if (options.wrapperClass !== undefined) result.wrapperClass = options.wrapperClass;
+    return result;
+};
+
+export const arrayT = (
+    itemDescriptor: Descriptor,
+    arrayKind: ArrayKind = "array",
+    ownership: Ownership = "borrowed",
+    options?: ArrayOptions,
+): ArrayDescriptor => {
+    const result: ArrayDescriptor = { kind: "array", itemDescriptor, arrayKind, ownership };
+    if (options?.elementSize !== undefined) result.elementSize = options.elementSize;
+    if (options?.sizeParamIndex !== undefined) result.sizeParamIndex = options.sizeParamIndex;
+    if (options?.fixedSize !== undefined) result.fixedSize = options.fixedSize;
+    return result;
+};
+
+export const listT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(itemDescriptor, "glist", ownership);
+
+export const slistT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(itemDescriptor, "gslist", ownership);
+
+export const ptrArrayT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(itemDescriptor, "gptrarray", ownership);
+
+export const gArrayT = (
+    itemDescriptor: Descriptor,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor =>
+    arrayT(itemDescriptor, "garray", ownership, elementSize === undefined ? undefined : { elementSize });
+
+export const byteArrayT = (ownership: Ownership = "borrowed"): ArrayDescriptor =>
+    arrayT(uint8T, "gbytearray", ownership);
+
+export const sizedArrayT = (
+    itemDescriptor: Descriptor,
+    sizeParamIndex: number,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { sizeParamIndex, elementSize });
+
+export const fixedArrayT = (
+    itemDescriptor: Descriptor,
+    fixedSize: number,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { fixedSize, elementSize });
+
+export const callbackT = (
+    argDescriptors: Descriptor[],
+    returnDescriptor: Descriptor,
+    options?: CallbackOptions,
+): CallbackDescriptor => {
+    const result: CallbackDescriptor = { kind: "callback", argDescriptors, returnDescriptor };
+    if (options?.hasDestroy !== undefined) result.hasDestroy = options.hasDestroy;
+    if (options?.userDataIndex !== undefined) result.userDataIndex = options.userDataIndex;
+    if (options?.scope !== undefined) result.scope = options.scope;
+    return result;
+};

package/src/error.ts

@@ -0,0 +1,49 @@
+import type { ExternalObject, Handle, Ref } from "@gtkx/native";
+import { getWrapperClass, wrapHandle } from "./registry.js";
+import { getErrorType, isTypedClass } from "./type.js";
+
+type ErrorLike = {
+    domain: number;
+    code: number;
+    message: string;
+};
+
+/**
+ * An error enum object carrying its member codes plus an `instanceof` check that
+ * matches wrapped GLib errors belonging to a specific error domain.
+ */
+export type ErrorDomain<T extends Record<string, number>> = T & {
+    [Symbol.hasInstance]: (value: unknown) => value is ErrorLike;
+};
+
+export function checkError(error: Ref): void {
+    if (error.value !== null) {
+        const gerror = wrapHandle<ErrorLike>(error.value as ExternalObject<Handle>, getWrapperClass(getErrorType()));
+        Error.captureStackTrace(gerror, checkError);
+        throw gerror;
+    }
+}
+
+const isError = (value: unknown): value is ErrorLike => isTypedClass(value) && value.__type__ === getErrorType();
+
+/**
+ * Builds an error domain enum object from its members and a lazy resolver for the
+ * domain quark, giving it an `instanceof` check that matches wrapped GLib errors of
+ * that domain.
+ *
+ * @param resolveDomain Called once, on first `instanceof` check, to obtain the domain quark.
+ * @param members The error code enum members to expose on the returned object.
+ */
+export function createErrorDomain<const T extends Record<string, number>>(
+    resolveDomain: () => number,
+    members: T,
+): ErrorDomain<T> {
+    let domain: number | undefined;
+    const hasInstance = (value: unknown): value is ErrorLike => {
+        domain ??= resolveDomain();
+        return isError(value) && value.domain === domain;
+    };
+    const enumObject: Record<string, unknown> = { ...members };
+    Object.defineProperty(enumObject, Symbol.hasInstance, { value: hasInstance });
+    return enumObject as ErrorDomain<T>;
+}

package/src/fn.ts

@@ -0,0 +1,108 @@
+import type { Descriptor, Ref } from "@gtkx/native";
+import { type Arg, isCallerAllocatedArg, isInoutArg, isOutputArg, isRefArg } from "./arg.js";
+import { bind } from "./bind.js";
+import { wrapCallbackValue } from "./callback.js";
+import { boxedT, refT } from "./descriptors.js";
+import { checkError } from "./error.js";
+import { LIB } from "./library.js";
+import { fromNative } from "./native-value.js";
+import { getHandle } from "./registry.js";
+import { packTupleResult } from "./tuple.js";
+
+type FnSpec = {
+    args: Arg[];
+    returns: Descriptor;
+    throws?: boolean;
+};
+
+type ArgSpec = {
+    arg: Arg;
+    isRef: boolean;
+    isCallerAllocated: boolean;
+    consumesInput: boolean;
+    inputIndex: number;
+    isOutParam: boolean;
+};
+
+const buildNativeArgTypes = (args: Arg[], throws: boolean): Descriptor[] => {
+    const nativeArgTypes = args.map((argSpec) =>
+        argSpec.direction !== undefined && argSpec.callerAllocated !== true ? refT(argSpec.type) : argSpec.type,
+    );
+    if (throws)
+        nativeArgTypes.push(
+            refT(boxedT("GError", { ownership: "full", sharedLibrary: LIB, getTypeFnName: "g_error_get_type" })),
+        );
+    return nativeArgTypes;
+};
+
+const buildArgSpecs = (args: Arg[]): ArgSpec[] => {
+    let inputCursor = 0;
+    return args.map((arg) => {
+        const isRef = isRefArg(arg);
+        const consumesInput = !isRef || isInoutArg(arg);
+        const isOutParam = isOutputArg(arg) && arg.consumed !== true;
+        return {
+            arg,
+            isRef,
+            isCallerAllocated: isCallerAllocatedArg(arg),
+            consumesInput,
+            inputIndex: consumesInput ? inputCursor++ : -1,
+            isOutParam,
+        };
+    });
+};
+
+const buildNativeValues = (plans: ArgSpec[], inputs: unknown[]): unknown[] =>
+    plans.map(({ arg, isRef, isCallerAllocated, consumesInput, inputIndex }) => {
+        if (isCallerAllocated) {
+            const wrapper = inputs[inputIndex];
+            return wrapper == null ? wrapper : getHandle(wrapper as object);
+        }
+        if (isRef) {
+            return { value: consumesInput ? inputs[inputIndex] : null };
+        }
+        if (arg.type.kind === "callback") {
+            return wrapCallbackValue(arg.type, inputs[inputIndex]);
+        }
+        return inputs[inputIndex];
+    });
+
+const readOutParams = (plans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
+    const outParams: unknown[] = [];
+    plans.forEach(({ arg, isCallerAllocated, inputIndex, isOutParam }, index) => {
+        if (!isOutParam) return;
+        outParams.push(
+            isCallerAllocated ? inputs[inputIndex] : fromNative(arg.type, (nativeValues[index] as Ref).value),
+        );
+    });
+    return outParams;
+};
+
+export function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: unknown[]) => unknown {
+    const { args, returns: returnDescriptor, throws = false } = spec;
+    const nativeArgTypes = buildNativeArgTypes(args, throws);
+    const nativeFn = bind(sharedLibrary, symbol, nativeArgTypes, returnDescriptor);
+    const hasPrimary = returnDescriptor.kind !== "void";
+    const plans = buildArgSpecs(args);
+
+    const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown => {
+        const primary = hasPrimary ? fromNative(returnDescriptor, nativeResult) : undefined;
+        return packTupleResult(readOutParams(plans, inputs, nativeValues), primary, hasPrimary);
+    };
+
+    if (throws) {
+        return (...inputs) => {
+            const nativeValues = buildNativeValues(plans, inputs);
+            const errorRef: Ref = { value: null };
+            nativeValues.push(errorRef);
+            const nativeResult = nativeFn(...nativeValues);
+            checkError(errorRef);
+            return shape(inputs, nativeValues, nativeResult);
+        };
+    }
+
+    return (...inputs) => {
+        const nativeValues = buildNativeValues(plans, inputs);
+        return shape(inputs, nativeValues, nativeFn(...nativeValues));
+    };
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+export { alloc, type ExternalObject, type Handle, read, setWrapper, write } from "@gtkx/native";
+export { createErrorDomain, type ErrorDomain } from "./error.js";
+export { type ApplicationLike, onExit, quit, quitApplication, runApplication } from "./lifecycle.js";
+export { offSignal, onceSignal, onSignal } from "./listeners.js";
+export { installMixins, type Mixin } from "./mixin.js";
+export { fromNative } from "./native-value.js";
+export { getObjectProperty, newObjectWithProperties, setObjectProperty } from "./object.js";
+export { promisify } from "./promisify.js";
+export { registerClass } from "./register-class.js";
+export {
+    getHandle,
+    getInstanceType,
+    getWrapperClass,
+    registerInterface,
+    registerWrapperClass,
+    type StaticBase,
+    setHandle,
+    tryGetHandle,
+    wrapHandle,
+} from "./registry.js";
+export { connectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
+export { t } from "./t.js";
+export {
+    resolveType,
+    TYPE_BOOLEAN,
+    TYPE_BOXED,
+    TYPE_CHAR,
+    TYPE_DOUBLE,
+    TYPE_ENUM,
+    TYPE_FLAGS,
+    TYPE_FLOAT,
+    TYPE_GTYPE,
+    TYPE_INT,
+    TYPE_INT64,
+    TYPE_INTERFACE,
+    TYPE_INVALID,
+    TYPE_LONG,
+    TYPE_NONE,
+    TYPE_OBJECT,
+    TYPE_PARAM,
+    TYPE_POINTER,
+    TYPE_STRING,
+    TYPE_UCHAR,
+    TYPE_UINT,
+    TYPE_UINT64,
+    TYPE_ULONG,
+    TYPE_UNICHAR,
+    TYPE_VARIANT,
+    type TypedClass,
+    typeFromName,
+    typeInterfaces,
+    typeIsA,
+    typeName,
+    typeParent,
+    valueIsA,
+} from "./type.js";
+export { getBoxedValue, setBoxedValue } from "./value.js";

package/src/internal.ts

@@ -0,0 +1,12 @@
+export { checkError, createErrorDomain } from "./error.js";
+export { registerClassType, resolveWrapperClass, wrapHandle } from "./registry.js";
+export { resolveType } from "./type.js";
+export {
+    fromValue,
+    getBoxedValue,
+    getValueType,
+    inoutValueForBoxedDescriptor,
+    newValueForDescriptor,
+    outValueForBoxedDescriptor,
+    toValue,
+} from "./value.js";

package/src/library.ts

@@ -0,0 +1,15 @@
+import { type BoxedDescriptor, boxedT, type FundamentalDescriptor, fundamentalT } from "./descriptors.js";
+
+export const LIB = "libgobject-2.0.so.0,libglib-2.0.so.0";
+export const VALUE_SIZE = 24;
+export const VALUE_T: BoxedDescriptor = boxedT("GValue", { sharedLibrary: LIB, getTypeFnName: "g_value_get_type" });
+
+export const PARAM_T: FundamentalDescriptor = fundamentalT(LIB, "g_param_spec_ref", "g_param_spec_unref", {
+    ownership: "borrowed",
+    typeName: "GParam",
+});
+
+export const VARIANT_T: FundamentalDescriptor = fundamentalT(LIB, "g_variant_ref", "g_variant_unref", {
+    ownership: "borrowed",
+    typeName: "GVariant",
+});

package/src/lifecycle.ts

@@ -0,0 +1,73 @@
+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.
+ */
+export 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)[] = [];
+let hasQuit = false;
+
+/**
+ * Registers a callback to run once when the process quits, before the native
+ * runtime is torn down.
+ *
+ * @param callback Invoked during shutdown.
+ */
+export const onExit = (callback: () => void): void => {
+    shutdownCallbacks.push(callback);
+};
+
+/**
+ * Runs every registered exit callback and shuts down the native runtime. Safe to
+ * call more than once; only the first call takes effect.
+ */
+export const quit = (): void => {
+    if (hasQuit) return;
+    hasQuit = true;
+
+    for (const callback of shutdownCallbacks) callback();
+
+    nativeQuit();
+};
+
+process.on("exit", quit);
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export const quitApplication = (application: ApplicationLike): void => {
+    if (!application.getIsRegistered()) return;
+    for (const window of application.getWindows?.() ?? []) application.removeWindow?.(window);
+    application.on("shutdown", () => application.quit());
+    blockMatchedSignalHandlers(application, "activate");
+    application.run([]);
+};

package/src/listeners.ts

@@ -0,0 +1,84 @@
+import type { SignalHandler } from "./signal.js";
+
+type SignalConnectable = {
+    connect(signal: string, handler: SignalHandler, after?: boolean): number;
+    disconnect(handlerId: number): void;
+};
+
+const listenerTable = new WeakMap<object, Map<string, Map<SignalHandler, number>>>();
+
+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 untrackListener = (instance: object, signal: string, handler: SignalHandler): void => {
+    const bySignal = listenerTable.get(instance);
+    const byHandler = bySignal?.get(signal);
+    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 after When true, run the handler after the default handler.
+ */
+export function onSignal(instance: SignalConnectable, signal: string, handler: SignalHandler, after?: boolean): void {
+    const handlerId = instance.connect(signal, handler, after);
+    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 after When true, run the handler after the default handler.
+ */
+export function onceSignal(instance: SignalConnectable, signal: string, handler: SignalHandler, after?: boolean): void {
+    let handlerId = 0;
+    const wrapped: SignalHandler = (...args) => {
+        untrackListener(instance, signal, wrapped);
+        untrackListener(instance, signal, handler);
+        instance.disconnect(handlerId);
+        return handler(...args);
+    };
+    handlerId = instance.connect(signal, wrapped, after);
+    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.
+ */
+export function offSignal(instance: SignalConnectable, signal: string, handler: SignalHandler): void {
+    const handlerId = findListenerHandlerId(instance, signal, handler);
+    if (handlerId !== undefined) {
+        instance.disconnect(handlerId);
+        untrackListener(instance, signal, handler);
+    }
+}

package/src/mixin.ts

@@ -0,0 +1,48 @@
+import type { AnyClass } from "@gtkx/utils";
+
+export type MixinReceiver = {
+    connect(signal: string, handler: (...args: unknown[]) => unknown, after?: 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.
+ */
+export type Mixin = (base: AnyClass<MixinReceiver>) => AnyClass;
+
+function definedInClassChain(prototype: object, key: string): boolean {
+    let current: object | null = prototype;
+    while (current !== null && current !== Object.prototype) {
+        if (Object.hasOwn(current, key)) return true;
+        current = Object.getPrototypeOf(current);
+    }
+    return false;
+}
+
+/**
+ * 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.
+ */
+export 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) {
+        const layer: object = mixin(empty).prototype;
+        for (const key of Object.getOwnPropertyNames(layer)) {
+            if (key === "constructor") continue;
+            if (definedInClassChain(target.prototype, key)) continue;
+            const descriptor = Object.getOwnPropertyDescriptor(layer, key);
+            if (descriptor !== undefined) Object.defineProperty(target.prototype, key, descriptor);
+        }
+    }
+}