@gtkx/gir 0.1.0

package/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "@gtkx/gir",
+    "version": "0.1.0",
+    "description": "GObject Introspection file parser for GTKX",
+    "license": "MPL-2.0",
+    "author": "Eugenio Depalo <eugeniodepalo@gmail.com>",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/eugeniodepalo/gtkx.git",
+        "directory": "packages/gir"
+    },
+    "homepage": "https://eugeniodepalo.github.io/gtkx",
+    "bugs": "https://github.com/eugeniodepalo/gtkx/issues",
+    "keywords": ["gtk", "gtk4", "gir", "gobject", "introspection", "parser"],
+    "type": "module",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": "./src/index.ts"
+    },
+    "files": ["src"]
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./parser.js";
+export * from "./types.js";

package/src/parser.ts

@@ -0,0 +1,313 @@
+import { XMLParser } from "fast-xml-parser";
+import type {
+    GirClass,
+    GirConstructor,
+    GirEnumeration,
+    GirEnumerationMember,
+    GirFunction,
+    GirInterface,
+    GirMethod,
+    GirNamespace,
+    GirParameter,
+    GirProperty,
+    GirSignal,
+    GirType,
+} from "./types.js";
+
+const ARRAY_ELEMENT_PATHS = new Set<string>([
+    "namespace.class",
+    "namespace.interface",
+    "namespace.function",
+    "namespace.enumeration",
+    "namespace.bitfield",
+    "namespace.class.method",
+    "namespace.class.constructor",
+    "namespace.class.property",
+    "namespace.class.signal",
+    "namespace.class.glib:signal",
+    "namespace.interface.method",
+    "namespace.interface.property",
+    "namespace.interface.signal",
+    "namespace.interface.glib:signal",
+    "namespace.class.method.parameters.parameter",
+    "namespace.class.constructor.parameters.parameter",
+    "namespace.function.parameters.parameter",
+    "namespace.enumeration.member",
+    "namespace.bitfield.member",
+    "namespace.interface.method.parameters.parameter",
+    "namespace.class.glib:signal.parameters.parameter",
+    "namespace.interface.glib:signal.parameters.parameter",
+]);
+
+const extractDoc = (node: Record<string, unknown>): string | undefined => {
+    const doc = node.doc as Record<string, unknown> | undefined;
+    if (!doc) return undefined;
+    const text = doc["#text"] as string | undefined;
+    return text?.trim();
+};
+
+/**
+ * Parser for GObject Introspection (GIR) XML files.
+ * Converts GIR XML into structured TypeScript interfaces.
+ */
+export class GirParser {
+    private parser: XMLParser;
+
+    /** Creates a new GIR parser instance. */
+    constructor() {
+        this.parser = new XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: "@_",
+            textNodeName: "#text",
+            isArray: (_name, jpath, _isLeafNode, _isAttribute) => {
+                const path = jpath.split(".").slice(1).join(".");
+                return ARRAY_ELEMENT_PATHS.has(path);
+            },
+        });
+    }
+
+    /**
+     * Parses a GIR XML string into a structured namespace definition.
+     * @param girXml - The GIR XML content to parse
+     * @returns The parsed namespace containing all type definitions
+     * @throws Error if the XML is invalid or missing required elements
+     */
+    parse(girXml: string): GirNamespace {
+        const parsed = this.parser.parse(girXml);
+        const repository = parsed.repository;
+
+        if (!repository?.namespace) {
+            throw new Error("Invalid GIR file: missing repository or namespace");
+        }
+
+        const namespace = repository.namespace;
+
+        return {
+            name: namespace["@_name"],
+            version: namespace["@_version"],
+            sharedLibrary: namespace["@_shared-library"] ?? "",
+            cPrefix: namespace["@_c:identifier-prefixes"] ?? namespace["@_c:prefix"] ?? "",
+            classes: this.parseClasses(namespace.class ?? []),
+            interfaces: this.parseInterfaces(namespace.interface ?? []),
+            functions: this.parseFunctions(namespace.function ?? []),
+            enumerations: this.parseEnumerations(namespace.enumeration ?? []),
+            bitfields: this.parseEnumerations(namespace.bitfield ?? []),
+        };
+    }
+
+    private parseClasses(classes: Record<string, unknown>[]): GirClass[] {
+        return classes.map((cls) => ({
+            name: String(cls["@_name"] ?? ""),
+            cType: String(cls["@_c:type"] ?? cls["@_glib:type-name"] ?? ""),
+            parent: String(cls["@_parent"] ?? ""),
+            abstract: cls["@_abstract"] === "1",
+            implements: this.parseImplements(
+                cls.implements as Record<string, unknown>[] | Record<string, unknown> | undefined,
+            ),
+            methods: this.parseMethods(Array.isArray(cls.method) ? (cls.method as Record<string, unknown>[]) : []),
+            constructors: this.parseConstructors(
+                Array.isArray(cls.constructor) ? (cls.constructor as Record<string, unknown>[]) : [],
+            ),
+            properties: this.parseProperties(
+                Array.isArray(cls.property) ? (cls.property as Record<string, unknown>[]) : [],
+            ),
+            signals: this.parseSignals(
+                Array.isArray(cls["glib:signal"]) ? (cls["glib:signal"] as Record<string, unknown>[]) : [],
+            ),
+            doc: extractDoc(cls),
+        }));
+    }
+
+    private parseImplements(implements_: Record<string, unknown>[] | Record<string, unknown> | undefined): string[] {
+        if (!implements_) return [];
+        const arr = Array.isArray(implements_) ? implements_ : [implements_];
+        return arr.map((impl) => String(impl["@_name"] ?? "")).filter(Boolean);
+    }
+
+    private parseInterfaces(interfaces: Record<string, unknown>[]): GirInterface[] {
+        if (!interfaces || !Array.isArray(interfaces)) {
+            return [];
+        }
+        return interfaces.map((iface) => ({
+            name: String(iface["@_name"] ?? ""),
+            cType: String(iface["@_c:type"] ?? iface["@_glib:type-name"] ?? ""),
+            methods: this.parseMethods(Array.isArray(iface.method) ? (iface.method as Record<string, unknown>[]) : []),
+            properties: this.parseProperties(
+                Array.isArray(iface.property) ? (iface.property as Record<string, unknown>[]) : [],
+            ),
+            signals: this.parseSignals(
+                Array.isArray(iface["glib:signal"]) ? (iface["glib:signal"] as Record<string, unknown>[]) : [],
+            ),
+            doc: extractDoc(iface),
+        }));
+    }
+
+    private parseMethods(methods: Record<string, unknown>[]): GirMethod[] {
+        if (!methods || !Array.isArray(methods)) {
+            return [];
+        }
+        return methods.map((method) => ({
+            name: String(method["@_name"] ?? ""),
+            cIdentifier: String(method["@_c:identifier"] ?? ""),
+            returnType: this.parseReturnType(method["return-value"] as Record<string, unknown> | undefined),
+            parameters: this.parseParameters(
+                (method.parameters && typeof method.parameters === "object" && method.parameters !== null
+                    ? method.parameters
+                    : {}) as Record<string, unknown>,
+            ),
+            throws: method["@_throws"] === "1",
+            doc: extractDoc(method),
+        }));
+    }
+
+    private parseConstructors(constructors: Record<string, unknown>[]): GirConstructor[] {
+        if (!constructors || !Array.isArray(constructors)) {
+            return [];
+        }
+        return constructors.map((ctor) => ({
+            name: String(ctor["@_name"] ?? ""),
+            cIdentifier: String(ctor["@_c:identifier"] ?? ""),
+            returnType: this.parseReturnType(ctor["return-value"] as Record<string, unknown> | undefined),
+            parameters: this.parseParameters(
+                (ctor.parameters && typeof ctor.parameters === "object" && ctor.parameters !== null
+                    ? ctor.parameters
+                    : {}) as Record<string, unknown>,
+            ),
+            doc: extractDoc(ctor),
+        }));
+    }
+
+    private parseFunctions(functions: Record<string, unknown>[]): GirFunction[] {
+        if (!functions || !Array.isArray(functions)) {
+            return [];
+        }
+        return functions.map((func) => ({
+            name: String(func["@_name"] ?? ""),
+            cIdentifier: String(func["@_c:identifier"] ?? ""),
+            returnType: this.parseReturnType(func["return-value"] as Record<string, unknown> | undefined),
+            parameters: this.parseParameters(
+                (func.parameters && typeof func.parameters === "object" && func.parameters !== null
+                    ? func.parameters
+                    : {}) as Record<string, unknown>,
+            ),
+            throws: func["@_throws"] === "1",
+            doc: extractDoc(func),
+        }));
+    }
+
+    private parseParameters(parametersNode: Record<string, unknown>): GirParameter[] {
+        if (!parametersNode?.parameter) {
+            return [];
+        }
+
+        const params = Array.isArray(parametersNode.parameter) ? parametersNode.parameter : [parametersNode.parameter];
+
+        return params.map((param: Record<string, unknown>) => ({
+            name: String(param["@_name"] ?? ""),
+            type: this.parseType((param.type ?? param.array) as Record<string, unknown> | undefined),
+            direction: (String(param["@_direction"] ?? "in") as "in" | "out" | "inout") || "in",
+            nullable: param["@_nullable"] === "1",
+            optional: param["@_allow-none"] === "1",
+            doc: extractDoc(param),
+        }));
+    }
+
+    private parseReturnType(returnValue: Record<string, unknown> | undefined): GirType {
+        if (!returnValue) {
+            return { name: "void" };
+        }
+        return this.parseType((returnValue.type ?? returnValue.array) as Record<string, unknown> | undefined);
+    }
+
+    private parseType(typeNode: Record<string, unknown> | undefined): GirType {
+        if (!typeNode) {
+            return { name: "void" };
+        }
+
+        if (typeNode["@_name"]) {
+            return {
+                name: String(typeNode["@_name"] ?? ""),
+                cType: typeNode["@_c:type"] ? String(typeNode["@_c:type"]) : undefined,
+            };
+        }
+
+        const isArrayNode =
+            typeNode.type ||
+            typeNode["@_zero-terminated"] !== undefined ||
+            typeNode["@_fixed-size"] !== undefined ||
+            typeNode["@_length"] !== undefined;
+
+        if (isArrayNode) {
+            return {
+                name: "array",
+                isArray: true,
+                elementType: typeNode.type ? this.parseType(typeNode.type as Record<string, unknown>) : undefined,
+            };
+        }
+
+        return { name: "void" };
+    }
+
+    private parseProperties(properties: Record<string, unknown>[]): GirProperty[] {
+        if (!properties || !Array.isArray(properties)) {
+            return [];
+        }
+        return properties.map((prop) => ({
+            name: String(prop["@_name"] ?? ""),
+            type: this.parseType((prop.type ?? prop.array) as Record<string, unknown> | undefined),
+            readable: prop["@_readable"] !== "0",
+            writable: prop["@_writable"] === "1",
+            constructOnly: prop["@_construct-only"] === "1",
+            hasDefault: prop["@_default-value"] !== undefined,
+            doc: extractDoc(prop),
+        }));
+    }
+
+    private parseSignals(signals: Record<string, unknown>[]): GirSignal[] {
+        if (!signals || !Array.isArray(signals)) {
+            return [];
+        }
+        return signals.map((signal) => {
+            const whenValue = String(signal["@_when"] ?? "last");
+            const validWhen = whenValue === "first" || whenValue === "last" || whenValue === "cleanup";
+            return {
+                name: String(signal["@_name"] ?? ""),
+                when: validWhen ? (whenValue as "first" | "last" | "cleanup") : "last",
+                returnType: signal["return-value"]
+                    ? this.parseReturnType(signal["return-value"] as Record<string, unknown>)
+                    : undefined,
+                parameters:
+                    signal.parameters && typeof signal.parameters === "object" && signal.parameters !== null
+                        ? this.parseParameters(signal.parameters as Record<string, unknown>)
+                        : [],
+                doc: extractDoc(signal),
+            };
+        });
+    }
+
+    private parseEnumerations(enumerations: Record<string, unknown>[]): GirEnumeration[] {
+        if (!enumerations || !Array.isArray(enumerations)) {
+            return [];
+        }
+        return enumerations.map((enumeration) => ({
+            name: String(enumeration["@_name"] ?? ""),
+            cType: String(enumeration["@_c:type"] ?? ""),
+            members: this.parseEnumerationMembers(
+                Array.isArray(enumeration.member) ? (enumeration.member as Record<string, unknown>[]) : [],
+            ),
+            doc: extractDoc(enumeration),
+        }));
+    }
+
+    private parseEnumerationMembers(members: Record<string, unknown>[]): GirEnumerationMember[] {
+        if (!members || !Array.isArray(members)) {
+            return [];
+        }
+        return members.map((member) => ({
+            name: String(member["@_name"] ?? ""),
+            value: String(member["@_value"] ?? ""),
+            cIdentifier: String(member["@_c:identifier"] ?? ""),
+            doc: extractDoc(member),
+        }));
+    }
+}

package/src/types.ts

@@ -0,0 +1,469 @@
+/**
+ * Represents a parsed GIR namespace containing all type definitions.
+ */
+export interface GirNamespace {
+    /** The namespace name (e.g., "Gtk", "Gio"). */
+    name: string;
+    /** The namespace version (e.g., "4.0"). */
+    version: string;
+    /** The shared library file name. */
+    sharedLibrary: string;
+    /** The C identifier prefix for this namespace. */
+    cPrefix: string;
+    /** All classes defined in this namespace. */
+    classes: GirClass[];
+    /** All interfaces defined in this namespace. */
+    interfaces: GirInterface[];
+    /** All standalone functions defined in this namespace. */
+    functions: GirFunction[];
+    /** All enumerations defined in this namespace. */
+    enumerations: GirEnumeration[];
+    /** All bitfield enumerations defined in this namespace. */
+    bitfields: GirEnumeration[];
+    /** Documentation for the namespace. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR interface definition.
+ */
+export interface GirInterface {
+    /** The interface name. */
+    name: string;
+    /** The C type name. */
+    cType: string;
+    /** Methods defined on this interface. */
+    methods: GirMethod[];
+    /** Properties defined on this interface. */
+    properties: GirProperty[];
+    /** Signals defined on this interface. */
+    signals: GirSignal[];
+    /** Documentation for the interface. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR class definition.
+ */
+export interface GirClass {
+    /** The class name. */
+    name: string;
+    /** The C type name. */
+    cType: string;
+    /** The parent class name, if any. */
+    parent?: string;
+    /** Whether this is an abstract class. */
+    abstract?: boolean;
+    /** List of interface names this class implements. */
+    implements: string[];
+    /** Methods defined on this class. */
+    methods: GirMethod[];
+    /** Constructor functions for this class. */
+    constructors: GirConstructor[];
+    /** Properties defined on this class. */
+    properties: GirProperty[];
+    /** Signals defined on this class. */
+    signals: GirSignal[];
+    /** Documentation for the class. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR method definition.
+ */
+export interface GirMethod {
+    /** The method name. */
+    name: string;
+    /** The C function identifier. */
+    cIdentifier: string;
+    /** The return type. */
+    returnType: GirType;
+    /** The method parameters. */
+    parameters: GirParameter[];
+    /** Whether this method can throw a GError. */
+    throws?: boolean;
+    /** Documentation for the method. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR constructor definition.
+ */
+export interface GirConstructor {
+    /** The constructor name. */
+    name: string;
+    /** The C function identifier. */
+    cIdentifier: string;
+    /** The return type (typically the class type). */
+    returnType: GirType;
+    /** The constructor parameters. */
+    parameters: GirParameter[];
+    /** Documentation for the constructor. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR standalone function definition.
+ */
+export interface GirFunction {
+    /** The function name. */
+    name: string;
+    /** The C function identifier. */
+    cIdentifier: string;
+    /** The return type. */
+    returnType: GirType;
+    /** The function parameters. */
+    parameters: GirParameter[];
+    /** Whether this function can throw a GError. */
+    throws?: boolean;
+    /** Documentation for the function. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR parameter definition.
+ */
+export interface GirParameter {
+    /** The parameter name. */
+    name: string;
+    /** The parameter type. */
+    type: GirType;
+    /** The parameter direction (in, out, or inout). */
+    direction?: "in" | "out" | "inout";
+    /** Whether this parameter can be null. */
+    nullable?: boolean;
+    /** Whether this parameter is optional. */
+    optional?: boolean;
+    /** Documentation for the parameter. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR type reference.
+ */
+export interface GirType {
+    /** The type name. */
+    name: string;
+    /** The C type name. */
+    cType?: string;
+    /** Whether this is an array type. */
+    isArray?: boolean;
+    /** The element type for array types. */
+    elementType?: GirType;
+}
+
+/**
+ * Represents a GIR property definition.
+ */
+export interface GirProperty {
+    /** The property name. */
+    name: string;
+    /** The property type. */
+    type: GirType;
+    /** Whether this property is readable. */
+    readable?: boolean;
+    /** Whether this property is writable. */
+    writable?: boolean;
+    /** Whether this property can only be set at construction time. */
+    constructOnly?: boolean;
+    /** Whether this property has a default value. */
+    hasDefault?: boolean;
+    /** Documentation for the property. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR signal definition.
+ */
+export interface GirSignal {
+    /** The signal name. */
+    name: string;
+    /** When the signal handler runs relative to the default handler. */
+    when?: "first" | "last" | "cleanup";
+    /** The signal return type. */
+    returnType?: GirType;
+    /** The signal parameters passed to handlers. */
+    parameters?: GirParameter[];
+    /** Documentation for the signal. */
+    doc?: string;
+}
+
+/**
+ * Represents a GIR enumeration or bitfield definition.
+ */
+export interface GirEnumeration {
+    /** The enumeration name. */
+    name: string;
+    /** The C type name. */
+    cType: string;
+    /** The enumeration members. */
+    members: GirEnumerationMember[];
+    /** Documentation for the enumeration. */
+    doc?: string;
+}
+
+/**
+ * Represents a single enumeration member.
+ */
+export interface GirEnumerationMember {
+    /** The member name. */
+    name: string;
+    /** The numeric value. */
+    value: string;
+    /** The C identifier. */
+    cIdentifier: string;
+    /** Documentation for the member. */
+    doc?: string;
+}
+
+/**
+ * Describes an FFI type for code generation.
+ */
+export interface FfiTypeDescriptor {
+    /** The FFI type category. */
+    type: string;
+    /** Size in bits for integer/float types. */
+    size?: number;
+    /** Whether the integer type is unsigned. */
+    unsigned?: boolean;
+    /** Whether the pointer is borrowed (not owned). */
+    borrowed?: boolean;
+    /** Inner type for ref types. */
+    innerType?: FfiTypeDescriptor;
+    /** Item type for array types. */
+    itemType?: FfiTypeDescriptor;
+}
+
+/**
+ * Converts a snake_case or kebab-case string to camelCase.
+ * @param str - The input string
+ * @returns The camelCase version
+ */
+export const toCamelCase = (str: string): string => str.replace(/[-_]([a-z])/g, (_, letter) => letter.toUpperCase());
+
+/**
+ * Converts a snake_case or kebab-case string to PascalCase.
+ * @param str - The input string
+ * @returns The PascalCase version
+ */
+export const toPascalCase = (str: string): string => {
+    const camel = toCamelCase(str);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+};
+
+/**
+ * Builds a map of class names to class definitions for quick lookup.
+ * @param classes - Array of GIR class definitions
+ * @returns Map from class name to class definition
+ */
+export const buildClassMap = (classes: GirClass[]): Map<string, GirClass> => {
+    const classMap = new Map<string, GirClass>();
+    for (const cls of classes) {
+        classMap.set(cls.name, cls);
+    }
+    return classMap;
+};
+
+/**
+ * Registers all enumerations and bitfields from a namespace with a type mapper.
+ * @param typeMapper - The TypeMapper instance to register with
+ * @param namespace - The GIR namespace containing enums to register
+ */
+export const registerEnumsFromNamespace = (typeMapper: TypeMapper, namespace: GirNamespace): void => {
+    for (const enumeration of namespace.enumerations) {
+        typeMapper.registerEnum(enumeration.name, toPascalCase(enumeration.name));
+    }
+    for (const bitfield of namespace.bitfields) {
+        typeMapper.registerEnum(bitfield.name, toPascalCase(bitfield.name));
+    }
+};
+
+type TypeMapping = { ts: string; ffi: FfiTypeDescriptor };
+
+const BASIC_TYPE_MAP = new Map<string, TypeMapping>([
+    ["gboolean", { ts: "boolean", ffi: { type: "boolean" } }],
+    ["gchar", { ts: "number", ffi: { type: "int", size: 8, unsigned: false } }],
+    ["guchar", { ts: "number", ffi: { type: "int", size: 8, unsigned: true } }],
+    ["gint", { ts: "number", ffi: { type: "int", size: 32, unsigned: false } }],
+    ["guint", { ts: "number", ffi: { type: "int", size: 32, unsigned: true } }],
+    ["gshort", { ts: "number", ffi: { type: "int", size: 32, unsigned: false } }],
+    ["gushort", { ts: "number", ffi: { type: "int", size: 32, unsigned: true } }],
+    ["glong", { ts: "number", ffi: { type: "int", size: 64, unsigned: false } }],
+    ["gulong", { ts: "number", ffi: { type: "int", size: 64, unsigned: true } }],
+    ["GType", { ts: "number", ffi: { type: "int", size: 64, unsigned: true } }],
+    ["gint8", { ts: "number", ffi: { type: "int", size: 8, unsigned: false } }],
+    ["guint8", { ts: "number", ffi: { type: "int", size: 8, unsigned: true } }],
+    ["gint16", { ts: "number", ffi: { type: "int", size: 32, unsigned: false } }],
+    ["guint16", { ts: "number", ffi: { type: "int", size: 32, unsigned: true } }],
+    ["gint32", { ts: "number", ffi: { type: "int", size: 32, unsigned: false } }],
+    ["guint32", { ts: "number", ffi: { type: "int", size: 32, unsigned: true } }],
+    ["gint64", { ts: "number", ffi: { type: "int", size: 64, unsigned: false } }],
+    ["guint64", { ts: "number", ffi: { type: "int", size: 64, unsigned: true } }],
+    ["gfloat", { ts: "number", ffi: { type: "float", size: 32 } }],
+    ["gdouble", { ts: "number", ffi: { type: "float", size: 64 } }],
+    ["utf8", { ts: "string", ffi: { type: "string" } }],
+    ["filename", { ts: "string", ffi: { type: "string" } }],
+    ["gpointer", { ts: "unknown", ffi: { type: "gobject" } }],
+    ["gconstpointer", { ts: "unknown", ffi: { type: "gobject" } }],
+    ["void", { ts: "void", ffi: { type: "undefined" } }],
+    ["none", { ts: "void", ffi: { type: "undefined" } }],
+    ["int", { ts: "number", ffi: { type: "int", size: 32, unsigned: false } }],
+    ["uint", { ts: "number", ffi: { type: "int", size: 32, unsigned: true } }],
+    ["long", { ts: "number", ffi: { type: "int", size: 64, unsigned: false } }],
+    ["ulong", { ts: "number", ffi: { type: "int", size: 64, unsigned: true } }],
+    ["size_t", { ts: "number", ffi: { type: "int", size: 64, unsigned: true } }],
+    ["ssize_t", { ts: "number", ffi: { type: "int", size: 64, unsigned: false } }],
+    ["double", { ts: "number", ffi: { type: "float", size: 64 } }],
+    ["float", { ts: "number", ffi: { type: "float", size: 32 } }],
+]);
+
+const LIBRARY_MAP: Record<string, string> = {
+    Gtk: "libgtk-4.so.1",
+    GObject: "libgobject-2.0.so.0",
+    GLib: "libglib-2.0.so.0",
+    Gio: "libgio-2.0.so.0",
+    GdkPixbuf: "libgdk_pixbuf-2.0.so.0",
+    Pango: "libpango-1.0.so.0",
+    Cairo: "libcairo.so.2",
+};
+
+/**
+ * Maps GIR types to TypeScript types and FFI type descriptors.
+ * Handles basic types, enumerations, arrays, and object references.
+ */
+export class TypeMapper {
+    private enumNames: Set<string> = new Set();
+    private enumTransforms: Map<string, string> = new Map();
+    private onEnumUsed?: (enumName: string) => void;
+
+    /**
+     * Registers an enumeration type for mapping.
+     * @param originalName - The original GIR enum name
+     * @param transformedName - The transformed TypeScript enum name
+     */
+    registerEnum(originalName: string, transformedName?: string): void {
+        this.enumNames.add(originalName);
+        if (transformedName) {
+            this.enumTransforms.set(originalName, transformedName);
+        }
+    }
+
+    /**
+     * Sets a callback to track enum usage during type mapping.
+     * @param callback - Called when an enum is used, or null to clear
+     */
+    setEnumUsageCallback(callback: ((enumName: string) => void) | null): void {
+        this.onEnumUsed = callback ?? undefined;
+    }
+
+    /**
+     * Gets the current enum usage callback.
+     * @returns The callback or null if not set
+     */
+    getEnumUsageCallback(): ((enumName: string) => void) | null {
+        return this.onEnumUsed ?? null;
+    }
+
+    /**
+     * Maps a GIR type to TypeScript and FFI type descriptors.
+     * @param girType - The GIR type to map
+     * @param isReturn - Whether this is a return type (affects pointer ownership)
+     * @returns The TypeScript type string and FFI descriptor
+     */
+    mapType(girType: GirType, isReturn = false): TypeMapping {
+        if (girType.isArray || girType.name === "array") {
+            if (girType.elementType) {
+                const elementType = this.mapType(girType.elementType);
+                return {
+                    ts: `${elementType.ts}[]`,
+                    ffi: { type: "array", itemType: elementType.ffi },
+                };
+            }
+            return {
+                ts: `unknown[]`,
+                ffi: { type: "array", itemType: { type: "undefined" } },
+            };
+        }
+
+        const basicType = BASIC_TYPE_MAP.get(girType.name);
+        if (basicType) {
+            return basicType;
+        }
+
+        if (this.enumNames.has(girType.name)) {
+            const transformedName = this.enumTransforms.get(girType.name) ?? girType.name;
+            this.onEnumUsed?.(transformedName);
+            return {
+                ts: transformedName,
+                ffi: { type: "int", size: 32, unsigned: false },
+            };
+        }
+
+        if (girType.name.includes(".")) {
+            const [_ns, typeName] = girType.name.split(".", 2);
+            if (typeName && this.enumNames.has(typeName)) {
+                const transformedName = this.enumTransforms.get(typeName) ?? typeName;
+                this.onEnumUsed?.(transformedName);
+                return {
+                    ts: transformedName,
+                    ffi: { type: "int", size: 32, unsigned: false },
+                };
+            }
+            return {
+                ts: "unknown",
+                ffi: { type: "gobject", borrowed: isReturn },
+            };
+        }
+
+        return {
+            ts: "unknown",
+            ffi: { type: "gobject", borrowed: isReturn },
+        };
+    }
+
+    /**
+     * Maps a GIR parameter to TypeScript and FFI type descriptors.
+     * Handles out/inout parameters by wrapping in Ref type.
+     * @param param - The GIR parameter to map
+     * @returns The TypeScript type string and FFI descriptor
+     */
+    mapParameter(param: GirParameter): TypeMapping {
+        if (param.direction === "out" || param.direction === "inout") {
+            const innerType = this.mapType(param.type);
+            return {
+                ts: `Ref<${innerType.ts}>`,
+                ffi: {
+                    type: "ref",
+                    innerType: innerType.ffi,
+                },
+            };
+        }
+
+        if (param.type.name === "GLib.Closure" || param.type.name.endsWith("Func")) {
+            return {
+                ts: "(...args: unknown[]) => unknown",
+                ffi: { type: "callback" },
+            };
+        }
+
+        return this.mapType(param.type);
+    }
+
+    /**
+     * Checks if a parameter can accept null values.
+     * @param param - The parameter to check
+     * @returns True if the parameter is nullable or optional
+     */
+    isNullable(param: GirParameter): boolean {
+        return param.nullable === true || param.optional === true;
+    }
+
+    /**
+     * Gets the shared library name for a namespace.
+     * @param namespace - The namespace name
+     * @returns The shared library file name
+     */
+    getLibraryName(namespace: string): string {
+        return LIBRARY_MAP[namespace] ?? `lib${namespace.toLowerCase()}.so`;
+    }
+}