@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/store/gi/class.ts

@@ -0,0 +1,334 @@
+import { pascalCase, toCamelIdentifier } from "@gtkx/utils";
+import type { GirClass } from "../../gir/class.js";
+import type { GirFunction } from "../../gir/function.js";
+import type { ModuleContext } from "../../writer/context.js";
+import {
+    collectInheritedMethods,
+    collectInheritedPropertyTypes,
+    collectInterfaceMergeOmissions,
+    conflictRename,
+    type InheritedMethods,
+} from "../../analysis/inheritance.js";
+import { ancestorChain, type ResolvedAncestor } from "../../gir/ancestry.js";
+import { splitOptionalNamespace } from "../../gir/type-ref.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { indentMembers } from "../../writer/emit.js";
+import {
+    type Callables,
+    classConstructorMemberNames,
+    dedupeCallables,
+    generateBindings,
+    type InstanceScope,
+    instanceScope,
+    renderClassInstanceMember,
+    renderStaticHead,
+} from "./callables.js";
+import { renderClassConstructor, renderConstructorPropsInterface } from "./constructor-props.js";
+import { gtypeMemberDeclaration, renderSourceGtype } from "./gtype-binding.js";
+import { methodExportName } from "./method.js";
+import { renderPropertyDeclarations } from "./properties.js";
+import { renderResolvedPropertyAccessor, resolveAccessor, type ResolvedAccessor } from "./property-accessor.js";
+import { appendWrapperClassRegistration } from "./registration.js";
+import { renderSignalDeclarations, renderSignalMembers } from "./signal.js";
+import { renderVfuncMetadata } from "./vtable.js";
+
+type ImplementedRef = {
+    typeRef: string;
+    makerRef: string;
+    interfaceKlass: GirClass;
+    interfaceNamespace: string;
+};
+
+type MemberDeclarationsOptions = {
+    context: ModuleContext;
+    klass: GirClass;
+    className: string;
+    accessors: ResolvedAccessor[];
+    implemented: ImplementedRef[];
+};
+
+type ClassMembers = { members: string[]; accessors: ResolvedAccessor[] };
+
+type AppendInstanceMethodsOptions = {
+    context: ModuleContext;
+    methods: GirFunction[];
+    scope: InstanceScope;
+    inherited: InheritedMethods;
+    members: string[];
+    claimedNames: Set<string>;
+    className: string;
+};
+
+const generateClass = (context: ModuleContext, klass: GirClass): void => {
+    if (!klass.introspectable) {
+        return;
+    }
+
+    if (klass.name.length === 0) {
+        return;
+    }
+
+    const className = pascalCase(klass.name);
+
+    const callables: Callables = {
+        constructors: dedupeCallables(klass.constructors),
+        functions: dedupeCallables(klass.functions),
+        methods: dedupeCallables(klass.methods),
+    };
+
+    generateBindings(context, callables);
+    const parentExpression = resolveParent(context, klass);
+    const extendsClause = renderExtendsClause(context, parentExpression, callables);
+    const implemented = resolveImplementedRefs(context, klass);
+    const typeRefs = implemented.map((ref) => ref.typeRef);
+    const implementsClause = typeRefs.length === 0 ? "" : ` implements ${typeRefs.join(", ")}`;
+    const { members, accessors } = renderClassMembers(context, klass, callables, parentExpression !== undefined);
+    const body = indentMembers(members);
+
+    context.module.appendDeclaration(
+        `${renderJsDoc(klass.doc)}export class ${className}${extendsClause}${implementsClause} {\n${body}\n}`,
+    );
+
+    context.module.appendDeclaration(renderConstructorPropsInterface(context, klass, className));
+    appendMemberDeclarations({ context, klass, className, accessors, implemented });
+    appendInstallMixins(context, className, implemented);
+    appendClassRegistrations(context, klass, className);
+};
+
+const appendMemberDeclarations = (options: MemberDeclarationsOptions): void => {
+    const { context, klass, className, accessors, implemented } = options;
+
+    for (const declaration of renderPropertyDeclarations(context, klass, className, accessors)) {
+        context.module.appendDeclaration(declaration);
+    }
+
+    for (const declaration of renderSignalDeclarations(context, klass, className, false)) {
+        context.module.appendDeclaration(declaration);
+    }
+
+    appendInterfaceMerge(context, klass, className, implemented);
+};
+
+const appendInterfaceMerge = (
+    context: ModuleContext,
+    klass: GirClass,
+    className: string,
+    implemented: ImplementedRef[],
+): void => {
+    if (implemented.length === 0) {
+        return;
+    }
+
+    const mergeRefs = implemented.map((ref) => interfaceMergeRef(context, klass, ref));
+    context.module.appendDeclaration(`export interface ${className} extends ${mergeRefs.join(", ")} {}`);
+};
+
+const renderClassMembers = (
+    context: ModuleContext,
+    klass: GirClass,
+    callables: Callables,
+    hasParent: boolean,
+): ClassMembers => {
+    const className = pascalCase(klass.name);
+    const members: string[] = [gtypeMemberDeclaration(context)];
+    const constructorBlock = renderClassConstructor(context, klass, className, hasParent);
+
+    if (constructorBlock !== undefined) {
+        members.push(constructorBlock);
+    }
+
+    const claimedNames: Set<string> = new Set();
+    members.push(...renderStaticHead(context, callables, className));
+    const inherited = collectInheritedMethods(context, klass);
+    const scope = instanceScope(className, callables);
+
+    appendInstanceMethods({
+        context,
+        methods: callables.methods,
+        scope,
+        inherited,
+        members,
+        claimedNames,
+        className,
+    });
+
+    const inheritedPropertyTypes = collectInheritedPropertyTypes(context, klass);
+    const accessors: ResolvedAccessor[] = [];
+
+    for (const property of klass.properties) {
+        const inheritedType = inheritedPropertyTypes.get(toCamelIdentifier(property.name));
+
+        const accessor = resolveAccessor({
+            context,
+            property,
+            claimedNames,
+            methodByName: scope.methodByName,
+            inheritedType,
+        });
+
+        if (accessor === undefined) {
+            continue;
+        }
+
+        accessors.push(accessor);
+        members.push(renderResolvedPropertyAccessor(context, property, accessor));
+    }
+
+    members.push(...renderSignalMembers(context, klass));
+
+    return { members, accessors };
+};
+
+const appendInstanceMethods = (options: AppendInstanceMethodsOptions): void => {
+    const { context, methods, scope, inherited, members, claimedNames, className } = options;
+
+    for (const callable of methods) {
+        const rename = conflictRename(context, callable, inherited, className);
+        const block = renderClassInstanceMember(context, callable, scope, rename);
+
+        if (block === undefined) {
+            continue;
+        }
+
+        members.push(block);
+        claimedNames.add(rename ?? methodExportName(callable));
+    }
+};
+
+const appendInstallMixins = (context: ModuleContext, className: string, implemented: ImplementedRef[]): void => {
+    if (implemented.length === 0) {
+        return;
+    }
+
+    context.addRuntimeImport("installMixins");
+    const makers = implemented.map((ref) => ref.makerRef).join(", ");
+    context.module.appendRegistration(`installMixins(${className}, [${makers}]);`);
+};
+
+const appendClassRegistrations = (context: ModuleContext, klass: GirClass, className: string): void => {
+    const gtypeExpr = renderSourceGtype(context, klass);
+
+    appendWrapperClassRegistration(context, {
+        className,
+        gtypeExpr,
+        vfuncs: renderVfuncMetadata(context, klass),
+    });
+};
+
+const addAncestorInterfaceKeys = (context: ModuleContext, ancestor: ResolvedAncestor, keys: Set<string>): void => {
+    for (const name of ancestor.klass.implements) {
+        const resolved = context.library.resolveType(ancestor.namespaceName, name);
+
+        if (resolved?.kind === "interface") {
+            keys.add(`${resolved.namespace.name}.${resolved.value.name}`);
+        }
+    }
+};
+
+const inheritedInterfaceKeys = (context: ModuleContext, klass: GirClass): Set<string> => {
+    const keys: Set<string> = new Set();
+
+    if (klass.parent === undefined) {
+        return keys;
+    }
+
+    const parent = context.library.resolveType(context.namespace.name, klass.parent);
+
+    if (parent?.kind !== "class") {
+        return keys;
+    }
+
+    for (const ancestor of ancestorChain(context.library, parent.value, parent.namespace.name)) {
+        addAncestorInterfaceKeys(context, ancestor, keys);
+    }
+
+    return keys;
+};
+
+const interfaceMergeRef = (context: ModuleContext, klass: GirClass, ref: ImplementedRef): string => {
+    const omissions = collectInterfaceMergeOmissions(context, klass, {
+        klass: ref.interfaceKlass,
+        namespaceName: ref.interfaceNamespace,
+    });
+
+    if (omissions.length === 0) {
+        return ref.typeRef;
+    }
+
+    const keys = omissions.map((name) => JSON.stringify(name)).join(" | ");
+
+    return `Omit<${ref.typeRef}, ${keys}>`;
+};
+
+const implementedRefFor = (
+    context: ModuleContext,
+    name: string,
+    inherited: Set<string>,
+): ImplementedRef | undefined => {
+    const resolved = context.library.resolveType(context.namespace.name, name);
+
+    if (resolved?.kind !== "interface") {
+        return undefined;
+    }
+
+    if (inherited.has(`${resolved.namespace.name}.${resolved.value.name}`)) {
+        return undefined;
+    }
+
+    const pascal = pascalCase(resolved.value.name);
+
+    return {
+        typeRef: context.qualify(resolved.namespace.name, pascal),
+        makerRef: context.qualify(resolved.namespace.name, `make${pascal}`),
+        interfaceKlass: resolved.value,
+        interfaceNamespace: resolved.namespace.name,
+    };
+};
+
+const resolveImplementedRefs = (context: ModuleContext, klass: GirClass): ImplementedRef[] => {
+    const inherited = inheritedInterfaceKeys(context, klass);
+    const refs: ImplementedRef[] = [];
+
+    for (const name of klass.implements) {
+        const ref = implementedRefFor(context, name, inherited);
+
+        if (ref !== undefined) {
+            refs.push(ref);
+        }
+    }
+
+    return refs;
+};
+
+const renderExtendsClause = (
+    context: ModuleContext,
+    parentExpression: string | undefined,
+    callables: Callables,
+): string => {
+    if (parentExpression === undefined) {
+        return "";
+    }
+
+    const constructorNames = classConstructorMemberNames(context, callables);
+
+    if (constructorNames.length === 0) {
+        return ` extends ${parentExpression}`;
+    }
+
+    context.addRuntimeTypeImport("StaticBase");
+    const omitted = constructorNames.map((name) => JSON.stringify(name)).join(" | ");
+
+    return ` extends (${parentExpression} as StaticBase<typeof ${parentExpression}, ${omitted}>)`;
+};
+
+const resolveParent = (context: ModuleContext, klass: GirClass): string | undefined => {
+    if (klass.parent === undefined) {
+        return undefined;
+    }
+
+    const [namespace, typeName] = splitOptionalNamespace(klass.parent);
+
+    return context.qualify(namespace ?? context.namespace.name, pascalCase(typeName));
+};
+
+export { generateClass };

package/src/store/gi/companion.ts

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

package/src/store/gi/constant.ts

@@ -0,0 +1,58 @@
+import { 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";
+
+const TRUE_VALUES: Set<string> = new Set(["true", "1"]);
+// A `gint64`/`guint64` constant is typed `bigint`, and its decimal text does not survive a double:
+// G_MAXINT64 rounds to 2^63. The literal has to carry the BigInt suffix the type promises.
+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)};`,
+    );
+};
+
+const constantLiteral = (context: ModuleContext, constant: GirConstant): string => {
+    if (hasPrimitiveCategory(context, constant.type, "string")) {
+        return sourceStringLiteral(constant.value);
+    }
+
+    if (hasPrimitiveCategory(context, constant.type, "boolean")) {
+        return TRUE_VALUES.has(constant.value) ? "true" : "false";
+    }
+
+    return numericConstantLiteral(context, constant);
+};
+
+const numericConstantLiteral = (context: ModuleContext, constant: GirConstant): string => {
+    if (!isNumericLiteral(constant.value)) {
+        return sourceStringLiteral(constant.value);
+    }
+
+    return isBigIntConstant(context, constant.type) ? `${constant.value}n` : constant.value;
+};
+
+const isBigIntConstant = (context: ModuleContext, type: TypeId | undefined): boolean =>
+    [...BIGINT_CATEGORIES].some((category) => hasPrimitiveCategory(context, type, category));
+
+const hasPrimitiveCategory = (
+    context: ModuleContext,
+    type: TypeId | undefined,
+    category: PrimitiveCategory,
+): boolean => {
+    if (type === undefined) {
+        return false;
+    }
+
+    const resolved = context.library.typeFor(type);
+
+    return resolved?.kind === "primitive" && resolved.category === category;
+};
+
+const isNumericLiteral = (value: string): boolean => /^-?(?:\d+|\d*\.\d+)$/.test(value);
+
+export { generateConstant, constantLiteral };

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

@@ -0,0 +1,108 @@
+import { sourceStringLiteral, toCamelIdentifier, uniqBy } from "@gtkx/utils";
+import type { GirClass } from "../../gir/class.js";
+import type { ModuleContext } from "../../writer/context.js";
+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 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>";
+
+const constructablePropNames = (klass: GirClass): string[] =>
+    klass.properties.filter(isConstructableProperty).map((property) => toCamelIdentifier(property.name));
+
+const ancestorConstructablePropNames = (context: ModuleContext, klass: GirClass): Set<string> => {
+    const names: Set<string> = new Set();
+
+    for (const { klass: ancestor } of ancestorChain(context.library, klass, context.namespace.name)) {
+        if (ancestor === klass) {
+            continue;
+        }
+
+        for (const name of constructablePropNames(ancestor)) {
+            names.add(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),
+    );
+};
+
+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"));
+};
+
+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 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) => {
+        const descriptor = renderDescriptor(context, property.type, property.transferOwnership);
+
+        return `${sourceStringLiteral(property.name)}: [${descriptor}, ${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);
+};
+
+export { renderConstructorPropsInterface, renderClassConstructor };

package/src/store/gi/enum.ts

@@ -0,0 +1,64 @@
+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";
+
+const generateEnum = (context: ModuleContext, enumeration: GirEnum): void => {
+    if (!enumeration.introspectable) {
+        return;
+    }
+
+    const name = enumeration.name;
+    const members = enumeration.members.map((member) => ({ ...member, key: enumMemberKey(member.name) }));
+
+    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;`);
+
+        context.module.appendDeclaration(
+            `export const ${name}: ErrorDomain<{ ${typeFields} }> = ` +
+            `createErrorDomain(${quarkExpression}, { ${memberEntries.join(", ")} });`,
+        );
+
+        return;
+    }
+
+    if (members.some((member) => member.doc !== undefined)) {
+        const memberBlocks = members.map((member) => `${renderJsDoc(member.doc)}${member.key} = ${member.value},`);
+
+        context.module.appendDeclaration(
+            `${renderJsDoc(enumeration.doc)}export enum ${name} {\n${indent(memberBlocks.join("\n"), 1)}\n}`,
+        );
+
+        return;
+    }
+
+    const memberDeclarations = members.map((member) => `${member.key} = ${member.value}`);
+
+    context.module.appendDeclaration(
+        `${renderJsDoc(enumeration.doc)}export enum ${name} { ${memberDeclarations.join(", ")} }`,
+    );
+};
+
+const enumMemberKey = (name: string): string => {
+    const upper = name.toUpperCase().replaceAll("-", "_");
+
+    return /^\d/.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)})`;
+};
+
+export { generateEnum, enumMemberKey };