@ts-for-gir/lib 4.0.0-beta.40 → 4.0.0-beta.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/lib",
-  "version": "4.0.0-beta.40",
+  "version": "4.0.0-beta.41",
   "description": "Typescript .d.ts generator from GIR for gjs",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -41,18 +41,19 @@
     "type definitions"
   ],
   "devDependencies": {
+    "@ts-for-gir/tsconfig": "^4.0.0-beta.41",
     "@types/ejs": "^3.1.5",
     "@types/lodash": "^4.17.24",
-    "@types/node": "^24.11.0",
+    "@types/node": "^24.12.0",
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@gi.ts/parser": "^4.0.0-beta.40",
-    "@ts-for-gir/reporter": "^4.0.0-beta.40",
-    "@ts-for-gir/templates": "^4.0.0-beta.40",
+    "@gi.ts/parser": "^4.0.0-beta.41",
+    "@ts-for-gir/reporter": "^4.0.0-beta.41",
+    "@ts-for-gir/templates": "^4.0.0-beta.41",
     "colorette": "^2.0.20",
-    "ejs": "^4.0.1",
+    "ejs": "^5.0.1",
     "glob": "^13.0.6",
     "lodash": "^4.17.23"
   }

package/src/constants.ts

@@ -149,4 +149,4 @@ export const RESERVED_CLASS_NAMES = [
 
 export const RESERVED_FUNCTION_NAMES = ["false", "true", "break"];
 
-export const RESERVED_NAMESPACE_NAMES = {};
+export const RESERVED_NAMESPACE_NAMES: Record<string, boolean> = {};

package/src/gir/alias.ts

@@ -2,7 +2,7 @@ import type { FormatGenerator, GenericDescriptor } from "../generators/generator
 import type { TypeExpression } from "../gir.ts";
 import type { GirAliasElement } from "../index.ts";
 import type { IntrospectedOptions, OptionsLoad } from "../types/index.ts";
-import { parseDoc, parseMetadata } from "../utils/gir-parsing.ts";
+import { girParsingReporter, parseDoc, parseMetadata } from "../utils/gir-parsing.ts";
 import { isIntrospectable } from "../utils/girs.ts";
 import { sanitizeIdentifierName } from "../utils/naming.ts";
 import { getAliasType } from "../utils/types.ts";
@@ -52,7 +52,7 @@ export class IntrospectedAlias extends IntrospectedNamespaceMember {
 
 	static fromXML(element: GirAliasElement, ns: IntrospectedNamespace, options: OptionsLoad): IntrospectedAlias | null {
 		if (!element.$.name) {
-			console.error(`Alias in ${ns.namespace} lacks name.`);
+			girParsingReporter.get().reportParsingFailure("alias", "alias", ns.namespace, "Alias lacks name attribute");
 			return null;
 		}
 

package/src/gir/introspected-classes.ts

@@ -72,6 +72,8 @@ export class IntrospectedClassFunction<
 	protected _generify: boolean = false;
 	interfaceParent: IntrospectedBaseClass | IntrospectedEnum | null = null;
 	returnTypeDoc?: string | null;
+	/** If this function was generated from a signal, stores the signal name. */
+	signalOrigin?: string;
 
 	generics: Generic[] = [];
 
@@ -794,105 +796,66 @@ export class IntrospectedClass extends IntrospectedBaseClass {
 		);
 	}
 
-	implementedProperties(potentialConflicts: IntrospectedBase<never>[] = []) {
+	private collectImplementedItems<T extends { name: string }>(
+		getItems: (node: IntrospectedBaseClass) => T[],
+		validate: (item: T) => boolean,
+	): Map<string, T> {
 		const resolution = this.resolveParents();
 		const implementedOnParent = [...(resolution.extends() ?? [])].flatMap((r) => r.implements());
-		const properties = new Map<string, IntrospectedProperty>();
-
-		const validateProp = (prop: IntrospectedProperty) =>
-			!this.hasInstanceSymbol(prop) &&
-			!properties.has(prop.name) &&
-			potentialConflicts.every((p) => prop.name !== p.name);
+		const items = new Map<string, T>();
 
 		for (const implemented of resolution.implements()) {
 			if (implemented.node instanceof IntrospectedClass) continue;
-
 			if (implementedOnParent.find((p) => p.identifier.equals(implemented.identifier))?.node?.generics?.length === 0)
 				continue;
-			for (const prop of implemented.node.props) {
-				if (!validateProp(prop)) continue;
-				properties.set(prop.name, prop);
+			for (const item of getItems(implemented.node)) {
+				if (items.has(item.name) || !validate(item)) continue;
+				items.set(item.name, item);
 			}
 		}
 
 		for (const implemented of resolution.implements()) {
 			[...implemented].forEach((e) => {
 				if (e.node instanceof IntrospectedClass) return;
-
 				if (implementedOnParent.find((p) => p.identifier.equals(e.identifier))?.node.generics.length === 0) return;
-				for (const prop of e.node.props) {
-					if (!validateProp(prop)) continue;
-
-					properties.set(prop.name, prop);
+				for (const item of getItems(e.node)) {
+					if (items.has(item.name) || !validate(item)) continue;
+					items.set(item.name, item);
 				}
 			});
 		}
 
 		// If an interface inherits from a class (such as Gtk.Widget)
-		// we need to pull in every property from that class...
+		// we need to pull in every item from that class...
 		for (const implemented of resolution.implements()) {
 			const extended = implemented.extends();
-
 			if (extended?.node instanceof IntrospectedClass) {
-				for (const prop of extended.node.props) {
-					if (!validateProp(prop)) continue;
-
-					properties.set(prop.name, prop);
+				for (const item of getItems(extended.node)) {
+					if (items.has(item.name) || !validate(item)) continue;
+					items.set(item.name, item);
 				}
 			}
 		}
 
+		return items;
+	}
+
+	implementedProperties(potentialConflicts: IntrospectedBase<never>[] = []) {
+		const properties = this.collectImplementedItems(
+			(node) => node.props,
+			(prop) => !this.hasInstanceSymbol(prop) && potentialConflicts.every((p) => prop.name !== p.name),
+		);
 		return [...properties.values()];
 	}
 
 	implementedMethods(potentialConflicts: ClassMember[] = []) {
-		const resolution = this.resolveParents();
-		const implementedOnParent = [...(resolution.extends() ?? [])].flatMap((r) => r.implements());
-		const methods = new Map<string, IntrospectedClassFunction>();
-
-		const validateMethod = (method: IntrospectedClassFunction) =>
-			!(method instanceof IntrospectedStaticClassFunction) &&
-			!this.hasInstanceSymbol(method) &&
-			!methods.has(method.name) &&
-			potentialConflicts.every((m) => method.name !== m.name);
-
-		for (const implemented of resolution.implements()) {
-			if (implemented.node instanceof IntrospectedClass) continue;
-
-			if (implementedOnParent.find((p) => p.identifier.equals(implemented.identifier))?.node?.generics?.length === 0)
-				continue;
-			for (const member of implemented.node.members) {
-				if (!validateMethod(member)) continue;
-				methods.set(member.name, member);
-			}
-		}
-
-		for (const implemented of resolution.implements()) {
-			[...implemented].forEach((e) => {
-				if (e.node instanceof IntrospectedClass) return;
-
-				if (implementedOnParent.find((p) => p.identifier.equals(e.identifier))?.node.generics.length === 0) return;
-				for (const member of e.node.members) {
-					if (!validateMethod(member)) continue;
-
-					methods.set(member.name, member);
-				}
-			});
-		}
-
-		// If an interface inherits from a class (such as Gtk.Widget)
-		// we need to pull in every method from that class...
-		for (const implemented of resolution.implements()) {
-			const extended = implemented.extends();
-
-			if (extended?.node instanceof IntrospectedClass) {
-				for (const member of extended.node.members) {
-					if (!validateMethod(member)) continue;
-
-					methods.set(member.name, member);
-				}
-			}
-		}
+		const methods = this.collectImplementedItems(
+			(node) => node.members,
+			(method) =>
+				!(method instanceof IntrospectedStaticClassFunction) &&
+				!this.hasInstanceSymbol(method) &&
+				potentialConflicts.every((m) => method.name !== m.name),
+		);
 
 		return [...methods.values()].map((f) => {
 			const mapping = new Map<string, TypeExpression>();

package/src/gir/record.ts

@@ -248,7 +248,7 @@ export class IntrospectedRecord extends IntrospectedBaseClass {
 		namespace: IntrospectedNamespace,
 		name: string,
 	): void {
-		const gtypeStructFor = element.$["glib:is-gtype-struct-for"];
+		const gtypeStructFor = "glib:is-gtype-struct-for" in element.$ ? element.$["glib:is-gtype-struct-for"] : undefined;
 
 		if (typeof gtypeStructFor === "string" && gtypeStructFor) {
 			const structFor = parseTypeIdentifier(namespace.namespace, gtypeStructFor);

package/src/gir/registry.ts

@@ -13,7 +13,6 @@ import { InterfaceVisitor } from "../validators/interface.ts";
 import type { GirVisitor } from "../visitor.ts";
 import type { IntrospectedNamespace } from "./namespace.ts";
 
-// TODO: Singleton
 export class NSRegistry {
 	mapping: TwoKeyMap<string, string, IntrospectedNamespace> = new TwoKeyMap();
 	private formatters: Map<string, Formatter> = new Map();

package/src/gir/signal.ts

@@ -34,12 +34,20 @@ export class IntrospectedSignal extends IntrospectedClassMember<IntrospectedClas
 	parameters: IntrospectedFunctionParameter[];
 	return_type: TypeExpression;
 	detailed: boolean;
+	action: boolean;
+	noRecurse: boolean;
+	noHooks: boolean;
+	when?: "first" | "last" | "cleanup";
 
 	constructor({
 		name,
 		parameters = [],
 		return_type = UnknownType,
 		detailed = false,
+		action = false,
+		noRecurse = false,
+		noHooks = false,
+		when,
 		parent,
 		...args
 	}: Options<{
@@ -47,6 +55,10 @@ export class IntrospectedSignal extends IntrospectedClassMember<IntrospectedClas
 		parameters?: IntrospectedFunctionParameter[];
 		return_type?: TypeExpression;
 		detailed?: boolean;
+		action?: boolean;
+		noRecurse?: boolean;
+		noHooks?: boolean;
+		when?: "first" | "last" | "cleanup";
 		parent: IntrospectedClass;
 	}>) {
 		super(name, parent, { ...args });
@@ -54,6 +66,10 @@ export class IntrospectedSignal extends IntrospectedClassMember<IntrospectedClas
 		this.parameters = parameters.map((p) => p.copy({ parent: this }));
 		this.return_type = return_type;
 		this.detailed = detailed;
+		this.action = action;
+		this.noRecurse = noRecurse;
+		this.noHooks = noHooks;
+		this.when = when;
 	}
 
 	accept(visitor: GirVisitor): IntrospectedSignal {
@@ -72,11 +88,19 @@ export class IntrospectedSignal extends IntrospectedClassMember<IntrospectedClas
 		parameters,
 		returnType,
 		detailed,
+		action,
+		noRecurse,
+		noHooks,
+		when,
 	}: {
 		parent?: IntrospectedClass;
 		parameters?: IntrospectedFunctionParameter[];
 		returnType?: TypeExpression;
 		detailed?: boolean;
+		action?: boolean;
+		noRecurse?: boolean;
+		noHooks?: boolean;
+		when?: "first" | "last" | "cleanup";
 	} = {}): IntrospectedSignal {
 		return new IntrospectedSignal({
 			name: this.name,
@@ -84,6 +108,10 @@ export class IntrospectedSignal extends IntrospectedClassMember<IntrospectedClas
 			parameters: parameters ?? this.parameters,
 			return_type: returnType ?? this.return_type,
 			detailed: detailed ?? this.detailed,
+			action: action ?? this.action,
+			noRecurse: noRecurse ?? this.noRecurse,
+			noHooks: noHooks ?? this.noHooks,
+			when: when ?? this.when,
 		})._copyBaseProperties(this);
 	}
 
@@ -93,6 +121,10 @@ export class IntrospectedSignal extends IntrospectedClassMember<IntrospectedClas
 			name: element.$.name,
 			parent,
 			detailed: element.$.detailed === "1",
+			action: element.$.action === "1",
+			noRecurse: element.$["no-recurse"] === "1",
+			noHooks: element.$["no-hooks"] === "1",
+			when: element.$.when as "first" | "last" | "cleanup" | undefined,
 			isIntrospectable: isIntrospectable(element),
 		});
 

package/src/gir-module.ts

@@ -1,4 +1,4 @@
-import type { GirType } from "@gi.ts/parser";
+import type { GirBoxedElement, GirInfoAttrs, GirType } from "@gi.ts/parser";
 import { ConsoleReporter, ReporterService } from "@ts-for-gir/reporter";
 import { DependencyManager } from "./dependency-manager.ts";
 import { IntrospectedAlias } from "./gir/alias.ts";
@@ -19,11 +19,13 @@ import { NullableType, ObjectType, TypeIdentifier } from "./gir.ts";
 import type { LibraryVersion } from "./library-version.ts";
 import type {
 	Dependency,
+	GirAliasElement,
 	GirBitfieldElement,
 	GirConstantElement,
 	GirEnumElement,
 	GirInterfaceElement,
 	IGirModule,
+	IntrospectedMetadata,
 	OptionsGeneration,
 	OptionsLoad,
 	TsDocTag,
@@ -244,6 +246,23 @@ export class GirModule implements IGirModule {
 		return tags;
 	}
 
+	getTsDocMetadataTags(metadata?: IntrospectedMetadata): TsDocTag[] {
+		const tags: TsDocTag[] = [];
+		if (metadata?.introducedVersion) {
+			tags.push({ tagName: "since", paramName: "", text: metadata.introducedVersion });
+		}
+		if (metadata?.deprecated) {
+			const text = [
+				metadata.deprecatedVersion ? `since ${metadata.deprecatedVersion}` : "",
+				metadata.deprecatedDoc ?? "",
+			]
+				.filter(Boolean)
+				.join(": ");
+			tags.push({ tagName: "deprecated", paramName: "", text });
+		}
+		return tags;
+	}
+
 	registerResolveName(resolveName: string, namespace: string, name: string) {
 		this._resolve_names.set(resolveName, new TypeIdentifier(name, namespace));
 	}
@@ -570,6 +589,90 @@ export class GirModule implements IGirModule {
 		return building;
 	}
 
+	/** Parse and store elements into this.members using a common pattern */
+	private parseAndStore<TXml, TResult extends GirNSMember>(
+		elements: TXml[] | undefined,
+		fromXML: (el: TXml) => TResult,
+		filter?: (el: TResult) => boolean,
+	): void {
+		if (!elements) return;
+		let items = (elements as Array<TXml & { $?: GirInfoAttrs }>).filter(isIntrospectable).map(fromXML);
+		if (filter) items = items.filter(filter);
+		for (const item of items) {
+			this.members.set(item.name, item);
+		}
+	}
+
+	/** Parse enumerations, which may be either enums or error domains */
+	private parseEnumerations(
+		enumerations: GirEnumElement[] | undefined,
+		options: OptionsLoad,
+		importConflicts: (el: { name: string }) => boolean,
+	): void {
+		this.parseAndStore(
+			enumerations,
+			(enumeration) => {
+				if (enumeration.$["glib:error-domain"]) {
+					return IntrospectedError.fromXML(enumeration, this, options);
+				}
+				return IntrospectedEnum.fromXML(enumeration, this, options);
+			},
+			importConflicts,
+		);
+	}
+
+	/** Parse glib:boxed elements into aliases */
+	private parseBoxed(boxed: GirBoxedElement[] | undefined): void {
+		if (!boxed) return;
+		const items = boxed.filter(isIntrospectable).map(
+			(b) =>
+				new IntrospectedAlias({
+					name: b.$["glib:name"],
+					namespace: this,
+					type: new NullableType(ObjectType),
+				}),
+		);
+		for (const item of items) {
+			this.members.set(item.name, item);
+		}
+	}
+
+	/** Parse aliases, filtering out non-introspectable symbol references */
+	private parseAliases(aliases: GirAliasElement[], options: OptionsLoad): void {
+		type NamedType = GirType & { $: { name: string } };
+
+		const parsed = aliases
+			.filter(isIntrospectable)
+			.map((b) => {
+				b.type = b.type
+					?.filter((t): t is NamedType => !!t?.$.name)
+					.map((t) => {
+						if (t.$.name && !this.hasSymbol(t.$.name) && !isPrimitiveType(t.$.name) && !t.$.name.includes(".")) {
+							return { $: { name: "unknown", "c:type": "unknown" } } as GirType;
+						}
+						return t;
+					});
+				return b;
+			})
+			.map((alias) => IntrospectedAlias.fromXML(alias, this, options))
+			.filter((alias): alias is IntrospectedAlias => alias != null);
+
+		for (const c of parsed) {
+			this.members.set(c.name, c);
+		}
+	}
+
+	/** Build the enum_constants map from parsed enum members */
+	private buildEnumConstantsMap(): void {
+		for (const m of this.members.values()) {
+			if (m instanceof IntrospectedEnum) {
+				for (const member of m.members.values()) {
+					this.enum_constants.set(member.c_identifier, [m.name, member.name] as const);
+				}
+			}
+		}
+	}
+
 	/** Start to parse all the data from the XML we need for the typescript generation */
 	public parse() {
 		this.log.debug(`Parsing ${this.dependency.packageName}...`);
@@ -590,170 +693,27 @@ export class GirModule implements IGirModule {
 			throw new Error(`Missing namespace in ${packageName}`);
 		}
 
-		const importConflicts = (
-			el: IntrospectedConstant | IntrospectedBaseClass | IntrospectedFunction | IntrospectedEnum | IntrospectedError,
-		) => {
-			return !this.hasImport(el.name);
-		};
-
-		if (ns.enumeration) {
-			// Get the requested enums
-			const enumerations = ns.enumeration
-				?.filter(isIntrospectable)
-				.map((enumeration) => {
-					if (enumeration.$["glib:error-domain"]) {
-						return IntrospectedError.fromXML(enumeration as GirEnumElement, this, options);
-					} else {
-						return IntrospectedEnum.fromXML(enumeration as GirEnumElement, this, options);
-					}
-				})
-				.filter(importConflicts);
-
-			for (const c of enumerations) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// Constants
-		if (ns.constant) {
-			const constants = ns.constant
-				?.filter(isIntrospectable)
-				.map((constant) => IntrospectedConstant.fromXML(constant, this, options))
-				.filter(importConflicts);
-
-			for (const c of constants) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// Get the requested functions
-		if (ns.function) {
-			const functions = ns.function
-				?.filter(isIntrospectable)
-				.map((func) => IntrospectedFunction.fromXML(func, this, options))
-				.filter(importConflicts);
-
-			for (const c of functions) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.callback) {
-			const callbacks = ns.callback
-				?.filter(isIntrospectable)
-				.map((callback) => IntrospectedCallback.fromXML(callback, this, options))
-				.filter(importConflicts);
-
-			for (const c of callbacks) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns["glib:boxed"]) {
-			const boxed = ns["glib:boxed"]?.filter(isIntrospectable).map(
-				(boxed) =>
-					new IntrospectedAlias({
-						name: boxed.$["glib:name"],
-						namespace: this,
-						type: new NullableType(ObjectType),
-					}),
-			);
-
-			for (const c of boxed) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// Bitfield is a type of enum
-		if (ns.bitfield) {
-			const bitfields = ns.bitfield
-				?.filter(isIntrospectable)
-				.map((field) => IntrospectedEnum.fromXML(field as GirBitfieldElement, this, options, true));
-
-			for (const c of bitfields) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// The `enum_constants` map maps the C identifiers (GTK_BUTTON_TYPE_Y)
-		// to the name of the enum (Button) to resolve references (Gtk.Button.Y)
-		Array.from(this.members.values())
-			.filter((m): m is IntrospectedEnum => m instanceof IntrospectedEnum)
-			.forEach((m) => {
-				m.members.forEach((member) => {
-					this.enum_constants.set(member.c_identifier, [m.name, member.name] as const);
-				});
-			});
-
-		// Get the requested classes
-		if (ns.class) {
-			const classes = ns.class
-				?.filter(isIntrospectable)
-				.map((klass) => IntrospectedClass.fromXML(klass, this, options))
-				.filter(importConflicts);
-
-			for (const c of classes) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.record) {
-			const records = ns.record
-				?.filter(isIntrospectable)
-				.map((record) => IntrospectedRecord.fromXML(record, this, options))
-				.filter(importConflicts);
+		const importConflicts = (el: { name: string }) => !this.hasImport(el.name);
 
-			for (const c of records) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.union) {
-			const unions = ns.union
-				?.filter(isIntrospectable)
-				.map((union) => IntrospectedRecord.fromXML(union, this, options))
-				.filter(importConflicts);
-
-			for (const c of unions) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.interface) {
-			const interfaces = ns.interface
-				?.map((inter) => IntrospectedInterface.fromXML(inter as GirInterfaceElement, this, options))
-				.filter(importConflicts);
-
-			for (const c of interfaces) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.alias) {
-			type NamedType = GirType & { $: { name: string } };
-
-			const aliases = ns.alias
-				?.filter(isIntrospectable)
-				// Avoid attempting to alias non-introspectable symbols.
-				.map((b) => {
-					b.type = b.type
-						?.filter((t): t is NamedType => !!t?.$.name)
-						.map((t) => {
-							if (t.$.name && !this.hasSymbol(t.$.name) && !isPrimitiveType(t.$.name) && !t.$.name.includes(".")) {
-								return { $: { name: "unknown", "c:type": "unknown" } } as GirType;
-							}
-
-							return t;
-						});
-
-					return b;
-				})
-				.map((alias) => IntrospectedAlias.fromXML(alias, this, options))
-				.filter((alias): alias is IntrospectedAlias => alias != null);
-
-			for (const c of aliases) {
-				this.members.set(c.name, c);
-			}
-		}
+		this.parseEnumerations(ns.enumeration as GirEnumElement[] | undefined, options, importConflicts);
+		this.parseAndStore(
+			ns.constant,
+			(c) => IntrospectedConstant.fromXML(c as GirConstantElement, this, options),
+			importConflicts,
+		);
+		this.parseAndStore(ns.function, (f) => IntrospectedFunction.fromXML(f, this, options), importConflicts);
+		this.parseAndStore(ns.callback, (cb) => IntrospectedCallback.fromXML(cb, this, options), importConflicts);
+		this.parseBoxed(ns["glib:boxed"]);
+		this.parseAndStore(ns.bitfield, (f) => IntrospectedEnum.fromXML(f as GirBitfieldElement, this, options, true));
+		this.buildEnumConstantsMap();
+		this.parseAndStore(ns.class, (k) => IntrospectedClass.fromXML(k, this, options), importConflicts);
+		this.parseAndStore(ns.record, (r) => IntrospectedRecord.fromXML(r, this, options), importConflicts);
+		this.parseAndStore(ns.union, (u) => IntrospectedRecord.fromXML(u, this, options), importConflicts);
+		this.parseAndStore(
+			ns.interface,
+			(i) => IntrospectedInterface.fromXML(i as GirInterfaceElement, this, options),
+			importConflicts,
+		);
+		if (ns.alias) this.parseAliases(ns.alias, options);
 	}
 }