@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/runner.ts

@@ -1,16 +1,14 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import type { GiStoreOptions } from "./store/gi-store.js";
-import type { JsxStoreOptions } from "./store/jsx-store.js";
+import type { ModuleExport } from "./react/element-config.js";
 import type { OmittedProps } from "./store/jsx/omitted-props.js";
+import type { StoreOptions } from "./store/store-fs.js";
 import { checkModules } from "./compile.js";
 import { isGiStoreFresh } from "./fingerprint.js";
 import { runGiCodegen } from "./gi.js";
 import { Library } from "./gir/library.js";
 import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
 
-type ModuleExport = { module: string; export: string };
-
 type GlCodegenOptions = {
     registryPath: string;
     overrideExports: Set<string>;
@@ -18,58 +16,71 @@ type GlCodegenOptions = {
     resolveFrom: string;
 };
 
+/** What to generate and where to write it. */
 type CodegenRunnerOptions = {
-    libraries?: string[];
-    girPath?: string[];
-    gi?: GiStoreOptions;
-    jsx?: JsxStoreOptions | undefined;
+    /** GIR library identifiers such as `"Gtk-4.0"`; a `"*"` selection must be expanded before it gets here. */
+    libraries: string[];
+    /** Directories to search for `.gir` files. */
+    girPath: string[];
+    /** Where to write and link the `@gtkx/gi` store. */
+    gi: StoreOptions;
+    /** Where to write and link the `@gtkx/jsx` store; omit to generate the gi store alone. */
+    jsx?: StoreOptions | undefined;
+    /** Subexport names of the installed `@gtkx/react`, whose element config shapes the jsx store. */
     reactSubexports?: string[];
+    /** Component wrappers the project layers over the built-ins, keyed by GLib type name. */
     userComponents?: Record<string, ModuleExport>;
+    /** GLib type names whose GObject their parent container creates, added to the framework's own. */
     userLazyElements?: string[];
+    /** Base props interfaces the project's elements extend, keyed by GLib type name. */
     userProps?: Record<string, ModuleExport>;
-    userOmitProps?: OmittedProps;
-    gl?: GlCodegenOptions;
-    force?: boolean;
+    /** Props the project drops from the generated element props, keyed by GLib type name. */
+    userOmittedProps?: OmittedProps;
+    /** Regenerates both stores even when their fingerprints are fresh. */
+    isForced?: boolean;
 };
 
+/** What a `runCodegen` run produced. */
 type CodegenRunnerResult = {
-    regenerated: boolean;
+    /** Whether either store was rewritten; false means both were already fresh. */
+    isRegenerated: boolean;
+    /** How many namespaces the gi store was written with, zero when it was already fresh. */
     namespaces: number;
+    /** How many JSX elements the jsx store binds, zero when no jsx store was requested. */
     intrinsicElements: number;
+    /** Wall-clock duration of the run, in milliseconds. */
     duration: number;
-    gl?: GlGenerationReport | undefined;
 };
 
 type StoreResult = {
-    regenerated: boolean;
+    isRegenerated: boolean;
     namespaces: number;
     intrinsicElements: number;
 };
 
 /**
- * Runs the `@gtkx` code generators, producing the `@gtkx/gi`, `@gtkx/jsx`, and `@gtkx/gl` bindings from the
- * configured GObject-introspection libraries and OpenGL registry. The gi store is regenerated only when its
- * fingerprint is stale unless `options.force` is set, then the jsx store is regenerated when the gi store or
- * the React element config changed; the OpenGL modules are regenerated whenever `options.gl` is provided.
+ * Writes and links a project's `@gtkx/gi` and `@gtkx/jsx` stores from the given GObject-Introspection
+ * libraries. The gi store is rewritten only when its GIR inputs changed, and the jsx store only when the gi
+ * store or the React element config changed, unless `options.isForced` is set. Pass the spread of
+ * `resolveStore(projectRoot)` for everything but `libraries` and `girPath`.
  *
- * @param options - What to generate and where to write it.
+ * @param options What to generate and where to write it.
  * @returns A summary of what was regenerated and how long the run took.
+ * @throws If `girPath` is empty, which would otherwise generate nothing and report success.
  */
 const runCodegen = async (options: CodegenRunnerOptions): Promise<CodegenRunnerResult> => {
     const start = Date.now();
-    const gl = options.gl === undefined ? undefined : emitGlModules(options.gl);
     const store = await emitStores(options);
 
     return {
-        regenerated: store.regenerated,
+        isRegenerated: store.isRegenerated,
         namespaces: store.namespaces,
         intrinsicElements: store.intrinsicElements,
         duration: Date.now() - start,
-        gl,
     };
 };
 
-const emitGlModules = (options: GlCodegenOptions): GlGenerationReport => {
+const runGlCodegen = (options: GlCodegenOptions): GlGenerationReport => {
     const { files, report } = generateGlModules({
         registryPath: options.registryPath,
         overrideExports: options.overrideExports,
@@ -97,24 +108,24 @@ const jsxUserOptions = (
     userComponents: Record<string, ModuleExport>;
     userLazyElements: string[];
     userProps: Record<string, ModuleExport>;
-    userOmitProps: OmittedProps;
+    userOmittedProps: OmittedProps;
 } => ({
     reactSubexports: options.reactSubexports ?? [],
     userComponents: options.userComponents ?? {},
     userLazyElements: options.userLazyElements ?? [],
     userProps: options.userProps ?? {},
-    userOmitProps: options.userOmitProps ?? {},
+    userOmittedProps: options.userOmittedProps ?? {},
 });
 
 const emitJsxStore = async (input: {
     options: CodegenRunnerOptions;
-    jsx: JsxStoreOptions;
-    gi: GiStoreOptions;
+    jsx: StoreOptions;
+    gi: StoreOptions;
     loadLibrary: () => Library;
-    giRegenerated: boolean;
+    isGiRegenerated: boolean;
     namespaces: number;
 }): Promise<StoreResult> => {
-    const { options, jsx, gi, loadLibrary, giRegenerated, namespaces } = input;
+    const { options, jsx, gi, loadLibrary, isGiRegenerated, namespaces } = input;
     const { runJsxCodegen } = await import("./jsx.js");
 
     const jsxResult = await runJsxCodegen({
@@ -122,12 +133,12 @@ const emitJsxStore = async (input: {
         jsx,
         giStoreDir: gi.storeDir,
         ...jsxUserOptions(options),
-        giRegenerated,
-        force: options.force === true,
+        isGiRegenerated,
+        isForced: options.isForced === true,
     });
 
     return {
-        regenerated: giRegenerated || jsxResult.regenerated,
+        isRegenerated: isGiRegenerated || jsxResult.isRegenerated,
         namespaces,
         intrinsicElements: jsxResult.intrinsicElementCount,
     };
@@ -135,35 +146,35 @@ const emitJsxStore = async (input: {
 
 const emitStoresWithConfig = async (config: {
     options: CodegenRunnerOptions;
-    gi: GiStoreOptions;
-    jsx: JsxStoreOptions | undefined;
+    gi: StoreOptions;
+    jsx: StoreOptions | undefined;
     libraries: string[];
     girPath: string[];
 }): Promise<StoreResult> => {
     const { options, gi, jsx, libraries, girPath } = config;
     let library: Library | undefined;
     const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath));
-    const isGiRegenerated = options.force === true || !isGiStoreFresh(gi.storeDir, libraries, girPath);
+    const isGiRegenerated = options.isForced === true || !isGiStoreFresh(gi.storeDir, libraries, girPath);
 
     const namespaces = isGiRegenerated
         ? runGiCodegen(loadLibrary(), { gi, libraries, girPath })
         : 0;
 
     if (jsx === undefined) {
-        return { regenerated: isGiRegenerated, namespaces, intrinsicElements: 0 };
+        return { isRegenerated: isGiRegenerated, namespaces, intrinsicElements: 0 };
     }
 
-    return emitJsxStore({ options, jsx, gi, loadLibrary, giRegenerated: isGiRegenerated, namespaces });
+    return emitJsxStore({ options, jsx, gi, loadLibrary, isGiRegenerated, namespaces });
 };
 
 const emitStores = async (options: CodegenRunnerOptions): Promise<StoreResult> => {
     const { gi, jsx, libraries, girPath } = options;
 
-    if (gi === undefined || libraries === undefined || girPath === undefined) {
-        return { regenerated: false, namespaces: 0, intrinsicElements: 0 };
+    if (girPath.length === 0) {
+        throw new Error("codegen needs at least one GIR search path; pass the result of resolveGirPath");
     }
 
     return emitStoresWithConfig({ options, gi, jsx, libraries, girPath });
 };
 
-export { runCodegen, type GlCodegenOptions, type CodegenRunnerOptions, type CodegenRunnerResult };
+export { runCodegen, runGlCodegen, type CodegenRunnerOptions, type CodegenRunnerResult };

package/src/store/compile-store.ts

@@ -6,8 +6,7 @@ type CompileStoreParams = {
     storeDir: string;
     files: SourceModule[];
     packageName: string;
-    /** Declare `virtual:gtkx-config` for the typecheck, needed when it follows imports into `@gtkx/react` source. */
-    configEnv?: boolean;
+    requiresEnvReference?: boolean;
 };
 
 const EMIT_OPTIONS = {
@@ -32,14 +31,14 @@ const writeEnvReference = (storeDir: string): (() => void) => {
 const compileStore = (params: CompileStoreParams): void => {
     const fileNames = params.files.map((file) => file.fileName);
 
-    const removeEnvReference = params.configEnv === true
+    const removeEnvReference = params.requiresEnvReference === true
         ? writeEnvReference(params.storeDir)
         : (): void => undefined;
 
     try {
         compileProject({
             projectDir: params.storeDir,
-            fileNames: params.configEnv === true ? [ENV_REFERENCE_FILE, ...fileNames] : fileNames,
+            fileNames: params.requiresEnvReference === true ? [ENV_REFERENCE_FILE, ...fileNames] : fileNames,
             compilerOptions: EMIT_OPTIONS,
             label: `the generated ${params.packageName} store`,
         });
@@ -52,4 +51,4 @@ const compileStore = (params: CompileStoreParams): void => {
     }
 };
 
-export { compileStore, type CompileStoreParams };
+export { compileStore };

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

@@ -0,0 +1,102 @@
+import type { GirFunction } from "../../gir/function.js";
+import type { GirCallable } from "../../gir/parameter.js";
+import type { ModuleContext } from "../../writer/context.js";
+import type { JsDocSpec } from "../../writer/doc.js";
+import { shouldOmitPrimaryReturn } from "../../analysis/descriptor-render.js";
+import { nulTerminatedByteParams } from "../../analysis/nul-terminated-bytes.js";
+import {
+    documentedParameters,
+    type InputParameter,
+    parameterIdentifier,
+    renamesWithInstance,
+} from "../../analysis/param-structure.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { annotationSpec, THROWS_TEXT } from "./doc-spec.js";
+import { isCallbackParameter, returnedOutParameters } from "./method.js";
+
+type CallableDocOptions = {
+    finishFn?: GirFunction | undefined;
+    renames?: Map<string, string> | undefined;
+};
+
+const WHITESPACE_RUN_PATTERN = /\s+/g;
+
+const nulTerminatedNote = (context: ModuleContext, callable: GirCallable): string | undefined => {
+    const parameters = nulTerminatedByteParams(context.library, callable);
+
+    if (parameters.length === 0) {
+        return undefined;
+    }
+
+    const names = parameters.map((parameter) => `\`${parameter.name}\``).join(", ");
+
+    return [
+        `The C function reads ${names} as a NUL-terminated string, so it stops at the`,
+        "first zero byte and drops every byte after it without reporting an error.",
+        "Pass binary data through a `GLib.Bytes` route such as `GLib.Variant.newFromBytes`",
+        "instead.",
+    ].join("\n");
+};
+
+const tupleBullet = (name: string, doc: string | undefined): string | undefined => {
+    const text = (doc ?? "").replaceAll(WHITESPACE_RUN_PATTERN, " ").trim();
+
+    return text.length === 0 ? undefined : `- \`${name}\`: ${text}`;
+};
+
+const tupleReturnsText = (primary: string | undefined, outs: InputParameter[]): string | undefined => {
+    const bullets = [
+        tupleBullet("result", primary),
+        ...outs.map(({ parameter, index }) => tupleBullet(parameterIdentifier(parameter, index), parameter.doc)),
+    ].filter((bullet) => bullet !== undefined);
+
+    return bullets.length === 0 ? undefined : `Tuple of:\n\n${bullets.join("\n")}`;
+};
+
+const returnsText = (context: ModuleContext, fn: GirFunction): string | undefined => {
+    const outs = returnedOutParameters(context, fn);
+    const isPrimaryOmitted = shouldOmitPrimaryReturn(context.library, fn.returnValue);
+    const primary = isPrimaryOmitted ? undefined : fn.returnValue.doc;
+
+    if (outs.length === 0) {
+        return primary;
+    }
+
+    if (isPrimaryOmitted && outs.length === 1) {
+        return outs[0]?.parameter.doc;
+    }
+
+    return tupleReturnsText(primary, outs);
+};
+
+const docIdentifiers = (callable: GirFunction, renames: Map<string, string> | undefined): Map<string, string> => {
+    const identifiers = renamesWithInstance(callable.parameters, callable.instance);
+    const overrides = renames ?? new Map<string, string>();
+
+    for (const [girName, declaredName] of overrides) {
+        identifiers.set(girName, declaredName);
+    }
+
+    return identifiers;
+};
+
+const canCallableThrow = (callable: GirFunction, finishFn: GirFunction | undefined): boolean =>
+    callable.throws || finishFn?.throws === true;
+
+const callableSpec = (context: ModuleContext, callable: GirFunction, options: CallableDocOptions): JsDocSpec => ({
+    ...annotationSpec(callable.annotations),
+    identifiers: docIdentifiers(callable, options.renames),
+    params: documentedParameters(
+        context.library,
+        callable,
+        (parameter) => options.finishFn !== undefined && isCallbackParameter(context, parameter),
+        options.renames,
+    ),
+    returns: returnsText(context, options.finishFn ?? callable),
+    throws: canCallableThrow(callable, options.finishFn) ? THROWS_TEXT : undefined,
+});
+
+const callableDoc = (context: ModuleContext, callable: GirFunction, options: CallableDocOptions = {}): string =>
+    renderJsDoc(callable.doc, nulTerminatedNote(context, callable), callableSpec(context, callable, options));
+
+export { callableDoc, callableSpec };

package/src/store/gi/callables.ts

@@ -1,10 +1,11 @@
 import { camelCase, toCamelIdentifier, uniqBy } from "@gtkx/utils";
 import type { GirFunction } from "../../gir/function.js";
 import type { ModuleContext } from "../../writer/context.js";
-import { hasCallerAllocatedArrayLength } from "../../analysis/param-structure.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import type { JsDocSpec } from "../../writer/doc.js";
+import { hasUnmarshalableParam } from "../../analysis/param-capability.js";
 import { renderBlock } from "../../writer/emit.js";
 import { matchAsyncFinish } from "./async.js";
+import { callableDoc, callableSpec } from "./callable-doc.js";
 import { renderFnExpression } from "./function.js";
 import { gtypeMemberDeclaration } from "./gtype-binding.js";
 import {
@@ -16,7 +17,7 @@ import {
     renderPromisifiedBody,
     renderPromisifiedSignature,
 } from "./method.js";
-import { renderRuntimeOverride } from "./runtime-override.js";
+import { renderRuntimeOverride, runtimeOverrideRenames } from "./runtime-override.js";
 
 type Callables = {
     constructors: GirFunction[];
@@ -34,7 +35,7 @@ type CallableMemberOptions = {
     resolveName: (callable: GirFunction) => string | undefined;
     isStatic: boolean;
     returnTypeOverride?: string | undefined;
-    allowRuntimeOverride?: boolean;
+    canUseRuntimeOverride?: boolean;
 };
 
 type StaticEntryOptions = {
@@ -64,7 +65,7 @@ type PlainTypeMembersOptions = {
 
 const renderInstanceMethodSignature: InstanceMemberRenderer = instanceMemberRenderer(
     (context, callable, { name, finishFn }) =>
-        `${renderJsDoc(callable.doc)}${memberSignatureText(context, callable, name, { finishFn })};`,
+        `${memberDoc(context, callable, finishFn)}${memberSignatureText(context, callable, name, { finishFn })};`,
 );
 
 const renderClassInstanceMember: InstanceMemberRenderer = instanceMemberRenderer(
@@ -78,6 +79,12 @@ const renderClassInstanceMember: InstanceMemberRenderer = instanceMemberRenderer
                 }),
 );
 
+const memberDoc = (context: ModuleContext, callable: GirFunction, finishFn: GirFunction | undefined): string =>
+    callableDoc(context, callable, { finishFn });
+
+const instanceMemberSpec = (context: ModuleContext, callable: GirFunction, scope: InstanceScope): JsDocSpec =>
+    callableSpec(context, callable, { finishFn: matchFinishFunction(context, callable, scope) });
+
 const instanceScope = (ownerName: string, callables: Callables): InstanceScope => ({
     ownerName,
     methodByName: indexMethodsByName(callables.methods),
@@ -96,11 +103,7 @@ const renderBinding = (
     context: ModuleContext,
     callable: GirFunction,
 ): { text: string; cIdentifier: string } | undefined => {
-    if (!callable.introspectable) {
-        return undefined;
-    }
-
-    if (callable.shadowedBy !== undefined) {
+    if (!isEmittableCallable(context, callable)) {
         return undefined;
     }
 
@@ -159,9 +162,9 @@ const runtimeOverrideMember = (
     callable: GirFunction,
     name: string,
     doc: string,
-    allow: boolean | undefined,
+    canUseRuntimeOverride: boolean | undefined,
 ): string | undefined => {
-    if (allow !== true) {
+    if (canUseRuntimeOverride !== true) {
         return undefined;
     }
 
@@ -182,8 +185,9 @@ const renderCallableMember = (
     }
 
     const { cIdentifier, name } = resolved;
-    const doc = renderJsDoc(callable.doc);
-    const override = runtimeOverrideMember(callable, name, doc, options.allowRuntimeOverride);
+    const renames = options.canUseRuntimeOverride === true ? runtimeOverrideRenames(callable) : undefined;
+    const doc = callableDoc(context, callable, { renames });
+    const override = runtimeOverrideMember(callable, name, doc, options.canUseRuntimeOverride);
 
     if (override !== undefined) {
         return override;
@@ -240,7 +244,7 @@ const renderInstanceMethod = (
     renderCallableMember(context, callable, {
         resolveName: (member) => nameOverride ?? methodExportName(member),
         isStatic: false,
-        allowRuntimeOverride: true,
+        canUseRuntimeOverride: true,
     });
 
 const resolveInstanceMember = (
@@ -349,7 +353,7 @@ const renderPromisifiedCallable = (
     const prefix = member.isStatic ? "static " : "";
     const header = `${prefix}${member.name}(${signature}): ${returnType}`;
 
-    return `${renderJsDoc(callable.doc)}${renderBlock(header, body)}`;
+    return `${memberDoc(context, callable, finishFn)}${renderBlock(header, body)}`;
 };
 
 const indexMethodsByName = (methods: GirFunction[]): Map<string, GirFunction> => {
@@ -366,7 +370,7 @@ const isEmittableCallable = (context: ModuleContext, callable: GirFunction): boo
     callable.introspectable &&
     callable.shadowedBy === undefined &&
     callable.cIdentifier !== undefined &&
-    !hasCallerAllocatedArrayLength(context.library, callable);
+    !hasUnmarshalableParam(context, callable);
 
 const constructorMemberName = (girName: string): string | undefined => {
     const camel = camelCase(girName);
@@ -497,6 +501,7 @@ const renderPlainTypeMembers = (
 export {
     renderInstanceMethodSignature,
     renderClassInstanceMember,
+    instanceMemberSpec,
     instanceScope,
     dedupeCallables,
     generateBindings,
@@ -508,5 +513,6 @@ export {
     renderStaticHead,
     renderPlainTypeMembers,
     type Callables,
+    type InstanceMemberRenderer,
     type InstanceScope,
 };

package/src/store/gi/callback.ts

@@ -1,6 +1,6 @@
 import type { ModuleContext } from "../../writer/context.js";
 import { callbackAsFunction, type GirCallback } from "../../gir/callback.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { callableDoc } from "./callable-doc.js";
 import { renderMethodReturnType, renderMethodSignature } from "./method.js";
 
 const generateCallback = (context: ModuleContext, callback: GirCallback): void => {
@@ -17,7 +17,8 @@ const generateCallback = (context: ModuleContext, callback: GirCallback): void =
     const returnType = renderMethodReturnType(context, fn);
 
     context.module.appendDeclaration(
-        `${renderJsDoc(callback.doc)}export type ${callback.name} = (${signature}) => ${returnType};`,
+        `${callableDoc(context, fn)}export type ${callback.name} = (${signature}) => ${returnType};`,
+        context.declaredType(callback.name),
     );
 };
 

package/src/store/gi/class.ts

@@ -11,7 +11,6 @@ import {
 } 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,
@@ -24,13 +23,14 @@ import {
     renderStaticHead,
 } from "./callables.js";
 import { renderClassConstructor, renderConstructorPropsInterface } from "./constructor-props.js";
+import { getDoc } from "./doc-spec.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";
+import { renderVfuncMembers, renderVfuncMetadata } from "./vtable.js";
 
 type ImplementedRef = {
     typeRef: string;
@@ -84,9 +84,11 @@ const generateClass = (context: ModuleContext, klass: GirClass): void => {
     const implementsClause = typeRefs.length === 0 ? "" : ` implements ${typeRefs.join(", ")}`;
     const { members, accessors } = renderClassMembers(context, klass, callables, parentExpression !== undefined);
     const body = indentMembers(members);
+    const doc = getDoc(klass);
 
     context.module.appendDeclaration(
-        `${renderJsDoc(klass.doc)}export class ${className}${extendsClause}${implementsClause} {\n${body}\n}`,
+        `${doc}export class ${className}${extendsClause}${implementsClause} {\n${body}\n}`,
+        context.declaredType(className),
     );
 
     context.module.appendDeclaration(renderConstructorPropsInterface(context, klass, className));
@@ -152,6 +154,7 @@ const renderClassMembers = (
         className,
     });
 
+    members.push(...renderVfuncMembers({ context, klass, mode: "implementation" }));
     const inheritedPropertyTypes = collectInheritedPropertyTypes(context, klass);
     const accessors: ResolvedAccessor[] = [];
 

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/constant.ts

@@ -3,17 +3,14 @@ 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 { getDoc } from "./doc-spec.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 doc = getDoc(constant);
+    context.module.appendDeclaration(`${doc}export const ${constant.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});`);
 
-    return renderBlock(`constructor(${pattern}: ${className}ConstructorProps = {})`, body);
+    return renderBlock(`constructor(props: ${className}ConstructorProps = {})`, "super(props);");
 };
 
 export { renderConstructorPropsInterface, renderClassConstructor };