@ts-for-gir/generator-typescript 4.0.0-beta.9 → 4.0.0-rc.2

package/README.md

@@ -16,5 +16,22 @@
   <img src="https://raw.githubusercontent.com/gjsify/ts-for-gir/main/.github/feeling.gif" />
 </p>
 
-# Generator base
-TypeScript type definition generator for ts-for-gir.
+# TypeScript Generator
+
+TypeScript-specific generator for `ts-for-gir`. This package implements the actual generation of TypeScript declaration files (.d.ts) from the processed GIR data. It transforms the intermediate representation of GObject types into TypeScript type definitions.
+
+## Features
+
+- Generation of TypeScript declaration files (.d.ts) from GIR data
+- Support for generating NPM packages with proper package.json configuration
+- Template-based code generation using EJS templates
+- Complete handling of complex type transformations:
+  - Classes, interfaces, and records
+  - Functions, methods, and constructors 
+  - Properties, fields, and constants
+  - Enums and callbacks
+  - Signals and their event handlers
+- Generation of proper JSDoc comments from GIR documentation
+- Support for GJS-specific module formats and ambient type declarations
+
+This package is responsible for the final output of the `ts-for-gir` toolchain, producing TypeScript definition files that can be used in GJS projects.

package/package.json

@@ -1,36 +1,26 @@
 {
   "name": "@ts-for-gir/generator-typescript",
-  "version": "4.0.0-beta.9",
+  "version": "4.0.0-rc.2",
   "description": "TypeScript type definition generator for ts-for-gir",
-  "module": "lib/index.js",
-  "main": "lib/index.js",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
   "type": "module",
   "engines": {
     "node": ">=18"
   },
   "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "import": "./lib/index.js"
-    }
+    ".": "./src/index.ts"
   },
   "scripts": {
-    "build": "yarn lint && yarn build:ts",
-    "build:ts": "tsc",
-    "clear": "yarn clear:build",
-    "clear:build": "rimraf ./lib",
-    "watch": "yarn build:ts --watch",
-    "lint": "eslint . --ext .ts,.tsx --fix"
+    "check": "tsc --noEmit"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gjsify/ts-for-gir.git"
   },
-  "author": "Pascal Garber <pascal@artandcode.studio>",
+  "author": "Pascal Garber <pascal@mailfreun.de>",
   "files": [
-    "lib",
-    "templates",
-    "packages.xml"
+    "src"
   ],
   "license": "Apache-2.0",
   "bugs": {
@@ -41,22 +31,18 @@
     "generator"
   ],
   "devDependencies": {
+    "@ts-for-gir/tsconfig": "^4.0.0-rc.2",
     "@types/ejs": "^3.1.5",
-    "@types/node": "^20.14.11",
+    "@types/node": "^24.12.2",
     "@types/xml2js": "^0.4.14",
-    "@typescript-eslint/eslint-plugin": "^7.16.1",
-    "@typescript-eslint/parser": "^7.16.1",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.2.1",
-    "prettier": "^3.3.3",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.5.3"
+    "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@ts-for-gir/generator-base": "^4.0.0-beta.9",
-    "@ts-for-gir/lib": "^4.0.0-beta.9",
-    "ejs": "^3.1.10",
+    "@gi.ts/parser": "^4.0.0-rc.2",
+    "@ts-for-gir/generator-base": "^4.0.0-rc.2",
+    "@ts-for-gir/lib": "^4.0.0-rc.2",
+    "@ts-for-gir/templates": "^4.0.0-rc.2",
+    "ejs": "^5.0.1",
     "xml2js": "^0.6.2"
   }
 }

package/src/generators/index.ts

@@ -0,0 +1,2 @@
+export { ModuleExporter } from "./module-exporter.ts";
+export { SignalGenerator } from "./signal-generator.ts";

package/src/generators/module-exporter.ts

@@ -0,0 +1,88 @@
+import type { DependencyManager, GirModule, NSRegistry, OptionsGeneration, Reporter } from "@ts-for-gir/lib";
+import type { ModuleGenerator } from "../module-generator.ts";
+import { NpmPackage } from "../npm-package.ts";
+import type { TemplateProcessor } from "../template-processor.ts";
+
+/** Handles exporting generated modules to files. */
+export class ModuleExporter {
+	constructor(private readonly core: ModuleGenerator) {}
+
+	private get config(): OptionsGeneration {
+		return this.core.config;
+	}
+
+	private get log(): Reporter {
+		return this.core.log;
+	}
+
+	private get moduleTemplateProcessor(): TemplateProcessor {
+		return this.core.moduleTemplateProcessor;
+	}
+
+	private get dependencyManager(): DependencyManager {
+		return this.core.dependencyManager;
+	}
+
+	/** Export a template file to outdir or log its content. */
+	private async exportTemplate(template: string, target: string): Promise<void> {
+		if (this.config.outdir) {
+			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
+		} else {
+			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
+			this.log.log(append + prepend);
+		}
+	}
+
+	async exportModuleTS(): Promise<void> {
+		const girModule = this.core.girNamespace;
+		const template = "module.d.ts";
+		const explicitTemplate = `${girModule.importName}.d.ts`;
+		const output = await this.core.generateModule(girModule);
+
+		if (!output) {
+			this.log.error("Failed to generate gir module");
+			return;
+		}
+
+		if (await this.moduleTemplateProcessor.exists(explicitTemplate)) {
+			const { append: appendExplicit, prepend: prependExplicit } =
+				await this.moduleTemplateProcessor.load(explicitTemplate);
+			output.unshift(prependExplicit);
+			output.push(appendExplicit);
+		}
+
+		const { append, prepend } = await this.moduleTemplateProcessor.load(template);
+		output.unshift(prepend);
+		output.push(append);
+
+		if (this.config.outdir) {
+			await this.moduleTemplateProcessor.write(output.join("\n"), this.config.outdir, explicitTemplate);
+		} else {
+			this.log.log(output.join("\n"));
+		}
+	}
+
+	async exportModule(registry: NSRegistry, girModule: GirModule): Promise<void> {
+		await this.exportModuleTS();
+
+		if (this.config.package) {
+			const name = girModule.importName;
+			await this.exportTemplate("module.js", `${name}.js`);
+			await this.exportTemplate("index.d.ts", "index.d.ts");
+			await this.exportTemplate("index.js", "index.js");
+			await this.exportTemplate("module-ambient.d.ts", `${name}-ambient.d.ts`);
+			await this.exportTemplate("module-ambient.js", `${name}-ambient.js`);
+			await this.exportTemplate("module-import.d.ts", `${name}-import.d.ts`);
+			await this.exportTemplate("module-import.js", `${name}-import.js`);
+
+			const pkg = new NpmPackage(
+				this.config,
+				this.dependencyManager,
+				registry,
+				girModule,
+				girModule.transitiveDependencies,
+			);
+			await pkg.exportNPMPackage();
+		}
+	}
+}

package/src/generators/signal-generator.ts

@@ -0,0 +1,264 @@
+import { GirDirection } from "@gi.ts/parser";
+import {
+	BinaryType,
+	BooleanType,
+	FilterBehavior,
+	filterConflicts,
+	type GirModule,
+	generateIndent,
+	type IntrospectedBaseClass,
+	IntrospectedClass,
+	IntrospectedClassFunction,
+	IntrospectedInterface,
+	type IntrospectedRecord,
+	mergeDescs,
+	NumberType,
+	type OptionsGeneration,
+	VoidType,
+} from "@ts-for-gir/lib";
+import type { ModuleGenerator } from "../module-generator.ts";
+
+const SIGNAL_JSDOC = "/** @signal */";
+
+/** Handles generation of GObject signal-related TypeScript definitions. */
+export class SignalGenerator {
+	constructor(private readonly core: ModuleGenerator) {}
+
+	private get namespace(): GirModule {
+		return this.core.girNamespace;
+	}
+
+	private get config(): OptionsGeneration {
+		return this.core.config;
+	}
+
+	/**
+	 * Generate SignalSignatures interface for type-safe signal handling.
+	 *
+	 * Creates a comprehensive mapping of signal names to their callback types,
+	 * enabling TypeScript to provide proper type checking and IntelliSense for
+	 * GObject signals using the centralized getAllSignals() method from the model.
+	 */
+	generateClassSignalInterfaces(girClass: IntrospectedClass, indentCount = 0): string[] {
+		const def: string[] = [];
+		const indent = generateIndent(indentCount);
+
+		def.push(`${indent}// Signal signatures`);
+		def.push(`${indent}interface SignalSignatures`);
+
+		const parentSignatures: string[] = [];
+
+		// Inherit signal signatures from parent class
+		const parentResolution = girClass.resolveParents().extends();
+		if (parentResolution && parentResolution.node instanceof IntrospectedClass) {
+			const parentClass = parentResolution.node as IntrospectedClass;
+			const parentTypeIdentifier = parentResolution.identifier
+				.resolveIdentifier(this.namespace, this.config)
+				?.print(this.namespace, this.config);
+
+			const hasSignalMethods = parentClass.signals?.length > 0;
+			const isNotTemplateWorkaround = !(
+				this.namespace.namespace === "Gimp" && ["ParamObject", "ParamItem", "ParamArray"].includes(parentClass.name)
+			);
+
+			if (parentTypeIdentifier && (hasSignalMethods || isNotTemplateWorkaround)) {
+				parentSignatures.push(`${parentTypeIdentifier}.SignalSignatures`);
+			}
+		}
+
+		// Inherit signal signatures from implemented interfaces
+		const interfaceSignatures = girClass
+			.resolveParents()
+			.implements()
+			.filter((iface) => iface.node instanceof IntrospectedInterface)
+			.filter((iface) => {
+				const node = iface.node as unknown as { signals?: unknown[] };
+				return node.signals && node.signals.length > 0;
+			})
+			.map((iface) => {
+				const interfaceTypeIdentifier = iface.identifier
+					.resolveIdentifier(this.namespace, this.config)
+					?.print(this.namespace, this.config);
+				return interfaceTypeIdentifier ? `${interfaceTypeIdentifier}.SignalSignatures` : null;
+			})
+			.filter((sig): sig is string => !!sig);
+
+		parentSignatures.push(...interfaceSignatures);
+
+		if (parentSignatures.length > 0) {
+			def.push(` extends ${parentSignatures.join(", ")} {`);
+		} else {
+			const isGObjectObject = girClass.name === "Object" && girClass.namespace.namespace === "GObject";
+
+			if (isGObjectObject) {
+				def.push(" {");
+			} else {
+				const gobjectNamespace = this.namespace.assertInstalledImport("GObject");
+				const gobjectObjectClass = gobjectNamespace.assertClass("Object");
+				const gobjectRef = gobjectObjectClass
+					.getType()
+					.resolveIdentifier(this.namespace, this.config)
+					?.print(this.namespace, this.config);
+
+				const fallbackRef = gobjectRef ? `${gobjectRef}.SignalSignatures` : "GObject.Object.SignalSignatures";
+				def.push(` extends ${fallbackRef} {`);
+			}
+		}
+
+		const allSignals = girClass.getAllSignals();
+
+		allSignals.forEach((signalInfo) => {
+			let cbType: string;
+
+			if (signalInfo.isNotifySignal) {
+				const gobjectRef = this.namespace.namespace === "GObject" ? "" : "GObject.";
+				cbType = `(pspec: ${gobjectRef}ParamSpec) => void`;
+			} else if (signalInfo.signal) {
+				// Signal handlers are invoked from C to JS: in-params come _out_ of C
+				// (so e.g. 64-bit ints arrive as `number`, not `bigint | number`), and
+				// the handler's return value goes _in_ to C.
+				const paramTypes = signalInfo.signal.parameters
+					.map((p, idx) => `arg${idx}: ${this.core.generateDirectedType(p.type, GirDirection.Out)}`)
+					.join(", ");
+
+				let returnType = signalInfo.signal.return_type;
+				if (signalInfo.signal.return_type.equals(BooleanType)) {
+					returnType = new BinaryType(BooleanType, VoidType);
+				}
+				const returnTypeStr = this.core.generateDirectedType(returnType, GirDirection.In);
+
+				cbType = `(${paramTypes}) => ${returnTypeStr}`;
+			} else {
+				const paramTypes = signalInfo.parameterTypes?.map((type, idx) => `arg${idx}: ${type}`) || [];
+				const returnTypeStr = signalInfo.returnType || "void";
+				cbType = `(${paramTypes.join(", ")}) => ${returnTypeStr}`;
+			}
+
+			// Template literal catch-all signals use index signature syntax
+			if (signalInfo.isTemplateLiteral) {
+				def.push(`${indent}    [key: \`${signalInfo.name}\`]: ${cbType};`);
+				return;
+			}
+
+			const signalKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(signalInfo.name) ? signalInfo.name : `"${signalInfo.name}"`;
+
+			// Add signal doc comment with @signal tag and signal-specific modifier tags
+			if (!signalInfo.isNotifySignal && signalInfo.signal) {
+				const signalTags = [
+					{ tagName: "signal", paramName: "", text: "" },
+					...this.namespace.getTsDocMetadataTags(signalInfo.signal.metadata),
+				];
+				if (signalInfo.signal.detailed) signalTags.push({ tagName: "detailed", paramName: "", text: "" });
+				if (signalInfo.signal.action) signalTags.push({ tagName: "action", paramName: "", text: "" });
+				if (signalInfo.signal.when)
+					signalTags.push({ tagName: `run-${signalInfo.signal.when}`, paramName: "", text: "" });
+				const comment = this.core.addGirDocComment(signalInfo.signal.doc, signalTags, indentCount + 1);
+				if (comment.length) {
+					def.push(...comment);
+				} else {
+					def.push(`${indent}    /** @signal */`);
+				}
+			} else if (!signalInfo.isNotifySignal) {
+				def.push(`${indent}    /** @signal */`);
+			}
+			def.push(`${indent}    ${signalKey}: ${cbType};`);
+		});
+
+		def.push(`${indent}}`);
+		def.push("");
+
+		return def;
+	}
+
+	/**
+	 * Generate signal methods section with header comment
+	 */
+	generateClassSignals(girClass: IntrospectedClass): string[] {
+		return mergeDescs(this.generateSignalMethods(girClass), "Signals", 1);
+	}
+
+	/**
+	 * Generate the $signals property for type-safe signal access
+	 */
+	generateClassSignalsProperty(girClass: IntrospectedClass | IntrospectedRecord, indentCount = 1): string[] {
+		const isGObjectObject = girClass.name === "Object" && girClass.namespace.namespace === "GObject";
+		const hasGObjectParent =
+			isGObjectObject ||
+			girClass.someParent((p: IntrospectedBaseClass) => p.namespace.namespace === "GObject" && p.name === "Object");
+
+		if (!hasGObjectParent) return [];
+
+		const indent = generateIndent(indentCount);
+		return [
+			"",
+			`${indent}/**`,
+			`${indent} * Compile-time signal type information.`,
+			`${indent} *`,
+			`${indent} * This instance property is generated only for TypeScript type checking.`,
+			`${indent} * It is not defined at runtime and should not be accessed in JS code.`,
+			`${indent} * @internal`,
+			`${indent} */`,
+			`${indent}$signals: ${girClass.name}.SignalSignatures;`,
+			"",
+		];
+	}
+
+	/**
+	 * Generate type-safe connect/connect_after/emit signal methods
+	 */
+	private generateSignalMethods(girClass: IntrospectedClass): string[] {
+		const signalFunctions = [
+			new IntrospectedClassFunction({
+				name: "connect",
+				parent: girClass,
+				parameters: [],
+				return_type: NumberType,
+			}),
+			new IntrospectedClassFunction({
+				name: "connect_after",
+				parent: girClass,
+				parameters: [],
+				return_type: NumberType,
+			}),
+			new IntrospectedClassFunction({
+				name: "emit",
+				parent: girClass,
+				parameters: [],
+				return_type: VoidType,
+			}),
+		];
+
+		const filteredFunctions = filterConflicts(girClass.namespace, girClass, signalFunctions, FilterBehavior.DELETE);
+		const allowedNames = new Set(filteredFunctions.map((f) => f.name));
+
+		const gobjectRef = this.namespace.namespace === "GObject" ? "" : "GObject.";
+
+		const methods: string[] = [];
+
+		if (allowedNames.has("connect")) {
+			methods.push(
+				SIGNAL_JSDOC,
+				`connect<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, callback: ${gobjectRef}SignalCallback<this, ${girClass.name}.SignalSignatures[K]>): number;`,
+				"connect(signal: string, callback: (...args: any[]) => any): number;",
+			);
+		}
+
+		if (allowedNames.has("connect_after")) {
+			methods.push(
+				SIGNAL_JSDOC,
+				`connect_after<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, callback: ${gobjectRef}SignalCallback<this, ${girClass.name}.SignalSignatures[K]>): number;`,
+				"connect_after(signal: string, callback: (...args: any[]) => any): number;",
+			);
+		}
+
+		if (allowedNames.has("emit")) {
+			methods.push(
+				SIGNAL_JSDOC,
+				`emit<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, ...args: ${gobjectRef}GjsParameters<${girClass.name}.SignalSignatures[K]> extends [any, ...infer Q] ? Q : never): void;`,
+				"emit(signal: string, ...args: any[]): void;",
+			);
+		}
+
+		return methods;
+	}
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { ModuleGenerator, ModuleGeneratorFormat } from "./module-generator.ts";
+export { NpmPackage } from "./npm-package.ts";
+export { TemplateProcessor } from "./template-processor.ts";
+export { TypeDefinitionGenerator } from "./type-definition-generator.ts";

package/src/module-generator-example.ts

@@ -0,0 +1,68 @@
+/**
+ * Example usage of the refactored ModuleGenerator
+ *
+ * This demonstrates how the unified ModuleGenerator now incorporates
+ * functionality from DtsGenerator and DtsModuleGenerator
+ */
+
+import type { GirModule, NSRegistry, OptionsGeneration } from "@ts-for-gir/lib";
+import { ModuleGenerator } from "./module-generator.ts";
+
+// Example: Using ModuleGenerator with different output formats
+async function generateTypeDefinitions(girModule: GirModule, config: OptionsGeneration, registry: NSRegistry) {
+	// Create a ModuleGenerator instance
+	const generator = new ModuleGenerator(girModule, config, registry);
+
+	// 1. Generate as string array (default behavior)
+	const arrayOutput = await generator.generateModule(girModule);
+	console.log("String array output:", arrayOutput);
+
+	// 2. Generate as single string (DtsGenerator compatibility)
+	const stringOutput = await generator.generateModuleString(girModule);
+	console.log("String output:", stringOutput);
+
+	// 3. Generate as module declaration (DtsModuleGenerator compatibility)
+	const moduleDeclaration = await generator.generateModuleDeclaration(girModule);
+	console.log("Module declaration output:", moduleDeclaration);
+
+	// 4. Generate namespace as string
+	const namespaceString = await generator.generateNamespaceAsString(girModule);
+	console.log("Namespace string output:", namespaceString);
+
+	// 5. The AdvancedVariants feature is automatically applied
+	// when generating GLib or GObject modules (unless disabled with noAdvancedVariants option)
+	if (girModule.namespace === "GLib" && !config.noAdvancedVariants) {
+		console.log("GLib module will include advanced variant type definitions");
+	}
+	if (girModule.namespace === "GObject") {
+		console.log("GObject module will include registerClass overrides");
+	}
+}
+
+// Example: Migrating from DtsGenerator
+function migrateFromDtsGenerator(girModule: GirModule, config: OptionsGeneration, registry: NSRegistry) {
+	// Before (using DtsGenerator):
+	// const generator = new DtsGenerator(girModule, config);
+	// const output = await generator.generateNamespace(girModule);
+
+	// After (using ModuleGenerator):
+	const generator = new ModuleGenerator(girModule, config, registry);
+	const output = generator.generateNamespaceAsString(girModule);
+
+	return output;
+}
+
+// Example: Migrating from DtsModuleGenerator
+function migrateFromDtsModuleGenerator(girModule: GirModule, config: OptionsGeneration, registry: NSRegistry) {
+	// Before (using DtsModuleGenerator):
+	// const generator = new DtsModuleGenerator(girModule, config);
+	// const output = await generator.generateNamespace(girModule);
+
+	// After (using ModuleGenerator):
+	const generator = new ModuleGenerator(girModule, config, registry);
+	const output = generator.generateModuleDeclaration(girModule);
+
+	return output;
+}
+
+export { generateTypeDefinitions, migrateFromDtsGenerator, migrateFromDtsModuleGenerator };