@ts-for-gir/lib 4.0.0-beta.9 → 4.0.0-rc.10

package/src/gir/introspected-namespace-member.ts

@@ -0,0 +1,24 @@
+import type { GirMemberElement, OptionsLoad, PartOfClass, PartOfModule } from "../types/index.ts";
+import type { IntrospectedBaseOptions } from "../types/introspected.ts";
+import { IntrospectedBase } from "./introspected-base.ts";
+import type { IntrospectedNamespace } from "./namespace.ts";
+
+export abstract class IntrospectedNamespaceMember extends IntrospectedBase<IntrospectedNamespace> {
+	constructor(name: string, namespace: IntrospectedNamespace, options: IntrospectedBaseOptions = {}) {
+		super(name, namespace, options);
+	}
+
+	get namespace() {
+		return this.parent;
+	}
+
+	static fromXML(
+		_element: PartOfClass | PartOfModule | GirMemberElement,
+
+		_parent: IntrospectedNamespace,
+
+		_options: OptionsLoad,
+	): IntrospectedNamespaceMember | null {
+		throw new Error("GirBase cannot be instantiated");
+	}
+}

package/src/gir/namespace.ts

@@ -0,0 +1,76 @@
+import { BinaryType, BooleanType, ClosureType, PromiseType, TupleType, TypeIdentifier, VoidType } from "../gir.ts";
+
+import type { GirModule } from "../gir-module.ts";
+import type { IntrospectedAlias } from "./alias.ts";
+import type { IntrospectedConstant } from "./const.ts";
+import type { IntrospectedEnum } from "./enum.ts";
+import { IntrospectedFunction } from "./function.ts";
+import type { IntrospectedBaseClass } from "./introspected-classes.ts";
+
+// TODO: Move to types/
+export type GirNSMember =
+	| IntrospectedBaseClass
+	| IntrospectedFunction
+	| IntrospectedConstant
+	| IntrospectedEnum
+	| IntrospectedAlias;
+
+export function promisifyNamespaceFunctions(namespace: GirModule) {
+	return namespace.members.forEach((node) => {
+		if (!(node instanceof IntrospectedFunction)) return;
+
+		if (node.parameters.length < 1) return;
+
+		const last_param = node.parameters[node.parameters.length - 1];
+
+		if (!last_param) return;
+
+		const last_param_unwrapped = last_param.type.unwrap();
+
+		if (!(last_param_unwrapped instanceof ClosureType)) return;
+
+		const internal = last_param_unwrapped.type;
+
+		if (internal instanceof TypeIdentifier && internal.is("Gio", "AsyncReadyCallback")) {
+			const async_res = [
+				...Array.from(namespace.members.values()).filter(
+					(m): m is IntrospectedFunction => m instanceof IntrospectedFunction,
+				),
+			].find((m) => m.name === `${node.name.replace(/_async$/, "")}_finish` || m.name === `${node.name}_finish`);
+
+			if (async_res) {
+				const async_parameters = node.parameters.slice(0, -1).map((p) => p.copy());
+				const sync_parameters = node.parameters.map((p) => p.copy({ isOptional: false }));
+				const output_parameters = async_res.output_parameters;
+
+				let async_return = new PromiseType(async_res.return());
+
+				if (output_parameters.length > 0) {
+					const raw_return = async_res.return();
+					if (raw_return.equals(VoidType) || raw_return.equals(BooleanType)) {
+						const [output_type, ...output_types] = output_parameters.map((op) => op.type);
+						async_return = new PromiseType(new TupleType(output_type, ...output_types));
+					} else {
+						const [...output_types] = output_parameters.map((op) => op.type);
+						async_return = new PromiseType(new TupleType(raw_return, ...output_types));
+					}
+				}
+
+				namespace.members.set(node.name, [
+					node.copy({
+						parameters: async_parameters,
+						return_type: async_return,
+					}),
+					node.copy({
+						parameters: sync_parameters,
+					}),
+					node.copy({
+						return_type: new BinaryType(async_return, node.return()),
+					}),
+				]);
+			}
+		}
+	});
+}
+
+export { GirModule as IntrospectedNamespace } from "../gir-module.ts";

package/src/gir/parameter.ts

@@ -0,0 +1,199 @@
+import { GirDirection } from "@gi.ts/parser";
+import type { FormatGenerator } from "../generators/generator.ts";
+import { ArrayType, type TypeExpression } from "../gir.ts";
+
+import type { GirCallableParamElement } from "../index.ts";
+import type { IntrospectedOptions, OptionsLoad } from "../types/index.ts";
+import { getType, parseDoc, parseMetadata } from "../utils/gir-parsing.ts";
+import { isIntrospectable } from "../utils/girs.ts";
+import { isInvalid, sanitizeMemberName } from "../utils/naming.ts";
+import type { GirVisitor } from "../visitor.ts";
+import type { IntrospectedConstructor } from "./constructor.ts";
+import type { IntrospectedDirectAllocationConstructor } from "./direct-allocation-constructor.ts";
+import type { IntrospectedFunction } from "./function.ts";
+import { IntrospectedBase } from "./introspected-base.ts";
+import { IntrospectedBaseClass, type IntrospectedClassFunction } from "./introspected-classes.ts";
+import { IntrospectedField } from "./property.ts";
+import type { IntrospectedSignal } from "./signal.ts";
+
+export class IntrospectedFunctionParameter extends IntrospectedBase<
+	| IntrospectedClassFunction
+	| IntrospectedFunction
+	| IntrospectedSignal
+	| IntrospectedConstructor
+	| IntrospectedDirectAllocationConstructor
+	| null
+> {
+	readonly type: TypeExpression;
+	readonly direction: GirDirection;
+	readonly isVarArgs: boolean = false;
+	readonly isOptional: boolean = false;
+	readonly isNullable: boolean = false;
+
+	constructor({
+		name,
+		direction,
+		type,
+		parent,
+		doc,
+		isVarArgs = false,
+		isOptional = false,
+		isNullable = false,
+		...args
+	}: IntrospectedOptions<{
+		name: string;
+		parent?:
+			| IntrospectedClassFunction
+			| IntrospectedFunction
+			| IntrospectedSignal
+			| IntrospectedConstructor
+			| IntrospectedDirectAllocationConstructor
+			| null;
+		type: TypeExpression;
+		direction: GirDirection;
+		doc?: string | null;
+		isVarArgs?: boolean;
+		isOptional?: boolean;
+		isNullable?: boolean;
+	}>) {
+		super(name, parent ?? null, { ...args });
+
+		this.type = type;
+		this.direction = direction;
+		this.doc = doc;
+		this.isVarArgs = isVarArgs;
+		this.isOptional = isOptional;
+		this.isNullable = isNullable;
+	}
+
+	get namespace() {
+		if (!this.parent) throw new Error(`Failed to get namespace for ${this.name}`);
+
+		return this.parent.namespace;
+	}
+
+	asField() {
+		const { name, parent, isOptional: optional, type } = this;
+
+		if (!(parent?.parent instanceof IntrospectedBaseClass)) {
+			throw new Error("Can't convert parameter of non-class function to field");
+		}
+
+		return new IntrospectedField({ name, parent: parent.parent, optional, type });
+	}
+
+	copy(
+		options: {
+			parent?:
+				| IntrospectedClassFunction
+				| IntrospectedFunction
+				| IntrospectedSignal
+				| IntrospectedConstructor
+				| IntrospectedDirectAllocationConstructor
+				| null;
+			type?: TypeExpression;
+			isOptional?: boolean;
+			isNullable?: boolean;
+		} = {
+			parent: this.parent,
+		},
+	): IntrospectedFunctionParameter {
+		const { type, parent, direction, isVarArgs, isOptional, isNullable, name, doc } = this;
+
+		return new IntrospectedFunctionParameter({
+			parent: options.parent ?? parent,
+			name,
+			direction,
+			isVarArgs,
+			isOptional: options.isOptional ?? isOptional,
+			isNullable: options.isNullable ?? isNullable,
+			type: options.type ?? type,
+			doc,
+		})._copyBaseProperties(this);
+	}
+
+	accept(visitor: GirVisitor): IntrospectedFunctionParameter {
+		const node = this.copy({
+			type: visitor.visitType?.(this.type),
+		});
+
+		return visitor.visitParameter?.(node) ?? node;
+	}
+
+	asString<T>(generator: FormatGenerator<T>): T {
+		return generator.generateParameter(this);
+	}
+
+	static fromXML<
+		Parent extends IntrospectedSignal | IntrospectedClassFunction | IntrospectedFunction | IntrospectedConstructor,
+	>(
+		parameter: GirCallableParamElement & { $: { name: string } },
+		parent: Parent,
+		options: OptionsLoad,
+	): IntrospectedFunctionParameter {
+		const ns = parent.namespace;
+		let name = sanitizeMemberName(parameter.$.name);
+
+		if (isInvalid(name)) {
+			name = `_${name}`;
+		}
+
+		let isVarArgs = false;
+		let isOptional = false;
+		let isNullable = false;
+
+		let type: TypeExpression;
+		let direction: GirDirection;
+
+		if (
+			!parameter.$.direction ||
+			parameter.$.direction === GirDirection.In ||
+			parameter.$.direction === GirDirection.Inout ||
+			parameter.$.direction === GirDirection.InOut
+		) {
+			if (name === "...") {
+				isVarArgs = true;
+				name = "args";
+			}
+
+			// Default to "in" direction
+			direction = parameter.$.direction || GirDirection.In;
+
+			const optional = parameter.$.optional === "1";
+			const nullable = parameter.$.nullable === "1";
+
+			if (optional) {
+				isOptional = true;
+			}
+
+			if (nullable) {
+				isNullable = true;
+			}
+
+			type = getType(ns, parameter);
+		} else if (parameter.$.direction === GirDirection.Out) {
+			direction = parameter.$.direction;
+			type = getType(ns, parameter);
+		} else {
+			throw new Error(`Unknown parameter direction: ${parameter.$.direction as string}`);
+		}
+
+		const fp = new IntrospectedFunctionParameter({
+			isVarArgs,
+			type: isVarArgs ? new ArrayType(type) : type,
+			direction,
+			parent: parent ?? undefined,
+			isOptional,
+			isNullable,
+			name,
+			isIntrospectable: isIntrospectable(parameter),
+		});
+
+		if (options.loadDocs) {
+			fp.doc = parseDoc(parameter);
+			fp.metadata = parseMetadata(parameter);
+		}
+
+		return fp;
+	}
+}

package/src/gir/promisify.ts

@@ -0,0 +1,214 @@
+import { BinaryType, BooleanType, ClosureType, PromiseType, TupleType, TypeIdentifier, VoidType } from "../gir.ts";
+import { IntrospectedConstructor } from "./constructor.ts";
+import type { IntrospectedClassFunction } from "./introspected-classes.ts";
+import {
+	IntrospectedBaseClass,
+	IntrospectedInterface,
+	IntrospectedStaticClassFunction,
+	IntrospectedVirtualClassFunction,
+} from "./introspected-classes.ts";
+import type { IntrospectedFunctionParameter } from "./parameter.ts";
+
+/**
+ * Generates three overloaded function signatures for async methods:
+ * 1. A Promise-based version without callback
+ * 2. A callback-based version with required callback
+ * 3. A union version with optional callback
+ *
+ * @param node - The original class function to create overloads from
+ * @param async_parameters - Parameters for the Promise-based version (without callback)
+ * @param sync_parameters - Parameters for the callback version
+ * @param async_return - The Promise return type
+ * @returns Array of three overloaded function signatures
+ */
+function generatePromisifyOverloadedSignatures(
+	node: IntrospectedClassFunction,
+	async_parameters: IntrospectedFunctionParameter[],
+	sync_parameters: IntrospectedFunctionParameter[],
+	async_return: PromiseType,
+): IntrospectedClassFunction[] {
+	// Promise-based overload (without callback)
+	const promiseOverload = node.copy({
+		parameters: async_parameters,
+		returnType: async_return,
+	});
+
+	// Callback-based overload (with required callback)
+	const callbackOverload = node.copy({
+		parameters: sync_parameters,
+		returnType: VoidType,
+	});
+
+	// Union overload (with optional callback)
+	const unionOverload = node.copy({
+		parameters: [...async_parameters, sync_parameters[sync_parameters.length - 1].copy({ isOptional: true })],
+		returnType: new BinaryType(async_return, VoidType),
+	});
+
+	return [promiseOverload, callbackOverload, unionOverload];
+}
+
+/**
+ * Searches for a corresponding finish method within a class
+ * Matches either {name}_finish or {name without _async}_finish
+ *
+ * @param cls - The class to search in
+ * @param node - The async function to find the finish method for
+ * @returns The finish method if found, undefined otherwise
+ */
+function findFinishMethodInClass(cls: IntrospectedBaseClass, node: IntrospectedClassFunction) {
+	const members =
+		node instanceof IntrospectedStaticClassFunction
+			? [...cls.constructors, ...cls.members.filter((m) => m instanceof IntrospectedStaticClassFunction)]
+			: [...cls.members.filter((m) => !(m instanceof IntrospectedStaticClassFunction))];
+
+	// Prefer the GIR-specified finish function name over name heuristics
+	if (node.finishFuncName) {
+		return members.find((m) => m.name === node.finishFuncName);
+	}
+
+	return members.find(
+		(m) => m.name === `${node.name.replace(/_async$/, "")}_finish` || m.name === `${node.name}_finish`,
+	);
+}
+
+/**
+ * Searches for a finish method in the class hierarchy:
+ * 1. Searches in the current class
+ * 2. Searches in the interface parent if available
+ * 3. Searches through the parent class hierarchy
+ *
+ * @param node - The async function to find the finish method for
+ * @param parent - The immediate parent class
+ * @param interfaceParent - Optional interface parent to search in
+ * @returns The finish method if found, undefined otherwise
+ */
+function findFinishMethod(
+	node: IntrospectedClassFunction,
+	parent: IntrospectedBaseClass,
+	interfaceParent?: IntrospectedInterface,
+) {
+	// Search in current class
+	let async_res = findFinishMethodInClass(parent, node);
+
+	// If not found and we have an interface parent, search there
+	if (!async_res && interfaceParent) {
+		async_res = findFinishMethodInClass(interfaceParent, node);
+	}
+
+	// If still not found, search through parent hierarchy
+	if (!async_res) {
+		async_res = parent.findParentMap((parentClass) => findFinishMethodInClass(parentClass, node));
+	}
+
+	return async_res;
+}
+
+/**
+ * Creates a Promise return type for an async function
+ * Handles both simple returns and tuple returns with output parameters
+ *
+ * @param async_res - The finish method or constructor to create the return type from
+ * @returns A PromiseType containing the appropriate return type
+ */
+function createAsyncReturn(async_res: IntrospectedClassFunction | IntrospectedConstructor): PromiseType {
+	const output_parameters = async_res instanceof IntrospectedConstructor ? [] : async_res.output_parameters;
+	const return_type = async_res.return();
+
+	// For async methods that return multiple values (like read_bytes_finish)
+	if (output_parameters.length > 0) {
+		// If there's only one output parameter and the return type is void/boolean,
+		// use the output parameter as the Promise result type
+		if (output_parameters.length === 1 && (return_type.equals(VoidType) || return_type.equals(BooleanType))) {
+			return new PromiseType(output_parameters[0].type);
+		}
+
+		// Special case: If return type is boolean and we have multiple output parameters,
+		// GJS drops the boolean from the tuple (as it's used for error handling)
+		if (return_type.equals(BooleanType) && output_parameters.length > 0) {
+			const [firstParam, ...restParams] = output_parameters;
+			return new PromiseType(new TupleType(firstParam.type, ...restParams.map((p) => p.type)));
+		}
+
+		// Otherwise, return a tuple of [return_value, ...output_parameters]
+		return new PromiseType(new TupleType(return_type, ...output_parameters.map((p) => p.type)));
+	}
+
+	// For simple async methods that just return a value
+	return new PromiseType(return_type);
+}
+
+/**
+ * Checks if a parameter is a Gio.AsyncReadyCallback
+ *
+ * @param param - The function parameter to check
+ * @returns true if the parameter is an AsyncReadyCallback, false otherwise
+ */
+function isAsyncReadyCallback(param: IntrospectedFunctionParameter): boolean {
+	const unwrapped = param.type.unwrap();
+	return (
+		unwrapped instanceof ClosureType &&
+		unwrapped.type instanceof TypeIdentifier &&
+		unwrapped.type.is("Gio", "AsyncReadyCallback")
+	);
+}
+
+/**
+ * Checks if a function is an async function that can be promisified
+ * Must have a corresponding _finish method and take an AsyncReadyCallback
+ */
+function isPromisifiable(node: IntrospectedClassFunction): boolean {
+	// Skip virtual functions
+	if (node instanceof IntrospectedVirtualClassFunction) return false;
+
+	// Must have at least one parameter
+	if (node.parameters.length === 0) return false;
+
+	// Last parameter must be AsyncReadyCallback
+	const last_param = node.parameters[node.parameters.length - 1];
+	if (!last_param || !isAsyncReadyCallback(last_param)) return false;
+
+	// Must have a parent class
+	const parent = node.parent;
+	if (!(parent instanceof IntrospectedBaseClass)) return false;
+
+	// Must have a corresponding finish method
+	const async_res = findFinishMethod(
+		node,
+		parent,
+		node.interfaceParent instanceof IntrospectedInterface ? node.interfaceParent : undefined,
+	);
+
+	return async_res !== undefined;
+}
+
+/**
+ * Transforms async functions to include Promise-based overloads
+ */
+export function promisifyFunctions(functions: IntrospectedClassFunction[]): IntrospectedClassFunction[] {
+	return functions.flatMap((node) => {
+		// Check if function can be promisified
+		if (!isPromisifiable(node)) return node;
+
+		const parent = node.parent as IntrospectedBaseClass;
+		const async_res = findFinishMethod(
+			node,
+			parent,
+			node.interfaceParent instanceof IntrospectedInterface ? node.interfaceParent : undefined,
+		);
+
+		if (!async_res) return node;
+
+		// Create parameters for Promise version (without callback)
+		const async_parameters = node.parameters.slice(0, -1).map((p) => p.copy({ parent: node }));
+
+		// Create parameters for callback version (all parameters required)
+		const sync_parameters = node.parameters.map((p) => p.copy({ isOptional: false }));
+
+		// Create Promise return type
+		const async_return = createAsyncReturn(async_res);
+
+		// Generate the three overloaded signatures
+		return generatePromisifyOverloadedSignatures(node, async_parameters, sync_parameters, async_return);
+	});
+}