@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/src/store/gi/closure-invocation.ts

@@ -0,0 +1,26 @@
+import type { GirFunction } from "../../gir/function.js";
+
+const FUNCTIONS_INVOKING_CLOSURE_PARAMETERS: Set<string> = new Set([
+    "g_binding_group_bind_with_closures",
+    "g_bus_own_name_on_connection_with_closures",
+    "g_bus_own_name_with_closures",
+    "g_bus_watch_name_on_connection_with_closures",
+    "g_bus_watch_name_with_closures",
+    "g_dbus_connection_register_object_with_closures",
+    "g_dbus_connection_register_object_with_closures2",
+    "g_file_copy_async_with_closures",
+    "g_file_move_async_with_closures",
+    "g_object_bind_property_with_closures",
+    "g_settings_bind_with_mapping_closures",
+    "g_signal_connect_closure",
+    "g_signal_connect_closure_by_id",
+    "g_signal_group_connect_closure",
+    "g_signal_override_class_closure",
+    "g_source_set_closure",
+    "gtk_closure_expression_new",
+]);
+
+const areClosuresInvoked = (fn: GirFunction): boolean =>
+    fn.cIdentifier !== undefined && FUNCTIONS_INVOKING_CLOSURE_PARAMETERS.has(fn.cIdentifier);
+
+export { areClosuresInvoked };

package/src/store/gi/companion.ts

@@ -1,16 +1,17 @@
-import { pascalCase } from "@gtkx/utils";
+import { sanitizeTypeIdentifier } from "@gtkx/utils";
 import type { GirClass } from "../../gir/class.js";
 import type { ModuleContext } from "../../writer/context.js";
-import { splitOptionalNamespace } from "../../gir/type-ref.js";
+import { getParentRef } from "../../gir/ancestry.js";
 
 const parentCompanionRef = (context: ModuleContext, klass: GirClass, suffix: string): string | undefined => {
-    if (klass.parent === undefined) {
+    const parent = getParentRef(klass);
+
+    if (parent === undefined) {
         return undefined;
     }
 
-    const [parentNamespace, typeName] = splitOptionalNamespace(klass.parent);
-    const namespaceName = parentNamespace ?? context.namespace.name;
-    const name = `${pascalCase(typeName)}${suffix}`;
+    const namespaceName = parent.namespaceName ?? context.namespace.name;
+    const name = `${sanitizeTypeIdentifier(parent.typeName)}${suffix}`;
 
     if (namespaceName === context.namespace.name) {
         return name;

package/src/store/gi/constant.ts

@@ -1,17 +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 { renderJsDoc } from "../../writer/doc.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 generateConstant = (context: ModuleContext, constant: GirConstant): void => {
-    context.module.appendDeclaration(
-        `${renderJsDoc(constant.doc)}export const ${constant.name} = ${constantLiteral(context, constant)};`,
-    );
+    if (!isEmittableEntity(constant)) {
+        return;
+    }
+
+    const doc = getDoc(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

@@ -8,8 +8,7 @@ import { ancestorChain } from "../../gir/ancestry.js";
 import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
 import { renderBlock, renderBraced, renderBracedOrEmpty } from "../../writer/emit.js";
 import { parentCompanionRef } from "./companion.js";
-
-const PROPS_RECORD = "Record<string, unknown>";
+import { propertyDoc } from "./property-accessor.js";
 
 const constructablePropNames = (klass: GirClass): string[] =>
     klass.properties.filter(isConstructableProperty).map((property) => toCamelIdentifier(property.name));
@@ -47,7 +46,8 @@ const renderConstructorPropsInterface = (context: ModuleContext, klass: GirClass
 
     const lines = collectConstructableProps(context, klass).map(
         (property) =>
-            `${toCamelIdentifier(property.name)}?: ${renderTsType(context, property.type, true)} | undefined;`,
+            `${propertyDoc(property)}${toCamelIdentifier(property.name)}?: ` +
+            `${renderTsType(context, property.type, true)} | undefined;`,
     );
 
     return renderBracedOrEmpty(`export interface ${className}ConstructorProps${extendsClause}`, lines.join("\n"));
@@ -73,36 +73,32 @@ const renderClassConstructor = (
 };
 
 const renderRootConstructor = (context: ModuleContext): string => {
-    context.addRuntimeImport("getInstanceType");
+    context.addRuntimeTypeImport("AnyClass");
+    context.addRuntimeImport("getClassType");
     context.addRuntimeImport("newObjectWithProperties");
-    context.addRuntimeImport("setHandle");
-    context.addRuntimeImport("setWrapper");
-
-    const body = [
-        "const handle = newObjectWithProperties(getInstanceType(this), props);",
-        "setHandle(this, handle);",
-        "setWrapper(handle, this);",
-    ].join("\n");
+    const body = "newObjectWithProperties(getClassType(this.constructor as AnyClass), props, this);";
 
-    return renderBlock(`constructor(props: ${PROPS_RECORD} = {})`, body);
+    return renderBlock("constructor(props: object = {})", body);
 };
 
-const renderTranslatingConstructor = (context: ModuleContext, props: GirProperty[], className: string): string => {
-    context.addRuntimeImport("t");
-    const destructured = props.map((property) => toCamelIdentifier(property.name));
-    const pattern = `{ ${[...destructured, "...rest"].join(", ")} }`;
-
+const renderConstructBindings = (context: ModuleContext, props: GirProperty[]): string => {
     const entries = props.map((property) => {
         const descriptor = renderDescriptor(context, property.type, property.transferOwnership);
+        const key = sourceStringLiteral(toCamelIdentifier(property.name));
 
-        return `${sourceStringLiteral(property.name)}: [${descriptor}, ${toCamelIdentifier(property.name)}],`;
+        return `${key}: [${sourceStringLiteral(property.name)}, ${descriptor}],`;
     });
 
-    const recordLiteral = renderBraced(entries.join("\n"));
-    const lines = [`const props: ${PROPS_RECORD} = ${recordLiteral};`, "super({ ...props, ...rest });"];
-    const body = lines.join("\n");
+    return renderBraced(entries.join("\n"));
+};
+
+const renderTranslatingConstructor = (context: ModuleContext, props: GirProperty[], className: string): string => {
+    context.addRuntimeImport("t");
+    context.addRuntimeImport("registerConstructProperties");
+    const bindings = renderConstructBindings(context, props);
+    context.module.appendRegistration(`registerConstructProperties(${className}, ${bindings});`, [className]);
 
-    return renderBlock(`constructor(${pattern}: ${className}ConstructorProps = {})`, body);
+    return renderBlock(`constructor(props: ${className}ConstructorProps = {})`, "super(props);");
 };
 
 export { renderConstructorPropsInterface, renderClassConstructor };

package/src/store/gi/doc-spec.ts

@@ -0,0 +1,38 @@
+import type { GirAnnotations } from "../../gir/annotations.js";
+import type { GirCallable, GirParameter } from "../../gir/parameter.js";
+import type { JsDocSpec } from "../../writer/doc.js";
+import { documentedHandlerParameters, handlerRenames } from "../../analysis/param-structure.js";
+import { renderJsDoc } from "../../writer/doc.js";
+
+type DocumentedNode = { doc: string | undefined; annotations: GirAnnotations };
+
+const SELF_PARAM_DOC = "The instance the signal was emitted on.";
+const THROWS_TEXT = "A `GLib.Error` carrying the failing operation's domain, code, and message.";
+
+const annotationSpec = (annotations: GirAnnotations): JsDocSpec => ({
+    deprecated: annotations.isDeprecated
+        ? { since: annotations.deprecatedSince, doc: annotations.deprecationDoc }
+        : undefined,
+    since: annotations.since,
+});
+
+const getDoc = (node: DocumentedNode): string => renderJsDoc(node.doc, undefined, annotationSpec(node.annotations));
+
+const handlerSpec = (
+    callable: GirCallable,
+    parameters: GirParameter[],
+    identifiers?: Map<string, string>,
+): JsDocSpec => ({
+    ...annotationSpec(callable.annotations),
+    identifiers: identifiers ?? handlerRenames(parameters),
+    params: documentedHandlerParameters(parameters),
+    returns: callable.returnValue.doc,
+});
+
+const selfHandlerSpec = (signal: GirCallable): JsDocSpec => {
+    const spec = handlerSpec(signal, signal.parameters);
+
+    return { ...spec, params: [...(spec.params ?? []), { name: "self", doc: SELF_PARAM_DOC }] };
+};
+
+export { annotationSpec, getDoc, handlerSpec, selfHandlerSpec, THROWS_TEXT };

package/src/store/gi/enum.ts

@@ -1,48 +1,97 @@
-import { sourceStringLiteral } from "@gtkx/utils";
-import type { GirEnum } from "../../gir/enum.js";
+import { sanitizeTypeIdentifier, sourceStringLiteral, uniqBy } from "@gtkx/utils";
+import type { EnumMember, GirEnum } from "../../gir/enum.js";
 import type { ModuleContext } from "../../writer/context.js";
-import { renderJsDoc } from "../../writer/doc.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";
+
+type KeyedMember = EnumMember & { key: string };
+
+const memberDoc = (member: KeyedMember): string =>
+    getDoc(member);
+
+const enumDoc = (enumeration: GirEnum): string =>
+    getDoc(enumeration);
 
 const generateEnum = (context: ModuleContext, enumeration: GirEnum): void => {
-    if (!enumeration.introspectable) {
+    if (!isEmittableEntity(enumeration)) {
         return;
     }
 
-    const name = enumeration.name;
-    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,
+    );
 
-    if (enumeration.errorDomain !== undefined) {
-        const memberEntries = members.map((member) => `${member.key}: ${member.value}`);
-        const typeFields = members.map((member) => `${member.key}: number`).join("; ");
-        context.addRuntimeImport("createErrorDomain");
-        context.addRuntimeImport("ErrorDomain");
-        const quarkExpression = renderQuarkExpression(context, enumeration.errorDomain);
-        context.module.appendDeclaration(`${renderJsDoc(enumeration.doc)}export type ${name} = number;`);
+    const errorDomain = enumeration.errorDomain;
 
-        context.module.appendDeclaration(
-            `export const ${name}: ErrorDomain<{ ${typeFields} }> = ` +
-            `createErrorDomain(${quarkExpression}, { ${memberEntries.join(", ")} });`,
-        );
+    if (errorDomain !== undefined) {
+        appendErrorDomain(context, enumeration, members, errorDomain);
 
         return;
     }
 
-    if (members.some((member) => member.doc !== undefined)) {
-        const memberBlocks = members.map((member) => `${renderJsDoc(member.doc)}${member.key} = ${member.value},`);
+    appendEnumDeclaration(context, enumeration, members);
+};
 
-        context.module.appendDeclaration(
-            `${renderJsDoc(enumeration.doc)}export enum ${name} {\n${indent(memberBlocks.join("\n"), 1)}\n}`,
-        );
+const appendErrorDomain = (
+    context: ModuleContext,
+    enumeration: GirEnum,
+    members: KeyedMember[],
+    errorDomain: string,
+): void => {
+    const memberEntries = members.map((member) => `${member.key}: ${member.value}`);
+    const typeFields = members.map((member) => `${memberDoc(member)}${member.key}: number;`);
+    context.addRuntimeImport("createErrorDomain");
+    context.addRuntimeImport("ErrorDomain");
+    const quarkExpression = renderQuarkExpression(context, errorDomain);
+    const doc = enumDoc(enumeration);
+    const shape = typeFields.length === 0 ? "{}" : `{\n${indent(typeFields.join("\n"), 1)}\n}`;
+    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 =>
+    member.doc !== undefined || hasAnnotations(member.annotations);
+
+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.declare({
+            name,
+            code: `${doc}export enum ${name} {\n${indent(blocks.join("\n"), 1)}\n}`,
+            owner: enumeration.name,
+        });
 
         return;
     }
 
-    const memberDeclarations = members.map((member) => `${member.key} = ${member.value}`);
+    const declarations = members.map((member) => `${member.key} = ${member.value}`);
 
-    context.module.appendDeclaration(
-        `${renderJsDoc(enumeration.doc)}export enum ${name} { ${memberDeclarations.join(", ")} }`,
-    );
+    context.declare({
+        name,
+        code: `${doc}export enum ${name} { ${declarations.join(", ")} }`,
+        owner: enumeration.name,
+    });
 };
 
 const enumMemberKey = (name: string): string => {

package/src/store/gi/function.ts

@@ -1,12 +1,11 @@
 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 { hasCallerAllocatedArrayLength } from "../../analysis/param-structure.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { hasUnmarshalableParam } from "../../analysis/param-capability.js";
 import { arrayLiteral, renderBlock } from "../../writer/emit.js";
 import { matchAsyncFinish } from "./async.js";
+import { callableDoc } from "./callable-doc.js";
 import {
     planCallArgs,
     renderMethodBody,
@@ -17,6 +16,19 @@ import {
     renderReturnDescriptor,
 } from "./method.js";
 
+type NamespaceFinish = {
+    fn: GirFunction;
+    exportName: string;
+};
+
+type NamespaceFunctionOptions = {
+    context: ModuleContext;
+    fn: GirFunction;
+    finish: NamespaceFinish | undefined;
+    exportName: string;
+    bindingName: string;
+};
+
 const renderFnExpression = (context: ModuleContext, fn: GirFunction): string | undefined => {
     if (fn.cIdentifier === undefined) {
         return undefined;
@@ -30,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 => {
@@ -58,7 +75,7 @@ const canEmitNamespaceFunction = (context: ModuleContext, fn: GirFunction): bool
     !isMovedOntoEmittedMember(context, fn) &&
     fn.shadowedBy === undefined &&
     fn.cIdentifier !== undefined &&
-    !hasCallerAllocatedArrayLength(context.library, fn);
+    !hasUnmarshalableParam(context, fn);
 
 const generateNamespaceFunction = (context: ModuleContext, fn: GirFunction): void => {
     if (!canEmitNamespaceFunction(context, fn)) {
@@ -77,33 +94,54 @@ 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);
-    const declaration = renderNamespaceFunctionDeclaration(context, fn, exportName, bindingName);
-    context.module.appendDeclaration(`${renderJsDoc(fn.doc)}${declaration}`);
+
+    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.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 renderNamespaceFunctionDeclaration = (
-    context: ModuleContext,
-    fn: GirFunction,
-    exportName: string,
-    bindingName: string,
-): string => {
+const matchNamespaceFinish = (context: ModuleContext, fn: GirFunction): NamespaceFinish | undefined => {
     const finishFn = matchAsyncFinish(context.library, fn, context.namespace.functions);
-    const finishCIdentifier = finishFn?.cIdentifier;
+    const cIdentifier = finishFn?.cIdentifier;
 
-    if (finishFn !== undefined && finishCIdentifier !== undefined && canEmitNamespaceFunction(context, finishFn)) {
-        const finishExport = namespaceFunctionExportName(
-            finishCIdentifier,
-            finishFn.name,
-            context.namespace.cSymbolPrefixes,
-        );
+    if (finishFn === undefined || cIdentifier === undefined || !canEmitNamespaceFunction(context, finishFn)) {
+        return undefined;
+    }
+
+    return {
+        fn: finishFn,
+        exportName: namespaceFunctionExportName(cIdentifier, finishFn.name, context.namespace.cSymbolPrefixes),
+    };
+};
+
+const renderPromisifiedNamespaceFunction = (options: NamespaceFunctionOptions, finish: NamespaceFinish): string => {
+    const { context, fn, exportName, bindingName } = options;
+    const { signature, returnType } = renderPromisifiedSignature(context, fn, finish.fn);
+    const body = renderPromisifiedBody(context, fn, finish.exportName, bindingName);
 
-        const { signature, returnType } = renderPromisifiedSignature(context, fn, finishFn);
-        const body = renderPromisifiedBody(context, fn, finishExport, bindingName);
+    return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+};
 
-        return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+const renderNamespaceFunctionDeclaration = (options: NamespaceFunctionOptions): string => {
+    const { context, fn, finish, exportName, bindingName } = options;
+
+    if (finish !== undefined) {
+        return renderPromisifiedNamespaceFunction(options, finish);
     }
 
     const signature = renderMethodSignature(context, fn);
@@ -137,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)})`;
 };