@gtkx/codegen 1.0.0 → 1.2.0

package/src/store/gi/constant.ts

@@ -1,16 +1,26 @@
-import { sourceStringLiteral } from "@gtkx/utils";
+import { sanitizeIdentifier, sourceStringLiteral } from "@gtkx/utils";
 import type { GirConstant } from "../../gir/namespace.js";
 import type { PrimitiveCategory } from "../../gir/primitives.js";
 import type { TypeId } from "../../gir/type-id.js";
 import type { ModuleContext } from "../../writer/context.js";
+import { isEmittableEntity } from "../../gir/emittable.js";
 import { getDoc } from "./doc-spec.js";
 
 const TRUE_VALUES: Set<string> = new Set(["true", "1"]);
-const BIGINT_CATEGORIES: Set<PrimitiveCategory> = new Set(["bigint64", "biguint64", "gtype"]);
+const BIGINT_CATEGORIES: Set<PrimitiveCategory> = new Set(["bigint64", "biguint64", "gtype", "pointer"]);
 
 const generateConstant = (context: ModuleContext, constant: GirConstant): void => {
+    if (!isEmittableEntity(constant)) {
+        return;
+    }
+
     const doc = getDoc(constant);
-    context.module.appendDeclaration(`${doc}export const ${constant.name} = ${constantLiteral(context, constant)};`);
+    const name = sanitizeIdentifier(constant.name);
+
+    context.declare({
+        name,
+        code: `${doc}export const ${name} = ${constantLiteral(context, constant)};`,
+    });
 };
 
 const constantLiteral = (context: ModuleContext, constant: GirConstant): string => {

package/src/store/gi/constructor-props.ts

@@ -96,7 +96,7 @@ const renderTranslatingConstructor = (context: ModuleContext, props: GirProperty
     context.addRuntimeImport("t");
     context.addRuntimeImport("registerConstructProperties");
     const bindings = renderConstructBindings(context, props);
-    context.module.appendRegistration(`registerConstructProperties(${className}, ${bindings});`);
+    context.module.appendRegistration(`registerConstructProperties(${className}, ${bindings});`, [className]);
 
     return renderBlock(`constructor(props: ${className}ConstructorProps = {})`, "super(props);");
 };

package/src/store/gi/enum.ts

@@ -1,7 +1,8 @@
-import { sourceStringLiteral } from "@gtkx/utils";
+import { escapeIdentifierStart, sanitizeTypeIdentifier, sourceStringLiteral, uniqBy } from "@gtkx/utils";
 import type { EnumMember, GirEnum } from "../../gir/enum.js";
 import type { ModuleContext } from "../../writer/context.js";
 import { hasAnnotations } from "../../gir/annotations.js";
+import { isEmittableEntity } from "../../gir/emittable.js";
 import { indent } from "../../writer/emit.js";
 import { getDoc } from "./doc-spec.js";
 
@@ -14,11 +15,17 @@ const enumDoc = (enumeration: GirEnum): string =>
     getDoc(enumeration);
 
 const generateEnum = (context: ModuleContext, enumeration: GirEnum): void => {
-    if (!enumeration.introspectable) {
+    if (!isEmittableEntity(enumeration)) {
         return;
     }
 
-    const members = enumeration.members.map((member) => ({ ...member, key: enumMemberKey(member.name) }));
+    const members = uniqBy(
+        enumeration.members
+            .map((member) => ({ ...member, key: enumMemberKey(member.name) }))
+            .filter((member) => member.key.length > 0),
+        (member) => member.key,
+    );
+
     const errorDomain = enumeration.errorDomain;
 
     if (errorDomain !== undefined) {
@@ -43,16 +50,20 @@ const appendErrorDomain = (
     const quarkExpression = renderQuarkExpression(context, errorDomain);
     const doc = enumDoc(enumeration);
     const shape = typeFields.length === 0 ? "{}" : `{\n${indent(typeFields.join("\n"), 1)}\n}`;
-
-    context.module.appendDeclaration(
-        `${doc}export type ${enumeration.name} = number;`,
-        context.declaredType(enumeration.name),
-    );
-
-    context.module.appendDeclaration(
-        `${doc}export const ${enumeration.name}: ErrorDomain<${shape}> = ` +
-        `createErrorDomain(${quarkExpression}, { ${memberEntries.join(", ")} });`,
-    );
+    const name = sanitizeTypeIdentifier(enumeration.name);
+
+    context.declare({
+        name,
+        code: `${doc}export type ${name} = number;`,
+        owner: enumeration.name,
+    });
+
+    context.declare({
+        name,
+        code:
+            `${doc}export const ${name}: ErrorDomain<${shape}> = ` +
+            `createErrorDomain(${quarkExpression}, { ${memberEntries.join(", ")} });`,
+    });
 };
 
 const isMemberDocumented = (member: KeyedMember): boolean =>
@@ -60,31 +71,30 @@ const isMemberDocumented = (member: KeyedMember): boolean =>
 
 const appendEnumDeclaration = (context: ModuleContext, enumeration: GirEnum, members: KeyedMember[]): void => {
     const doc = enumDoc(enumeration);
+    const name = sanitizeTypeIdentifier(enumeration.name);
 
     if (members.some((member) => isMemberDocumented(member))) {
         const blocks = members.map((member) => `${memberDoc(member)}${member.key} = ${member.value},`);
 
-        context.module.appendDeclaration(
-            `${doc}export enum ${enumeration.name} {\n${indent(blocks.join("\n"), 1)}\n}`,
-            context.declaredType(enumeration.name),
-        );
+        context.declare({
+            name,
+            code: `${doc}export enum ${name} {\n${indent(blocks.join("\n"), 1)}\n}`,
+            owner: enumeration.name,
+        });
 
         return;
     }
 
     const declarations = members.map((member) => `${member.key} = ${member.value}`);
 
-    context.module.appendDeclaration(
-        `${doc}export enum ${enumeration.name} { ${declarations.join(", ")} }`,
-        context.declaredType(enumeration.name),
-    );
+    context.declare({
+        name,
+        code: `${doc}export enum ${name} { ${declarations.join(", ")} }`,
+        owner: enumeration.name,
+    });
 };
 
-const enumMemberKey = (name: string): string => {
-    const upper = name.toUpperCase().replaceAll("-", "_");
-
-    return /^\d/.test(upper) ? `_${upper}` : upper;
-};
+const enumMemberKey = (name: string): string => escapeIdentifierStart(name.toUpperCase().replaceAll("-", "_"));
 
 const renderQuarkExpression = (context: ModuleContext, errorDomain: string): string => {
     if (context.namespace.name === "GLib") {

package/src/store/gi/function.ts

@@ -1,6 +1,5 @@
 import { toCamelIdentifier } from "@gtkx/utils";
 import type { GirFunction } from "../../gir/function.js";
-import type { GirNamespace } from "../../gir/namespace.js";
 import type { ModuleContext } from "../../writer/context.js";
 import { tFn } from "../../analysis/descriptor.js";
 import { hasUnmarshalableParam } from "../../analysis/param-capability.js";
@@ -43,9 +42,14 @@ const renderFnExpression = (context: ModuleContext, fn: GirFunction): string | u
 
     context.addRuntimeImport("t");
     const params = planCallArgs(context, fn).map((arg) => arg.paramLiteral);
-    const ret = renderReturnDescriptor(context, fn);
-
-    return tFn(library, fn.cIdentifier, { args: arrayLiteral(params), returns: ret, canThrow: fn.throws });
+    const returnPlan = renderReturnDescriptor(context, fn);
+
+    return tFn(library, fn.cIdentifier, {
+        args: arrayLiteral(params),
+        returns: returnPlan.descriptor,
+        isReturnSkipped: returnPlan.isSkipped,
+        canThrow: fn.throws,
+    });
 };
 
 const isMovedOntoEmittedMember = (context: ModuleContext, fn: GirFunction): boolean => {
@@ -90,13 +94,25 @@ const generateNamespaceFunction = (context: ModuleContext, fn: GirFunction): voi
         return;
     }
 
-    const bindingName = toCamelIdentifier(cIdentifier);
-    context.module.appendBinding(`const ${bindingName} = ${expression};`, cIdentifier);
     const exportName = namespaceFunctionExportName(cIdentifier, fn.name, context.namespace.cSymbolPrefixes);
+
+    if (exportName.length === 0) {
+        return;
+    }
+
+    const bindingName = namespaceBindingName(cIdentifier, exportName);
+    context.module.appendBinding(`const ${bindingName} = ${expression};`, cIdentifier);
     const finish = matchNamespaceFinish(context, fn);
     const declaration = renderNamespaceFunctionDeclaration({ context, fn, finish, exportName, bindingName });
     const doc = callableDoc(context, fn, { finishFn: finish?.fn });
-    context.module.appendDeclaration(`${doc}${declaration}`);
+    context.declare({ name: exportName, code: `${doc}${declaration}` });
+    appendBootstrapRegistration(context, fn, exportName);
+};
+
+const namespaceBindingName = (cIdentifier: string, exportName: string): string => {
+    const bindingName = toCamelIdentifier(cIdentifier);
+
+    return bindingName === exportName ? `_${bindingName}` : bindingName;
 };
 
 const matchNamespaceFinish = (context: ModuleContext, fn: GirFunction): NamespaceFinish | undefined => {
@@ -159,31 +175,21 @@ const stripLongestPrefix = (input: string, prefixes: string[]): string => {
     return best.length === 0 ? input : input.slice(best.length);
 };
 
-const isBootstrapFunction = (fn: GirFunction): boolean =>
-    fn.parameters.length === 0 && fn.introspectable && fn.shadowedBy === undefined && fn.cIdentifier !== undefined;
-
 const appendBootstrapRegistration = (context: ModuleContext, fn: GirFunction, exportName: string): void => {
+    if (fn.parameters.length > 0) {
+        return;
+    }
+
     if (fn.name === "init") {
-        context.module.appendRegistration(`${exportName}();`);
+        context.module.appendRegistration(`${exportName}();`, [exportName]);
 
         return;
     }
 
     if (fn.name === "finalize") {
         context.addRuntimeImport("onExit");
-        context.module.appendRegistration(`onExit(${exportName});`);
-    }
-};
-
-const generateNamespaceBootstrap = (context: ModuleContext, namespace: GirNamespace): void => {
-    for (const fn of namespace.functions) {
-        if (!isBootstrapFunction(fn) || fn.cIdentifier === undefined) {
-            continue;
-        }
-
-        const exportName = namespaceFunctionExportName(fn.cIdentifier, fn.name, context.namespace.cSymbolPrefixes);
-        appendBootstrapRegistration(context, fn, exportName);
+        context.module.appendRegistration(`onExit(${exportName});`, [exportName]);
     }
 };
 
-export { renderFnExpression, generateNamespaceFunction, namespaceFunctionExportName, generateNamespaceBootstrap };
+export { renderFnExpression, generateNamespaceFunction, namespaceFunctionExportName };

package/src/store/gi/gtype-binding.ts

@@ -24,9 +24,14 @@ const renderInternGtype = (context: ModuleContext, typeName: string | undefined)
     return `typeFromName(${sourceStringLiteral(typeName)})`;
 };
 
-const renderResolveGtype = (context: ModuleContext, typeFnName: string): string => {
+const renderResolveGtype = (context: ModuleContext, typeFnName: string): string | undefined => {
+    const lib = context.namespace.sharedLibrary;
+
+    if (lib === undefined) {
+        return undefined;
+    }
+
     context.addRuntimeImport("resolveType");
-    const lib = context.namespace.sharedLibrary ?? "";
 
     return `resolveType(${sourceStringLiteral(lib)}, ${sourceStringLiteral(typeFnName)})`;
 };

package/src/store/gi/interface.ts

@@ -1,9 +1,11 @@
-import { pascalCase, sourceStringLiteral } from "@gtkx/utils";
+import { sanitizeTypeIdentifier, sourceStringLiteral } from "@gtkx/utils";
 import type { GirClass } from "../../gir/class.js";
 import type { GirProperty } from "../../gir/property.js";
 import type { ModuleContext } from "../../writer/context.js";
 import { reservedSignalMemberRename, resolvePrerequisiteReference } from "../../analysis/inheritance.js";
-import { resolveInterfaces } from "../../gir/ancestry.js";
+import { omittedTypeRef, prerequisiteConflicts } from "../../analysis/interface-conflicts.js";
+import { resolveClassOrInterface, resolveInterfaces } from "../../gir/ancestry.js";
+import { isEmittableEntity } from "../../gir/emittable.js";
 import { renderJsDoc } from "../../writer/doc.js";
 import { renderBlock, renderBraced, renderBracedOrEmpty } from "../../writer/emit.js";
 import {
@@ -72,15 +74,11 @@ const BRAND_NOTE = [
 ].join("\n");
 
 const generateInterface = (context: ModuleContext, iface: GirClass): void => {
-    if (!iface.introspectable) {
+    if (!isEmittableEntity(iface)) {
         return;
     }
 
-    if (iface.name.length === 0) {
-        return;
-    }
-
-    const className = pascalCase(iface.name);
+    const className = sanitizeTypeIdentifier(iface.name);
 
     const callables: Callables = {
         constructors: dedupeCallables(iface.constructors),
@@ -92,13 +90,16 @@ const generateInterface = (context: ModuleContext, iface: GirClass): void => {
     const gtypeExpr = renderSourceGtype(context, iface);
     const implRef = appendInterfaceTypes(context, iface, className, callables) ?? "unknown";
     const classCode = renderInterfaceClass(context, { iface, className, callables, gtypeExpr, implRef });
-    context.module.appendDeclaration(classCode, context.declaredType(className));
+    context.declare({ name: className, code: classCode, owner: iface.name });
 
     for (const declaration of renderSignalDeclarations(context, iface, className, true)) {
-        context.module.appendDeclaration(declaration);
+        context.declare(declaration);
     }
 
-    context.module.appendDeclaration(renderInterfaceMaker(context, iface, className, callables));
+    context.declare({
+        name: makerName(className),
+        code: renderInterfaceMaker(context, iface, className, callables),
+    });
 
     appendInterfaceRegistration(context, {
         className,
@@ -136,7 +137,7 @@ const renderInterfaceLayout = (
 };
 
 const invokerMembers = (context: ModuleContext, iface: GirClass, callables: Callables): Map<string, string> => {
-    const className = pascalCase(iface.name);
+    const className = sanitizeTypeIdentifier(iface.name);
 
     const invokers: Set<string> = new Set(
         iface.vfuncs.map((vfunc) => vfunc.invoker).filter((invoker) => invoker !== undefined),
@@ -201,7 +202,7 @@ const appendInterfaceTypes = (
     callables: Callables,
 ): string | undefined => {
     const typeCode = renderInterfaceType(context, iface, className, callables);
-    context.module.appendDeclaration(typeCode, context.declaredType(className));
+    context.declare({ name: className, code: typeCode, owner: iface.name });
     const implType = renderInterfaceImplType(context, iface, className);
 
     if (implType === undefined) {
@@ -209,21 +210,39 @@ const appendInterfaceTypes = (
     }
 
     const implName = implTypeName(className);
-    context.module.appendDeclaration(implType, context.declaredType(className, implName));
+    context.declare({ name: implName, code: implType, owner: iface.name });
 
     return implName;
 };
 
+const prerequisiteRef = (context: ModuleContext, iface: GirClass, name: string): string | undefined => {
+    const ref = resolvePrerequisiteReference(context, name);
+    const base = resolveClassOrInterface(context.library, context.namespace.name, name);
+
+    if (ref === undefined || base === undefined) {
+        return undefined;
+    }
+
+    return omittedTypeRef(ref, prerequisiteConflicts(context.library, iface, base));
+};
+
+const rootPrerequisiteRef = (context: ModuleContext, iface: GirClass): string => {
+    const ref = context.qualify("GObject", "Object");
+    const base = resolveClassOrInterface(context.library, "GObject", "Object");
+
+    return base === undefined ? ref : omittedTypeRef(ref, prerequisiteConflicts(context.library, iface, base));
+};
+
 const interfaceTypeExtends = (context: ModuleContext, iface: GirClass): string => {
     const refs = iface.prerequisites
-        .map((name) => resolvePrerequisiteReference(context, name))
+        .map((name) => prerequisiteRef(context, iface, name))
         .filter((entry): entry is string => entry !== undefined);
 
     if (refs.length > 0) {
         return refs.join(", ");
     }
 
-    return context.qualify("GObject", "Object");
+    return rootPrerequisiteRef(context, iface);
 };
 
 const renderInterfaceType = (
@@ -264,7 +283,7 @@ const implPrerequisiteRefs = (context: ModuleContext, iface: GirClass): string[]
             continue;
         }
 
-        const name = implTypeName(pascalCase(prerequisite.klass.name));
+        const name = implTypeName(sanitizeTypeIdentifier(prerequisite.klass.name));
         refs.push(context.qualify(prerequisite.namespaceName, name));
     }
 
@@ -317,11 +336,11 @@ const collectMethodMembers = (options: MethodMemberOptions): string[] => {
 };
 
 const collectPropertyMembers = (options: PropertyMemberOptions): string[] => {
-    const { context, iface, scope, renderers, claimedNames } = options;
+    const { context, iface, renderers, claimedNames } = options;
     const members: string[] = [];
 
     for (const property of iface.properties) {
-        const block = renderers.renderProperty({ context, property, claimedNames, methodByName: scope.methodByName });
+        const block = renderers.renderProperty({ context, property, claimedNames });
 
         if (block !== undefined) {
             members.push(block);
@@ -337,7 +356,7 @@ const renderInterfaceMembers = (
     callables: Callables,
     renderers: InterfaceMemberRenderers,
 ): string[] => {
-    const className = pascalCase(iface.name);
+    const className = sanitizeTypeIdentifier(iface.name);
     const scope = instanceScope(className, callables);
     const claimedNames: Set<string> = new Set();
     const methodMembers = collectMethodMembers({ context, className, scope, callables, renderers, claimedNames });

package/src/store/gi/method.ts

@@ -1,8 +1,9 @@
-import { camelCase, sourceStringLiteral } from "@gtkx/utils";
+import { camelCase, escapeIdentifierStart, sourceStringLiteral } from "@gtkx/utils";
 import type { GirFunction } from "../../gir/function.js";
 import type { GirType } from "../../gir/type.js";
 import type { ModuleContext } from "../../writer/context.js";
 import {
+    isSkippedPrimaryReturn,
     renderCallbackType,
     renderDescriptor,
     renderSelfDescriptor,
@@ -18,12 +19,18 @@ import {
     inputParameters,
     parameterIdentifier,
 } from "../../analysis/param-structure.js";
-import { renderTsType } from "../../analysis/ts-type.js";
+import { renderParameterTsType, renderTsType } from "../../analysis/ts-type.js";
 import { type GirParameter, isCallerAllocatedOut, isInoutParameter, isOutParameter } from "../../gir/parameter.js";
 import { hasUnknownArrayLength, type TypeId } from "../../gir/type-id.js";
 import { areClosuresInvoked } from "./closure-invocation.js";
 import { itemComparatorArgDescriptors, itemComparatorTsType } from "./item-comparators.js";
-import { isClosureType, isCollectibleCallerOut, isHandlePassedInPlace, isHandlePassing } from "./param-marshal.js";
+import {
+    isClosureType,
+    isCollectibleCallerOut,
+    isHandlePassedInPlace,
+    isHandlePassing,
+    renderCallerOutInstance,
+} from "./param-marshal.js";
 
 type PromisifiedStep = { hasSeenOptional: boolean; expression: string | undefined };
 
@@ -54,6 +61,11 @@ type CallArgPlan = {
     inputExpr: string | undefined;
 };
 
+type ReturnDescriptorPlan = {
+    descriptor: string;
+    isSkipped: boolean;
+};
+
 type ParamDescriptorOptions = {
     direction?: "out" | "inout";
     isCallerAllocated?: boolean;
@@ -74,7 +86,8 @@ type PlanArgsContext = {
     folded: Set<number>;
 };
 
-const methodExportName = (fn: GirFunction): string => camelCase(fn.name);
+const memberName = (girName: string): string => escapeIdentifierStart(camelCase(girName));
+const methodExportName = (fn: GirFunction): string => memberName(fn.name);
 
 const arrayLengthArgument = (source: GirParameter, sourceIndex: number): string => {
     const identifier = parameterIdentifier(source, sourceIndex);
@@ -107,7 +120,7 @@ const parameterAnnotation = (context: ModuleContext, fn: GirFunction, parameter:
         return comparator;
     }
 
-    const base = renderTsType(context, parameter.type, parameter.nullable);
+    const base = renderParameterTsType(context, parameter.type, parameter.nullable);
 
     return requiresClosureAnnotation(context, fn, parameter) ? closureAnnotation(context, base) : base;
 };
@@ -346,14 +359,16 @@ const paramDescriptorLiteral = (descriptor: string, options: ParamDescriptorOpti
     return `{ ${parts.join(", ")} }`;
 };
 
-const renderReturnDescriptor = (context: ModuleContext, fn: GirFunction): string => {
+const renderReturnDescriptor = (context: ModuleContext, fn: GirFunction): ReturnDescriptorPlan => {
     const instanceOffset = fn.instance === undefined ? 0 : 1;
 
-    return renderDescriptor(context, fn.returnValue.type, fn.returnValue.transferOwnership, {
+    const descriptor = renderDescriptor(context, fn.returnValue.type, fn.returnValue.transferOwnership, {
         argIndexOffset: instanceOffset,
         argIndexMap: emittedArgIndices(fn, instanceOffset),
         isNewlyCreated: fn.instance === undefined,
     });
+
+    return { descriptor, isSkipped: isSkippedPrimaryReturn(context.library, fn.returnValue) };
 };
 
 const planCallArgs = (context: ModuleContext, fn: GirFunction): CallArgPlan[] => {
@@ -473,6 +488,7 @@ const planOutParam = (
 ): CallArgPlan => {
     const descriptor = renderDescriptor(context, parameter.type, parameter.transferOwnership, {
         ...argIndex,
+        cursor: parameter.cursor,
         hasOutIndirection: true,
     });
 
@@ -482,41 +498,19 @@ const planOutParam = (
     };
 };
 
-const constructibleName = (
-    context: ModuleContext,
-    ref: GirParameter["type"],
-): { namespaceName: string; typeName: string } | undefined => {
-    let current = ref;
-
-    while (current !== undefined) {
-        const resolved = context.library.typeFor(current);
-
-        if (resolved?.kind === "alias" && resolved.value.target !== undefined) {
-            current = resolved.value.target;
-            continue;
-        }
-
-        return context.library.nameFor(current);
-    }
-
-    return undefined;
-};
-
 const planCallerOut = (
     context: ModuleContext,
     parameter: GirParameter,
     argIndex: ArgIndexOptions,
 ): CallArgPlan => {
     const descriptor = renderDescriptor(context, parameter.type, "none", argIndex);
-    const name = constructibleName(context, parameter.type);
 
-    if (name !== undefined && isCollectibleCallerOut(context, parameter)) {
+    if (isCollectibleCallerOut(context, parameter)) {
         context.addRuntimeImport("getHandle");
-        const classExpression = context.qualify(name.namespaceName, name.typeName);
 
         return {
             paramLiteral: paramDescriptorLiteral(descriptor, { direction: "out", isCallerAllocated: true }),
-            inputExpr: `new ${classExpression}()`,
+            inputExpr: renderCallerOutInstance(context, parameter),
         };
     }
 
@@ -678,8 +672,8 @@ const parameterCallExpression = (
 };
 
 export {
-    constructibleName,
     isCallbackParameter,
+    memberName,
     methodExportName,
     renderMethodSignature,
     renderMethodReturnType,

package/src/store/gi/param-marshal.ts

@@ -1,7 +1,13 @@
+import { sanitizeTypeIdentifier } from "@gtkx/utils";
 import type { TypeId } from "../../gir/type-id.js";
 import type { GirType } from "../../gir/type.js";
 import type { ModuleContext } from "../../writer/context.js";
 import { type GirParameter, isInoutParameter } from "../../gir/parameter.js";
+import { recordInlineSize } from "./record-layout.js";
+import { isConstructibleRecord } from "./value-marshalable.js";
+
+type TypeName = { namespaceName: string; typeName: string };
+type CallerOutAllocation = TypeName & ({ strategy: "construct" } | { strategy: "allocate"; size: number });
 
 const isHandlePassedInPlace = (context: ModuleContext, parameter: GirParameter): boolean => {
     if (parameter.direction !== "out" && parameter.direction !== "inout") {
@@ -28,14 +34,78 @@ const underlyingType = (context: ModuleContext, ref: TypeId): GirType | undefine
 const underlyingParamKind = (context: ModuleContext, parameter: GirParameter): GirType["kind"] | undefined =>
     parameter.type === undefined ? undefined : underlyingType(context, parameter.type)?.kind;
 
-const isCollectibleCallerOut = (context: ModuleContext, parameter: GirParameter): boolean => {
-    const kind = underlyingParamKind(context, parameter);
+const resolvedTypeName = (context: ModuleContext, ref: TypeId | undefined): TypeName | undefined => {
+    let current = ref;
+
+    while (current !== undefined) {
+        const resolved = context.library.typeFor(current);
+
+        if (resolved?.kind === "alias" && resolved.value.target !== undefined) {
+            current = resolved.value.target;
+            continue;
+        }
+
+        return context.library.nameFor(current);
+    }
+
+    return undefined;
+};
+
+const recordCallerOutAllocation = (
+    context: ModuleContext,
+    name: TypeName,
+    type: Extract<GirType, { kind: "record" }>,
+): CallerOutAllocation | undefined => {
+    const size = recordInlineSize(context, type.value);
+
+    if (size === undefined) {
+        return undefined;
+    }
+
+    return isConstructibleRecord(context, type.namespace.name, type.value)
+        ? { ...name, strategy: "construct" }
+        : { ...name, strategy: "allocate", size };
+};
+
+const callerOutAllocation = (context: ModuleContext, parameter: GirParameter): CallerOutAllocation | undefined => {
+    const name = resolvedTypeName(context, parameter.type);
+    const type = parameter.type === undefined ? undefined : underlyingType(context, parameter.type);
 
-    return kind === "record" || kind === "class";
+    if (name === undefined || type === undefined) {
+        return undefined;
+    }
+
+    if (type.kind === "class") {
+        return { ...name, strategy: "construct" };
+    }
+
+    return type.kind === "record" ? recordCallerOutAllocation(context, name, type) : undefined;
+};
+
+const renderCallerOutInstance = (context: ModuleContext, parameter: GirParameter): string => {
+    const allocation = callerOutAllocation(context, parameter);
+
+    if (allocation === undefined) {
+        throw new Error("renderCallerOutInstance: expected a caller-allocated out-parameter with a known layout");
+    }
+
+    const classExpression = context.qualify(allocation.namespaceName, sanitizeTypeIdentifier(allocation.typeName));
+
+    if (allocation.strategy === "construct") {
+        return `new ${classExpression}()`;
+    }
+
+    context.addRuntimeImport("alloc");
+    context.addRuntimeImport("wrapHandle");
+
+    return `wrapHandle(alloc(${String(allocation.size)}), ${classExpression})`;
 };
 
-const isRecordCallerOut = (context: ModuleContext, parameter: GirParameter): boolean =>
-    underlyingParamKind(context, parameter) === "record";
+const isCollectibleCallerOut = (context: ModuleContext, parameter: GirParameter): boolean =>
+    callerOutAllocation(context, parameter) !== undefined;
+
+const isAllocatableCallerOut = (context: ModuleContext, parameter: GirParameter): boolean =>
+    underlyingParamKind(context, parameter) === "record" && isCollectibleCallerOut(context, parameter);
 
 const isRecordInout = (context: ModuleContext, parameter: GirParameter): boolean =>
     isInoutParameter(parameter) && underlyingParamKind(context, parameter) === "record";
@@ -75,11 +145,12 @@ const isClosureType = (context: ModuleContext, ref: TypeId): boolean => {
 };
 
 export {
+    isAllocatableCallerOut,
     isClosureType,
     isHandlePassedInPlace,
     isCollectibleCallerOut,
-    isRecordCallerOut,
     isRecordInout,
     isHandlePassing,
+    renderCallerOutInstance,
     underlyingType,
 };