@gtkx/codegen 0.21.0

package/src/writers/signal.ts

@@ -0,0 +1,318 @@
+import { quote, toCamelCase } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import { indent } from "../dsl/emit.js";
+import type { GirClass } from "../gir/class.js";
+import type { GirParameter } from "../gir/parameter.js";
+import { isOutParameter } from "../gir/parameter.js";
+import { qualifyTypeRef } from "../gir/qualify.js";
+import type { GirSignal } from "../gir/signal.js";
+import type { GirTypeRef, PrimitiveTypeRef } from "../gir/type-ref.js";
+import { forEachAncestor, resolveImplementedInterface } from "./inheritance.js";
+import { planTrampolineArgs, renderTupleWriteback } from "./method.js";
+import { isHandlePassing } from "./param-classify.js";
+import { isCellInout, renderFfiType } from "./value.js";
+
+const SIGNAL_HANDLER_TYPE = "(...args: any[]) => any";
+
+/**
+ * A signal together with the namespace its parameter and return references
+ * belong to. Own signals carry the class's namespace; signals flattened from
+ * an implemented interface carry the interface's namespace so their references
+ * resolve correctly.
+ */
+type CollectedSignal = {
+    readonly signal: GirSignal;
+    readonly namespaceName: string;
+};
+
+/** The generated marshalling references a class's inline `emit` switch uses. */
+type GObjectRefs = {
+    readonly Value: string;
+    readonly signalEmitv: string;
+    readonly signalLookup: string;
+};
+
+/**
+ * Renders the `connect` and `emit` instance methods for a class that owns or
+ * inherits-by-interface at least one signal.
+ *
+ * Each method is a `switch` over the type's own signals. `connect` resolves the
+ * per-signal trampoline, wraps the handler, and hands it to the thin
+ * `connectSignal` wrapper around the non-introspectable `g_signal_connect_data`.
+ * `emit` marshals the arguments into `GValue`s with `valueFromFfi` and calls the
+ * generated `signalLookup` / `signalEmitv` directly. Unknown signals route up
+ * the class chain via `super.connect` / `super.emit`; the root `GObject.Object`
+ * throws because it bottoms out the hierarchy.
+ *
+ * Returns an empty array when the class contributes no signals of its own.
+ *
+ * @param context - The module context
+ * @param klass - The class whose signal methods to render
+ */
+export const renderSignalMembers = (context: ModuleContext, klass: GirClass): readonly string[] => {
+    if (klass.glibGetType === undefined) return [];
+    const signals = collectClassSignals(context, klass);
+    if (signals.length === 0) return [];
+    const isRootObject = context.namespace.name === "GObject" && klass.name === "Object";
+
+    context.addRuntimeImport("connectSignal");
+    context.addRuntimeImport("signalBaseName");
+    context.addRuntimeImport("t");
+
+    const connectCases = signals.map((collected) => renderConnectCase(context, collected));
+    const emitCases = signals.map((collected) => renderEmitCase(context, collected));
+    const connectDefault = isRootObject
+        ? `default:\n    throw new globalThis.Error("Unknown signal '" + signal + "'");`
+        : "default:\n    return super.connect(signal, handler, after);";
+    const emitDefault = isRootObject
+        ? `default:\n    throw new globalThis.Error("Unknown signal '" + sigName + "'");`
+        : "default:\n    super.emit(sigName, ...args);";
+
+    const connectSwitch = `switch (signalBaseName(signal)) {\n${indent([...connectCases, connectDefault].join("\n"), 1)}\n}`;
+    const emitSwitch = `switch (sigName) {\n${indent([...emitCases, emitDefault].join("\n"), 1)}\n}`;
+
+    return [
+        `connect(signal: string, handler: ${SIGNAL_HANDLER_TYPE}, after?: boolean): number {\n${indent(connectSwitch, 1)}\n}`,
+        `emit(sigName: string, ...args: unknown[]): void {\n${indent(emitSwitch, 1)}\n}`,
+    ];
+};
+
+/**
+ * Renders one `connect` switch case: it resolves the signal's typed trampoline,
+ * wraps the user handler with the per-signal in-parameter marshalling closure,
+ * and dispatches `g_signal_connect_data` through {@link connectSignal} with the
+ * full detailed signal name.
+ */
+const renderConnectCase = (context: ModuleContext, collected: CollectedSignal): string => {
+    const { signal } = collected;
+    const { trampoline, invoke } = renderTrampolineAndInvoke(context, collected);
+    const body = [
+        `const invoke = ${invoke};`,
+        "const handlerWrapper = (...args: unknown[]): unknown => invoke(handler, args);",
+        `return connectSignal(this, signal, ${trampoline}, handlerWrapper, after ?? false);`,
+    ].join("\n");
+    return `case ${quote(signal.name)}: {\n${indent(body, 1)}\n}`;
+};
+
+/**
+ * Renders one `emit` switch case: it marshals the emitting instance and each
+ * signal parameter into a `GValue` with `valueFromFfi`, resolves the signal id
+ * from the instance's runtime `GType`, and dispatches `g_signal_emitv`. Signals
+ * with a non-void return supply an initialized return `GValue`.
+ */
+const renderEmitCase = (context: ModuleContext, collected: CollectedSignal): string => {
+    const { signal, namespaceName } = collected;
+    const params = signal.parameters.filter((parameter) => !parameter.isVarargs);
+    const paramFfi = params.map((parameter) =>
+        renderFfiType(context, qualifyTypeRef(parameter.type, namespaceName), parameter.transferOwnership),
+    );
+    context.addValueFromFfiImport();
+    const refs = gobjectRefs(context);
+    const valueArgs = [
+        'valueFromFfi(t.object("full"), this)',
+        ...paramFfi.map((ffi, index) => `valueFromFfi(${ffi}, args[${index}])`),
+    ];
+    const values = `[${valueArgs.join(", ")}]`;
+    const lookup = `${refs.signalLookup}(${quote(signal.name)}, this.__gtype__)`;
+    const returnRef = qualifyTypeRef(signal.returnValue.type, namespaceName);
+    const emitStatements =
+        returnRef === undefined || isVoidRef(returnRef)
+            ? `${refs.signalEmitv}(${values}, ${lookup}, 0);`
+            : [
+                  `const returnValue = new ${refs.Value}();`,
+                  `returnValue.init(${renderReturnGType(context, returnRef)});`,
+                  `${refs.signalEmitv}(${values}, ${lookup}, 0, returnValue);`,
+              ].join("\n");
+    return `case ${quote(signal.name)}: {\n${indent(`${emitStatements}\nreturn;`, 1)}\n}`;
+};
+
+/**
+ * Resolves the `GObject` marshalling references the inline `emit` switch needs.
+ * Within the `GObject` namespace the generated `Value`, `signalEmitv`, and
+ * `signalLookup` are local; elsewhere they are reached through the cross-
+ * namespace `GObject` alias.
+ */
+const gobjectRefs = (context: ModuleContext): GObjectRefs => {
+    if (context.namespace.name === "GObject") {
+        return { Value: "Value", signalEmitv: "signalEmitv", signalLookup: "signalLookup" };
+    }
+    const alias = context.addCrossNamespaceImport("GObject");
+    return { Value: `${alias}.Value`, signalEmitv: `${alias}.signalEmitv`, signalLookup: `${alias}.signalLookup` };
+};
+
+/**
+ * Renders the trampoline FFI descriptor used to connect a handler and the
+ * `invoke` closure that marshals the trampoline arguments into the user handler.
+ *
+ * Out-parameter cells are wrapped in `t.ref(...)` so the native trampoline can
+ * write them back; the `invoke` closure mirrors the out-parameter tuple
+ * convention used by method out-parameters.
+ */
+const renderTrampolineAndInvoke = (
+    context: ModuleContext,
+    collected: CollectedSignal,
+): { readonly trampoline: string; readonly invoke: string } => {
+    const { signal, namespaceName } = collected;
+    const params = signal.parameters.filter((parameter) => !parameter.isVarargs);
+    const paramFfi = params.map((parameter) =>
+        renderFfiType(context, qualifyTypeRef(parameter.type, namespaceName), parameter.transferOwnership),
+    );
+    const trampolineParamFfi = params.map((parameter, index) =>
+        isOutParameter(parameter) || isCellInout(context, parameter) ? `t.ref(${paramFfi[index]})` : paramFfi[index],
+    );
+    const returnRef = qualifyTypeRef(signal.returnValue.type, namespaceName);
+    const isVoid = isVoidRef(returnRef);
+    const returnFfi = isVoid ? "t.void" : renderFfiType(context, returnRef, signal.returnValue.transferOwnership);
+    const trampolineArgs = ['t.object("borrowed")', ...trampolineParamFfi, "t.void"].join(", ");
+    const trampoline = `t.trampoline([${trampolineArgs}], ${returnFfi}, { hasDestroy: true, userDataIndex: ${params.length + 1} })`;
+    const invoke = renderInvokeClosure(context, collected, params, isVoid ? undefined : returnRef);
+    return { trampoline, invoke };
+};
+
+const collectClassSignals = (context: ModuleContext, klass: GirClass): readonly CollectedSignal[] => {
+    const inheritedNames = collectInheritedSignalNames(context, klass);
+    const seen = new Set<string>();
+    const result: CollectedSignal[] = [];
+    for (const signal of klass.signals) {
+        const name = toCamelCase(signal.name);
+        if (inheritedNames.has(name) || seen.has(name)) continue;
+        seen.add(name);
+        result.push({ signal, namespaceName: context.namespace.name });
+    }
+    for (const implementName of klass.implements) {
+        const iface = resolveImplementedInterface(context, implementName);
+        if (iface === undefined) continue;
+        for (const signal of iface.klass.signals) {
+            const name = toCamelCase(signal.name);
+            if (inheritedNames.has(name) || seen.has(name)) continue;
+            seen.add(name);
+            result.push({ signal, namespaceName: iface.namespaceName });
+        }
+    }
+    return result;
+};
+
+const collectInheritedSignalNames = (context: ModuleContext, klass: GirClass): ReadonlySet<string> => {
+    const names = new Set<string>();
+    forEachAncestor(context, klass, (ancestor) => {
+        for (const signal of ancestor.klass.signals) names.add(toCamelCase(signal.name));
+        for (const implementName of ancestor.klass.implements) {
+            const iface = resolveImplementedInterface(context, implementName, ancestor.namespaceName);
+            if (iface === undefined) continue;
+            for (const signal of iface.klass.signals) names.add(toCamelCase(signal.name));
+        }
+    });
+    return names;
+};
+
+const renderInvokeClosure = (
+    context: ModuleContext,
+    collected: CollectedSignal,
+    params: readonly GirParameter[],
+    returnRef: GirTypeRef | undefined,
+): string => {
+    const { namespaceName } = collected;
+    const { callArgs, outArgIndices } = planTrampolineArgs(context, params, namespaceName, 1);
+    if (outArgIndices.length === 0) {
+        if (returnRef !== undefined && isHandlePassing(context, returnRef)) {
+            context.addRuntimeImport("tryGetHandle");
+            return `(handler, args) => {\n    const _result = handler(${callArgs});\n    return tryGetHandle(_result);\n}`;
+        }
+        return `(handler, args) => handler(${callArgs})`;
+    }
+    return renderOutParamInvoke(context, callArgs, outArgIndices, returnRef);
+};
+
+/**
+ * Renders the invoke closure for a signal with out-parameters.
+ *
+ * The handler returns its results as the tuple {@link renderMethodReturnType}
+ * describes (`[primary, ...outs]` when both exist, the scalar out alone for a
+ * void return with a single out, or an out-only tuple otherwise). The shared
+ * {@link renderTupleWriteback} destructures that tuple and writes each out
+ * value into its trampoline cell's `value` slot — the native side flushes
+ * those cells through the matching C out-pointers, so the tuple convention
+ * stays entirely in generated code.
+ *
+ * @param context - The module context
+ * @param callArgs - The rendered in-parameter call arguments
+ * @param outArgIndices - Trampoline-arg indices of the out-parameter cells
+ * @param returnRef - The signal's return type, or `undefined` for void
+ */
+const renderOutParamInvoke = (
+    context: ModuleContext,
+    callArgs: string,
+    outArgIndices: readonly number[],
+    returnRef: GirTypeRef | undefined,
+): string => {
+    const body = renderTupleWriteback(context, `handler(${callArgs})`, outArgIndices, returnRef);
+    return `(handler, args) => {\n    ${body}\n}`;
+};
+
+const renderReturnGType = (context: ModuleContext, ref: GirTypeRef): string => {
+    if (ref.kind === "primitive") {
+        return `${typeFromNameReference(context)}(${quote(primitiveGTypeName(ref.category))})`;
+    }
+    if (ref.kind === "named") {
+        const owner = ref.namespaceName ?? context.namespace.name;
+        const resolved = context.repository.resolveNamed(owner, ref.typeName);
+        if (resolved !== undefined && resolved.kind === "enum") {
+            context.addNativeImport("call");
+            context.addRuntimeImport("t");
+            const lib = resolved.namespace.sharedLibrary ?? "";
+            const getter = resolved.value.glibGetType ?? "";
+            return `call(${quote(lib)}, ${quote(getter)}, [], t.uint64)`;
+        }
+        if (
+            resolved !== undefined &&
+            (resolved.kind === "class" || resolved.kind === "interface" || resolved.kind === "boxed")
+        ) {
+            const glibTypeName = glibTypeNameOf(resolved.value) ?? ref.typeName;
+            return `${typeFromNameReference(context)}(${quote(glibTypeName)})`;
+        }
+    }
+    return `${typeFromNameReference(context)}("GObject")`;
+};
+
+const isVoidRef = (ref: GirTypeRef | undefined): boolean =>
+    ref === undefined || (ref.kind === "primitive" && ref.category === "void");
+
+const glibTypeNameOf = (value: {
+    readonly glibTypeName?: string | undefined;
+    readonly cType?: string | undefined;
+}): string | undefined => value.glibTypeName ?? value.cType;
+
+const typeFromNameReference = (context: ModuleContext): string => {
+    if (context.namespace.name === "GObject") return "typeFromName";
+    const alias = context.addCrossNamespaceImport("GObject");
+    return `${alias}.typeFromName`;
+};
+
+const primitiveGTypeName = (category: PrimitiveTypeRef["category"]): string => {
+    switch (category) {
+        case "boolean":
+            return "gboolean";
+        case "int8":
+        case "int16":
+        case "int32":
+            return "gint";
+        case "uint8":
+        case "uint16":
+        case "uint32":
+        case "unichar":
+            return "guint";
+        case "int64":
+            return "gint64";
+        case "uint64":
+        case "pointer":
+            return "guint64";
+        case "float32":
+            return "gfloat";
+        case "float64":
+            return "gdouble";
+        case "string":
+            return "gchararray";
+        case "void":
+            return "void";
+    }
+};

package/src/writers/ts-type.ts

@@ -0,0 +1,115 @@
+import type { ModuleContext } from "../dsl/context.js";
+import { aliasExportName } from "../dsl/identifier.js";
+import { PRIMITIVE_TS_TYPE } from "../gir/primitives.js";
+import type { ResolvedNamed } from "../gir/repository.js";
+import type { GirTypeRef, NamedTypeRef } from "../gir/type-ref.js";
+
+/**
+ * TypeScript type annotations the writers emit alongside runtime values.
+ *
+ * Generated `.ts` files are consumed both as runtime modules (transpiled to
+ * `.js`) and as declaration sources (`ts.transpileDeclaration` extracts the
+ * `.d.ts` shape). Every exported value, parameter, and return position
+ * therefore carries an explicit annotation so isolated declaration emit
+ * succeeds without inference. The helpers below produce those annotations
+ * from the same `GirTypeRef` shapes the runtime FFI writers consume,
+ * importing referenced cross-namespace classes on demand.
+ */
+
+/**
+ * Strategy describing the type-ref shapes the FFI and React generators render
+ * differently: container style (`Map` vs `Record`), the callback placeholder,
+ * whether a `GByteArray` collapses to `number[]`, and how a named reference is
+ * qualified and imported. {@link renderBaseTypeFor} renders every other shape
+ * identically for both.
+ */
+export type TsTypeTarget = {
+    /** `"map"` → `Map<K, V>`; `"record"` → `Record<K, V>`. */
+    readonly containerStyle: "map" | "record";
+    /** The placeholder emitted for a callback type. */
+    readonly callbackType: string;
+    /** Whether a `GByteArray` renders as `number[]` instead of `element[]`. */
+    readonly byteArrayAsNumber: boolean;
+    /** Renders a named reference (class/interface/boxed/enum/callback/alias). */
+    readonly renderNamed: (ref: NamedTypeRef) => string;
+};
+
+/**
+ * Renders the TypeScript annotation for a `GirTypeRef`, dispatching the shapes
+ * both generators share and delegating the divergent ones to {@link target}.
+ *
+ * @param target - The per-generator rendering strategy
+ * @param ref - The type reference, or `undefined` for void
+ */
+export const renderBaseTypeFor = (target: TsTypeTarget, ref: GirTypeRef | undefined): string => {
+    if (ref === undefined) return "void";
+    switch (ref.kind) {
+        case "primitive":
+            return PRIMITIVE_TS_TYPE[ref.category];
+        case "varargs":
+            return "unknown[]";
+        case "callback":
+            return target.callbackType;
+        case "named":
+            return target.renderNamed(ref);
+        case "array":
+            return `${renderBaseTypeFor(target, ref.element)}[]`;
+        case "list":
+            if (ref.flavor === "gbytearray" && target.byteArrayAsNumber) return "number[]";
+            return `${renderBaseTypeFor(target, ref.element)}[]`;
+        case "hashtable": {
+            const key = renderBaseTypeFor(target, ref.key);
+            const value = renderBaseTypeFor(target, ref.value);
+            return target.containerStyle === "record" ? `Record<${key}, ${value}>` : `Map<${key}, ${value}>`;
+        }
+    }
+};
+
+const moduleTarget = (context: ModuleContext): TsTypeTarget => ({
+    containerStyle: "map",
+    callbackType: "((...args: any[]) => any)",
+    byteArrayAsNumber: true,
+    renderNamed: (ref) => namedTsType(context, ref),
+});
+
+/**
+ * Renders a TypeScript type annotation for a `GirTypeRef` in an FFI module:
+ * classes/interfaces/boxeds/enums/callbacks as their qualified identifier,
+ * arrays and lists as `T[]`, hashtables as `Map<K, V>`, primitives to their TS
+ * counterpart, and `undefined` to `void`.
+ *
+ * @param context - The module context
+ * @param ref - The type reference, or `undefined` for void
+ * @param isNullable - Whether the slot accepts `null`
+ */
+export const renderTsType = (context: ModuleContext, ref: GirTypeRef | undefined, isNullable = false): string => {
+    const base = renderBaseTypeFor(moduleTarget(context), ref);
+    return isNullable ? `${base} | null` : base;
+};
+
+const namedTsType = (context: ModuleContext, ref: NamedTypeRef): string => {
+    const namespaceName = ref.namespaceName ?? context.namespace.name;
+    const resolved = context.repository.resolveNamed(namespaceName, ref.typeName);
+    if (resolved === undefined) {
+        return context.qualify(namespaceName, ref.typeName);
+    }
+    return resolvedTsType(context, namespaceName, ref.typeName, resolved);
+};
+
+const resolvedTsType = (
+    context: ModuleContext,
+    namespaceName: string,
+    typeName: string,
+    resolved: ResolvedNamed,
+): string => {
+    switch (resolved.kind) {
+        case "class":
+        case "interface":
+        case "boxed":
+        case "enum":
+        case "callback":
+            return context.qualify(namespaceName, typeName);
+        case "alias":
+            return context.qualify(namespaceName, aliasExportName(namespaceName, typeName));
+    }
+};