@gtkx/codegen 0.21.0 → 1.0.0-rc.1

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

@@ -0,0 +1,82 @@
+import { sourceStringLiteral, toCamelIdentifier, uniqBy } from "@gtkx/utils";
+import { renderDescriptor } from "../../analysis/descriptor-render.js";
+import { collectInterfaceProperties } from "../../analysis/inheritance.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+import { ancestorChain } from "../../gir/ancestry.js";
+import type { GirClass } from "../../gir/class.js";
+import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderBlock, renderBraced, renderBracedOrEmpty } from "../../writer/emit.js";
+import { parentCompanionRef } from "./companion.js";
+
+const ancestorConstructablePropNames = (context: ModuleContext, klass: GirClass): Set<string> => {
+    const names = new Set<string>();
+    for (const { klass: ancestor } of ancestorChain(context.library, klass, context.namespace.name)) {
+        if (ancestor === klass) continue;
+        for (const property of ancestor.properties) {
+            if (isConstructableProperty(property)) names.add(toCamelIdentifier(property.name));
+        }
+    }
+    return names;
+};
+
+const collectConstructableProps = (context: ModuleContext, klass: GirClass): GirProperty[] => {
+    const inherited = ancestorConstructablePropNames(context, klass);
+    return uniqBy(
+        [...klass.properties, ...collectInterfaceProperties(context, klass).map((entry) => entry.property)]
+            .filter(isConstructableProperty)
+            .filter((property) => !inherited.has(toCamelIdentifier(property.name))),
+        (property) => toCamelIdentifier(property.name),
+    );
+};
+
+export const renderConstructorPropsInterface = (context: ModuleContext, klass: GirClass, className: string): string => {
+    const parentRef = parentCompanionRef(context, klass, "ConstructorProps");
+    const extendsClause = parentRef === undefined ? "" : ` extends ${parentRef}`;
+    const lines = collectConstructableProps(context, klass).map(
+        (property) =>
+            `${toCamelIdentifier(property.name)}?: ${renderTsType(context, property.type, true)} | undefined;`,
+    );
+    return renderBracedOrEmpty(`export interface ${className}ConstructorProps${extendsClause}`, lines.join("\n"));
+};
+
+export const renderClassConstructor = (
+    context: ModuleContext,
+    klass: GirClass,
+    className: string,
+    hasParent: boolean,
+): string | undefined => {
+    if (!hasParent) return renderRootConstructor(context);
+    const props = collectConstructableProps(context, klass);
+    if (props.length === 0) return undefined;
+    return renderTranslatingConstructor(context, props, className);
+};
+
+const PROPS_RECORD = "Record<string, unknown>";
+
+const renderRootConstructor = (context: ModuleContext): string => {
+    context.addRuntimeImport("getInstanceType");
+    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");
+    return renderBlock(`constructor(props: ${PROPS_RECORD} = {})`, 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 entries = props.map(
+        (property) =>
+            `${sourceStringLiteral(property.name)}: [${renderDescriptor(context, property.type, property.transferOwnership)}, ${toCamelIdentifier(property.name)}],`,
+    );
+    const recordLiteral = renderBraced(entries.join("\n"));
+    const lines = [`const props: ${PROPS_RECORD} = ${recordLiteral};`, "super({ ...props, ...rest });"];
+    const body = lines.join("\n");
+    return renderBlock(`constructor(${pattern}: ${className}ConstructorProps = {})`, body);
+};

package/src/store/gi/enum.ts

@@ -0,0 +1,49 @@
+import { sourceStringLiteral } from "@gtkx/utils";
+import type { GirEnum } from "../../gir/enum.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { indent } from "../../writer/emit.js";
+
+export const generateEnum = (context: ModuleContext, enumeration: GirEnum): void => {
+    if (!enumeration.introspectable) return;
+    const name = enumeration.name;
+    const memberKeys = enumeration.members.map((member) => enumMemberKey(member.name));
+    if (enumeration.errorDomain !== undefined) {
+        const memberEntries = enumeration.members.map((member, index) => `${memberKeys[index]}: ${member.value}`);
+        const typeFields = memberKeys.map((key) => `${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;`);
+        context.module.appendDeclaration(
+            `export const ${name}: ErrorDomain<{ ${typeFields} }> = createErrorDomain(${quarkExpression}, { ${memberEntries.join(", ")} });`,
+        );
+        return;
+    }
+    if (enumeration.members.some((member) => member.doc !== undefined)) {
+        const memberBlocks = enumeration.members.map(
+            (member, index) => `${renderJsDoc(member.doc)}${memberKeys[index]} = ${member.value},`,
+        );
+        context.module.appendDeclaration(
+            `${renderJsDoc(enumeration.doc)}export enum ${name} {\n${indent(memberBlocks.join("\n"), 1)}\n}`,
+        );
+        return;
+    }
+    const memberDeclarations = enumeration.members.map((member, index) => `${memberKeys[index]} = ${member.value}`);
+    context.module.appendDeclaration(
+        `${renderJsDoc(enumeration.doc)}export enum ${name} { ${memberDeclarations.join(", ")} }`,
+    );
+};
+
+export const enumMemberKey = (name: string): string => {
+    const upper = name.toUpperCase().replaceAll("-", "_");
+    return /^[0-9]/.test(upper) ? `_${upper}` : upper;
+};
+
+const renderQuarkExpression = (context: ModuleContext, errorDomain: string): string => {
+    if (context.namespace.name === "GLib") {
+        return `() => quarkFromString(${sourceStringLiteral(errorDomain)})`;
+    }
+    const alias = context.addCrossNamespaceImport("GLib");
+    return `() => ${alias}.quarkFromString(${sourceStringLiteral(errorDomain)})`;
+};

package/src/store/gi/function.ts

@@ -0,0 +1,107 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import { tFn } from "../../analysis/descriptor.js";
+import { hasCallerAllocatedArrayLength } from "../../analysis/param-structure.js";
+import type { GirFunction } from "../../gir/function.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { arrayLiteral, renderBlock } from "../../writer/emit.js";
+import { matchAsyncFinish } from "./async.js";
+import { callableReferencesClassStruct } from "./class-struct-record.js";
+import {
+    planCallArgs,
+    renderMethodBody,
+    renderMethodReturnType,
+    renderMethodSignature,
+    renderPromisifiedBody,
+    renderPromisifiedSignature,
+    renderReturnDescriptor,
+} from "./method.js";
+
+export const renderFnExpression = (context: ModuleContext, fn: GirFunction): string | undefined => {
+    if (fn.cIdentifier === undefined) return undefined;
+    const library = context.namespace.sharedLibrary;
+    if (library === undefined) return undefined;
+    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, throws: fn.throws });
+};
+
+const namespaceFunctionEmittable = (context: ModuleContext, fn: GirFunction): boolean =>
+    fn.introspectable &&
+    fn.shadowedBy === undefined &&
+    fn.cIdentifier !== undefined &&
+    !callableReferencesClassStruct(context, fn) &&
+    !hasCallerAllocatedArrayLength(context.library, fn);
+
+export const generateNamespaceFunction = (context: ModuleContext, fn: GirFunction): void => {
+    if (!namespaceFunctionEmittable(context, fn)) return;
+    const expression = renderFnExpression(context, fn);
+    if (expression === undefined) return;
+    const cIdentifier = fn.cIdentifier;
+    if (cIdentifier === undefined) 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}`);
+};
+
+const renderNamespaceFunctionDeclaration = (
+    context: ModuleContext,
+    fn: GirFunction,
+    exportName: string,
+    bindingName: string,
+): string => {
+    const finishFn = matchAsyncFinish(context.library, fn, context.namespace.functions);
+    const finishCIdentifier = finishFn?.cIdentifier;
+    if (finishFn !== undefined && finishCIdentifier !== undefined && namespaceFunctionEmittable(context, finishFn)) {
+        const finishExport = namespaceFunctionExportName(
+            finishCIdentifier,
+            finishFn.name,
+            context.namespace.cSymbolPrefixes,
+        );
+        const { signature, returnType } = renderPromisifiedSignature(context, fn, finishFn);
+        const body = renderPromisifiedBody(context, fn, finishExport, bindingName);
+        return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+    }
+    const signature = renderMethodSignature(context, fn);
+    const returnType = renderMethodReturnType(context, fn);
+    const body = renderMethodBody(context, fn, { bindingExpression: bindingName });
+    return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+};
+
+export const namespaceFunctionExportName = (cIdentifier: string, girName: string, symbolPrefixes: string[]): string => {
+    if (girName.length > 0) {
+        return toCamelIdentifier(girName);
+    }
+    const stripped = stripLongestPrefix(cIdentifier, symbolPrefixes);
+    return toCamelIdentifier(stripped);
+};
+
+const stripLongestPrefix = (input: string, prefixes: string[]): string => {
+    let best = "";
+    for (const prefix of prefixes) {
+        const candidate = `${prefix}_`;
+        if (input.startsWith(candidate) && candidate.length > best.length) {
+            best = candidate;
+        }
+    }
+    return best.length === 0 ? input : input.slice(best.length);
+};
+
+export const generateNamespaceBootstrap = (context: ModuleContext, namespace: GirNamespace): void => {
+    for (const fn of namespace.functions) {
+        if (fn.parameters.length > 0) continue;
+        if (!fn.introspectable || fn.shadowedBy !== undefined || fn.cIdentifier === undefined) continue;
+        const exportName = namespaceFunctionExportName(fn.cIdentifier, fn.name, context.namespace.cSymbolPrefixes);
+        if (fn.name === "init") {
+            context.module.appendRegistration(`${exportName}();`);
+        } else if (fn.name === "finalize") {
+            context.addRuntimeImport("onExit");
+            context.module.appendRegistration(`onExit(${exportName});`);
+        }
+    }
+};

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

@@ -0,0 +1,33 @@
+import { sourceStringLiteral } from "@gtkx/utils";
+import { PRIMITIVE_TS_TYPE } from "../../gir/primitives.js";
+import type { ModuleContext } from "../../writer/context.js";
+
+export const gtypeTsType = (context: ModuleContext): string =>
+    context.namespace.name === "GObject" ? "Type" : PRIMITIVE_TS_TYPE.gtype;
+
+export const gtypeMemberDeclaration = (context: ModuleContext): string => `declare __type__: ${gtypeTsType(context)};`;
+
+const renderGtypeExpression = (
+    context: ModuleContext,
+    getType: string,
+    typeName: string | undefined,
+): string | undefined => {
+    if (getType === "intern") {
+        if (typeName === undefined) return undefined;
+        if (context.namespace.name !== "GObject") context.addRuntimeImport("typeFromName");
+        return `typeFromName(${sourceStringLiteral(typeName)})`;
+    }
+    context.addRuntimeImport("resolveType");
+    const lib = context.namespace.sharedLibrary ?? "";
+    return `resolveType(${sourceStringLiteral(lib)}, ${sourceStringLiteral(getType)})`;
+};
+
+type TypeSource = {
+    glibGetType: string | undefined;
+    glibTypeName: string | undefined;
+};
+
+export const gtypeExprFor = (context: ModuleContext, source: TypeSource): string | undefined =>
+    source.glibGetType === undefined
+        ? undefined
+        : renderGtypeExpression(context, source.glibGetType, source.glibTypeName);

package/src/store/gi/interface.ts

@@ -0,0 +1,157 @@
+import { toPascalCase } from "@gtkx/utils";
+import { reservedSignalMemberRename, resolvePrerequisiteReference } from "../../analysis/inheritance.js";
+import type { GirClass } from "../../gir/class.js";
+import type { GirFunction } from "../../gir/function.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { renderBlock, renderBracedOrEmpty } from "../../writer/emit.js";
+import {
+    type Callables,
+    dedupeCallables,
+    generateBindings,
+    indexMethodsByName,
+    renderClassInstanceMember,
+    renderInstanceMethodSignature,
+    renderStaticHead,
+} from "./callables.js";
+import { gtypeExprFor } from "./gtype-binding.js";
+import { methodExportName } from "./method.js";
+import {
+    type PropertyAccessorArgs,
+    renderPropertyAccessor,
+    renderPropertyAccessorSignature,
+} from "./property-accessor.js";
+import { appendInterfaceRegistration } from "./registration.js";
+import { renderSignalDeclarations, renderSignalMembers } from "./signal.js";
+import { renderVfuncMetadata } from "./vtable.js";
+
+export const generateInterface = (context: ModuleContext, iface: GirClass): void => {
+    if (!iface.introspectable) return;
+    if (iface.name.length === 0) return;
+    const className = toPascalCase(iface.name);
+    const callables: Callables = {
+        constructors: dedupeCallables(iface.constructors),
+        functions: dedupeCallables(iface.functions),
+        methods: dedupeCallables(iface.methods),
+    };
+    generateBindings(context, callables);
+
+    const gtypeExpr = gtypeExprFor(context, iface);
+
+    context.module.appendDeclaration(renderInterfaceType(context, iface, className, callables));
+    context.module.appendDeclaration(renderInterfaceClass(context, className, callables, gtypeExpr));
+    for (const declaration of renderSignalDeclarations(context, iface, className, true)) {
+        context.module.appendDeclaration(declaration);
+    }
+    context.module.appendDeclaration(renderInterfaceMaker(context, iface, className, callables));
+
+    appendInterfaceRegistration(context, {
+        className,
+        makerName: makerName(className),
+        gtypeExpr,
+        vfuncs: renderVfuncMetadata(context, iface),
+    });
+};
+
+const makerName = (className: string): string => `make${className}`;
+
+const interfaceTypeExtends = (context: ModuleContext, iface: GirClass): string => {
+    const refs = iface.prerequisites
+        .map((name) => resolvePrerequisiteReference(context, name))
+        .filter((entry): entry is string => entry !== undefined);
+    if (refs.length > 0) return refs.join(", ");
+    return context.qualify("GObject", "Object");
+};
+
+const renderInterfaceType = (
+    context: ModuleContext,
+    iface: GirClass,
+    className: string,
+    callables: Callables,
+): string => {
+    const members = renderInterfaceTypeMembers(context, iface, callables);
+    return `${renderJsDoc(iface.doc)}${renderBracedOrEmpty(
+        `export interface ${className} extends ${interfaceTypeExtends(context, iface)}`,
+        members.join("\n"),
+    )}`;
+};
+
+type InterfaceMemberRenderers = {
+    renderMethod: (
+        context: ModuleContext,
+        callable: GirFunction,
+        methodByName: Map<string, GirFunction>,
+        nameOverride?: string,
+    ) => string | undefined;
+    renderProperty: (args: PropertyAccessorArgs) => string | undefined;
+};
+
+const renderInterfaceMembers = (
+    context: ModuleContext,
+    iface: GirClass,
+    callables: Callables,
+    renderers: InterfaceMemberRenderers,
+): string[] => {
+    const className = toPascalCase(iface.name);
+    const members: string[] = [];
+    const claimedNames = new Set<string>();
+    const methodByName = indexMethodsByName(callables.methods);
+    for (const callable of callables.methods) {
+        const rename = reservedSignalMemberRename(className, callable);
+        const block = renderers.renderMethod(context, callable, methodByName, rename);
+        if (block === undefined) continue;
+        members.push(block);
+        claimedNames.add(rename ?? methodExportName(callable));
+    }
+    for (const property of iface.properties) {
+        const block = renderers.renderProperty({ context, property, claimedNames, methodByName });
+        if (block !== undefined) members.push(block);
+    }
+    return members;
+};
+
+const renderInterfaceTypeMembers = (context: ModuleContext, iface: GirClass, callables: Callables): string[] =>
+    renderInterfaceMembers(context, iface, callables, {
+        renderMethod: renderInstanceMethodSignature,
+        renderProperty: renderPropertyAccessorSignature,
+    });
+
+const renderInterfaceClass = (
+    context: ModuleContext,
+    className: string,
+    callables: Callables,
+    gtypeExpr: string | undefined,
+): string => {
+    const members: string[] = [];
+    if (gtypeExpr !== undefined) members.push(renderInterfaceHasInstance(context, className, gtypeExpr));
+    members.push(...renderStaticHead(context, callables, className));
+    return renderBracedOrEmpty(`export abstract class ${className}`, members.join("\n\n"));
+};
+
+const renderInterfaceHasInstance = (context: ModuleContext, className: string, gtypeExpr: string): string => {
+    context.addRuntimeImport("valueIsA");
+    return renderBlock(
+        `static [Symbol.hasInstance](value: unknown): value is ${className}`,
+        `return valueIsA(value, ${gtypeExpr});`,
+    );
+};
+
+const renderInterfaceMaker = (
+    context: ModuleContext,
+    iface: GirClass,
+    className: string,
+    callables: Callables,
+): string => {
+    context.addRuntimeTypeImport("Mixin");
+    const members = renderInterfaceInstanceMembers(context, iface, callables);
+    const classExpression = renderBracedOrEmpty("class extends Base", members.join("\n\n"));
+    return `export const ${makerName(className)}: Mixin = (Base) =>\n${classExpression};`;
+};
+
+const renderInterfaceInstanceMembers = (context: ModuleContext, iface: GirClass, callables: Callables): string[] => [
+    ...renderInterfaceMembers(context, iface, callables, {
+        renderMethod: renderClassInstanceMember,
+        renderProperty: renderPropertyAccessor,
+    }),
+    ...renderSignalMembers(context, iface),
+];

package/src/store/gi/item-comparators.ts

@@ -0,0 +1,90 @@
+import { tObject } from "../../analysis/descriptor.js";
+import { inputParameters, parameterIdentifier } from "../../analysis/param-structure.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+import { resolveInterface } from "../../gir/ancestry.js";
+import { callbackAsFunction, type GirCallback } from "../../gir/callback.js";
+import type { GirFunction } from "../../gir/function.js";
+import type { GirParameter } from "../../gir/parameter.js";
+import type { TypeId } from "../../gir/type-id.js";
+import type { ModuleContext } from "../../writer/context.js";
+
+const COMPARATOR_CALLBACK_TYPES = new Set([
+    "GLib.CompareFunc",
+    "GLib.CompareDataFunc",
+    "GLib.EqualFunc",
+    "GLib.EqualFuncFull",
+]);
+
+const OBJECT_ITEM_COMPARATOR_OWNERS = new Set(["Gtk.CustomSorter"]);
+
+const qualifiedName = (context: ModuleContext, ref: TypeId): string | undefined => {
+    const name = context.library.nameOf(ref);
+    return name === undefined ? undefined : `${name.namespaceName}.${name.typeName}`;
+};
+
+const implementsListModel = (context: ModuleContext, ref: TypeId): boolean => {
+    const resolved = context.library.typeOf(ref);
+    if (resolved?.kind !== "class") return false;
+    return resolved.value.implements.some((interfaceName) => {
+        const iface = resolveInterface(context.library, resolved.namespace.name, interfaceName);
+        return iface?.namespaceName === "Gio" && iface.klass.name === "ListModel";
+    });
+};
+
+const comparesObjectItems = (context: ModuleContext, fn: GirFunction): boolean => {
+    const ownerRef = fn.instance?.type ?? fn.returnValue.type;
+    if (ownerRef === undefined) return false;
+    const owner = qualifiedName(context, ownerRef);
+    if (owner !== undefined && OBJECT_ITEM_COMPARATOR_OWNERS.has(owner)) return true;
+    return implementsListModel(context, ownerRef);
+};
+
+const isItemPointer = (context: ModuleContext, ref: TypeId | undefined): boolean => {
+    if (ref === undefined) return false;
+    const resolved = context.library.typeOf(ref);
+    return resolved?.kind === "primitive" && resolved.category === "pointer";
+};
+
+const itemComparatorCallback = (
+    context: ModuleContext,
+    fn: GirFunction,
+    parameter: GirParameter,
+): GirCallback | undefined => {
+    if (parameter.type === undefined) return undefined;
+    const resolved = context.library.typeOf(parameter.type);
+    if (resolved?.kind !== "callback") return undefined;
+    const name = qualifiedName(context, parameter.type);
+    if (name === undefined || !COMPARATOR_CALLBACK_TYPES.has(name)) return undefined;
+    return comparesObjectItems(context, fn) ? resolved.value : undefined;
+};
+
+export const itemComparatorArgDescriptors = (
+    context: ModuleContext,
+    fn: GirFunction,
+    parameter: GirParameter,
+): Map<number, string> | undefined => {
+    const callback = itemComparatorCallback(context, fn, parameter);
+    if (callback === undefined) return undefined;
+    const overrides = new Map<number, string>();
+    for (const { parameter: item, index } of inputParameters(context.library, callbackAsFunction(callback))) {
+        if (isItemPointer(context, item.type)) overrides.set(index, tObject("borrowed"));
+    }
+    return overrides.size > 0 ? overrides : undefined;
+};
+
+export const itemComparatorTsType = (
+    context: ModuleContext,
+    fn: GirFunction,
+    parameter: GirParameter,
+): string | undefined => {
+    const callback = itemComparatorCallback(context, fn, parameter);
+    if (callback === undefined) return undefined;
+    const itemType = `${context.qualify("GObject", "Object")} | null`;
+    const args = inputParameters(context.library, callbackAsFunction(callback)).map(({ parameter: item, index }) => {
+        const tsType = isItemPointer(context, item.type) ? itemType : renderTsType(context, item.type, item.nullable);
+        return `${parameterIdentifier(item, index)}: ${tsType}`;
+    });
+    const returnType = renderTsType(context, callback.returnValue.type, callback.returnValue.nullable);
+    const fnType = `(${args.join(", ")}) => ${returnType}`;
+    return parameter.nullable ? `(${fnType}) | null` : fnType;
+};