@gtkx/codegen 0.21.0

package/src/writers/param-classify.ts

@@ -0,0 +1,178 @@
+import { toCamelCase, toIdentifier } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import type { GirFunction } from "../gir/function.js";
+import { type GirParameter, isCallerAllocatedOut, isOutParameter } from "../gir/parameter.js";
+import type { GirTypeRef } from "../gir/type-ref.js";
+
+/**
+ * Parameter classification shared across the callable writers: which positions
+ * a TypeScript signature exposes, which marshal through a `{ value }` ref cell,
+ * which cross the FFI as native handles, and how a parameter is named. Depends
+ * only on the GIR model and the module context.
+ */
+
+/**
+ * A callable input parameter paired with its original GIR position.
+ */
+export type InputParameter = {
+    /** The GIR parameter. */
+    readonly parameter: GirParameter;
+    /** The parameter's index in the callable's full parameter list. */
+    readonly index: number;
+};
+
+/**
+ * The input parameters a callable's TypeScript signature exposes.
+ *
+ * Drops `<varargs>` slots, out-only and caller-allocated-out parameters,
+ * array-length parameters computed from a sibling array, and the
+ * `user_data`/`GDestroyNotify` slots folded into a callback descriptor. Each
+ * surviving parameter keeps its original index so callers can recover argument
+ * names.
+ *
+ * @param fn - The callable
+ */
+export const inputParameters = (fn: GirFunction): readonly InputParameter[] => {
+    const lengthIndices = arrayLengthIndices(fn);
+    const closureIndices = closureAndDestroyIndices(fn);
+    const result: InputParameter[] = [];
+    fn.parameters.forEach((parameter, index) => {
+        if (parameter.isVarargs) return;
+        if (isOutParameter(parameter)) return;
+        if (isCallerAllocatedOut(parameter)) return;
+        if (lengthIndices.has(index)) return;
+        if (closureIndices.has(index)) return;
+        result.push({ parameter, index });
+    });
+    return result;
+};
+
+/**
+ * Indices of the `gpointer user_data` and `GDestroyNotify` parameters paired
+ * to a callback parameter. These slots are folded into the callback's
+ * trampoline descriptor and are not emitted as standalone FFI arguments.
+ *
+ * @param fn - The callable
+ */
+export const closureAndDestroyIndices = (fn: GirFunction): ReadonlySet<number> => {
+    const indices = new Set<number>();
+    for (const parameter of fn.parameters) {
+        if (parameter.closureIndex !== undefined) indices.add(parameter.closureIndex);
+        if (parameter.destroyIndex !== undefined) indices.add(parameter.destroyIndex);
+    }
+    return indices;
+};
+
+const arrayLengthIndices = (fn: GirFunction): ReadonlySet<number> => {
+    const map = arrayLengthSources(fn);
+    return new Set(map.keys());
+};
+
+/**
+ * Maps each array-length parameter's index to the array parameter whose
+ * `.length` supplies it.
+ *
+ * @param fn - The callable
+ */
+export const arrayLengthSources = (fn: GirFunction): ReadonlyMap<number, number> => {
+    const map = new Map<number, number>();
+    fn.parameters.forEach((parameter, index) => {
+        if (parameter.type?.kind !== "array") return;
+        const lengthIndex = parameter.type.lengthParameterIndex;
+        if (lengthIndex === undefined) return;
+        map.set(lengthIndex, index);
+    });
+    return map;
+};
+
+/**
+ * Indices of parameters consumed as the length of the return array (and so
+ * dropped from the return tuple).
+ *
+ * @param fn - The callable
+ */
+export const returnArrayLengthIndices = (fn: GirFunction): ReadonlySet<number> => {
+    if (fn.returnValue.type?.kind !== "array") return new Set();
+    const lengthIndex = fn.returnValue.type.lengthParameterIndex;
+    if (lengthIndex === undefined) return new Set();
+    return new Set([lengthIndex]);
+};
+
+/**
+ * Whether a parameter is passed to the FFI binding as a `t.ref(...)` cell.
+ *
+ * Pure out parameters marshal through a `{ value }` ref cell the native layer
+ * writes into. Inout parameters do too — except handle-passing ones
+ * (objects, interfaces, boxed), which are passed by their existing handle
+ * and mutated in place, not through a pointer-to-pointer cell.
+ * Caller-allocated outs pass a pre-built handle and are excluded.
+ *
+ * @param context - The module context
+ * @param parameter - The parameter to test
+ */
+export const needsRefArg = (context: ModuleContext, parameter: GirParameter): boolean => {
+    if (parameter.direction !== "out" && parameter.direction !== "inout") return false;
+    const passesHandleDirectly =
+        (parameter.callerAllocates || parameter.direction === "inout") &&
+        parameter.type !== undefined &&
+        isHandlePassing(context, parameter.type);
+    return !passesHandleDirectly;
+};
+
+/**
+ * Whether a caller-allocated-out parameter is one the body can materialize and
+ * collect into the return — a boxed record or class the runtime can allocate
+ * via its wrapper constructor. Array and other caller-out buffers cannot be
+ * allocated here, so they are excluded from both the body and the return type.
+ *
+ * @param context - The module context
+ * @param parameter - The parameter to test
+ */
+export const isCollectibleCallerOut = (context: ModuleContext, parameter: GirParameter): boolean => {
+    if (parameter.type === undefined || parameter.type.kind !== "named") return false;
+    const resolved = context.repository.resolveNamed(
+        parameter.type.namespaceName ?? context.namespace.name,
+        parameter.type.typeName,
+    );
+    return resolved?.kind === "boxed" || resolved?.kind === "class";
+};
+
+/**
+ * Whether a value of `ref` is passed across the FFI boundary as a native
+ * handle (object, interface, boxed, or an alias to one) instead of by value.
+ *
+ * @param context - The module context
+ * @param ref - The type reference to test
+ */
+export const isHandlePassing = (context: ModuleContext, ref: GirTypeRef): boolean => {
+    if (ref.kind !== "named") return false;
+    const owner = ref.namespaceName ?? context.namespace.name;
+    const resolved = context.repository.resolveNamed(owner, ref.typeName);
+    if (resolved === undefined) return true;
+    switch (resolved.kind) {
+        case "class":
+        case "interface":
+        case "boxed":
+            return true;
+        case "alias": {
+            const target = resolved.targetRef;
+            if (target === undefined || target.kind !== "named") return false;
+            return isHandlePassing(context, target);
+        }
+        case "enum":
+        case "callback":
+            return false;
+    }
+};
+
+/**
+ * The JavaScript identifier for a parameter: the camelCased GIR name, or
+ * `arg<index>` for an unnamed position.
+ *
+ * @param parameter - The GIR parameter
+ * @param index - The parameter's position in the callable
+ */
+export const parameterIdentifier = (parameter: GirParameter, index: number): string => {
+    if (parameter.name.length === 0) return `arg${index}`;
+    return toIdentifier(toCamelCase(parameter.name));
+};

package/src/writers/property-accessor.ts

@@ -0,0 +1,139 @@
+import { quote, toCamelCase, toIdentifier } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import { indent } from "../dsl/emit.js";
+import type { GirFunction } from "../gir/function.js";
+import type { GirProperty } from "../gir/property.js";
+import type { GirTypeRef } from "../gir/type-ref.js";
+import { renderMethodReturnType } from "./method.js";
+import { renderTsType } from "./ts-type.js";
+
+/**
+ * Whether a GObject property of `type` can hold `null`.
+ *
+ * Reference values — objects, boxed records, interfaces, and containers —
+ * marshal to `null` when unset; scalar value types (numbers, booleans,
+ * strings, `unichar`, enums) are surfaced non-null to match their typed
+ * setters. Aliases resolve to their target.
+ *
+ * @param context - The module context
+ * @param type - The property's value type
+ */
+const isNullablePropertyType = (context: ModuleContext, type: GirTypeRef | undefined): boolean => {
+    if (type === undefined) return false;
+    if (type.kind === "primitive") return false;
+    if (type.kind !== "named") return true;
+    const resolved = context.repository.resolveNamed(type.namespaceName ?? context.namespace.name, type.typeName);
+    if (resolved === undefined) return true;
+    if (resolved.kind === "enum") return false;
+    if (resolved.kind === "alias") return isNullablePropertyType(context, resolved.targetRef);
+    return true;
+};
+
+/**
+ * Renders the `get` / `set` accessor pair for a single GObject property
+ * on a class declaration.
+ *
+ * Read-only properties get only a getter; readonly + non-writable
+ * properties are skipped entirely. Properties whose name has already
+ * been claimed by an emitted method (its camelCase form clashes) are
+ * skipped, since the method takes precedence — the runtime accessor is
+ * always reachable via `this.getProperty(girName)` in that case.
+ *
+ * @param context - The module context
+ * @param property - The property to surface
+ * @param claimedNames - Names already used by emitted methods
+ */
+export const renderPropertyAccessor = (
+    context: ModuleContext,
+    property: GirProperty,
+    claimedNames: ReadonlySet<string>,
+    methodByName: ReadonlyMap<string, GirFunction>,
+): string | undefined => {
+    const jsName = toIdentifier(toCamelCase(property.name));
+    if (claimedNames.has(jsName)) return undefined;
+    if (jsName === "constructor") return undefined;
+
+    const writable = property.writable || property.construct || property.constructOnly;
+    const getterMember = delegateMember(property.getter, jsName, claimedNames);
+    const getMethod =
+        getterMember !== undefined && property.getter !== undefined ? methodByName.get(property.getter) : undefined;
+    const setterMember = writable ? delegateMember(property.setter, jsName, claimedNames) : undefined;
+    const setMethod =
+        setterMember !== undefined && property.setter !== undefined ? methodByName.get(property.setter) : undefined;
+    const setParam = setMethod?.parameters[0];
+
+    const tsType =
+        setParam !== undefined
+            ? renderTsType(context, setParam.type, setParam.nullable || setParam.optional)
+            : getMethod !== undefined
+              ? renderMethodReturnType(context, getMethod)
+              : renderTsType(context, property.type, isNullablePropertyType(context, property.type));
+
+    const blocks: string[] = [];
+    const getBody = renderGetterBody({ context, property, getterMember, getMethod, tsType });
+    blocks.push(`get ${jsName}(): ${tsType} {\n${indent(getBody, 1)}\n}`);
+
+    if (writable) {
+        const setBody =
+            setterMember !== undefined
+                ? `this.${setterMember}(value);`
+                : `this.setProperty(${quote(property.name)}, value);`;
+        blocks.push(`set ${jsName}(value: ${tsType}) {\n${indent(setBody, 1)}\n}`);
+    }
+    return blocks.join("\n\n");
+};
+
+/**
+ * Inputs for {@link renderGetterBody}.
+ */
+type GetterBodyOptions = {
+    readonly context: ModuleContext;
+    readonly property: GirProperty;
+    readonly getterMember: string | undefined;
+    readonly getMethod: GirFunction | undefined;
+    readonly tsType: string;
+};
+
+/**
+ * Renders a property getter body.
+ *
+ * The property type follows the setter's parameter (what callers may assign),
+ * so a getter whose own GIR nullability differs is narrowed to it with a single
+ * assertion; matching nullability needs no cast. Properties with no typed
+ * getter read through the generic `getProperty` GValue path.
+ *
+ * @param options - {@link GetterBodyOptions}
+ */
+const renderGetterBody = (options: GetterBodyOptions): string => {
+    const { context, property, getterMember, getMethod, tsType } = options;
+    if (getterMember === undefined) return `return this.getProperty(${quote(property.name)}) as ${tsType};`;
+    if (getMethod === undefined) return `return this.${getterMember}() as ${tsType};`;
+    const getType = renderMethodReturnType(context, getMethod);
+    return getType === tsType ? `return this.${getterMember}();` : `return this.${getterMember}() as ${tsType};`;
+};
+
+/**
+ * Resolves a property's GIR `getter`/`setter` method name to the camelCase
+ * member to delegate the accessor to, or `undefined` to fall back to the
+ * generic `getProperty`/`setProperty` GValue path.
+ *
+ * Delegation is used only when the named method was actually emitted on the
+ * class (so object, interface, and boxed values marshal through their typed
+ * setter rather than the GValue `valueFromJS` path) and the member name does
+ * not collide with the accessor itself, which would recurse.
+ *
+ * @param accessorName - The accessor's own camelCase member name
+ * @param attribute - The GIR `getter`/`setter` attribute, if present
+ * @param claimedNames - Names already emitted as methods on the class
+ */
+const delegateMember = (
+    attribute: string | undefined,
+    accessorName: string,
+    claimedNames: ReadonlySet<string>,
+): string | undefined => {
+    if (attribute === undefined) return undefined;
+    const member = toCamelCase(attribute);
+    if (member === accessorName) return undefined;
+    if (!claimedNames.has(member)) return undefined;
+    return member;
+};

package/src/writers/registration.ts

@@ -0,0 +1,42 @@
+import { quote } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import { indent } from "../dsl/emit.js";
+
+/**
+ * The pre-rendered pieces of a single `registerNativeClass(...)` descriptor.
+ *
+ * Each metadata field is the already-rendered object-literal fragment for that
+ * descriptor key, or `undefined` when the type contributes nothing for it.
+ */
+export type NativeClassRegistration = {
+    readonly className: string;
+    readonly role: "class" | "interface" | "boxed";
+    readonly getTypeRef?: string | undefined;
+    readonly construction?: string | undefined;
+    readonly vfuncs?: string | undefined;
+};
+
+/**
+ * Appends the single `registerNativeClass(Class, { … })` registration that
+ * collapses a type's GType, construction, and vfunc metadata into one
+ * module-load call.
+ *
+ * Emits nothing when the registration carries no metadata at all, so callers
+ * can pass the result of optional sub-renderers without pre-checking.
+ *
+ * @param context - The module context
+ * @param registration - The pre-rendered descriptor pieces
+ */
+export const appendNativeClassRegistration = (context: ModuleContext, registration: NativeClassRegistration): void => {
+    const { className, role, getTypeRef, construction, vfuncs } = registration;
+    if (getTypeRef === undefined && construction === undefined && vfuncs === undefined) {
+        return;
+    }
+    context.addRuntimeImport("registerNativeClass");
+    const lines: string[] = [`role: ${quote(role)},`];
+    if (getTypeRef !== undefined) lines.push(`gtype: ${getTypeRef},`);
+    if (construction !== undefined) lines.push(`construction: ${construction},`);
+    if (vfuncs !== undefined) lines.push(`vfuncs: ${vfuncs},`);
+    const body = lines.map((line) => indent(line, 1)).join("\n");
+    context.module.appendRegistration(`registerNativeClass(${className}, {\n${body}\n});`);
+};

package/src/writers/return-wrap.ts

@@ -0,0 +1,180 @@
+import type { ModuleContext } from "../dsl/context.js";
+import type { ParameterTransfer } from "../gir/parameter.js";
+import type { ResolvedNamed } from "../gir/repository.js";
+import type { GirTypeRef, NamedTypeRef, PrimitiveTypeRef } from "../gir/type-ref.js";
+import { renderTsType } from "./ts-type.js";
+
+/**
+ * Lifting raw FFI call results into their typed JavaScript form: objects to
+ * their runtime-registered wrappers, boxed values to typed wrappers,
+ * collections per element, and primitives with the appropriate coercion.
+ * Shared by method-body return handling, signal/callback argument marshalling,
+ * and boxed field accessors.
+ */
+
+/**
+ * Casts a raw FFI call result to a native handle so the registry wrappers
+ * (`getNativeObject` / `getNativeObjectAsInterface`) accept it. The cast widens
+ * to `NativeHandle | null` for a GIR-nullable value so the wrapper result type
+ * stays nullable, matching the declared return.
+ */
+export const handleCast = (context: ModuleContext, valueExpression: string, nullable: boolean): string => {
+    context.addNativeTypeImport("NativeHandle");
+    return `${valueExpression} as NativeHandle${nullable ? " | null" : ""}`;
+};
+
+/**
+ * Inputs for {@link wrapReturnValue}.
+ */
+export type WrapReturnOptions = {
+    readonly ref: GirTypeRef | undefined;
+    readonly transfer: ParameterTransfer;
+    readonly nullable: boolean;
+    readonly valueExpression: string;
+};
+
+/**
+ * Wraps a raw FFI value into its typed JavaScript form.
+ *
+ * Objects resolve to their runtime-registered wrapper, interfaces to the
+ * interface wrapper, boxed values to a typed wrapper, collections recurse per
+ * element, and primitives pass through with the appropriate coercion. Shared
+ * by return-value handling and signal-handler argument marshalling.
+ *
+ * @param context - The module context
+ * @param options - {@link WrapReturnOptions}
+ */
+export const wrapReturnValue = (context: ModuleContext, options: WrapReturnOptions): string => {
+    const { ref, nullable, valueExpression } = options;
+    if (ref === undefined) return valueExpression;
+    switch (ref.kind) {
+        case "primitive":
+            return wrapPrimitive(ref, nullable, valueExpression);
+        case "named":
+            return wrapNamed(context, ref, valueExpression, nullable);
+        case "array":
+            return wrapCollection(context, ref.element, valueExpression, nullable);
+        case "list":
+            return ref.flavor === "gbytearray"
+                ? `(${valueExpression} as number[]${nullable ? " | null" : ""})`
+                : wrapCollection(context, ref.element, valueExpression, nullable);
+        case "hashtable":
+            return nullable
+                ? `(${valueExpression} === null ? null : new globalThis.Map(${valueExpression} as Iterable<readonly [unknown, unknown]>))`
+                : `new globalThis.Map(${valueExpression} as Iterable<readonly [unknown, unknown]>)`;
+        case "callback":
+        case "varargs":
+            return `(${valueExpression} as unknown[])`;
+    }
+};
+
+/**
+ * Wraps a collection return value, mapping each element through the runtime
+ * wrapper its type requires.
+ *
+ * The native layer hands collection returns back as arrays of raw element
+ * values; object, interface, and boxed elements must be lifted into their
+ * typed JavaScript wrappers (matching the per-element wrapping a scalar
+ * return of the same type receives) while primitive and enum elements pass
+ * through untouched.
+ */
+const wrapCollection = (
+    context: ModuleContext,
+    element: GirTypeRef | undefined,
+    valueExpression: string,
+    nullable: boolean,
+): string => {
+    const itemExpression = collectionItemWrap(context, element);
+    if (itemExpression === undefined) {
+        const elementTs = element === undefined ? "unknown" : renderTsType(context, element, false);
+        return `(${valueExpression} as ${elementTs}[]${nullable ? " | null" : ""})`;
+    }
+    return nullable
+        ? `((${valueExpression} as unknown[] | null)?.map((item) => ${itemExpression}) ?? null)`
+        : `(${valueExpression} as unknown[]).map((item) => ${itemExpression})`;
+};
+
+const collectionItemWrap = (context: ModuleContext, element: GirTypeRef | undefined): string | undefined => {
+    if (element === undefined || element.kind !== "named") return undefined;
+    const owner = element.namespaceName ?? context.namespace.name;
+    const resolved = context.repository.resolveNamed(owner, element.typeName);
+    if (resolved === undefined) {
+        context.addRuntimeImport("getNativeObject");
+        return `getNativeObject(${handleCast(context, "item", false)})`;
+    }
+    switch (resolved.kind) {
+        case "class":
+        case "boxed":
+            context.addRuntimeImport("getNativeObject");
+            return `getNativeObject(${handleCast(context, "item", false)})`;
+        case "interface": {
+            context.addRuntimeImport("getNativeObjectAsInterface");
+            return `getNativeObjectAsInterface(${handleCast(context, "item", false)}, ${context.qualify(owner, element.typeName)})`;
+        }
+        case "alias":
+            return resolved.target === undefined
+                ? undefined
+                : collectionItemWrap(context, {
+                      kind: "named",
+                      namespaceName: resolved.namespace.name,
+                      typeName: resolved.target,
+                      cType: undefined,
+                  });
+        case "enum":
+        case "callback":
+            return undefined;
+    }
+};
+
+const wrapPrimitive = (ref: PrimitiveTypeRef, nullable: boolean, valueExpression: string): string => {
+    const category = ref.category;
+    if (category === "void") return valueExpression;
+    if (category === "string") return `(${valueExpression} as ${nullable ? "string | null" : "string"})`;
+    if (category === "boolean") return `Boolean(${valueExpression})`;
+    return `(${valueExpression} as number)`;
+};
+
+const wrapNamed = (context: ModuleContext, ref: NamedTypeRef, valueExpression: string, nullable: boolean): string => {
+    const owner = ref.namespaceName ?? context.namespace.name;
+    const resolved = context.repository.resolveNamed(owner, ref.typeName);
+    if (resolved === undefined) {
+        context.addRuntimeImport("getNativeObject");
+        return `getNativeObject(${handleCast(context, valueExpression, nullable)})`;
+    }
+    return wrapResolved(context, resolved, { namespaceName: owner, typeName: ref.typeName, valueExpression, nullable });
+};
+
+type WrapResolvedOptions = {
+    readonly namespaceName: string;
+    readonly typeName: string;
+    readonly valueExpression: string;
+    readonly nullable: boolean;
+};
+
+const wrapResolved = (context: ModuleContext, resolved: ResolvedNamed, options: WrapResolvedOptions): string => {
+    const { namespaceName, typeName, valueExpression, nullable } = options;
+    switch (resolved.kind) {
+        case "class": {
+            context.addRuntimeImport("getNativeObject");
+            return `getNativeObject(${handleCast(context, valueExpression, nullable)})`;
+        }
+        case "interface": {
+            const classExpression = context.qualify(namespaceName, typeName);
+            context.addRuntimeImport("getNativeObjectAsInterface");
+            return `getNativeObjectAsInterface(${handleCast(context, valueExpression, nullable)}, ${classExpression})`;
+        }
+        case "boxed": {
+            const classExpression = context.qualify(namespaceName, typeName);
+            context.addRuntimeImport("getNativeObject");
+            return `getNativeObject(${handleCast(context, valueExpression, nullable)}, ${classExpression})`;
+        }
+        case "enum":
+            return `(${valueExpression} as number)`;
+        case "callback":
+            return valueExpression;
+        case "alias":
+            return resolved.targetRef === undefined
+                ? valueExpression
+                : wrapReturnValue(context, { ref: resolved.targetRef, transfer: "full", nullable, valueExpression });
+    }
+};

package/src/writers/runtime-override.ts

@@ -0,0 +1,59 @@
+import type { GirFunction } from "../gir/function.js";
+
+/**
+ * Shape of a method that codegen cannot marshal and that the FFI runtime
+ * replaces on the prototype at module load.
+ */
+type RuntimeOverride = {
+    /** Optional generic parameter list, including angle brackets. */
+    readonly generics?: string;
+    /** Comma-separated TypeScript parameter list. */
+    readonly signature: string;
+    /** TypeScript return-type annotation. */
+    readonly returnType: string;
+    /** Body executed when the runtime override has not been installed yet. */
+    readonly body: string;
+};
+
+const RUNTIME_OVERRIDES: ReadonlyMap<string, RuntimeOverride> = new Map([
+    [
+        "g_value_get_boxed",
+        {
+            generics: "<T = unknown>",
+            signature: "",
+            returnType: "T",
+            body: 'throw new Error("g_value_get_boxed: runtime override not installed");',
+        },
+    ],
+    [
+        "g_value_set_boxed",
+        {
+            signature: "boxed: object | null",
+            returnType: "void",
+            body: 'throw new Error("g_value_set_boxed: runtime override not installed");',
+        },
+    ],
+]);
+
+/**
+ * Renders the method body for a callable whose marshaling is provided by a
+ * hand-written runtime override.
+ *
+ * `gpointer` exchanges (`GValue` boxed accessors and similar) cannot be
+ * marshaled from GIR alone; the FFI runtime replaces them on the prototype
+ * at module load. The codegen emits a stub with the override's signature
+ * so the consumer types resolve to the runtime shape and the runtime's
+ * `prototype` assignment type-checks.
+ *
+ * Returns `undefined` for callables without a registered override.
+ *
+ * @param callable - The callable to consider
+ * @param memberName - The camelCase JS method name
+ */
+export const renderRuntimeOverride = (callable: GirFunction, memberName: string): string | undefined => {
+    if (callable.cIdentifier === undefined) return undefined;
+    const override = RUNTIME_OVERRIDES.get(callable.cIdentifier);
+    if (override === undefined) return undefined;
+    const generics = override.generics ?? "";
+    return `${memberName}${generics}(${override.signature}): ${override.returnType} {\n    ${override.body}\n}`;
+};